@mathscan/geometry-engine 0.1.0

package/README.md

@@ -0,0 +1,1101 @@
+# Geometry Engine
+
+`@mathscan/geometry-engine` is a React + TypeScript library for authoring, rendering, and validating interactive geometry exercises. A teacher defines an exercise (given points, allowed constructions, instruments, and goals); a student constructs figures on an interactive canvas; the engine checks the construction against the goals and produces visual feedback.
+
+- **Konva / react-konva** power the visible canvas, pointer interactions, and the draggable instrument overlays (ruler, set square, protractor).
+- **JSXGraph** is the geometry kernel behind `src/measure/`: projective intersections during answer validation and snapping. No board, no DOM.
+- **Zod** schemas define and validate the exercise and student-state data model, including cross-reference checks (duplicate ids, missing point references, inconsistent goals).
+- **Geometry Engine** itself owns the exercise model, student state, pedagogical rules, tolerances, stores, and visual feedback.
+
+## Status
+
+Version 0.1.0. Publication to the public npm registry is decided
+([ADR 0007](./docs/adr/0007-audience-and-distribution.md)) and has not happened yet; what a release
+promises and what has to be green before one is published are in
+[docs/releasing.md](./docs/releasing.md), and what has changed is in [CHANGELOG.md](./CHANGELOG.md).
+The current feature set:
+
+| Area        | Supported today                                                                                                   |
+| ----------- | ----------------------------------------------------------------------------------------------------------------- |
+| Objects     | `point`, `segment`, `line`                                                                                        |
+| Goals       | `create`, `throughPoints`, `perpendicular`, `parallel`, `segmentLength`, `midpoint` (all tolerances configurable) |
+| Instruments | `ruler`, `setSquare`, `protractor` — **visual aids only**: draggable, rotatable, no mathematical effect           |
+| Modes       | Student solving (`StudentGeometryCanvas`) and teacher authoring (`GeometryCanvas`), both with undo/redo           |
+| Validation  | Structural (Zod) and geometric (JSXGraph kernel) — both run in bare Node, no DOM                                  |
+| Feedback    | Per-goal correct/incorrect status, matched/attempted construction highlighting, answer reveal                     |
+
+Where this is going: [FUTURE.md](./FUTURE.md) is the long-range feature map, [docs/implementation/ROADMAP.md](./docs/implementation/ROADMAP.md) is the executable order, and [docs/adr/](./docs/adr/) records the decisions already made.
+
+### Support matrix
+
+"Verified" means something in the repository proves it on every run. Everything else is marked **unverified** — it is expected to work and nobody has checked.
+
+| Area                  | Support                                                                                                                                                                              | Status                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Node                  | `^20.19.0 \|\| >=22.12.0` (`engines`)                                                                                                                                                | Verified in CI on 20.19.0, 22.12.0, and current LTS                                                                                                                                                                                                                                                                                                                                                                                                  |
+| React                 | `^19.0.0` peer, with `react-dom` `^19.0.0`. **`/react` requires React 19; React 18 is unsupported for now**                                                                          | Unverified below 19.2; React 19 is the only supported major ([ADR 0007](./docs/adr/0007-audience-and-distribution.md))                                                                                                                                                                                                                                                                                                                               |
+| Vitest + jsdom        | `StudentGeometryExercise` mounts and takes Pointer Events with two stubs — [Test a host with Vitest and jsdom](#test-a-host-with-vitest-and-jsdom)                                   | Verified by `pnpm run verify:package`, which runs a Vitest + jsdom suite against the installed tarball. jsdom draws no pixels and hit-tests nothing                                                                                                                                                                                                                                                                                                  |
+| Konva                 | `konva` `^10.3.0` and `react-konva` `^19.2.5`, both peers                                                                                                                            | Unverified against other majors                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| Build output          | ES2020 target; five entry points, each as ESM + `.d.ts` and CJS + `.d.cts`                                                                                                           | Verified by `pnpm run verify:entries`, which loads the built output in both modes                                                                                                                                                                                                                                                                                                                                                                    |
+| Package contents      | `dist`, `package.json`, `README.md` — no tests, sources or dev page                                                                                                                  | Verified by `pnpm run verify:package`, which packs the tarball and consumes it in both module systems                                                                                                                                                                                                                                                                                                                                                |
+| Public API shape      | Signatures and types snapshotted in [etc/api-report.md](./etc/api-report.md)                                                                                                         | Verified by `pnpm run verify:api` on every run                                                                                                                                                                                                                                                                                                                                                                                                       |
+| Bundle size           | Per-entry-point budgets in [etc/bundle-size.json](./etc/bundle-size.json)                                                                                                            | Verified by `pnpm run verify:size`; measurements in [docs/releasing.md](./docs/releasing.md)                                                                                                                                                                                                                                                                                                                                                         |
+| Browsers              | Any browser meeting the ES2020 target with Canvas support                                                                                                                            | Chromium and WebKit verified in CI; **no minimum version is claimed for either** — the support floor is still unchosen                                                                                                                                                                                                                                                                                                                               |
+| Mouse                 | Full: place, drag, connect, select                                                                                                                                                   | Verified in Chromium and WebKit by `tests/e2e/` — place, snap, drag, connect, select, delete                                                                                                                                                                                                                                                                                                                                                         |
+| Touch                 | One Pointer Events lifecycle for mouse, pen and touch since M3.H.4 — 8 px touch / 4 px mouse drag thresholds, full cancellation — with **44 CSS px activation targets** since M3.H.3 | `tests/e2e/touch.spec.ts` and `tests/e2e/gesture-cancellation.spec.ts` on both engines — tap to place, finger-drag to connect and to build on bare canvas, tap to select, drag a given, threshold boundaries, every cancellation trigger, no tap-plus-click duplicate; targets and layout in `tests/e2e/touch-targets.spec.ts` and `tests/dev-page/responsive-hardening.spec.ts` across five emulated profiles; **never exercised on a real device** |
+| Keyboard              | The chrome, not the canvas: arm and cancel a tool, undo, redo, delete, check, reveal                                                                                                 | Verified by `tests/e2e/keyboard.spec.ts` and `tests/a11y/dev-page-keyboard.a11y.spec.ts`. **Placing a figure still needs a pointer** — keyboard construction is a known gap                                                                                                                                                                                                                                                                          |
+| Screen readers        | The **semantic companion**: the figure republished as DOM, announced through one polite live region                                                                                  | Verified by `tests/a11y/dev-page-companion.a11y.spec.ts` — current tool, pending connection, every entity as a sentence, the selection, and the last verdict                                                                                                                                                                                                                                                                                         |
+| Structural validation | Bare Node, no DOM                                                                                                                                                                    | Verified by the unit suite                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| Geometric validation  | Bare Node, no DOM, no global state                                                                                                                                                   | Verified by `tests/measure/serverGrading.test.ts`, which runs with `document` undefined throughout                                                                                                                                                                                                                                                                                                                                                   |
+
+Touch is still the entry most likely to surprise: emulated pointer events and emulated device profiles prove the routing and the measurements, not how the gestures feel in a hand. [docs/accessibility.md](./docs/accessibility.md) § Pointer gestures states the gesture contract. Physical-device testing is deferred by decision, not done. The browser row is the other one — two engines are exercised, but **no minimum version has been chosen for either**, so this table says which engines are tested and not which releases are supported.
+
+## Installation
+
+> **Publication status:** `@mathscan/geometry-engine` is a public npm package by decision
+> ([ADR 0007](./docs/adr/0007-audience-and-distribution.md)), and the first publication has not
+> been made yet. Until it is, install the packed archive; the release checklist is in
+> [docs/releasing.md](./docs/releasing.md).
+
+Once published:
+
+```sh
+pnpm add @mathscan/geometry-engine react react-dom konva react-konva
+```
+
+Until then, build and pack the library:
+
+```sh
+pnpm install
+pnpm build
+pnpm pack
+```
+
+and install the generated `.tgz` archive in the consuming application:
+
+```sh
+pnpm add /path/to/mathscan-geometry-engine-0.1.0.tgz
+```
+
+Either way the consuming application gets the same archive contents — `dist`, `package.json` and
+`README.md`, nothing else — which `pnpm run verify:package` checks on every run.
+
+`react`, `react-dom`, `konva`, and `react-konva` are peer dependencies. `zod` and `jsxgraph` are installed as runtime dependencies.
+
+### Entry points
+
+The package has one root and four subpaths. Three of them load in a bare Node process — no React, no Konva, no DOM — which is what lets a grader import validation without a renderer:
+
+| Import                                 | Contains                                                  | Server-safe |
+| -------------------------------------- | --------------------------------------------------------- | ----------- |
+| `@mathscan/geometry-engine`            | the union of the four below                               | no          |
+| `@mathscan/geometry-engine/core`       | entity model, geometry, coordinates, snapping, the stores | yes         |
+| `@mathscan/geometry-engine/schemas`    | the stored documents, their goals, and their migrations   | yes         |
+| `@mathscan/geometry-engine/validation` | grading, feedback, answer reveal, the measurement seam    | yes         |
+| `@mathscan/geometry-engine/react`      | canvases, shapes, the toolbar, and the store hook         | no          |
+
+Each resolves in both of Node's module systems: `import` gets ESM with `.d.ts` declarations, `require` gets CommonJS with `.d.cts` declarations.
+
+[docs/api-surface.md](./docs/api-surface.md) classifies every export as **stable** or **advanced**, and states what tree-shaking does and does not do for you. It is the semver promise, and `tests/publicSurface.test.ts` parses it, so it cannot drift from the code.
+
+## Architecture
+
+For a plain-language overview, see [How the Geometry Engine Works](./docs/PROJECT_FLOW.md).
+
+The source is organized into small, dependency-directed modules:
+
+```
+src/
+├── index.ts                  Public API surface (everything is exported from here)
+├── geometry/                 Plain geometric types and math (Point, GeometryObject, distances, hit testing)
+├── coordinates/              Screen <-> math coordinate transforms, grid steps, viewport line clipping
+├── schemas/                  Zod schemas: exercise, geometry state, objects, goals, viewport
+│   └── goals/                One schema per goal kind (create, throughPoints, perpendicular, parallel, segmentLength, midpoint), plus each kind's authoring declaration
+├── snapping/                 Where a placed point lands (points, intersections, grid, objects)
+├── state/                    Resolves stored point origins into coordinates
+├── store/                    Framework-agnostic store primitive + teacher and student stores
+├── validation/               Answer checking, exercise validation, feedback derivation
+│   └── goals/                One handler per goal kind (accepts / satisfies / isRelevantAttempt / reveal)
+├── measure/                  The one JSXGraph boundary: kernel.ts (JXG) + geometryAdapter.ts
+└── renderer/                 React/Konva components: canvases, toolbar, grid, instruments
+    └── shapes/               Point, segment, and line Konva shapes
+```
+
+Key design decisions, recorded in full under [docs/adr/](./docs/adr/):
+
+- **Exercise vs. state separation.** `GeometryExercise` (the authored definition) and `GeometryState` (the student's live points and constructions) are distinct types. `createStudentStore()` copies the given point positions into a clean state, so student work never mutates the exercise ([ADR 0001](./docs/adr/0001-exercise-attempt-separation.md)).
+- **Framework-agnostic core.** `createStore()` is a minimal zustand-style store (getState/setState/subscribe) with no React dependency; `useStoreState()` bridges it into React. Geometry math, schemas, and structural validation all run in plain Node.
+- **Pluggable goal kinds.** Each goal type is a `GoalKindHandler` with three responsibilities: `satisfies()` (does a candidate fulfil the goal — a candidate is a construction or a point the student constructed), `isRelevantAttempt()` (should a failed construction be highlighted as an attempt), and `buildRevealedAnswer()` (synthesize a canonical answer shape). Adding a goal kind means adding one schema and one handler.
+- **A single measurement seam.** `src/measure/` is the only module that knows JSXGraph exists; everything else asks for a named measurement and passes plain coordinates ([ADR 0004](./docs/adr/0004-measurement-seam.md), [ADR 0005](./docs/adr/0005-jsxgraph-as-geometry-kernel.md)). Inside the seam the split is again one file deep: `kernel.ts` is the only file that imports JXG, and `geometryAdapter.ts` exposes named measurements built on it.
+- **No board, no global state.** Trivial operations — distance, coincidence, the angle of a line — are plain arithmetic under the numerical policy; only projective meets go to JSXGraph, and those need no board. Grading is a pure function call that runs in bare Node ([ADR 0006](./docs/adr/0006-no-jsxgraph-board.md)).
+- **Renderer-independent transforms.** `coordinates/transform.ts` maps the math viewport (y-up) onto canvas pixels (y-down) with `contain` (angle-preserving, default) or `stretch` projections; both rendering and pointer conversion consume the same placement.
+
+## Core model
+
+- `GeometryExercise` describes the viewport, the authored `entities`, how they are presented, which of them a student may drag, the allowed constructions, instruments, and goals.
+- `GeometryState` holds the student's own `entities` — one record for every kind — plus their `presentation` and `answerEntityIds`, the list of what counts as their answer.
+
+```ts
+import type { GeometryExercise, GeometryState } from '@mathscan/geometry-engine'
+```
+
+### Example exercise
+
+This exercise asks the student to construct segment `AB`:
+
+```ts
+import type { GeometryExercise } from '@mathscan/geometry-engine'
+
+const exercise: GeometryExercise = {
+  schemaVersion: 4,
+  id: 'segment-ab',
+  viewport: [0, 0, 10, 10],
+  showGrid: true,
+  // One record for every kind. v1's `givens[]` held four shapes with four
+  // vocabularies; a v2 entity is `{ kind, ... }` and a point's coordinates are
+  // its origin, not two loose fields.
+  entities: {
+    A: { kind: 'point', at: { x: 2, y: 3 } },
+    B: { kind: 'point', at: { x: 8, y: 3 } },
+  },
+  // How an entity is shown, kept out of what it *is*. A label and a role live
+  // here so that making a point visible never touches its definition.
+  presentation: {
+    A: { role: 'explicit', label: 'A' },
+    B: { role: 'explicit', label: 'B' },
+  },
+  // v1's per-given `draggable` flag. It is a list on the exercise and
+  // unrepresentable in an attempt, so a tampered attempt cannot declare a
+  // pinned given draggable and move what its own goals are measured against.
+  draggableEntityIds: [],
+  allowedObjects: ['segment'],
+  tools: ['ruler'],
+  goals: [
+    {
+      id: 'goal-ab',
+      type: 'throughPoints',
+      objectType: 'segment',
+      pointIds: ['A', 'B'],
+    },
+  ],
+}
+```
+
+Supported objects are `point`, `segment`, `line`, and `circle`. A circle is stored as
+`{ id, type: 'circle', center, through }` — the id of its centre point and the id of a point it
+passes through. Its radius is measured from those two on every evaluation and never stored, so
+dragging either one changes the circle and everything built on it. There is no compass tool and no
+circle goal kind yet: a circle can be authored as a given, persisted in an attempt, resolved,
+intersected, snapped to and drawn, which is what M2.8 landed. Supported goal kinds are currently `create`, `throughPoints`, `perpendicular`, `parallel`, `segmentLength`, and `midpoint`.
+
+A `perpendicular` or `parallel` goal names a reference object, a point the construction must pass through, and an angle tolerance in degrees. A `segmentLength` goal names a `targetLength`, and a `midpoint` goal names the reference segment; both take a `toleranceUnits` expressed in viewport units, not pixels. Because a parallel through a point that defines the reference is degenerate (redrawing the reference would be a correct answer), the exercise schema rejects that combination.
+
+## Hit testing
+
+`hitTest()` answers "what is under the pointer" in math space, with no renderer involved:
+
+```ts
+import { deriveStudentRenderableGeometry, hitTest } from '@mathscan/geometry-engine'
+
+// Coordinates are derived, never stored, so the scene comes from resolving the
+// exercise and the attempt together. `RenderableGeometry` is already
+// `{ points, objects }`, which is exactly what `hitTest()` takes.
+const scene = deriveStudentRenderableGeometry(exercise, geometry)
+
+const hits = hitTest({ x: 2, y: 1.05 }, scene, 0.3)
+// [{ id: 'P1', type: 'point', distance: 0.05 }, { id: 'ab', type: 'segment', distance: 0.28 }]
+```
+
+Results are ranked points first, then segments, then lines, and by distance within a kind — a small target that is harder to hit deliberately wins over a large one nearby. `firstHit()` returns the top result or `null`. Options are `exclude` (ids that can never be hit, such as the point a connection started from) and `types` (restrict the answer to certain kinds).
+
+The tolerance is a math-space distance, deliberately independent of how thick the object is drawn: on touch devices the finger target must be much larger than the stroke. Convert a pixel radius through the viewport placement:
+
+```ts
+import {
+  CONNECTION_SNAP_RADIUS_PX,
+  computePlacement,
+  screenLengthToMath,
+} from '@mathscan/geometry-engine'
+
+const placement = computePlacement(exercise.viewport, canvas)
+const tolerance = screenLengthToMath(CONNECTION_SNAP_RADIUS_PX, placement)
+```
+
+`distancePointToSegment()` and `distancePointToLine()` are exported for direct use; both are pure math-space functions.
+
+## Numerical policy
+
+Every epsilon that governs a geometric decision is named once, in `src/numerics/policy.ts`, and
+exported. Nothing else in the engine writes a numeric literal as a tolerance. The module separates
+three things that are easy to confuse:
+
+| Kind                      | Examples                                                                                | Who sets it                                 |
+| ------------------------- | --------------------------------------------------------------------------------------- | ------------------------------------------- |
+| **Calculation epsilon**   | `CALCULATION_EPSILON`, `COORDINATE_EPSILON`, `PARAMETER_EPSILON`, `POINT_REUSE_EPSILON` | the engine — a property of IEEE 754         |
+| **Grading tolerance**     | `toleranceUnits`, `toleranceDegrees` on a goal                                          | the author, in the exercise                 |
+| **Interaction tolerance** | `PLACEMENT_SNAP_RADIUS_PX`, `CONNECTION_SNAP_RADIUS_PX`                                 | the engine, in pixels, converted per canvas |
+
+Grading never consults a global tolerance: the only constant it may add to an authored tolerance is
+`GRADING_BOUNDARY_EPSILON`, so an answer exactly on the boundary is not rejected by floating-point
+noise. Degeneracy is measured relative to the size of the object it is asked about
+(`isDegenerateAtScale`) rather than against a fixed size, so the same construction behaves the same
+way whether it is drawn in thousandths or in thousands.
+
+The policy is exercised by property-based tests (`fast-check`, in `tests/numerics/`) covering
+distance as a metric, endpoint-order invariance, transform round trips, translation and rotation
+invariance, on-object snaps lying on their target, intersections lying on both parents, and segment
+parameters staying in `[0, 1]` — at three coordinate scales. Runs are seeded, so a failure prints a
+replay seed; set `FC_SEED` to reproduce one and `FC_RUNS` to soak locally. Counterexamples the
+properties have already found are pinned as ordinary tests in `tests/numerics/regressions.test.ts`.
+
+## Point origins and the dependency graph
+
+A point in `GeometryState` stores _why_ it is where it is, not a frozen pair of coordinates:
+
+| Origin                             | Meaning                                                                                         |
+| ---------------------------------- | ----------------------------------------------------------------------------------------------- |
+| `{ x, y }`                         | free — the point is simply there                                                                |
+| `{ onObject: 'ab', t }`            | on an object, at parameter `t` along its two defining points (`0` is the first, `1` the second) |
+| `{ intersectionOf: ['ab', 'cd'] }` | where two objects cross                                                                         |
+
+On a circle, `t` is a **turn** rather than a run between two points: `0` is the point at angle zero
+from the centre, `0.25` a quarter turn counterclockwise, and `1` a full turn, so every value is on
+the circle and `t` and `t + 1` name the same place. It is measured from the positive x-axis and not
+from the circle's own through-point, so that two definitions of the same circle put a point at `t`
+in the same place.
+
+Two objects can cross twice — a line and a circle, or two circles — so
+`{ intersectionOf: ['c1', 'c2'], which: 1 }` selects the second crossing. Crossings are ordered by
+coordinate rather than by whatever order the operands were given in, so a stored `which` still names
+the same point after an author reverses a line's two points.
+
+Coordinates are always derived, never stored alongside, so no cached copy can go stale:
+
+```ts
+import { resolvePoints } from '@mathscan/geometry-engine'
+
+const points = resolvePoints(exercise, geometry) // Map<PointId, Point>
+```
+
+Dragging a given point therefore moves everything built on it. A point that cannot be resolved — its object was deleted, its two objects became parallel so the crossing vanished, or its origins form a cycle — is simply **absent** from the map. Callers read that as "not on screen": renderers skip it, validation neither counts it as an answer nor reports it as an attempt. Nothing throws, because a student mid-construction is allowed to have a figure that briefly makes no sense.
+
+An unresolved point is **not** discarded. Its origin stays in the document, so it comes back the
+moment its parents make sense again: drag two parallel objects back across each other and the
+intersection point returns, keeping its id and everything built on it. Only an explicit deletion
+removes anything, and that takes the dependent closure with it.
+
+This is one-directional derivation (parents → children), not a constraint solver: nothing maintains a relationship _while_ the student drags, which would solve the exercise for them ([ADR 0002](./docs/adr/0002-one-way-dependency-graph.md), [ADR 0003](./docs/adr/0003-derived-point-origins.md)).
+
+Consequences elsewhere in the API:
+
+- `addStudentPoint(store, origin)` takes an origin. `{ x, y }` is still valid — that is a free point — while snapped placement passes `{ onObject, t }` or `{ intersectionOf }`.
+- `moveStudentPoint()` respects what the point is: a free point takes the new coordinates, an on-object point slides along its object (the drag re-parameterizes rather than detaching it), and an intersection point ignores the drag entirely. `isStudentPointDraggable()` reports which.
+- `getStudentRemovalImpact()` returns `{ constructionIds, pointIds }` and runs the cascade to a fixed point in both directions: deleting a segment can strip an intersection point built on it, which strips a construction that used that point, and so on. Given points are never removed.
+- Validation resolves before checking, so a goal is judged on where the figure actually is.
+
+## Save and restore an attempt
+
+A `GeometryState` carries its own `schemaVersion`, so a stored attempt can be restored later — resume after a refresh, teacher review, analytics:
+
+```ts
+import {
+  createStudentStore,
+  serializeGeometryState,
+  validateGeometryStateJson,
+} from '@mathscan/geometry-engine'
+
+// Save
+const saved = serializeGeometryState(store.getState().geometry)
+
+// Restore, checked against the exercise it belongs to
+const restored = validateGeometryStateJson(saved, exercise)
+if (restored.success) {
+  const store = createStudentStore(exercise, restored.data)
+}
+```
+
+`validateGeometryStateJson()` is the counterpart to `validateGeometryExerciseJson()`: it parses the JSON, migrates the document to the current version, checks its structure, and — when given the exercise — checks it against that exercise (given points present, only allowed object types, point origins naming objects that exist). Every failure comes back as errors; nothing throws. A resumed store starts with empty undo history, since undo must not reach back past what the student can see.
+
+### Versions and migration
+
+**The two documents version independently.** The exercise is at version **4** and the attempt is at version **2**. A v2 attempt is loaded and graded against a v4 exercise, and neither version implies the other. Version 3 exists for one optional field, `grading` (see [Strict grading](#strict-grading) below). Version 4 exists for one optional field, `solution`, the authored canonical attempt (see [Reveal answers](#reveal-answers)). An older exercise carrying a field added after its version is refused rather than promoted. An older reader rejects a newer exercise at its own version boundary rather than reading a field it does not understand.
+
+Both stored documents carry a `schemaVersion`, and both are migrated the same way. An exercise migrates through `geometryExerciseMigrations` up to `latestGeometryExerciseVersion`; an attempt through `geometryStateMigrations` up to `latestGeometryStateVersion`. Each list holds one step per version hop, walked in chain order by `applyMigrations()`, so a document three versions old takes three steps and each step only has to know about its own neighbour.
+
+**When migration runs.** On the way in, and only there: `validateGeometryExercise()`, `validateGeometryExerciseJson()`, `validateGeometryStateInput()` and `validateGeometryStateJson()` all migrate before they check structure, so an older stored document loads instead of failing as malformed. Nothing migrates on the way out.
+
+**Whether it mutates the input.** No. `applyMigrations()` builds a new document and never writes to the one it was handed, so the object you pass in is the object you still have afterwards. It does not deep-copy either: parts of a migrated document may be the same objects as parts of the input, so treat the input as read-only once you have migrated it.
+
+**Failure is a message, never a throw.** A step that trips over a shape it did not expect is caught, and every migration-stage refusal is reported as an ordinary validation error under the `schemaVersion` path, with a message naming the version and the field at fault — suitable to log as-is.
+
+**A newer document is refused, not downgraded.** Guessing which fields to drop would silently destroy student work, so there is no backward migration and none is planned. A document whose `schemaVersion` is newer than the code loading it fails validation with a message naming both versions — a refusal you can log and act on, never a partial load.
+
+**Rollback and backups are the host's, and this is the only place they can be taken.** The package migrates in memory and writes nothing: loading a v1 document does not change what is in your database. The old version stops existing at the _next save_, when a store that was seeded from a migrated document is serialized back over it. So the expectations are:
+
+- **Keep the bytes you were handed, before you migrate them.** The raw JSON string as it came out of storage is the backup; take it there rather than from the parsed object, because `applyMigrations()` does not deep-copy and a migrated document may share sub-objects with its input.
+- **Write the backup before the first save of a migrated document,** not before the load. A read-only session — grading, review, rendering a past attempt — migrates on the way in and never persists, so it needs no backup at all.
+- **Keep it for as long as your rollback window.** Downgrading the package is only safe while a pre-migration copy of every document written by the newer one still exists; a v2 document handed back to a build that only knows v1 is refused, so a rollback without backups leaves those attempts unreadable rather than corrupted.
+- **Migrate once, then store the result.** Re-migrating an already-current document is a no-op — `applyMigrations()` walks zero steps — so a backfill that migrates and saves every document is safe to re-run, and turns the rollback window into a decision you make once instead of per student.
+
+Restoring a backup is a plain overwrite: the older document loads and migrates again exactly as it did the first time, because migration is a pure function of the stored bytes.
+
+**Serialization always emits the current version.** `serializeGeometryState()` writes the document it is given, and a document only reaches it through a loader or a store — both of which produce the current version. There is no way to ask the package for an older one.
+
+## Snapping
+
+Both canvases snap a placed point instead of taking the raw pixel, so clicking near a landmark lands on exact coordinates. `computeSnap()` decides where:
+
+```ts
+import { computeSnap } from '@mathscan/geometry-engine'
+
+const snap = computeSnap(
+  pointerInMathSpace,
+  { points, objects, viewport: exercise.viewport, showGrid: exercise.showGrid },
+  { tolerance },
+)
+// { position: { x: 2, y: 2 }, kind: 'intersection', targetIds: ['ab', 'cd'], distance: 0.14 }
+```
+
+Four kinds, in priority order — the strongest kind with a candidate in range wins outright, so a nearby existing point is never passed over for a marginally closer grid crossing:
+
+| Kind           | Snaps to                                              |
+| -------------- | ----------------------------------------------------- |
+| `point`        | an existing point, given or constructed               |
+| `intersection` | where two objects cross, even with no point there yet |
+| `grid`         | a grid crossing, only when the grid is shown          |
+| `onObject`     | the nearest place on a segment or line                |
+
+`snapPosition()` is the convenience form, returning the pointer unchanged when nothing is in range. `exclude` skips ids (the point being dragged), `kinds` restricts which rules apply. Intersections come from `intersectionsOf()` in the JSXGraph adapter — real geometry rather than coordinate arithmetic — but that call needs no validation board, which is what makes it affordable on every pointer move.
+
+In the renderer, `usePlacementSnap()` tracks the pointer while the point tool is armed and resolves a click to its snapped position; `SnapMarker` draws where the point would land, since a silent snap reads as a bug.
+
+`originForSnap()` turns a snapped placement into the origin to store — which is what makes snapping structural rather than cosmetic. Snapping to an intersection records `{ intersectionOf }`, so the point _is_ the crossing and follows it; snapping onto an object records `{ onObject, t }`. It returns `null` when the pointer landed on an existing point, because stacking a second point there would be a duplicate rather than an answer. The student canvas also passes `createPoint` to `useConnectionPreview`, so a segment can end on an intersection that has no point yet: the point is created with that origin mid-gesture and immediately connected.
+
+## Validate exercise data
+
+Use the safe validation facade for data loaded from JSON, an API, or another untrusted source:
+
+```ts
+import { validateGeometryExerciseJson } from '@mathscan/geometry-engine'
+
+const validation = validateGeometryExerciseJson(json)
+
+if (!validation.success) {
+  console.error(validation.errors)
+} else {
+  console.log(validation.data)
+  console.log(validation.warnings)
+}
+```
+
+- `validateGeometryExercise(input)` validates an unknown value without throwing.
+- `validateGeometryExerciseJson(json)` parses and validates a JSON string.
+- `parseGeometryExercise(input)` returns a typed exercise or throws a Zod error.
+- `getGeometryExerciseWarnings(exercise)` reports pedagogical issues that are legal but suspicious.
+- Unknown properties, duplicate identifiers, duplicate geometry, missing references, and inconsistent goals are rejected by the schema's cross-reference checks.
+- **Entity ids: `__proto__` is the only name refused.** Every other id is legal, `constructor`, `toString`, `valueOf` and `hasOwnProperty` included — every record read is an own-property read, so an id that happens to name a JavaScript built-in resolves, renders and grades like any other. `__proto__` is refused, at parse for a v2 document and during migration for a v1 one, because no JavaScript object can carry it as an entry: a stored document naming it now fails to load with a message and a path, where it previously loaded one entity lighter and said nothing. If you read an `entities` or `presentation` record yourself, use the exported `entryOf(record, id)` rather than `record[id]` — a bare index answers for `constructor` with a function off the prototype chain.
+
+Structural validation works without a canvas and can run in Node.js.
+
+## Embed a student exercise
+
+`StudentGeometryExercise` is the whole student side in one component: tools, Undo, Redo, Delete,
+Reset, the construction notice, a canvas that fills its container's width and follows it as it
+resizes, and the semantic companion. Your application keeps Check, Reveal, saving and the wording of
+results.
+
+```tsx
+import { StudentGeometryExercise } from '@mathscan/geometry-engine/react'
+import type { GeometryState } from '@mathscan/geometry-engine/schemas'
+import { checkGeometryAnswer } from '@mathscan/geometry-engine/validation'
+import { useState } from 'react'
+
+function Exercise({ exercise, saved }: { exercise: unknown; saved?: GeometryState }) {
+  const [attempt, setAttempt] = useState(saved)
+  const [checked, setChecked] = useState<ReturnType<typeof checkGeometryAnswer> | null>(null)
+
+  return (
+    <>
+      <StudentGeometryExercise
+        exercise={exercise}
+        value={attempt}
+        // Hand the attempt straight back: an echo keeps Undo. `meta.action` says
+        // what the student did, for a sound or an effect.
+        onChange={(next) => setAttempt(next)}
+        validationFeedback={checked}
+      />
+      <button onClick={() => setChecked(checkGeometryAnswer(exercise, attempt))}>Check</button>
+    </>
+  )
+}
+```
+
+- **Controlled.** `exercise` and `value` are untrusted and parsed on every render. Both are compared
+  by content, so a copy or a JSON round trip of the attempt you were given is recognized as the same
+  value, and an object you edit in place is seen. A different value replaces the attempt, and a
+  different exercise starts a new session. Neither calls `onChange`, and both clear Undo and cancel a
+  gesture in progress. A change to the exercise's `solution` alone is not a new exercise. An absent
+  `value` (`undefined` or `null`) is a fresh attempt.
+- **A new value is one that differs from the last one you passed.** Passing back the attempt
+  `onChange` gave you is how the component stays in step. A host that never does cannot reset by
+  passing the same empty attempt again: use Reset, or pass a changed value.
+- **`onChange`** fires once per completed student action, with `{ action, entityIds }`, and never for
+  drag frames. It receives a copy, so editing it does not touch the component. A refused duplicate is
+  not a change: it is shown, and reported to `onNotice`.
+- **`validationFeedback`** takes the whole `checkGeometryAnswer()` result. It is shown only while the
+  exercise and attempt still match what was checked, so an edit hides it immediately.
+- **`readOnly`** locks the attempt in the store, not only in the controls; replacing `value` still
+  works. `controls={{ toolbar, history, delete, reset }}` hides built-in controls you replace with
+  your own.
+- **Invalid input** shows an alert, calls `onError` once per distinct list of issues, and leaves the
+  current session untouched. The built-in wording is English.
+- Every mounted component has its own store. Size it with CSS on `className`; the canvas takes the
+  full width at the exercise viewport's aspect ratio.
+
+### Test a host with Vitest and jsdom
+
+jsdom has no canvas backend and no layout, and the component needs both: Konva draws through
+`getContext('2d')`, which jsdom answers with `null`, and the canvas is sized by a `ResizeObserver`,
+which jsdom does not implement. Add a setup file with two stubs:
+
+```js
+// vitest.config.js: test: { environment: 'jsdom', setupFiles: ['./vitest.setup.js'] }
+
+HTMLCanvasElement.prototype.getContext = function getContext() {
+  const context = {
+    canvas: this,
+    measureText: () => ({ width: 0 }),
+    getImageData: () => ({ data: [] }),
+    createLinearGradient: () => ({ addColorStop() {} }),
+    createRadialGradient: () => ({ addColorStop() {} }),
+    createPattern: () => null,
+  }
+  // Anything else Konva calls becomes a no-op the first time it is read.
+  return new Proxy(context, {
+    get: (target, property) =>
+      property in target || typeof property !== 'string'
+        ? target[property]
+        : (target[property] = () => {}),
+  })
+}
+
+globalThis.ResizeObserver = class ResizeObserver {
+  constructor(callback) {
+    this.callback = callback
+  }
+  observe(target) {
+    this.callback([{ target, contentRect: { width: 400, height: 300 } }], this)
+  }
+  unobserve() {}
+  disconnect() {}
+}
+
+globalThis.IS_REACT_ACT_ENVIRONMENT = true
+```
+
+With it, the component mounts, its buttons work, and Pointer Events dispatched on its
+`.konvajs-content` element reach the gesture lifecycle; jsdom lays the stage out at the origin, so
+`clientX` and `clientY` are stage pixels. Two limits: nothing is drawn, and Konva's hit canvas finds
+nothing, so **every press lands on bare canvas** — a press cannot select or drag a drawn point. Test
+those in a real browser. `tests/consumer/` runs exactly this setup against the packed package on
+every `pnpm run check`.
+
+Run these tests with `NODE_ENV` unset or `test`, never `production`. Under `production`, Vite
+resolves the jsdom environment like a browser build, so `node:` imports fail to load, and React's
+production build has no `act()`.
+
+## Render a student exercise
+
+For a composition of your own, create one student store per attempt and pass it to the student
+canvas:
+
+```tsx
+import {
+  createStudentStore,
+  selectStudentObjectType,
+  StudentGeometryCanvas,
+  Toolbar,
+  useStoreState,
+  type GeometryExercise,
+} from '@mathscan/geometry-engine'
+import { useState } from 'react'
+
+function StudentExercise({ exercise }: { exercise: GeometryExercise }) {
+  const [store] = useState(() => createStudentStore(exercise))
+  const state = useStoreState(store)
+
+  return (
+    <>
+      <Toolbar
+        selected={state.pendingObjectType}
+        available={exercise.allowedObjects}
+        onSelect={(type) => selectStudentObjectType(store, type)}
+      />
+      <StudentGeometryCanvas store={store} size={{ width: 720, height: 540 }} />
+    </>
+  )
+}
+```
+
+`createStudentStore()` starts a clean `GeometryState`; the student's work stays separate from the exercise definition. Store actions include `addStudentPoint`, `moveStudentPoint`, `pickStudentPoint` (two picks connect a segment or line), `promoteStudentPoint`, and `selectStudentObjectType`.
+
+### One gesture, one command
+
+`executeConstruction(store, { tool, from, to })` is the single path from a gesture to geometry, and each end of it is either a point that already exists or an origin to build one from:
+
+```ts
+executeConstruction(store, {
+  tool: 'segment',
+  from: { kind: 'existing', id: 'A' },
+  to: { kind: 'create', origin: { kind: 'point', intersectionOf: ['ab', 'cd'] } },
+})
+```
+
+Three rules follow from that, and all three are visible to a host ([RFC 0001](./docs/rfc/0001-generalized-construction-architecture.md) § 11):
+
+- **One gesture is one commit, so one undo.** Every entity the command needs is written together. A segment that had to invent its endpoint still costs the student a single undo, and undoing it takes the invented point with it.
+- **An invented endpoint is not the answer.** It is written `role: 'implicit'` and left out of `answerEntityIds`, so a `create` goal is never satisfied by scaffolding the student did not choose to make. It is still a real graph node and still a snap target, so the next shape drawn from there shares the vertex rather than stacking a second point on it.
+- **Endpoints are the engine's problem.** A segment or line can be drawn on an empty canvas; nothing has to be placed first. `promoteStudentPoint()` later makes a hidden endpoint visible — one field, `role: 'explicit'`, with the point's id, origin and candidacy untouched.
+
+**A construction that is already there is not built twice** ([RFC 0004](./docs/rfc/0004-core-workflow-hardening.md) § Decision 1). Sameness is the entity kind's own `identityKey` — the comparison the schema's duplicate check uses — so drawing B→A repeats A→B, a line on the same points is a different construction, and two points that only happen to coincide are two points. A student's work is compared with the student's own work, never with the givens. A refused command changes nothing, costs no undo and keeps the redo stack; instead `state.constructionNotice` becomes `{ code: 'duplicate-construction', entityId }`, naming what is already there, for the host to say in its own words. The next creation attempt, a tool change, an undo or a redo clears it. Standalone point additions return the existing point's id in the same case.
+
+`executeGivenConstruction()` is the authoring equivalent on the teacher store, with one deliberate difference: a teacher endpoint that snaps to a crossing is stored as a free point at that position, because authoring derived givens is not yet an editor affordance.
+
+### Undo, redo, and deletion
+
+Every change to the student's geometry is a history entry: `undoStudentChange()` and `redoStudentChange()` walk `past`/`future` snapshots of `GeometryState`, and any new work clears the redo stack. Consecutive moves of the same point collapse into one entry so a drag costs one undo instead of one per pointer event; a renderer calls `endStudentPointDrag()` on drag end to close that window (`StudentGeometryCanvas` already does, and does so too when a drag is cancelled — the point keeps its last position and one undo takes it back).
+
+**History is capped at 100 entries**, in both stores. A snapshot is structurally shared — the entity definitions inside it are the same objects the live document holds — so an entry costs one record slot per entity rather than a deep copy, but it is not free and nothing used to release one. The 101st edit drops the oldest, so undo depth is finite. Why snapshots rather than inverse commands, and why the cap, are [ADR 0009](./docs/adr/0009-construction-commands-and-provenance.md) § Q3.
+
+**`resetStudentAttempt(store)` starts the attempt over** ([RFC 0004](./docs/rfc/0004-core-workflow-hardening.md) § Decision 2). The exercise and its givens stay; the student's constructions go, a given they dragged returns to where the teacher put it, and the tool, the selection, a pending endpoint and the construction notice are cleared. A resumed attempt resets to empty, not to what was saved. It is **not undoable** — both history stacks are emptied, so neither Undo nor Redo brings the old attempt back — and it keeps the store object, so the canvas and every other subscriber stay wired. It never touches a saved copy: saving is the host's, and so is deleting one. The interaction epoch moves even on an attempt that was already empty, which is how a mounted canvas drops a gesture in flight. **The host rule:** checked feedback describes the geometry it was made on, so clear it — and whatever goal it focused — whenever `geometry` or `interactionEpoch` changes; that is what clears a stale check after a reset with nothing to reset. Replacing the store, the older way to restart, still works, but it drops every subscription with it.
+
+`selectStudentObject(store, id)` selects a construction or a student point — `StudentGeometryCanvas` wires this to taps and draws the selection — and `deleteStudentObject(store, id)` removes it. Deleting a point also removes every construction built on it; `getStudentRemovalImpact(state, id)` reports that cascade first, so the application can confirm before deleting. Given points and given objects belong to the exercise and are never deletable (`isStudentOwned(state, id)` is the test).
+
+The exercise's `tools` render as draggable, rotatable instrument overlays (`GeometryInstruments`) on top of the canvas.
+
+**Instruments are visual aids with no mathematical effect.** The ruler, set square, and protractor
+are pictures the student can move and rotate. They constrain nothing, measure nothing, snap to
+nothing, and are invisible to validation — listing a tool in `tools` decorates the canvas, it does
+not require the tool's use. No goal can express "construct this with the compass", and no check can
+tell whether an instrument was touched. Functional instruments, including the missing compass, are
+deferred beyond the focused Milestone 3.
+
+## Check a student's answer
+
+`checkGeometryAnswer()` validates both inputs before evaluating the goals:
+
+```ts
+import { checkGeometryAnswer } from '@mathscan/geometry-engine'
+
+const checked = checkGeometryAnswer(exercise, store.getState().geometry)
+
+if (!checked.success) {
+  console.error(checked.errors)
+} else {
+  console.log(checked.data.result.status) // "correct" or "incorrect"
+  console.log(checked.data.goals) // matches used by visual feedback
+}
+```
+
+### Why an answer is wrong
+
+`checkGeometryAnswerDetailed()` takes the same untrusted inputs and reports the reasoning behind the
+verdict, as stable codes rather than prose:
+
+```ts
+import { checkGeometryAnswerDetailed } from '@mathscan/geometry-engine/validation'
+
+const checked = checkGeometryAnswerDetailed(exerciseJson, attemptJson)
+
+if (!checked.success) {
+  // 'invalid-exercise' or 'invalid-attempt' — a malformed document, not a wrong answer.
+  console.error(checked.errors.map((issue) => issue.code))
+} else {
+  for (const goal of checked.data.goals) {
+    // 'goal-satisfied' | 'goal-not-satisfied' | 'unresolved-candidate' | 'no-candidate',
+    // with the entity ids behind each: matched, relevant, unresolved.
+    console.log(goal.id, goal.code, goal.matchedEntityIds)
+  }
+  // Whole-report notes: 'no-goals', 'unresolved-entity', 'extra-objects'.
+  console.log(checked.data.diagnostics)
+}
+```
+
+`checked.data.feedback` is exactly what `checkGeometryAnswer()` returns, so a host can adopt the
+report without changing what it already draws. The codes are language-neutral by design: the wording
+shown to a student belongs to the application. `evaluateGeometryStateDetailed(exercise, geometry)` is
+the same report for already-typed documents. Numerical deviations ("out by 3°") are not part of this
+vocabulary.
+
+### Starting an attempt and knowing whether it has work
+
+Both check functions also return `fingerprints` on success: opaque strings describing the normalized
+exercise and attempt that were graded. Keep the whole result together; the engine uses them to hide
+feedback once the student's attempt no longer matches it. Do not parse or compare them yourself.
+
+```ts
+import { createEmptyGeometryAttempt, hasGeometryWork } from '@mathscan/geometry-engine/validation'
+
+const attempt = savedAttemptJson ?? createEmptyGeometryAttempt() // a fresh object every call
+
+// A "not started" hint, never a grade: true once the attempt holds any student entity,
+// including a moved given; false for empty, reset or malformed input.
+const started = hasGeometryWork(attempt)
+```
+
+`hasGeometryWork()` reads no exercise, so a stored version-1 attempt that still re-declares pinned
+givens counts as work.
+
+### Strict grading
+
+By default an answer object no goal needed costs nothing: the attempt is correct if every goal is.
+An exercise can ask for the opposite:
+
+```ts
+import { setExtraObjectPolicy } from '@mathscan/geometry-engine'
+
+setExtraObjectPolicy(teacherStore, 'reject') // stores grading: { extraObjects: 'reject' }
+setExtraObjectPolicy(teacherStore, 'allow') // removes the field again
+```
+
+The field is optional and **absence means `allow`**, so an exercise authored before this existed
+grades as it always did. Under `reject` the engine starts from the ids in `answerEntityIds` that the
+attempt owns, subtracts every entity that satisfies some goal and, transitively, everything those
+entities are built on, and reports what is left as `extraEntityIds` with an `extra-objects`
+diagnostic. A non-empty list makes the verdict `incorrect` while each goal keeps its own status —
+"the goals are met and something unused is still on the canvas" is a distinct outcome, and a host
+should say so rather than blame a goal.
+
+What is never an extra: a given, an engine-invented endpoint, an implicit or promoted entity outside
+`answerEntityIds`, and any entity a satisfied answer is built on, however deep and however the
+student created it. What is: an entity the attempt names as an answer and nothing needed —
+including one that no longer resolves. The policy does not count answers, so two correct segments
+for one goal are both matches. Reveal adds the canonical answer and deletes nothing, so a strict
+recheck after a reveal stays incorrect until the extra object is removed.
+
+`extraEntityIds` is reported under both policies; only `reject` files the diagnostic and changes the
+verdict.
+
+The lower-level APIs are also available:
+
+- `validateGeometryStateInput(geometry, exercise)` validates student data only.
+- `validateGeometryState(exercise, geometry)` evaluates already-typed data and returns the plain result.
+- `evaluateGeometryState(exercise, geometry)` also returns construction and point matches for visual feedback.
+- `deriveGeometryCanvasFeedback(feedback, geometry, focusedGoalId)` converts evaluation output for a custom renderer.
+
+### Geometric validation needs no DOM
+
+Geometry Engine selects candidate constructions and applies the exercise rules and configured tolerances (for example, `toleranceDegrees` on a `perpendicular` or `parallel` goal). Distance and angle comparisons are plain arithmetic under the [numerical policy](#numerical-policy); intersections go to the JSXGraph kernel, which needs no board and therefore no container element.
+
+**Validation — structural and geometric — runs in a bare Node process.** No DOM, no jsdom, no global state, and no rule about import order. Grading is a pure function call: it can be interleaved, called concurrently, and needs nothing freed afterwards. Earlier development builds ran geometric checks on a hidden JSXGraph board and needed jsdom on the server; that board is gone — see [ADR 0006](./docs/adr/0006-no-jsxgraph-board.md).
+
+### Grading on a server
+
+```ts
+import { checkGeometryAnswer } from '@mathscan/geometry-engine/validation'
+
+export function gradeAttempt(exerciseJson: unknown, attemptJson: unknown) {
+  const checked = checkGeometryAnswer(exerciseJson, attemptJson)
+  if (!checked.success) return { ok: false as const, errors: checked.errors }
+  return { ok: true as const, result: checked.data.result }
+}
+```
+
+That is the whole setup. Both arguments are untrusted JSON: `checkGeometryAnswer()` validates structure before any geometry runs, so malformed input comes back as errors rather than throwing. Importing `/validation` rather than the root is what keeps React and Konva out of the server build; `scripts/verify-entry-points.mjs` loads the built entry point in a bare Node process and fails if either becomes reachable. `tests/measure/serverGrading.test.ts` runs this exact path on every test run, asserting that `document` is undefined before the import, after it, and after grading.
+
+## Display validation feedback
+
+Pass the output of `evaluateGeometryState()` or the successful `checkGeometryAnswer()` result back to the student canvas:
+
+```tsx
+const checked = checkGeometryAnswer(exercise, store.getState().geometry)
+const feedback = checked.success ? checked.data : null
+
+<StudentGeometryCanvas
+  store={store}
+  size={{ width: 720, height: 540 }}
+  validationFeedback={feedback}
+  focusedGoalId="goal-ab"
+/>
+```
+
+Matching constructions are displayed as correct. Relevant unsuccessful attempts can be highlighted as incorrect.
+
+The verdict never rides on colour alone: correct work is drawn solid and
+incorrect work dashed, and every point the check touched gains a ring around
+it, so the three states — unchecked, correct, incorrect — differ in shape as
+well as in colour.
+
+## Teacher authoring
+
+Teacher mode edits the `GeometryExercise` itself:
+
+```tsx
+import { createTeacherStore, GeometryCanvas } from '@mathscan/geometry-engine'
+
+const teacherStore = createTeacherStore(exercise)
+
+<GeometryCanvas store={teacherStore} size={{ width: 720, height: 540 }} />
+```
+
+The teacher store exposes actions for points, segments, lines, goals, tools, selection, removal, and undo/redo (`undoTeacherChange` / `redoTeacherChange`, backed by past/future exercise snapshots). Point names are generated in spreadsheet order (`A`, `B`, …, `Z`, `AA`, …). Removing a given reports its impact first (`GivenRemovalImpact`: dependent objects and goals), so an application can confirm cascading deletions. `GeometryCanvas` handles the figure; an application can build its own surrounding authoring interface with these actions.
+
+## Reveal answers
+
+An exercise at version 4 can embed its authored canonical answer as `solution`, an ordinary attempt document. `revealGeometryAttempt()` is synchronous, needs no DOM and accepts untrusted JSON. It returns that attempt only when the solution is valid and correct for the exercise, so the host can replace the student's value with it:
+
+```ts
+import { revealGeometryAttempt } from '@mathscan/geometry-engine/validation'
+
+const revealed = revealGeometryAttempt(exerciseJson)
+
+if (revealed.success) {
+  saveAttempt(revealed.data) // replaces the student's attempt; nothing is merged
+} else {
+  // 'invalid-exercise' | 'invalid-canonical-attempt' | 'canonical-attempt-incorrect'
+  console.warn(revealed.errors.map((error) => error.code))
+}
+```
+
+A missing solution and a malformed one are both `invalid-canonical-attempt`. A malformed solution's error paths start at `solution`. A solution that is valid but fails the exercise's goals, or its strict extra-object policy, is `canonical-attempt-incorrect`. The solution is client-visible and is not a secret. Checking ignores it: a malformed solution never fails a check, and changing the solution changes neither the result nor its fingerprints. A student store is always given the exercise without it. `validateGeometryExercise()` validates the whole document instead, so an authoring tool learns about a broken solution when it saves.
+
+The older, goal-synthesized path stays available for advanced callers. It generates one possible answer per goal rather than reading an authored one:
+
+```ts
+import { revealGeometryAnswers, revealStudentAnswer } from '@mathscan/geometry-engine'
+
+const answers = revealGeometryAnswers(exercise)
+const answer = answers.find((item) => item.id === 'goal-ab')
+
+if (answer?.shape) {
+  revealStudentAnswer(store, answer.shape)
+}
+```
+
+Each goal handler can synthesize a canonical answer shape — a segment, a line, or a point. For example, the `perpendicular` handler builds a perpendicular through the goal point and picks the direction that stays most visible inside the viewport (the `parallel` handler does the same along the reference direction), and the `midpoint` handler returns the midpoint itself. Revealing a point answer adds it to the student's constructed points, so re-checking the attempt passes. Some goals, such as a generic `create` goal, have no single canonical shape to reveal and therefore return `shape: null`.
+
+## Development
+
+From a clean clone:
+
+```sh
+pnpm install --frozen-lockfile   # exactly what CI installs
+pnpm check                       # the full gate: typecheck, lint, test, format, build, verify
+```
+
+`pnpm install` (without the flag) is fine for day-to-day work; the frozen form is
+what a fresh clone and CI use, and it fails rather than silently updating
+`pnpm-lock.yaml`. pnpm itself is pinned by the `packageManager` field, so
+`corepack enable` is enough to get the right version.
+
+Launch the playground:
+
+```sh
+pnpm dev          # dev-page playground with teacher editor + student preview
+pnpm playground   # same, opens the browser automatically
+```
+
+The `dev-page/` app is a full demo: a teacher authoring surface, a live student preview, exercise JSON import/export, and answer checking. It is not part of the published package.
+
+Run the complete pre-publication verification (also enforced by `prepublishOnly`):
+
+```sh
+pnpm check
+```
+
+It ends with the four package verifiers — the export map, the API report, the bundle budgets, and a
+consumer installed from `pnpm pack`. [docs/releasing.md](./docs/releasing.md) says what each one
+guards and what to do when one fails.
+
+Or run checks individually:
+
+```sh
+pnpm typecheck
+pnpm lint
+pnpm test          # vitest + jsdom: schemas, stores, coordinates, geometry, snapping, state, validation
+pnpm test:e2e      # playwright + chromium and webkit: browser journeys (not part of `pnpm check`)
+pnpm test:a11y     # playwright + chromium + axe: dev-page accessibility (not part of `pnpm check`)
+pnpm bench         # performance baseline, Node (not part of `pnpm check`)
+pnpm bench:browser # performance baseline, browser frames (not part of `pnpm check`)
+pnpm bench:gate    # the enforced performance budget (runs in CI, not in `pnpm check`)
+pnpm format:check
+pnpm build
+pnpm build:dev-page
+pnpm verify:entries # the export map and declarations, against the built output
+pnpm verify:api     # the declaration snapshot in etc/api-report.md
+pnpm verify:size    # per-entry-point bundle budgets
+pnpm verify:package # pnpm pack, then a consumer fixture installed from the tarball
+pnpm api:report     # regenerate etc/api-report.md after an intended API change
+```
+
+The library build is generated in `dist/`. The standalone, single-file playground is generated in `dev-page-dist/index.html` and can be opened directly in a browser.
+
+Tooling: TypeScript (strict), Vite 8 (library mode + `vite-plugin-dts`), Vitest 4, Playwright (Chromium and WebKit), ESLint 10 (typescript-eslint + react-hooks), Prettier, pnpm.
+
+### Browser journeys
+
+Konva hit routing, pointer capture, touch behaviour, and the snap a click
+actually resolves to cannot be verified in jsdom — a direct-click snapping bug
+once shipped past a fully green unit suite. `tests/e2e/` covers that gap with a
+small set of Playwright journeys.
+
+```sh
+pnpm exec playwright install chromium webkit   # once per machine
+pnpm test:e2e                                  # both engines, headless; starts its own server
+pnpm test:e2e:critical                         # the @critical subset only
+pnpm test:e2e:chromium                         # one engine
+pnpm test:e2e:webkit
+pnpm test:e2e:dev-page                         # the dev-page journeys only, Chromium
+pnpm test:e2e:ui                               # the same journeys, in Playwright's UI
+```
+
+On Linux the browsers need system libraries as well as the download:
+`sudo pnpm exec playwright install-deps chromium webkit`. WebKit needs
+considerably more of them than Chromium (GTK 4, GStreamer, ICU), and without
+them it fails at launch, not at install.
+
+`pnpm test:e2e` starts its own Vite server on port 4176 (`vite.e2e.config.ts`)
+serving `tests/e2e/harness/`: a minimal host that renders the shipped `Toolbar`
+and `StudentGeometryCanvas` at a **fixed 600x600 canvas over the viewport
+`[-1, -1, 9, 9]`** — exactly 60 pixels per math unit, so every click a journey
+makes is an integer pixel. The exercise comes from `?scenario=<name>`
+(`tests/e2e/harness/scenarios.ts`); an unknown name throws rather than falling
+back. **`?canvas=WIDTHxHEIGHT`** and **`?projection=contain|stretch`** open that
+scenario at another size or aspect ratio (M1b.4.d), and
+`window.geometryHarness.resize()` changes it on a live page, which is what a
+`ResizeObserver` does to a real embed. The dev page is deliberately not used: it sizes its canvas from a
+`ResizeObserver` and takes its exercise from a textarea, neither of which a
+pixel-exact journey can depend on.
+
+**`?mode=teacher`** mounts the authoring half instead, as of M1b.4.c: the same
+`Toolbar` with `GeometryCanvas` and `TeacherGeometryCompanion`, the undo, redo
+and delete wiring, a JSON editor for the document round trip, and the switch
+into the student preview — which is why both hosts live on one page rather than
+two. The preview builds a student store from the exercise as it stands and is
+torn down on the way back.
+
+Journeys assert the resulting store and the serialized document through
+`window.geometryHarness` (the attempt) or `window.teacherHarness` (the
+exercise), not pixels. The teacher handle exists from load in `?mode=teacher`
+and the student one only while the preview is open, so a journey can tell the
+preview apart from a hidden one. DOM controls are addressed by role and
+**exact** accessible name — role-name matching is substring-based by default,
+which would let a renamed control keep passing — so the journeys are what pins
+the accessible names in place. Only the stage wrapper carries a test id
+(`data-testid="canvas"`), because a Konva canvas has no queryable DOM inside it.
+
+**Two engines**, as of M1b.4.a: `chromium` and `webkit`. Chromium is the desktop
+target; WebKit is the tablet one, because Safari is the only engine on iPad and a
+tablet is the likeliest classroom device. They disagree about canvas hit routing
+and pointer event ordering often enough that a journey passing on one proves
+little about the other. **Every harness journey runs on both, with no
+exceptions** since M1b.4.b. A touch drag is synthesized inside the page —
+Playwright's `touchscreen` API offers `tap` and nothing else — and since M3.H.4
+it is a sequence of touch `PointerEvent`s, which is all the canvases listen to;
+`pointerSequence()` dispatches the same way for second fingers and
+cancellations. Everything that can be native is: taps are real `tap()`s, with
+the browser's compatibility click after them, and mouse drags are real mouse
+input, which is the only kind a canvas can capture. The **`dev-page` project** described below drives DOM
+chrome rather than a stage, and is Chromium-only for that reason — except for
+**`dev-page-webkit`**, added at M3.H.3, which runs `responsive-hardening.spec.ts`
+and nothing else: layout, activation boxes and a live rotation are exactly what
+two engines can disagree about.
+
+**Five device profiles**, also M3.H.3 and also on both engines. `touch-targets.spec.ts`
+and `responsive-hardening.spec.ts` each run their whole body under a desktop
+profile (1280x900, mouse, DPR 1), a narrow phone (360x800), a phone in landscape
+(800x360) and both tablet orientations (768x1024, 1024x768) — the touch ones at
+DPR 2. The profiles are set per `test.describe` with explicit `viewport`,
+`hasTouch` and `deviceScaleFactor` rather than as ten more projects. They are
+**emulation**: two desktop browsers pretending, which proves the measurements
+and not the feel. No physical handset is tested, by decision.
+
+**`@critical`** tags the journeys whose failure means a student cannot do an
+exercise. Everything M1.4 and M1b.3 wrote carries it; broader coverage does not,
+which is what makes the two selections differ: `pnpm test:e2e:critical` is 28
+journeys and `pnpm test:e2e` is **391 selections** as of M3.H.4 — 167 harness
+selections on each of two engines, 31 dev-page selections on Chromium and the 26
+hardening selections on WebKit. The matrices are most of that growth: M3.H.3's two
+spec files run their bodies once per device profile, and M3.H.4's
+`gesture-cancellation.spec.ts` pins every threshold boundary per pointer type,
+scale factor and canvas size and every cancellation trigger.
+
+M2.9 crossed the documented ten-minute pull-request threshold at 168 selections
+and 10.2 minutes. M3.H.4 grew the suite to **391 selections**, measured at
+**14.4 minutes** with CI's settings (`CI=1`: two workers, one retry — none used) on
+a development machine. Run it that way locally too: at a machine's default worker
+count WebKit can crash mid-drag under the load, which reads as a failure and is
+not one. Pull requests
+therefore require the 56 critical selections across both engines; the full suite
+runs after a push to `main`. WebKit remains roughly half again as slow per journey
+here.
+
+The per-test timeout is **30 seconds**, raised from 20 at M1b.4.b. A WebKit
+_drag_ journey measures 12-17s where a click journey measures 6-7s: every pointer
+move commits a store change and redraws the stage, and each move is its own
+protocol round trip. The sizing journeys and the two M3.H.3 hardening
+specs raise their own budget to 90 seconds in-file, for the same reason at a
+larger scale: they resize a live stage repeatedly, and the whole profile matrix
+runs in parallel workers.
+
+The per-file exception is the visual suite's **90 seconds**: a determinism
+journey loads the page twice and captures two full rasters, and a WebKit raster
+is four times the pixels at that device's scale factor of 2.
+
+**The visual suite** — `visual.spec.ts` and `canvas-size.spec.ts`, M1b.4.d —
+asserts the raster where every other journey asserts the store, and it commits
+**no golden images**. A raster recorded on a developer's machine and compared on
+CI compares two font stacks and two browser builds, not two revisions of this
+renderer: every point label is canvas text in Konva's default Arial, which
+resolves to whatever fontconfig substitutes. It makes two machine-independent
+claims instead:
+
+- **Determinism** — one stable state, captured after two independent loads, is
+  the same bytes. That is the acceptance criterion the milestone states, and it
+  catches an unflushed frame, an animation, or anything else that makes a redraw
+  depend on when it ran.
+- **Probes** — the pixel at a known math coordinate, read from the layer's own
+  2D context. This is what a golden image would have caught and a store
+  assertion cannot: that `contain` letterboxes a wide canvas and leaves the
+  bands bare, that `stretch` reaches every edge, and that a live resize really
+  redrew the figure at the new placement rather than agreeing about it in the
+  transform alone.
+
+The **`dev-page` project** (M3.2.a) is the exception to all of the above: its
+journeys live in `tests/dev-page/`, run on Chromium only, and drive the dev page
+on its own Vite server on port 4177 (`vite.dev-page.config.ts`) rather than the
+harness. The harness has no Exercise JSON panel and no demo picker, so what the
+panel does with the store — a demo load is a load and not an edit, and a
+keystroke after one destroys nothing — cannot be journeyed there. The engine and
+canvas-size discussion above, and the `@critical` counts, are about the harness
+journeys; this project adds its own selections on top of them.
+
+`pnpm test:e2e` is not part of `pnpm check`, which must stay runnable without a
+browser download; CI runs it as its own job.
+
+### Accessibility checks
+
+`pnpm test:a11y` runs [axe-core](https://github.com/dequelabs/axe-core) over the
+dev page — the real DOM chrome — in four states: teacher mode empty, teacher
+mode with a figure, a selection and the goal editor open, and the student
+preview before and after checking. It also drives the student preview's
+keyboard shortcuts (Escape, Delete, Ctrl+Z) end to end, and covers the semantic
+companion under forced colours, at 200% zoom, with reduced motion, and through
+Tab order.
+
+```sh
+pnpm exec playwright install chromium   # once per machine
+pnpm test:a11y                          # headless; starts its own server
+```
+
+It starts its own Vite server on port 4178 (`vite.dev-page.config.ts`) and
+asserts axe reports **no** violations. No rule is ever disabled: a rule turned
+off is a regression that stops being reported, so a genuine exception belongs in
+the markup as a documented change instead.
+
+The Konva stage is deliberately out of scope — it is one `<canvas>` element
+with no accessible content, and nothing can give it any. The figure reaches
+assistive technology through the **semantic companion** instead: mount
+`StudentGeometryCompanion` or `TeacherGeometryCompanion` beside your canvas and
+the current tool, the pending connection, every entity as a sentence, the
+selection and the last verdict become ordinary DOM, derived from the same
+geometry context the canvas draws from. [docs/accessibility.md](./docs/accessibility.md)
+is the interaction design, the DOM and selector contract, and the manual test
+instructions (screen readers, OS high contrast, 400% zoom, reduced motion).
+
+Keyboard operation of the shipped components is pinned by Journey 10 in
+`tests/e2e/keyboard.spec.ts`: Tab order, arming and cancelling a tool, and
+undo/redo/delete, all without a pointer.
+
+### Performance baseline and budget
+
+`pnpm bench` and `pnpm bench:browser` measure the engine over deterministic
+scenes of 10, 50 and 100 objects and write machine-readable JSON to
+`docs/performance/`. They are a **report**, not a gate, and are run by hand.
+`docs/performance/README.md` holds the recorded baseline, the method, the M2
+delta, and a deliberately provisional target device profile.
+
+`pnpm bench:gate` is the **gate**, added at M1b.5, and it runs in CI on every
+pull request. Nothing it enforces is expressed in milliseconds: this repository's
+runs drift by tens of percent between sessions, so each of the twenty numbers
+in `docs/performance/budget.json` is a ratio between one benchmark row and a
+synthetic workload measured in the same run, and a slower machine slows both
+sides equally. See `docs/performance/README.md` § Threshold policy.
+
+Two headlines are there. `computeSnap`'s pairwise intersection scan is `O(n^2)`
+in object count and is about 90% of what one pointer move costs at 100 objects,
+while the browser's per-pointer-event cost is dominated by the re-render rather
+than by any of the measured computation. And M2 cost about **2x on the median
+benchmark row** against the M1.8 baseline, which M1b.5 measured, accepted in
+writing and did not optimize — the rows that regressed are cheap, and the one
+that dominates a pointer move got faster.
+
+### Continuous integration
+
+`.github/workflows/ci.yml` runs on every pull request and on pushes to `main`. There are three jobs.
+
+`check` runs the six commands above — typecheck, lint, unit tests, format check,
+library build, dev-page build — separately, so a red build names the failing gate,
+across Node 20.19.0, 22.12.0, and the current LTS.
+
+`browser journeys` installs Chromium and WebKit. Pull requests run
+`pnpm test:e2e:critical` on both; pushes to `main` run the full `pnpm test:e2e`.
+The job then runs `pnpm test:a11y` on Chromium, on a single Node version: these
+exercise the browser, not the runtime, and sharing one job means installing the
+browsers once. The axe pass stays single-engine on purpose — it reports on the
+DOM a page builds, not on how an engine paints it. On failure only, the job uploads the
+Playwright HTML report and `test-results/` (traces, videos, screenshots) as an
+artifact with a 7-day retention; artifacts are written per project, so a
+WebKit-only failure arrives with a WebKit trace.
+
+`performance gate` runs `pnpm run bench:gate` on a single Node version — the
+gate compares two numbers measured in the same process, so a second runtime
+would re-measure the same ratio. It re-runs the benchmark once before failing,
+so a neighbouring process on a shared runner has to slow the same row twice to
+turn the build red.
+
+Actions are pinned to a commit SHA, and only the pnpm store is cached; build
+output and the browser download are never restored from a cache that could hide
+an error.
+
+## Extending the engine
+
+To add a new goal kind:
+
+1. Add a schema in `src/schemas/goals/` and add it to the union in `geometryGoal.schema.ts`.
+2. Declare the kind in `src/schemas/goals/goalKindDeclaration.ts`: its schema, the givens it names (`referencedGivenIds`), and any cross-reference rules (`crossReferenceIssues`). `exercise.schema.ts` runs the rules, and the teacher editor reads the references when a given is deleted — neither needs an edit.
+3. Implement a `GoalKindHandler` in `src/validation/goals/` (`accepts`, `satisfies`, `isRelevantAttempt`, `buildRevealedAnswer`) and add it to the registry in `src/validation/goals/index.ts`.
+4. Cover it with tests in `tests/validation/goals/`.
+
+Both registries are frozen records keyed by goal kind, so a kind missing from either is a compile error rather than a lookup that depends on which module was imported first.
+
+Measurements that need real geometry (angles, intersections, incidence) go through `src/measure/geometryAdapter.ts`, keeping JSXGraph out of the handlers themselves.
+
+An entity kind is the same shape of change: one `EntityOperations` entry in `src/geometry/entities/`, declaring what the kind is built on (`parents`) and what it does with those parents once they are resolved (`resolve`), plus its shape, distance and identity. The construction graph itself is kind-blind — it resolves whatever a definition names, at any depth and in any mixture of kinds — so nothing in the traversal, the deletion cascade or the issue reporting is edited to add one.
+
+M2.8 added the circle as exactly that, and the full cost was: the kind in `EntityKind`, one
+operations file, one stored schema and its line in the v1 translation, the rows the relation tables
+demanded (which pairs it intersects, how it is parameterized and projected), the two kernel paths in
+`src/measure/`, and one shape component. Adding the kind was a **compile error** in each of those
+places until it was written — `EntityRegistry`, the intersection table, the parameterization and
+projection tables and the renderer's shape table are all mapped types over the kind union — and it
+was an error nowhere else. Hit testing, snapping, the graph, the indexed context, the stores and
+both canvases were not edited.
+
+### Upgrading JSXGraph
+
+`src/measure/kernel.ts` consumes JSXGraph internals — `JXG.Math.Geometry`'s meet functions and the `[c, b0, b1, a, k, r, q0, q1]` standard form they take — none of which is public, typed, or documented. The dependency is therefore pinned to an exact version.
+
+**Any version bump must re-run `tests/measure/kernelContract.test.ts`**, which pins the behavior the adapter relies on: parameter conventions, the invalid `[0, 0, 0]` sentinel and how it differs from a genuine ideal point, tangency returning a duplicate point, zero-radius and non-finite handling, and operand-order effects. A failure there is the kernel changing under the engine, not the engine breaking, and the adapter has to be re-derived before the bump lands. The suite runs as part of `pnpm run check`.
+
+## Known limitations
+
+- Object types are limited to points, segments, lines, and circles — no arcs, angles, or polygons yet.
+- A circle has no tool, no goal kind and no authoring UI: it can be authored in exercise JSON and persisted in an attempt, but a student cannot draw one. Only the centre-and-through-point construction exists — no radius provenance, no three-point circle.
+- Goal kinds are limited to `create`, `throughPoints`, `perpendicular`, `parallel`, `segmentLength`, and `midpoint` (no angle-measure, area, or transformation goals yet).
+- Instruments (`ruler`, `setSquare`, `protractor`) are visual aids only: draggable pictures with no mathematical effect. The engine can neither express nor verify that a student used one.
+- There is no compass, so authentic Euclidean construction exercises cannot be expressed at all.
+- The canvas cannot be _constructed on_ from the keyboard. The chrome is fully operable and the figure is published to assistive technology through the semantic companion, but placing a point still needs a pointer.
+- Touch is exercised in both engines by emulated events only — never on a real device.
+- No minimum browser versions have been chosen. Chromium and WebKit are tested; the support floor is undecided, so the table above names engines rather than releases.
+- Selection still rides on Konva shape events rather than `hitTest()`, so selection tolerance is coupled to how large an object is drawn.