---
estimated_steps: 4
estimated_files: 10
skills_used: []
---

# T01: Canvas types, state hook with undo/redo, artboard setup, and test infrastructure

Establish the foundation that every other task depends on: canvas type definitions (discriminated union for canvas objects, artboard config, canvas state), the central useCanvasState hook with full CRUD + selection + undo/redo, artboard shape utilities, the ArtboardSetup component, and canvas mock setup for Vitest. This is the riskiest piece — the state model shape affects every downstream component.

The useCanvasState hook is a useReducer + useRef pattern: current state in a reducer (triggers re-renders), history stack in a useRef (avoids re-renders on history push). Every mutation dispatches through the reducer which also pushes a history snapshot. Undo/redo pops from history.

The ArtboardSetup component renders a modal overlay on first entering the canvas view with shape picker (rect, square, circle, oval, shield, pennant, custom), width/height number inputs, and inches/mm units toggle. On confirm, it produces an ArtboardConfig that initializes the canvas.

Install konva, react-konva, and jest-canvas-mock as dependencies. Set up canvas mock in test-setup.ts so Konva components don't crash in jsdom.

## Inputs

- ``app/src/types/engine.ts` — TraceMetadata interface consumed by canvas state`
- ``app/src/index.css` — CSS variables for ArtboardSetup component styling`
- ``app/src/test-setup.ts` — existing test setup to extend with canvas mock`
- ``app/package.json` — existing dependencies to extend with konva/react-konva/jest-canvas-mock`

## Expected Output

- ``app/src/types/canvas.ts` — CanvasObject discriminated union, ArtboardConfig, CanvasState types`
- ``app/src/hooks/useCanvasState.ts` — Central state hook: addObject, removeObject, updateObject, selectObjects, deselectAll, reorderObject, toggleVisibility, toggleLock, undo, redo, setArtboard`
- ``app/src/hooks/__tests__/useCanvasState.test.ts` — Unit tests for all state transitions: add, remove, update, select, deselect, reorder, undo, redo`
- ``app/src/utils/artboardShapes.ts` — Artboard shape path data (shield, pennant) and dimension presets`
- ``app/src/utils/__tests__/artboardShapes.test.ts` — Tests for artboard shape path generation and presets`
- ``app/src/utils/alignment.ts` — Pure alignment functions: alignLeft/Center/Right/Top/Middle/Bottom, distributeH/V, centerOnArtboard`
- ``app/src/utils/__tests__/alignment.test.ts` — Tests for all alignment calculations`
- ``app/src/components/canvas/ArtboardSetup.tsx` — Artboard setup modal with shape picker, dimension inputs, units toggle`
- ``app/src/test-setup.ts` — Extended with jest-canvas-mock import`
- ``app/package.json` — Updated with konva, react-konva, jest-canvas-mock dependencies`

## Verification

cd app && npx vitest run --reporter=verbose && npx tsc --noEmit
