LessonLab

A local, working resource studio for teachers. The first generator is Maths → Number Lines → Subtraction, with deterministic questions, precise SVG worksheets and print-ready exports.

Start developing

Use Node.js 22.12 or newer and npm. From this directory:

npm ci
npm run dev

Open http://127.0.0.1:6173. Vite provides hot reload; the Node API runs on http://127.0.0.1:3001, proxied through /api. Both services start with one command. No environment variables, Firebase project, account or AI credentials are required.

What works

• Home, metadata-driven discovery, favourites, a searchable resource library and teaching preferences.
• A live subtraction workspace, defaulting to eight questions, A4 landscape, UK Year 2 and fully labelled 0–50 number lines. New worksheets use rounded pastel rows with the question and answer box beside each line; row backgrounds can be switched off.
• Simple and advanced controls for educational context, numeric constraints, paper, typography, spacing, ink, ticks, labels, row layout and print style.
• Simple settings include Answer space → Writing line / Answer box and Question number style → Number badges / Plain numbers. New worksheets use small outlined number badges, separated from the calculation. Plain numbers use a closing parenthesis, such as 1). Preview and every export use these choices.
• Exact tick/value coordinates, readable-label validation, automatic pagination, optional matched answer sheets and seeded regeneration.
• Five paper sizes, both orientations, fullscreen preview, zoom, fit page, fit width, 100% and page navigation.
• Vector PDF with embedded fonts; PNG, JPEG and WebP at 96, 150 or 300 DPI. Multiple image pages download in a ZIP. Exports have page selection, filename, answer-sheet and applicable quality settings.
• Versioned local history: exact reopen, save revision, duplicate with fresh seed, rename, favourite, search, filter and delete.
• Draft persistence, undo, section/all resets, visible saved/unsaved state, keyboard focus management and reduced-motion support.

Initial generation, regeneration and export save a snapshot. Changing settings updates the draft; Save creates a new history record. Earlier records are never overwritten by a settings edit. A title rename deliberately updates that record's title and printed heading. Reopening uses the complete saved configuration and seed; regeneration creates a fresh seed. Presentation changes retain the questions. New, restored and reopened worksheets place the question beside the line. The layout selector has been removed from Simple and Advanced settings. The Coloured rows switch remains available. Crowded settings now show validation guidance instead of moving the question above the line. Opening an older resource updates the active layout while preserving its questions and seed.

Schema-1 and schema-2 worksheets retain plain question numbers when reopened. Choose Question number style → Number badges to update a draft, then save a new revision. Current configurations use schema/layout/renderer version 6 for the fixed beside-line arrangement. Older numbering choices are retained when opening a worksheet. The subtraction algorithm and seed remain unchanged.

In simple mode, reducing the maximum also brings question bounds within the new number line. Range chips apply the settings they display; the 0–100 chip uses labels every five. Advanced mode preserves explicit constraints and explains incompatibilities. Dense labels are never silently dropped.

Production build, locally

npm run build
npm start

Open http://127.0.0.1:3001. The compiled API also serves the built frontend and supports bookmarked SPA routes. PORT=3002 npm start selects another port. Keep packages/shared/fonts beside the app when packaging: export reads these vendored fonts. LESSONLAB_ROOT can identify the repository root if launching outside the npm workspace commands.

The API binds to loopback and has no production authentication. This version is a local application, not an internet-facing multi-user deployment.

Checks

npm run typecheck
npm test
npm run test:e2e
npm run test:production # after npm run build

Browser tests use installed Google Chrome by default. Alternatively:

npx playwright install chromium
PLAYWRIGHT_CHANNEL=chromium npm run test:e2e

Vitest covers arithmetic across hundreds of seeded configurations, unique pools, impossible constraints, ordered labels and tick positions, page geometry, pagination, presets, versioned storage and real exports. PDF tests inspect page count, physical dimensions and font embedding; image tests inspect pixel dimensions. Playwright covers the user journey, downloads, history, preferences, responsive layouts, keyboard interactions and automated WCAG A/AA checks on the five main screens. Automated scans complement, rather than replace, assistive-technology and classroom testing.

Structure

Location	Responsibility
apps/web	React, Router, Zustand, shared controls, discovery, studio and local user state
apps/api	Express, validated generation/export requests and production static serving
packages/core	Generic generator contract, semantic document primitives, physical paper sizes, seeded utilities
packages/generators	Registry, subtraction schema/control metadata, educational presets, content generation and worksheet layout
packages/rendering	One SVG renderer, reusable text/number-line/answer primitives and font measurements
packages/export	Shared SVG → embedded-font vector PDF or high-resolution raster → optional ZIP
packages/persistence	Authentication boundary, repository interfaces, local adapters, versioned history, preferences, drafts and template contract
packages/shared	Vendored font assets, character support and font advance metrics

The pipeline is educational context + content + seed → questions → presentation + physical layout → structured pages → SVG → preview/export. The workspace memoises content separately from layout. The API validates requests again; it never accepts arbitrary SVG from the browser.

Different worksheet types own their content schemas, controls, presets and layout. They opt into shared paper, font and educational preferences. The workspace, drafts, history and API resolve the selected definition. A multiplication test plugin verifies different options and question data through the same infrastructure. See Adding worksheet types for the developer workflow.

See ARCHITECTURE.md for extension points, versioning, deferred work and significant decisions.

Limits and next steps

• One implemented generator, local browser persistence, light theme and two bundled worksheet font families. Clearing browser data removes the local library; downloads are independent files.
• Initial guardrails: 1–100 questions, nonnegative integer number lines up to 500, integer tick/label intervals, and supported printable characters in the selected font. Impossible or illegible combinations are rejected with guidance.
• Templates have a repository contract but no management UI. Authentication, Firestore, sharing, AI interpretation, more generators and historical renderer execution are deliberately deferred.
• Browser exports need the local API. There is no offline export worker, cloud sync, background job queue or public hosting in this version.
• The next practical milestones are a second classroom-ready generator, reusable template management, then Firebase authentication/Firestore with per-user security rules. AI should later produce validated configurations for deterministic plugins.

Font assets are distributed under the SIL Open Font License; licences are in packages/shared/fonts. To change font assets, run npx tsx scripts/font-metrics.ts to sync browser copies and metrics, then bump the renderer/layout version if historical output changes.