ue-too Canvas Toolkit Development

Development guidelines for the ue-too monorepo - a toolkit for building interactive HTML canvas applications with game development patterns.

Core Rules

CRITICAL: Package Manager

**This project uses Bun exclusively, NOT npm or pnpm.**

When working on this project:

1. **Always use Bun commands:**

- Install dependencies: `bun install`

- Run scripts: `bun run <script>`

- Add packages: `bun add <package>`

- Run tests: `bun test` or `bun run test`

2. **Never suggest npm or pnpm commands** - The project is configured for Bun and uses Bun-specific features

3. **Development environment:**

- Node version: 22.19.0

- Bun is required for development

- End-user packages remain compatible with npm/pnpm

Project Architecture

This is a monorepo with clear dependency layers:

**Directory Structure:**

**Dependency Layers (respect these strictly):**

1. **Foundational (zero internal dependencies):**

- `math` - Vector and geometric operations

- `being` - Core entity abstractions

- `ecs` - Entity Component System

2. **Mid-level (depend only on foundational):**

- `board` - Canvas rendering and interaction

- `animate` - Animation systems

- `curve` - Bezier curves and paths

- `border` - Collision detection

3. **Integration (depend on mid-level):**

- `board-react-adapter` - React integration

- `board-vue-adapter` - Vue integration

**Package Development Rules:**

TypeScript Standards

**Strict mode is non-negotiable:**

1. All packages use `strict: true` in tsconfig

2. TypeScript errors are BLOCKING - must be resolved before commit

3. No `any` types in public interfaces - use `unknown` with type guards instead

4. All exports require JSDoc comments with:

- `@param` for parameters

- `@returns` for return values

- `@example` for usage examples

- `@group` tags to organize API documentation

**Example:**

```typescript

/**

* Calculates the distance between two points

* @param p1 - First point

* @param p2 - Second point

* @returns The Euclidean distance

* @example

* ```ts

* const dist = distance({x: 0, y: 0}, {x: 3, y: 4});

* console.log(dist); // 5

* ```

* @group Math

*/

export function distance(p1: Point, p2: Point): number {

// implementation

}

```

Testing Requirements

**Use Jest for all testing:**

1. Tests are required for:

- All public APIs

- Critical paths (collision detection, physics, rendering loops)

- Edge cases and error handling

2. **Test file locations:**

- Place in `test/*.test.ts` or `test/*.spec.ts`

- Mirror the structure of source files

3. **Running tests:**

- Package-level: `bun run test` (in package directory)

- Root-level: `bun test` (runs all tests)

4. **Test coverage:**

- Aim for high coverage on public APIs

- Performance-critical code should include benchmarks

Code Style & Conventions

**Formatting:**

**Commit messages:**

- `feat(math): add vector cross product`

- `fix(board): resolve canvas scaling on HiDPI displays`

- `perf(ecs): optimize component lookup`

**Documentation:**

Performance Targets

**Canvas applications must hit 60 FPS:**

1. **Frame budget: 16.67ms per frame**

- Measure time spent in update/render loops

- Profile hotspots with browser DevTools

2. **Benchmark critical paths:**

- Math operations (vector ops, transforms)

- Collision detection algorithms

- Physics simulations

- Canvas drawing operations

3. **Package size targets:**

- Keep packages under 50KB minified+gzipped when practical

- Use tree-shaking friendly exports

- Minimize external dependencies

4. **Optimization strategies:**

- Object pooling for frequently created instances

- Spatial partitioning for collision detection

- RequestAnimationFrame for render loops

- Offscreen canvas for complex rendering

Common Commands

| Task | Command |

|------|---------|

| Install dependencies | `bun install` |

| Run tests (root) | `bun test` |

| Run tests (package) | `bun run test` |

| Build package | `bun run build` |

| Add dependency | `bun add <package>` |

| Add dev dependency | `bun add -d <package>` |

| Run script | `bun run <script-name>` |

Implementation Guidelines

When adding new features:

1. **Determine the correct layer** - Is this foundational, mid-level, or integration?

2. **Check dependencies** - Respect the dependency hierarchy

3. **Write types first** - Define interfaces before implementation

4. **Add JSDoc** - Document as you code, not after

5. **Write tests** - Cover public APIs and edge cases

6. **Benchmark if needed** - Profile performance-critical code

7. **Update README** - Document new APIs and examples

When fixing bugs:

1. **Write a failing test first** - Reproduce the issue

2. **Fix the implementation** - Make the test pass

3. **Check performance** - Ensure the fix doesn't regress performance

4. **Update docs** - If behavior changed, update JSDoc/README

Examples

**Adding a new math utility:**

```typescript

// packages/math/src/vector.ts

/**

* Normalizes a vector to unit length

* @param v - The vector to normalize

* @returns A new vector with length 1, or zero vector if input is zero

* @example

* ```ts

* const v = normalize({x: 3, y: 4});

* console.log(v); // {x: 0.6, y: 0.8}

* ```

* @group Vector

*/

export function normalize(v: Vector): Vector {

const len = length(v);

if (len === 0) return {x: 0, y: 0};

return {x: v.x / len, y: v.y / len};

}

```

**Creating a new integration package:**

```bash

Create package structure

mkdir -p packages/board-svelte-adapter/src

cd packages/board-svelte-adapter

Initialize with Bun

bun init

Add dependencies (note: use bun add, not npm)

bun add @ue-too/board

bun add -d svelte typescript

```

Constraints