@mathscan/geometry-engine 0.1.0

package/dist/snapping/computeSnap.d.ts

@@ -0,0 +1,31 @@
+import { SceneEntity } from '../geometry/hitTest.js';
+import { Point, PointId } from '../geometry/point.js';
+import { EntityId, PointDefinition } from '../geometry/entityModel.js';
+import { MathViewport } from '../schemas/viewport.schema.js';
+export type SnapKind = 'point' | 'intersection' | 'grid' | 'onObject';
+export interface SnapResult {
+    position: Point;
+    kind: SnapKind;
+    targetIds: string[];
+    parameter?: number;
+    distance: number;
+}
+export interface SnapScene {
+    points: ReadonlyMap<PointId, Point>;
+    objects: readonly SceneEntity[];
+    viewport: MathViewport;
+    showGrid?: boolean;
+    isSnapTarget?: (id: EntityId) => boolean;
+}
+export interface SnapOptions {
+    tolerance: number;
+    exclude?: readonly string[];
+    kinds?: readonly SnapKind[];
+}
+export declare function computeSnap(at: Point, scene: SnapScene, options: SnapOptions): SnapResult | null;
+export declare function snapPosition(at: Point, scene: SnapScene, options: SnapOptions): Point;
+export declare function originForSnap(placement: {
+    position: Point;
+    snap: SnapResult | null;
+}): PointDefinition | null;
+//# sourceMappingURL=computeSnap.d.ts.map

package/dist/snapping/computeSnap.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"computeSnap.d.ts","sourceRoot":"","sources":["../../src/snapping/computeSnap.ts"],"names":[],"mappings":"AAWA,OAAO,EAAW,KAAK,WAAW,EAAE,MAAM,qBAAqB,CAAA;AAC/D,OAAO,EAAmB,KAAK,KAAK,EAAE,KAAK,OAAO,EAAE,MAAM,mBAAmB,CAAA;AAC7E,OAAO,KAAK,EAAE,QAAQ,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAA;AAGxE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAA;AAE9D,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,cAAc,GAAG,MAAM,GAAG,UAAU,CAAA;AAErE,MAAM,WAAW,UAAU;IAEzB,QAAQ,EAAE,KAAK,CAAA;IACf,IAAI,EAAE,QAAQ,CAAA;IAGd,SAAS,EAAE,MAAM,EAAE,CAAA;IAGnB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,QAAQ,EAAE,MAAM,CAAA;CACjB;AAED,MAAM,WAAW,SAAS;IACxB,MAAM,EAAE,WAAW,CAAC,OAAO,EAAE,KAAK,CAAC,CAAA;IACnC,OAAO,EAAE,SAAS,WAAW,EAAE,CAAA;IAC/B,QAAQ,EAAE,YAAY,CAAA;IAEtB,QAAQ,CAAC,EAAE,OAAO,CAAA;IAQlB,YAAY,CAAC,EAAE,CAAC,EAAE,EAAE,QAAQ,KAAK,OAAO,CAAA;CACzC;AAED,MAAM,WAAW,WAAW;IAE1B,SAAS,EAAE,MAAM,CAAA;IACjB,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IAC3B,KAAK,CAAC,EAAE,SAAS,QAAQ,EAAE,CAAA;CAC5B;AA4GD,wBAAgB,WAAW,CAAC,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,OAAO,EAAE,WAAW,GAAG,UAAU,GAAG,IAAI,CAQhG;AAID,wBAAgB,YAAY,CAAC,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,OAAO,EAAE,WAAW,GAAG,KAAK,CAErF;AAaD,wBAAgB,aAAa,CAAC,SAAS,EAAE;IACvC,QAAQ,EAAE,KAAK,CAAA;IACf,IAAI,EAAE,UAAU,GAAG,IAAI,CAAA;CACxB,GAAG,eAAe,GAAG,IAAI,CAczB"}

package/dist/state/geometryContext.d.cts

@@ -0,0 +1,40 @@
+import { EntityId, EntityKind, GeometryContext } from '../geometry/entityModel.cjs';
+import { Point, PointId } from '../geometry/point.cjs';
+import { MeasuredObject } from '../measure/geometryAdapter.cjs';
+import { GeometryExercise, ToolName } from '../schemas/exercise.schema.cjs';
+import { GeometryState } from '../schemas/geometryState.schema.cjs';
+import { ObjectTypeName } from '../schemas/objectTypeName.schema.cjs';
+/**
+ * What M2.2 adds on top of the frozen `GeometryContext` minimum. The extra
+ * members are the lookups the four consumers actually asked for — the graph
+ * edges in both directions, the measured form the JSXGraph seam wants, the
+ * exercise's own capabilities, and the staleness check.
+ *
+ * Read-only to consumers: every collection is handed out as `readonly` or as a
+ * fresh array, and no index another consumer is reading is ever exposed.
+ */
+export interface IndexedGeometryContext extends GeometryContext {
+    kindOf(id: EntityId): EntityKind | undefined;
+    parentsOf(id: EntityId): readonly EntityId[];
+    removalClosureOf(id: EntityId): readonly EntityId[];
+    readonly points: ReadonlyMap<PointId, Point>;
+    measuredOf(id: EntityId): MeasuredObject | null;
+    allowsObjectType(type: ObjectTypeName): boolean;
+    allowsTool(tool: ToolName): boolean;
+    isBuiltFrom(exercise: GeometryExercise, geometry: GeometryState): boolean;
+}
+/**
+ * Indexes an exercise and one attempt against it into a single read-only
+ * scene, resolving every point once.
+ *
+ * Both arguments are the parsed, schema-checked types, which is what "built
+ * only from validated data" means here: there is no second builder taking
+ * `unknown`, and a caller holding untrusted JSON goes through
+ * `validateGeometryStateInput()` first, exactly as it does today.
+ *
+ * Nothing throws. A document the schemas would reject — a duplicate id, a
+ * parent that does not exist, a cycle — indexes anyway and reports what it
+ * found in `issues`, because the authoring warnings and the dev page must
+ * describe a broken exercise rather than disappear on it.
+ */
+export declare function buildGeometryContext(exercise: GeometryExercise, geometry: GeometryState): IndexedGeometryContext;

package/dist/state/geometryContext.d.ts

@@ -0,0 +1,41 @@
+import { EntityId, EntityKind, GeometryContext } from '../geometry/entityModel.js';
+import { Point, PointId } from '../geometry/point.js';
+import { MeasuredObject } from '../measure/geometryAdapter.js';
+import { GeometryExercise, ToolName } from '../schemas/exercise.schema.js';
+import { GeometryState } from '../schemas/geometryState.schema.js';
+import { ObjectTypeName } from '../schemas/objectTypeName.schema.js';
+/**
+ * What M2.2 adds on top of the frozen `GeometryContext` minimum. The extra
+ * members are the lookups the four consumers actually asked for — the graph
+ * edges in both directions, the measured form the JSXGraph seam wants, the
+ * exercise's own capabilities, and the staleness check.
+ *
+ * Read-only to consumers: every collection is handed out as `readonly` or as a
+ * fresh array, and no index another consumer is reading is ever exposed.
+ */
+export interface IndexedGeometryContext extends GeometryContext {
+    kindOf(id: EntityId): EntityKind | undefined;
+    parentsOf(id: EntityId): readonly EntityId[];
+    removalClosureOf(id: EntityId): readonly EntityId[];
+    readonly points: ReadonlyMap<PointId, Point>;
+    measuredOf(id: EntityId): MeasuredObject | null;
+    allowsObjectType(type: ObjectTypeName): boolean;
+    allowsTool(tool: ToolName): boolean;
+    isBuiltFrom(exercise: GeometryExercise, geometry: GeometryState): boolean;
+}
+/**
+ * Indexes an exercise and one attempt against it into a single read-only
+ * scene, resolving every point once.
+ *
+ * Both arguments are the parsed, schema-checked types, which is what "built
+ * only from validated data" means here: there is no second builder taking
+ * `unknown`, and a caller holding untrusted JSON goes through
+ * `validateGeometryStateInput()` first, exactly as it does today.
+ *
+ * Nothing throws. A document the schemas would reject — a duplicate id, a
+ * parent that does not exist, a cycle — indexes anyway and reports what it
+ * found in `issues`, because the authoring warnings and the dev page must
+ * describe a broken exercise rather than disappear on it.
+ */
+export declare function buildGeometryContext(exercise: GeometryExercise, geometry: GeometryState): IndexedGeometryContext;
+//# sourceMappingURL=geometryContext.d.ts.map

package/dist/state/geometryContext.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"geometryContext.d.ts","sourceRoot":"","sources":["../../src/state/geometryContext.ts"],"names":[],"mappings":"AA8DA,OAAO,KAAK,EAEV,QAAQ,EACR,UAAU,EAGV,eAAe,EAIhB,MAAM,yBAAyB,CAAA;AAGhC,OAAO,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAA;AACvD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAA;AAEhE,OAAO,KAAK,EAAE,gBAAgB,EAAE,QAAQ,EAAE,MAAM,4BAA4B,CAAA;AAC5E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iCAAiC,CAAA;AACpE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kCAAkC,CAAA;AAEtE;;;;;;;;GAQG;AACH,MAAM,WAAW,sBAAuB,SAAQ,eAAe;IAE7D,MAAM,CAAC,EAAE,EAAE,QAAQ,GAAG,UAAU,GAAG,SAAS,CAAA;IAI5C,SAAS,CAAC,EAAE,EAAE,QAAQ,GAAG,SAAS,QAAQ,EAAE,CAAA;IAI5C,gBAAgB,CAAC,EAAE,EAAE,QAAQ,GAAG,SAAS,QAAQ,EAAE,CAAA;IAKnD,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC,OAAO,EAAE,KAAK,CAAC,CAAA;IAK5C,UAAU,CAAC,EAAE,EAAE,QAAQ,GAAG,cAAc,GAAG,IAAI,CAAA;IAI/C,gBAAgB,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAAA;IAC/C,UAAU,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAA;IAInC,WAAW,CAAC,QAAQ,EAAE,gBAAgB,EAAE,QAAQ,EAAE,aAAa,GAAG,OAAO,CAAA;CAC1E;AAyLD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,gBAAgB,EAC1B,QAAQ,EAAE,aAAa,GACtB,sBAAsB,CAqLxB"}

package/dist/state/resolvePoints.d.cts

@@ -0,0 +1,51 @@
+import { EntityId } from '../geometry/entityModel.cjs';
+import { SceneEntity } from '../geometry/hitTest.cjs';
+import { Point, PointId } from '../geometry/point.cjs';
+import { GeometryExercise } from '../schemas/exercise.schema.cjs';
+import { GeometryState } from '../schemas/geometryState.schema.cjs';
+import { IndexedGeometryContext } from './geometryContext.cjs';
+/**
+ * Every object a point can be built on: the exercise's own entities plus the
+ * student's constructions, as the `{ id, definition }` pairs a hit-test or snap
+ * scene is made of.
+ *
+ * Keyed by id and in declaration order, exercise first, because a construction
+ * re-declaring a given id loses to it exactly as it does in the context.
+ */
+export declare function objectsInScope(exercise: GeometryExercise, geometry: GeometryState): Map<EntityId, SceneEntity>;
+/**
+ * Resolves every point to coordinates. A point is simply absent from the
+ * result when it cannot be resolved — its object was deleted, its two objects
+ * became parallel so the intersection vanished, or its origins form a cycle.
+ * Callers treat "absent" as "not on screen": renderers skip it, validation
+ * skips candidates and constructions built on it. Nothing throws, because a
+ * student mid-construction is allowed to have a figure that briefly makes no
+ * sense.
+ *
+ * Given points come from `exercise`, not from `geometry` — a pinned given is
+ * placed by the exercise whatever a submitted attempt claims, which is a
+ * grading-integrity rule and is enforced while the context is indexed.
+ *
+ * Iteration order is part of the contract: pinned givens, then draggable
+ * givens, then the attempt's own points. `findPointAt()` in the student store
+ * promotes the first point within reuse tolerance, so the order decides which
+ * point a revealed answer lands on.
+ */
+export declare function resolvePoints(exercise: GeometryExercise, geometry: GeometryState): ReadonlyMap<PointId, Point>;
+export declare function resolvePoint(exercise: GeometryExercise, geometry: GeometryState, id: PointId): Point | null;
+/**
+ * Every point an exercise places on its own, with no attempt against it — what
+ * the teacher canvas draws and what a revealed answer is measured against.
+ *
+ * A v1 given carried its coordinates and needed no resolution; a v2 exercise
+ * entity is a definition, so a given point sitting on a given segment has a
+ * position only once the graph has been walked (M2.6.c.1).
+ */
+export declare function resolveExercisePoints(exercise: GeometryExercise): ReadonlyMap<PointId, Point>;
+/**
+ * The same walk, kept whole rather than reduced to its points: a teacher-side
+ * caller that also needs presentation — which is every renderer, since M2.G.4
+ * routes drawing through the capability triple — would otherwise index the
+ * exercise a second time to answer what the context already knows.
+ */
+export declare function exerciseGeometryContext(exercise: GeometryExercise): IndexedGeometryContext;

package/dist/state/resolvePoints.d.ts

@@ -0,0 +1,52 @@
+import { EntityId } from '../geometry/entityModel.js';
+import { SceneEntity } from '../geometry/hitTest.js';
+import { Point, PointId } from '../geometry/point.js';
+import { GeometryExercise } from '../schemas/exercise.schema.js';
+import { GeometryState } from '../schemas/geometryState.schema.js';
+import { IndexedGeometryContext } from './geometryContext.js';
+/**
+ * Every object a point can be built on: the exercise's own entities plus the
+ * student's constructions, as the `{ id, definition }` pairs a hit-test or snap
+ * scene is made of.
+ *
+ * Keyed by id and in declaration order, exercise first, because a construction
+ * re-declaring a given id loses to it exactly as it does in the context.
+ */
+export declare function objectsInScope(exercise: GeometryExercise, geometry: GeometryState): Map<EntityId, SceneEntity>;
+/**
+ * Resolves every point to coordinates. A point is simply absent from the
+ * result when it cannot be resolved — its object was deleted, its two objects
+ * became parallel so the intersection vanished, or its origins form a cycle.
+ * Callers treat "absent" as "not on screen": renderers skip it, validation
+ * skips candidates and constructions built on it. Nothing throws, because a
+ * student mid-construction is allowed to have a figure that briefly makes no
+ * sense.
+ *
+ * Given points come from `exercise`, not from `geometry` — a pinned given is
+ * placed by the exercise whatever a submitted attempt claims, which is a
+ * grading-integrity rule and is enforced while the context is indexed.
+ *
+ * Iteration order is part of the contract: pinned givens, then draggable
+ * givens, then the attempt's own points. `findPointAt()` in the student store
+ * promotes the first point within reuse tolerance, so the order decides which
+ * point a revealed answer lands on.
+ */
+export declare function resolvePoints(exercise: GeometryExercise, geometry: GeometryState): ReadonlyMap<PointId, Point>;
+export declare function resolvePoint(exercise: GeometryExercise, geometry: GeometryState, id: PointId): Point | null;
+/**
+ * Every point an exercise places on its own, with no attempt against it — what
+ * the teacher canvas draws and what a revealed answer is measured against.
+ *
+ * A v1 given carried its coordinates and needed no resolution; a v2 exercise
+ * entity is a definition, so a given point sitting on a given segment has a
+ * position only once the graph has been walked (M2.6.c.1).
+ */
+export declare function resolveExercisePoints(exercise: GeometryExercise): ReadonlyMap<PointId, Point>;
+/**
+ * The same walk, kept whole rather than reduced to its points: a teacher-side
+ * caller that also needs presentation — which is every renderer, since M2.G.4
+ * routes drawing through the capability triple — would otherwise index the
+ * exercise a second time to answer what the context already knows.
+ */
+export declare function exerciseGeometryContext(exercise: GeometryExercise): IndexedGeometryContext;
+//# sourceMappingURL=resolvePoints.d.ts.map

package/dist/state/resolvePoints.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolvePoints.d.ts","sourceRoot":"","sources":["../../src/state/resolvePoints.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAA;AACvD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAA;AACtD,OAAO,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAA;AACvD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAA;AAClE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iCAAiC,CAAA;AACpE,OAAO,EAAwB,KAAK,sBAAsB,EAAE,MAAM,mBAAmB,CAAA;AAErF;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAC5B,QAAQ,EAAE,gBAAgB,EAC1B,QAAQ,EAAE,aAAa,GACtB,GAAG,CAAC,QAAQ,EAAE,WAAW,CAAC,CAS5B;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,aAAa,CAC3B,QAAQ,EAAE,gBAAgB,EAC1B,QAAQ,EAAE,aAAa,GACtB,WAAW,CAAC,OAAO,EAAE,KAAK,CAAC,CAO7B;AAGD,wBAAgB,YAAY,CAC1B,QAAQ,EAAE,gBAAgB,EAC1B,QAAQ,EAAE,aAAa,EACvB,EAAE,EAAE,OAAO,GACV,KAAK,GAAG,IAAI,CAEd;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,gBAAgB,GAAG,WAAW,CAAC,OAAO,EAAE,KAAK,CAAC,CAE7F;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,gBAAgB,GAAG,sBAAsB,CAE1F"}

package/dist/store/attemptChange.d.cts

@@ -0,0 +1,30 @@
+import { EntityId } from '../geometry/entityModel.cjs';
+import { GeometryState } from '../schemas/geometryState.schema.cjs';
+/**
+ * What a completed student action did to the attempt (RFC 0005 § Decision 2).
+ * Each code maps to a row of ADR 0009's student-mutation inventory. The list
+ * may grow additively, so a consumer treats a value it does not know as a
+ * generic change.
+ */
+export type StudentGeometryAction = 'point-placed' | 'point-promoted' | 'segment-created' | 'line-created' | 'point-moved' | 'deleted' | 'undo' | 'redo' | 'reset' | 'revealed';
+export interface StudentGeometryChangeMeta {
+    action: StudentGeometryAction;
+    entityIds: string[];
+}
+/**
+ * The store's record of its last completed action. `sequence` rises by one per
+ * action on that store, so two identical actions in a row are still two
+ * receipts. Delivery metadata, not a command log: only the latest is kept, and
+ * it is never serialized or put in history.
+ */
+export interface StudentAttemptChangeReceipt extends StudentGeometryChangeMeta {
+    sequence: number;
+}
+export declare function sameData(a: unknown, b: unknown): boolean;
+/**
+ * The ids whose definition, presentation entry or answer membership differs
+ * between two attempts — what an undo, a redo, a reset or a reveal changed.
+ * Ordered by first appearance: the earlier attempt's entities, presentation and
+ * answers, then the later one's.
+ */
+export declare function changedEntityIds(before: GeometryState, after: GeometryState): EntityId[];

package/dist/store/attemptChange.d.ts

@@ -0,0 +1,31 @@
+import { EntityId } from '../geometry/entityModel.js';
+import { GeometryState } from '../schemas/geometryState.schema.js';
+/**
+ * What a completed student action did to the attempt (RFC 0005 § Decision 2).
+ * Each code maps to a row of ADR 0009's student-mutation inventory. The list
+ * may grow additively, so a consumer treats a value it does not know as a
+ * generic change.
+ */
+export type StudentGeometryAction = 'point-placed' | 'point-promoted' | 'segment-created' | 'line-created' | 'point-moved' | 'deleted' | 'undo' | 'redo' | 'reset' | 'revealed';
+export interface StudentGeometryChangeMeta {
+    action: StudentGeometryAction;
+    entityIds: string[];
+}
+/**
+ * The store's record of its last completed action. `sequence` rises by one per
+ * action on that store, so two identical actions in a row are still two
+ * receipts. Delivery metadata, not a command log: only the latest is kept, and
+ * it is never serialized or put in history.
+ */
+export interface StudentAttemptChangeReceipt extends StudentGeometryChangeMeta {
+    sequence: number;
+}
+export declare function sameData(a: unknown, b: unknown): boolean;
+/**
+ * The ids whose definition, presentation entry or answer membership differs
+ * between two attempts — what an undo, a redo, a reset or a reveal changed.
+ * Ordered by first appearance: the earlier attempt's entities, presentation and
+ * answers, then the later one's.
+ */
+export declare function changedEntityIds(before: GeometryState, after: GeometryState): EntityId[];
+//# sourceMappingURL=attemptChange.d.ts.map

package/dist/store/attemptChange.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"attemptChange.d.ts","sourceRoot":"","sources":["../../src/store/attemptChange.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAA;AAEvD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iCAAiC,CAAA;AAEpE;;;;;GAKG;AACH,MAAM,MAAM,qBAAqB,GAC7B,cAAc,GACd,gBAAgB,GAChB,iBAAiB,GACjB,cAAc,GACd,aAAa,GACb,SAAS,GACT,MAAM,GACN,MAAM,GACN,OAAO,GACP,UAAU,CAAA;AAEd,MAAM,WAAW,yBAAyB;IACxC,MAAM,EAAE,qBAAqB,CAAA;IAI7B,SAAS,EAAE,MAAM,EAAE,CAAA;CACpB;AAED;;;;;GAKG;AACH,MAAM,WAAW,2BAA4B,SAAQ,yBAAyB;IAC5E,QAAQ,EAAE,MAAM,CAAA;CACjB;AAMD,wBAAgB,QAAQ,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,GAAG,OAAO,CAYxD;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,aAAa,EAAE,KAAK,EAAE,aAAa,GAAG,QAAQ,EAAE,CAexF"}

package/dist/store/constructionCommand.d.cts

@@ -0,0 +1,35 @@
+import { EntityId, PointDefinition } from '../geometry/entityModel.cjs';
+import { PointId } from '../geometry/point.cjs';
+/**
+ * An end of a construction, before the engine has decided what it costs. A
+ * gesture reports where it landed; whether that is a point yet is not the
+ * gesture's business.
+ *
+ * These types live apart from the store because the gesture layer speaks them
+ * too — `useConnectionPreview` resolves a release into one of these and hands
+ * it on, which is how the preview stopped creating entities of its own.
+ */
+export type ConstructionEndpoint = {
+    kind: 'existing';
+    id: PointId;
+} | {
+    kind: 'create';
+    origin: PointDefinition;
+};
+export interface ConstructionCommand {
+    tool: 'segment' | 'line';
+    from: ConstructionEndpoint;
+    to: ConstructionEndpoint;
+}
+/**
+ * Why the last construction attempt made nothing new: the document already
+ * declares that construction, as `entityId` (RFC 0004 § Decision 1). A code
+ * rather than a sentence, so a host can say it in its own language.
+ *
+ * Transient, like the rest of a store's gesture state: never serialized and
+ * never in history.
+ */
+export interface ConstructionNotice {
+    code: 'duplicate-construction';
+    entityId: EntityId;
+}

package/dist/store/constructionCommand.d.ts

@@ -0,0 +1,36 @@
+import { EntityId, PointDefinition } from '../geometry/entityModel.js';
+import { PointId } from '../geometry/point.js';
+/**
+ * An end of a construction, before the engine has decided what it costs. A
+ * gesture reports where it landed; whether that is a point yet is not the
+ * gesture's business.
+ *
+ * These types live apart from the store because the gesture layer speaks them
+ * too — `useConnectionPreview` resolves a release into one of these and hands
+ * it on, which is how the preview stopped creating entities of its own.
+ */
+export type ConstructionEndpoint = {
+    kind: 'existing';
+    id: PointId;
+} | {
+    kind: 'create';
+    origin: PointDefinition;
+};
+export interface ConstructionCommand {
+    tool: 'segment' | 'line';
+    from: ConstructionEndpoint;
+    to: ConstructionEndpoint;
+}
+/**
+ * Why the last construction attempt made nothing new: the document already
+ * declares that construction, as `entityId` (RFC 0004 § Decision 1). A code
+ * rather than a sentence, so a host can say it in its own language.
+ *
+ * Transient, like the rest of a store's gesture state: never serialized and
+ * never in history.
+ */
+export interface ConstructionNotice {
+    code: 'duplicate-construction';
+    entityId: EntityId;
+}
+//# sourceMappingURL=constructionCommand.d.ts.map

package/dist/store/constructionCommand.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constructionCommand.d.ts","sourceRoot":"","sources":["../../src/store/constructionCommand.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAA;AACxE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAA;AAEhD;;;;;;;;GAQG;AACH,MAAM,MAAM,oBAAoB,GAC5B;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,EAAE,EAAE,OAAO,CAAA;CAAE,GAIjC;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,eAAe,CAAA;CAAE,CAAA;AAE/C,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,SAAS,GAAG,MAAM,CAAA;IACxB,IAAI,EAAE,oBAAoB,CAAA;IAC1B,EAAE,EAAE,oBAAoB,CAAA;CACzB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,wBAAwB,CAAA;IAC9B,QAAQ,EAAE,QAAQ,CAAA;CACnB"}

package/dist/store/constructionIdentity.d.cts

@@ -0,0 +1,21 @@
+import { EntityDefinition, EntityId } from '../geometry/entityModel.cjs';
+import { PointId } from '../geometry/point.cjs';
+import { ConstructionEndpoint, ConstructionNotice } from './constructionCommand.cjs';
+type EntityRecord = Readonly<Record<EntityId, EntityDefinition>>;
+/**
+ * The first entity in `entities`, in record order, that declares the same
+ * construction as `candidate`, or `null`. `owns` narrows the search to one
+ * ownership domain: a student's answer may repeat a given, never their own work.
+ */
+export declare function findSameConstruction(entities: EntityRecord, candidate: EntityDefinition, owns?: (id: EntityId) => boolean): EntityId | null;
+/**
+ * The points a connection's `create` endpoints should land on instead of new
+ * ones, one answer per endpoint (`null` for an `existing` end, or one with
+ * nothing to land on): the first point with exactly that origin anywhere on
+ * the canvas. Givens come first — read through the attempt, since a moved
+ * draggable given is where the attempt says — then the attempt's own points in
+ * record order. Both ends in one pass, because a gesture asks for both at once.
+ */
+export declare function findEndpointsInScene(endpoints: readonly ConstructionEndpoint[], givens: EntityRecord, attempt?: EntityRecord): (PointId | null)[];
+export declare function duplicateOf(entityId: EntityId): ConstructionNotice;
+export {};

package/dist/store/constructionIdentity.d.ts

@@ -0,0 +1,22 @@
+import { EntityDefinition, EntityId } from '../geometry/entityModel.js';
+import { PointId } from '../geometry/point.js';
+import { ConstructionEndpoint, ConstructionNotice } from './constructionCommand.js';
+type EntityRecord = Readonly<Record<EntityId, EntityDefinition>>;
+/**
+ * The first entity in `entities`, in record order, that declares the same
+ * construction as `candidate`, or `null`. `owns` narrows the search to one
+ * ownership domain: a student's answer may repeat a given, never their own work.
+ */
+export declare function findSameConstruction(entities: EntityRecord, candidate: EntityDefinition, owns?: (id: EntityId) => boolean): EntityId | null;
+/**
+ * The points a connection's `create` endpoints should land on instead of new
+ * ones, one answer per endpoint (`null` for an `existing` end, or one with
+ * nothing to land on): the first point with exactly that origin anywhere on
+ * the canvas. Givens come first — read through the attempt, since a moved
+ * draggable given is where the attempt says — then the attempt's own points in
+ * record order. Both ends in one pass, because a gesture asks for both at once.
+ */
+export declare function findEndpointsInScene(endpoints: readonly ConstructionEndpoint[], givens: EntityRecord, attempt?: EntityRecord): (PointId | null)[];
+export declare function duplicateOf(entityId: EntityId): ConstructionNotice;
+export {};
+//# sourceMappingURL=constructionIdentity.d.ts.map

package/dist/store/constructionIdentity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constructionIdentity.d.ts","sourceRoot":"","sources":["../../src/store/constructionIdentity.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAA;AACzE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAA;AAGhD,OAAO,KAAK,EAAE,oBAAoB,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAA;AASrF,KAAK,YAAY,GAAG,QAAQ,CAAC,MAAM,CAAC,QAAQ,EAAE,gBAAgB,CAAC,CAAC,CAAA;AA0ChE;;;;GAIG;AACH,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,YAAY,EACtB,SAAS,EAAE,gBAAgB,EAC3B,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,QAAQ,KAAK,OAAO,GAC/B,QAAQ,GAAG,IAAI,CASjB;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAClC,SAAS,EAAE,SAAS,oBAAoB,EAAE,EAC1C,MAAM,EAAE,YAAY,EACpB,OAAO,GAAE,YAAiB,GACzB,CAAC,OAAO,GAAG,IAAI,CAAC,EAAE,CA+BpB;AAED,wBAAgB,WAAW,CAAC,QAAQ,EAAE,QAAQ,GAAG,kBAAkB,CAElE"}

package/dist/store/createStore.d.cts

@@ -0,0 +1,6 @@
+export interface Store<T> {
+    getState(): T;
+    setState(update: Partial<T> | ((state: T) => Partial<T>)): void;
+    subscribe(listener: (state: T, previousState: T) => void): () => void;
+}
+export declare function createStore<T extends object>(initialState: T): Store<T>;

package/dist/store/createStore.d.ts

@@ -0,0 +1,7 @@
+export interface Store<T> {
+    getState(): T;
+    setState(update: Partial<T> | ((state: T) => Partial<T>)): void;
+    subscribe(listener: (state: T, previousState: T) => void): () => void;
+}
+export declare function createStore<T extends object>(initialState: T): Store<T>;
+//# sourceMappingURL=createStore.d.ts.map

package/dist/store/createStore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"createStore.d.ts","sourceRoot":"","sources":["../../src/store/createStore.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,KAAK,CAAC,CAAC;IACtB,QAAQ,IAAI,CAAC,CAAA;IACb,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,CAAA;IAC/D,SAAS,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,CAAC,EAAE,aAAa,EAAE,CAAC,KAAK,IAAI,GAAG,MAAM,IAAI,CAAA;CACtE;AAED,wBAAgB,WAAW,CAAC,CAAC,SAAS,MAAM,EAAE,YAAY,EAAE,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,CAqBvE"}

package/dist/store/history.d.cts

@@ -0,0 +1,2 @@
+export declare const MAX_HISTORY_ENTRIES = 100;
+export declare function pushHistory<T>(past: readonly T[], entry: T): T[];

package/dist/store/history.d.ts

@@ -0,0 +1,3 @@
+export declare const MAX_HISTORY_ENTRIES = 100;
+export declare function pushHistory<T>(past: readonly T[], entry: T): T[];
+//# sourceMappingURL=history.d.ts.map

package/dist/store/history.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"history.d.ts","sourceRoot":"","sources":["../../src/store/history.ts"],"names":[],"mappings":"AAmBA,eAAO,MAAM,mBAAmB,MAAM,CAAA;AAEtC,wBAAgB,WAAW,CAAC,CAAC,EAAE,IAAI,EAAE,SAAS,CAAC,EAAE,EAAE,KAAK,EAAE,CAAC,GAAG,CAAC,EAAE,CAGhE"}

package/dist/store/studentStore.d.cts

@@ -0,0 +1,151 @@
+import { GeometryExercise } from '../schemas/exercise.schema.cjs';
+import { GeometryState } from '../schemas/geometryState.schema.cjs';
+import { PointDefinition } from '../geometry/entityModel.cjs';
+import { ObjectTypeName } from '../schemas/objectTypeName.schema.cjs';
+import { Point, PointId } from '../geometry/point.cjs';
+import { RevealedAnswerShape } from '../validation/types.cjs';
+import { ConstructionCommand, ConstructionNotice } from './constructionCommand.cjs';
+import { StudentAttemptChangeReceipt } from './attemptChange.cjs';
+import { Store } from './createStore.cjs';
+export type { StudentAttemptChangeReceipt, StudentGeometryAction, StudentGeometryChangeMeta, } from './attemptChange.cjs';
+export type { ConstructionCommand, ConstructionEndpoint, ConstructionNotice, } from './constructionCommand.cjs';
+export interface StudentState {
+    exercise: GeometryExercise;
+    geometry: GeometryState;
+    pendingObjectType: ObjectTypeName | null;
+    pendingFirstPointId: PointId | null;
+    selectedObjectId: string | null;
+    past: GeometryState[];
+    future: GeometryState[];
+    coalesceTag: string | null;
+    interactionEpoch?: number;
+    constructionNotice?: ConstructionNotice | null;
+    readOnly?: boolean;
+    lastAttemptChange?: StudentAttemptChangeReceipt | null;
+}
+export interface StudentRemovalImpact {
+    constructionIds: string[];
+    pointIds: string[];
+}
+/**
+ * One store per attempt. Pass `savedGeometry` to resume a stored attempt —
+ * validate it first with validateGeometryStateJson(), which checks it against
+ * this exercise. A resumed attempt starts with empty history: undo must not
+ * reach back past what the student can see.
+ *
+ * The store holds the exercise without its authored `solution` (ADR 0015):
+ * the canonical answer is never student state.
+ */
+export declare function createStudentStore(exercise: GeometryExercise, savedGeometry?: GeometryState): Store<StudentState>;
+/**
+ * Locks or unlocks the attempt (RFC 0005 § Decision 3). While read-only every
+ * public student action that could change attempt data does nothing and no
+ * tool can be armed; selection stays available for inspection.
+ *
+ * Locking disarms the tool and clears the pending endpoint, the selection and
+ * the notice, and moves the epoch so a late pointer release writes nothing. A
+ * drag whose frames already moved a point keeps that position, its one undo
+ * entry and its one `point-moved` receipt, all in the locking transition.
+ * Unlocking moves the epoch as well, so a contact pressed during the lock
+ * cannot start editing once it lifts; no point is draggable while locked.
+ * `replaceStudentAttempt()` and `replaceStudentSession()` still work while
+ * locked; `store.setState()` is not guarded at all.
+ */
+export declare function setStudentReadOnly(store: Store<StudentState>, readOnly: boolean): void;
+/**
+ * Host authority: installs `attempt` on the same store, as a controlled value
+ * that differs from the current one (RFC 0005 § Decision 2). Both history
+ * stacks and all interaction state are cleared and the epoch moves, so it
+ * cannot be undone and a live gesture is dropped. Works while read-only, and is
+ * not a student action: `lastAttemptChange` is left as it was, and a drag it
+ * interrupts gets no receipt.
+ *
+ * The attempt is taken as already parsed and checked against this exercise —
+ * validate untrusted input first, as for `createStudentStore()`.
+ */
+export declare function replaceStudentAttempt(store: Store<StudentState>, attempt: GeometryState): void;
+/**
+ * Host authority: installs a different exercise and its attempt together, in
+ * one transition, so no subscriber ever sees the new exercise with the old
+ * attempt. An absent attempt is a fresh empty one. Otherwise it behaves as
+ * `replaceStudentAttempt()` does: same store, history and interaction state
+ * cleared, epoch moved, read-only kept, no receipt, and parsed input expected.
+ * As at creation, the authored `solution` is left out of the store.
+ */
+export declare function replaceStudentSession(store: Store<StudentState>, exercise: GeometryExercise, attempt?: GeometryState): void;
+export declare function selectStudentObjectType(store: Store<StudentState>, type: ObjectTypeName | null): void;
+/**
+ * Abandons a click-click construction in progress: the first endpoint is
+ * forgotten and the tool stays armed. What a canvas calls when a gesture is
+ * cancelled — a system gesture, a second finger, a release off the canvas —
+ * so the next tap starts a construction rather than finishing a stale one.
+ */
+export declare function cancelStudentConstruction(store: Store<StudentState>): void;
+export declare function undoStudentChange(store: Store<StudentState>): void;
+export declare function redoStudentChange(store: Store<StudentState>): void;
+/**
+ * Starts the attempt over on the same store (RFC 0004 § Decision 2): the
+ * exercise and its givens stay, and everything the student did goes — their
+ * constructions, any given they dragged (it returns to where the teacher put
+ * it), the tool, the selection, a pending endpoint and the notice. A resumed
+ * attempt resets to empty, not to what was saved.
+ *
+ * Not undoable: both history stacks are emptied, so neither Undo nor Redo can
+ * bring the old attempt back. The store object and its subscribers are kept.
+ * The epoch moves even when the attempt was already empty, which is how a
+ * canvas drops a gesture in flight, and a host clearing checked feedback on a
+ * geometry or epoch change sees every reset. Nothing saved outside the store
+ * is touched.
+ *
+ * A student action: it does nothing while read-only, and it records a `reset`
+ * receipt even for an attempt that was already empty.
+ */
+export declare function resetStudentAttempt(store: Store<StudentState>): void;
+export declare function addStudentPoint(store: Store<StudentState>, definition: PointDefinition, countsAsConstruction?: boolean): PointId | null;
+export declare function promoteStudentPoint(store: Store<StudentState>, pointId: PointId): void;
+/**
+ * Drags a point to `point`, respecting what the point is:
+ * - free: takes the new coordinates;
+ * - on-object: slides along its object, so the drag re-parameterizes rather
+ *   than detaching it (a point placed on a line stays on that line);
+ * - intersection: ignored — its position is its parents' to decide.
+ */
+export declare function moveStudentPoint(store: Store<StudentState>, pointId: PointId, point: Point): void;
+export declare function isStudentPointDraggable(state: StudentState, pointId: PointId): boolean;
+export declare function endStudentPointDrag(store: Store<StudentState>): void;
+/**
+ * The one way a gesture becomes geometry (RFC 0001 § 11).
+ *
+ * Two rules the pre-M2.9 code broke, both of them here now:
+ *
+ * 1. **One gesture is one commit is one undo.** Every entity the command needs
+ *    is written inside a single `commitGeometry()`, so a segment that had to
+ *    invent its endpoint still costs the student exactly one undo — and undoing
+ *    it takes the invented point with it.
+ * 2. **An invented endpoint is not part of the answer.** Only the shape the
+ *    student drew is, which is what keeps a `create` goal from being satisfied
+ *    by scaffolding they never chose to make.
+ *
+ * A third since RFC 0004: **a construction the student already built is not
+ * built twice.** The whole staged document is dropped — no invented point, no
+ * history entry, the redo stack intact — and `constructionNotice` names the one
+ * that is there.
+ */
+export declare function executeConstruction(store: Store<StudentState>, command: ConstructionCommand): void;
+export declare function pickStudentPoint(store: Store<StudentState>, pointId: PointId): void;
+export declare function selectStudentObject(store: Store<StudentState>, id: string | null): void;
+export declare function isStudentOwned(state: StudentState, id: string): boolean;
+/**
+ * Everything that disappears along with `id`, the target included, the same
+ * way getGivenRemovalImpact() reports cascades on the teacher side.
+ *
+ * The cascade follows the dependency graph upwards: a construction needs its
+ * endpoints, and a derived point needs its objects, so deleting a segment can
+ * strip an intersection point, which can strip a construction that used it,
+ * and so on. Since M2.2 that is one walk of the context's reverse edges — the
+ * fixpoint loop it replaces rescanned both documents once per entity it
+ * removed.
+ */
+export declare function getStudentRemovalImpact(state: StudentState, id: string): StudentRemovalImpact;
+export declare function deleteStudentObject(store: Store<StudentState>, id: string): void;
+export declare function revealStudentAnswer(store: Store<StudentState>, shape: RevealedAnswerShape): void;