ue-too Canvas Toolkit Development

Expert guidance for developing interactive HTML canvas applications using the ue-too toolkit monorepo with Bun, strict TypeScript, and performance-first architecture.

Instructions

When working with ue-too projects, follow these strict development guidelines:

Package Manager

**CRITICAL: This project uses Bun exclusively, NOT npm/pnpm**

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 requires Bun for development

3. **Node version**: 22.19.0 is the target runtime

4. **Important**: While development requires Bun, published packages remain compatible with npm/pnpm for end users

Project Architecture

1. **Monorepo Structure**:

- `packages/` - Publishable npm packages (all namespaced as `@ue-too/*`)

- `apps/` - Example applications and demos

2. **Package Dependency Hierarchy**:

- **Foundational** (zero internal dependencies): `math`, `being`, `ecs`

- **Mid-level** (depend on foundational): `board`, `animate`, `curve`, `border`

- **Integration** (depend on mid-level): `board-react-adapter`, `board-vue-adapter`

3. **Package Design Principles**:

- Each package must be independently publishable

- Minimize workspace dependencies

- Document all cross-package dependencies in README

- Keep packages under 50KB minified+gzipped when practical

TypeScript Standards

1. **Strict Mode Required**:

- All packages use `strict: true` in tsconfig

- TypeScript errors are BLOCKING - must be resolved before committing

2. **Type Safety**:

- No `any` types in public interfaces

- Use `unknown` with type guards when dynamic typing is needed

- All exports require explicit type annotations

3. **Documentation Requirements**:

- JSDoc comments required for all exports

- Must include `@param` for all parameters

- Must include `@returns` for return values

- Must include `@example` showing usage

- Use `@group` tags to organize API documentation

Testing Strategy

1. **Test Framework**: Use Jest for all testing

2. **Test Coverage Requirements**:

- Tests required for all public APIs

- Tests required for critical paths

- Test file locations: `test/*.test.ts` or `test/*.spec.ts`

3. **Running Tests**:

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

- Root-level: `bun test` (from monorepo root)

Code Style

1. **Formatting**:

- 2-space indentation

- Consistent code style across all packages

2. **Commit Messages**:

- Follow conventional commits format

- Pattern: `<type>(<package>): <description>`

- Examples:

- `feat(math): add vector normalization`

- `fix(board): correct collision detection`

- `docs(ecs): update entity system examples`

Performance Requirements

1. **Frame Budget**: Target 60 FPS for canvas operations (16.67ms per frame)

2. **Benchmarking**:

- Benchmark critical paths (math operations, collision detection, physics)

- Profile canvas rendering performance

- Test with realistic data volumes

3. **Optimization Guidelines**:

- Minimize allocations in hot paths

- Use object pooling for frequently created objects

- Cache computed values when appropriate

- Prefer TypedArrays for numeric data

Common Commands

```bash

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-name>

Add dev dependency

bun add -d <package-name>

Run example app

bun run dev

```

Package Development Workflow

1. **Creating a New Package**:

- Place in appropriate tier (foundational/mid-level/integration)

- Set up `package.json` with `@ue-too/<name>` namespace

- Configure TypeDoc (`typedoc.json`)

- Add JSDoc comments to all exports

- Include README with usage examples

2. **Documentation Requirements**:

- Each package must have README with:

- Installation instructions

- Basic usage examples

- API overview

- Cross-package dependencies

3. **Publishing Checklist**:

- All tests passing

- TypeScript builds without errors

- Documentation complete

- Version bumped appropriately

- CHANGELOG updated

Architecture Patterns

1. **ECS (Entity Component System)**:

- Use `ecs` package for entity management

- Components are pure data structures

- Systems implement behavior

2. **Canvas Rendering**:

- Use `board` package for canvas management

- Leverage `animate` for animation loops

- Apply `curve` for bezier/spline operations

3. **Framework Integration**:

- Use appropriate adapter packages (`board-react-adapter`, `board-vue-adapter`)

- Keep framework-specific code in adapter packages only

Examples

Adding a New Feature

```bash

Install dependencies

bun install

Create tests first

In packages/math/test/quaternion.test.ts

import { describe, it, expect } from '@jest/globals';

Implement feature with JSDoc

/**

* Normalizes a quaternion to unit length

* @param q - The quaternion to normalize

* @returns A new normalized quaternion

* @example

* ```ts

* const q = { x: 1, y: 1, z: 1, w: 1 };

* const normalized = normalizeQuaternion(q);

* ```

* @group Quaternion

*/

export function normalizeQuaternion(q: Quaternion): Quaternion {

// Implementation

}

Run tests

bun run test

Build package

bun run build

Commit with conventional format

git commit -m "feat(math): add quaternion normalization"

```

Running Performance Benchmarks

```bash

Run benchmark suite

bun run bench

Profile specific package

cd packages/board

bun run bench

```

Constraints