Read README.md and ARCHITECTURE.md before changing generator, rendering or persistence boundaries.
- Run commands from this repository root.
npm run devstarts Vite and the API;npm run buildtype-checks and builds both. - Keep educational/content generation separate from presentation and layout. Presentation edits must preserve question content and seed.
- Never use unseeded randomness inside a generator. Fresh seeds belong in the application state layer.
- The same semantic pages and SVG renderer must power preview and every export. Geometry uses millimetres; typography uses points.
- Validate numeric constraints and label collisions. Never silently drop requested labels, change intervals or loosen mathematical constraints.
- Register generator metadata centrally. Compose shared controls and rendering primitives; do not scatter generator branches through shared navigation/export.
- History records store full configurations, versions and seeds, never rendered documents or thumbnails. Edits save new revisions. Do not silently migrate old records.
- Bump algorithm/schema/layout/renderer versions when their changes affect historical output. Preserve or explicitly reject unsupported versions. Update compatibility fixtures deliberately.
- Storage belongs behind repository interfaces; this is an explicitly local workspace, not production authentication.
- Put application design choices in
apps/web/src/styles/tokens.css; worksheet appearance remains independent. - Keep font binaries, browser copies and metrics in sync using
npx tsx scripts/font-metrics.ts. Respect their bundled licences. - Run
npm testfor core/export/storage changes andnpm run test:e2efor UI changes. Browser tests default to installed Chrome;PLAYWRIGHT_CHANNEL=chromiumuses installed Playwright Chromium. - Do not add speculative cloud/AI/sharing features to the initial spike. Their boundaries and deferred scope are documented.