@classytic/stage 0.1.0

package/dist/chem/index.mjs

@@ -0,0 +1,131 @@
+//#region src/chem/index.ts
+/**
+* `chem` — acid–base / pH AND electrochemistry / Nernst, as a PURE kernel (no
+* React, no pixels). The engine behind titration curves, pH problems, and galvanic
+* cells.
+*
+* pH at any point is found by solving the exact charge balance for [H⁺] = h:
+*
+*     [titrant cation] + h  =  [OH⁻] + [A⁻]
+*     n_b/V + h  =  K_w/h  +  (n_a/V)·K_a/(K_a + h)
+*
+* where n_a is the acid initially present, n_b the strong base added, V the total
+* volume. A strong acid is just the K_a → ∞ limit (fully dissociated). Solving the
+* balance (monotonic in h → bisection) is robust everywhere — initial point, buffer
+* region, equivalence, and past it — with no piecewise approximations to get wrong.
+*
+* Concentrations in mol/L, volumes in litres. Currently models an ACID analyte
+* titrated by a STRONG BASE (covers strong-acid and weak-acid curves).
+*/
+const Kw = 1e-14;
+const kaOf = (spec) => spec.analyte === "strong-acid" ? 1e9 : 10 ** -(spec.pKa ?? 4.76);
+/** Solve the charge balance n_b/V + h = K_w/h + (n_a/V)·K_a/(K_a+h) for h>0. */
+function solveH(naOverV, nbOverV, Ka) {
+	const f = (h) => nbOverV + h - Kw / h - naOverV * Ka / (Ka + h);
+	let lo = 1e-14, hi = 10;
+	for (let i = 0; i < 200; i++) {
+		const mid = Math.sqrt(lo * hi);
+		if (f(mid) > 0) hi = mid;
+		else lo = mid;
+	}
+	return Math.sqrt(lo * hi);
+}
+/** pH after adding `Vb` litres of titrant. */
+function pHAt(spec, Vb) {
+	const Ka = kaOf(spec);
+	const na = spec.Ca * spec.Va;
+	const nb = spec.Cb * Math.max(0, Vb);
+	const V = spec.Va + Math.max(0, Vb);
+	const h = solveH(na / V, nb / V, Ka);
+	return -Math.log10(h);
+}
+/** Sample the full titration curve from 0 to `span`·vEq (default 2×). */
+function titrationCurve(spec, n = 160, span = 2) {
+	const vEq = spec.Ca * spec.Va / spec.Cb;
+	const vMax = vEq * span;
+	const points = [];
+	for (let i = 0; i <= n; i++) {
+		const v = i / n * vMax;
+		points.push({
+			v,
+			pH: pHAt(spec, v)
+		});
+	}
+	return {
+		points,
+		vEq,
+		pHEq: pHAt(spec, vEq),
+		pHHalf: pHAt(spec, vEq / 2),
+		pKa: spec.analyte === "weak-acid" ? spec.pKa ?? 4.76 : NaN
+	};
+}
+/** Universal gas constant, J/(mol·K). */
+const R = 8.314462618;
+/** Faraday constant, C/mol. */
+const F = 96485.332;
+/** Standard temperature, K (25 °C). */
+const T_STD = 298.15;
+const gcd = (a, b) => b === 0 ? a : gcd(b, a % b);
+const lcm = (a, b) => a * b / gcd(a, b);
+/** Galvanic cell from two half-cells; cathode/anode assigned by standard potential. */
+function galvanicCell(x, y, T = T_STD) {
+	const xIsCathode = x.E0 > y.E0 || x.E0 === y.E0 && x.conc >= y.conc;
+	const cathode = xIsCathode ? x : y;
+	const anode = xIsCathode ? y : x;
+	const E0cell = cathode.E0 - anode.E0;
+	const n = lcm(anode.z, cathode.z);
+	const Q = Math.pow(anode.conc, n / anode.z) / Math.pow(cathode.conc, n / cathode.z);
+	const E = E0cell - R * T / (n * F) * Math.log(Q);
+	return {
+		cathode,
+		anode,
+		E0cell,
+		n,
+		Q,
+		E,
+		spontaneous: E > 0
+	};
+}
+/** Arrhenius rate constant k = A·e^(−Ea/RT). */
+function arrhenius(A, Ea, T) {
+	return A * Math.exp(-Ea / (R * T));
+}
+/** Ratio k(T)/k(Tref) at fixed Ea — the stable way to scale a rate without a raw A. */
+function arrheniusRatio(Ea, T, Tref = T_STD) {
+	return Math.exp(-(Ea / R) * (1 / T - 1 / Tref));
+}
+/** Fraction of molecules with energy ≥ Ea (Boltzmann) ≈ e^(−Ea/RT). */
+function fractionAboveEa(Ea, T) {
+	return Math.exp(-Ea / (R * T));
+}
+/** Concentration [A] at time t for a reaction of the given order, rate = k·[A]^order. */
+function concAt(order, A0, k, t) {
+	if (order === 0) return Math.max(0, A0 - k * t);
+	if (order === 1) return A0 * Math.exp(-k * t);
+	return A0 / (1 + A0 * k * t);
+}
+/** Half-life for the given order (constant only for first order). */
+function halfLife(order, A0, k) {
+	if (order === 0) return A0 / (2 * k);
+	if (order === 1) return Math.LN2 / k;
+	return 1 / (k * A0);
+}
+/** Solve a balanced reaction for the limiting reagent, extent, products and leftovers. */
+function solveStoichiometry(reactants, products, amountsMol) {
+	const ratios = reactants.map((r, i) => (amountsMol[i] ?? 0) / r.coeff);
+	const extent = Math.min(...ratios);
+	return {
+		extent,
+		limiting: reactants.filter((_, i) => Math.abs(ratios[i] - extent) < 1e-9).map((r) => r.name),
+		consumed: reactants.map((r) => r.coeff * extent),
+		leftover: reactants.map((r, i) => (amountsMol[i] ?? 0) - r.coeff * extent),
+		products: products.map((p) => ({
+			name: p.name,
+			moles: p.coeff * extent,
+			grams: p.molarMass != null ? p.coeff * extent * p.molarMass : void 0
+		}))
+	};
+}
+
+//#endregion
+export { F, Kw, R, T_STD, arrhenius, arrheniusRatio, concAt, fractionAboveEa, galvanicCell, halfLife, pHAt, solveStoichiometry, titrationCurve };

package/dist/core/clock.d.mts

@@ -0,0 +1,41 @@
+import { ReactNode } from "react";
+
+//#region src/core/clock.d.ts
+interface FrameInfo {
+  /** Milliseconds on the active timeline. */
+  timeMs: number;
+  /** Delta since previous tick, ms. */
+  dtMs: number;
+  /** Monotonic frame counter. */
+  frame: number;
+  /** Frames per second (measured for RAF; exact for a fixed driver). */
+  fps: number;
+}
+/** A frame source: push `FrameInfo` to subscribers. Implement this to drive
+ *  the engine from a non-RAF timeline (e.g. Remotion). */
+interface FrameDriver {
+  subscribe(cb: (f: FrameInfo) => void): () => void;
+}
+interface ClockProviderProps {
+  driver: FrameDriver;
+  children: ReactNode;
+}
+/** Override the default RAF loop for everything inside (e.g. Remotion). */
+declare function ClockProvider({
+  driver,
+  children
+}: ClockProviderProps): ReactNode;
+/**
+ * Run `cb` once per frame from the active clock. Default = RAF. When `running`
+ * is false the loop is idle. `cb` is held in a ref so changing it doesn't
+ * restart the loop.
+ *
+ * Visibility/offscreen pausing is NOT this hook's job — gate `running` on
+ * `useInView()` (the one canonical hook) for that: `useFrameLoop(tick, { running:
+ * playing && inView })`. Keeps the clock a single-purpose primitive.
+ */
+declare function useFrameLoop(cb: (f: FrameInfo) => void, options?: {
+  running?: boolean;
+}): void;
+//#endregion
+export { ClockProvider, ClockProviderProps, FrameDriver, FrameInfo, useFrameLoop };

package/dist/core/clock.mjs

@@ -0,0 +1,62 @@
+'use client';
+
+import { createContext, createElement, useContext, useEffect, useRef } from "react";
+
+//#region src/core/clock.ts
+/**
+* Injectable clock. Components drive animation through `useFrameLoop(cb)` instead
+* of calling `requestAnimationFrame` directly. By default that's a RAF loop
+* (interactive). A host can wrap a subtree in `<ClockProvider driver={…}>` to
+* supply frames from another source — e.g. a Remotion app pushing
+* `useCurrentFrame()`-derived frames for deterministic, scrubbable video. The
+* engine itself stays unaware of Remotion.
+*
+* Discipline for video-determinism: compute visuals from the `FrameInfo` you
+* receive (timeMs / frame), not a private accumulating counter — so the same
+* component renders identically at any frame.
+*/
+const DriverContext = createContext(null);
+/** Override the default RAF loop for everything inside (e.g. Remotion). */
+function ClockProvider({ driver, children }) {
+	return createElement(DriverContext.Provider, { value: driver }, children);
+}
+const now = () => typeof performance !== "undefined" ? performance.now() : Date.now();
+/**
+* Run `cb` once per frame from the active clock. Default = RAF. When `running`
+* is false the loop is idle. `cb` is held in a ref so changing it doesn't
+* restart the loop.
+*
+* Visibility/offscreen pausing is NOT this hook's job — gate `running` on
+* `useInView()` (the one canonical hook) for that: `useFrameLoop(tick, { running:
+* playing && inView })`. Keeps the clock a single-purpose primitive.
+*/
+function useFrameLoop(cb, options = {}) {
+	const { running = true } = options;
+	const driver = useContext(DriverContext);
+	const cbRef = useRef(cb);
+	cbRef.current = cb;
+	useEffect(() => {
+		if (!running) return;
+		if (driver) return driver.subscribe((f) => cbRef.current(f));
+		let raf = 0;
+		let last = now();
+		let frame = 0;
+		const loop = () => {
+			const t = now();
+			const dtMs = t - last;
+			last = t;
+			cbRef.current({
+				timeMs: t,
+				dtMs,
+				frame: frame++,
+				fps: dtMs > 0 ? 1e3 / dtMs : 60
+			});
+			raf = requestAnimationFrame(loop);
+		};
+		raf = requestAnimationFrame(loop);
+		return () => cancelAnimationFrame(raf);
+	}, [running, driver]);
+}
+
+//#endregion
+export { ClockProvider, useFrameLoop };

package/dist/core/context.d.mts

@@ -0,0 +1,13 @@
+import { Vec2 } from "./vec.mjs";
+import { CoordinateSystem } from "./coords.mjs";
+import { RefObject } from "react";
+
+//#region src/core/context.d.ts
+declare const CoordsContext: import("react").Context<CoordinateSystem | null>;
+declare function useCoords(): CoordinateSystem;
+declare const StageRefContext: import("react").Context<RefObject<SVGSVGElement | null> | null>;
+declare function useStageRef(): RefObject<SVGSVGElement | null> | null;
+declare const DragOverlayContext: import("react").Context<ReadonlyMap<string, Vec2>>;
+declare function useDragOverlay(): ReadonlyMap<string, Vec2>;
+//#endregion
+export { CoordsContext, DragOverlayContext, StageRefContext, useCoords, useDragOverlay, useStageRef };

package/dist/core/context.mjs

@@ -0,0 +1,29 @@
+'use client';
+
+import { createContext, useContext } from "react";
+
+//#region src/core/context.ts
+/**
+* Engine React contexts. Kept dependency-light: the scene/editor contexts are
+* added in the scene-graph phase. Primitives read CoordsContext; interaction
+* reads StageRefContext (for getScreenCTM) and DragOverlayContext (ephemeral
+* per-frame drag values that resolve() reads without mutating the doc).
+*/
+const CoordsContext = createContext(null);
+function useCoords() {
+	const c = useContext(CoordsContext);
+	if (!c) throw new Error("Stage primitives must be rendered inside <Stage>.");
+	return c;
+}
+const StageRefContext = createContext(null);
+function useStageRef() {
+	return useContext(StageRefContext);
+}
+const EMPTY_OVERLAY = /* @__PURE__ */ new Map();
+const DragOverlayContext = createContext(EMPTY_OVERLAY);
+function useDragOverlay() {
+	return useContext(DragOverlayContext);
+}
+
+//#endregion
+export { CoordsContext, DragOverlayContext, StageRefContext, useCoords, useDragOverlay, useStageRef };

package/dist/core/control.d.mts

@@ -0,0 +1,58 @@
+//#region src/core/control.d.ts
+type ControlSpec = {
+  type: 'number';
+  label?: string;
+  min?: number;
+  max?: number;
+  step?: number;
+  unit?: string;
+  get: () => number;
+  set: (v: number) => void;
+} | {
+  type: 'boolean';
+  label?: string;
+  get: () => boolean;
+  set: (v: boolean) => void;
+} | {
+  type: 'enum';
+  label?: string;
+  options: readonly string[];
+  get: () => string;
+  set: (v: string) => void;
+} | {
+  type: 'action';
+  label?: string;
+  invoke: () => void;
+};
+type ControlMap = Record<string, ControlSpec>;
+interface ControlSurface {
+  readonly id: string;
+  /** Machine-readable description of every control (for agent discovery). */
+  describe(): Array<{
+    name: string;
+    type: ControlSpec['type'];
+    label?: string;
+    value?: unknown;
+    min?: number;
+    max?: number;
+    options?: readonly string[];
+  }>;
+  get(name: string): unknown;
+  set(name: string, value: unknown): boolean;
+  invoke(name: string): boolean;
+}
+/**
+ * Register a widget's controls under `id` for its lifetime (no-op if `id` is
+ * undefined). Registration happens in an effect (render stays side-effect-free,
+ * per React 19 / concurrent rules); a ref holds the latest controls so getters
+ * and setters always see current state.
+ */
+declare function useControlSurface(id: string | undefined, controls: ControlMap): void;
+/** Look up a live control surface by id (returns null if no such widget is mounted). */
+declare function getControlSurface(id: string): ControlSurface | null;
+/** Every mounted control surface — for an agent to discover what's on the page. */
+declare function listControlSurfaces(): ControlSurface[];
+/** Subscribe to registry changes (surfaces mounting/unmounting or values set). */
+declare function onControlChange(fn: () => void): () => void;
+//#endregion
+export { ControlMap, ControlSpec, ControlSurface, getControlSurface, listControlSurfaces, onControlChange, useControlSurface };

package/dist/core/control.mjs

@@ -0,0 +1,113 @@
+'use client';
+
+import { useEffect, useRef } from "react";
+
+//#region src/core/control.ts
+/**
+* control — an addressable control surface so an external driver (a voice/AI
+* agent, an autograder, a Remotion timeline, a "show me" button) can inspect and
+* operate a live visualization without prop-drilling.
+*
+* A widget registers named controls under an `id`; anyone can later look the id
+* up and read/set values or invoke actions:
+*
+*   useControlSurface('balance-1', {
+*     x:    { type: 'number', min: 0, max: 8, get: () => x, set: setX },
+*     check:{ type: 'action', invoke: () => grade() },
+*   });
+*
+*   getControlSurface('balance-1')?.set('x', 3);
+*   listControlSurfaces(); // discover what's on the page
+*
+* In scene/builder mode, prefer `controlsFromScene(editor, …)` so set() routes
+* through the editor's command stack (undoable + persisted) instead of raw
+* closures.
+*/
+const registry = /* @__PURE__ */ new Map();
+const listeners = /* @__PURE__ */ new Set();
+const notify = () => listeners.forEach((l) => l());
+function makeSurface(id, getControls) {
+	return {
+		id,
+		describe: () => Object.entries(getControls()).map(([name, c]) => ({
+			name,
+			type: c.type,
+			label: c.label,
+			value: c.type === "action" ? void 0 : c.get(),
+			...c.type === "number" ? {
+				min: c.min,
+				max: c.max
+			} : {},
+			...c.type === "enum" ? { options: c.options } : {}
+		})),
+		get: (name) => {
+			const c = getControls()[name];
+			return c && c.type !== "action" ? c.get() : void 0;
+		},
+		set: (name, value) => {
+			const c = getControls()[name];
+			if (!c || c.type === "action") return false;
+			if (c.type === "number" && typeof value === "number") {
+				c.set(value);
+				notify();
+				return true;
+			}
+			if (c.type === "boolean" && typeof value === "boolean") {
+				c.set(value);
+				notify();
+				return true;
+			}
+			if (c.type === "enum" && typeof value === "string" && c.options.includes(value)) {
+				c.set(value);
+				notify();
+				return true;
+			}
+			return false;
+		},
+		invoke: (name) => {
+			const c = getControls()[name];
+			if (c?.type === "action") {
+				c.invoke();
+				notify();
+				return true;
+			}
+			return false;
+		}
+	};
+}
+/**
+* Register a widget's controls under `id` for its lifetime (no-op if `id` is
+* undefined). Registration happens in an effect (render stays side-effect-free,
+* per React 19 / concurrent rules); a ref holds the latest controls so getters
+* and setters always see current state.
+*/
+function useControlSurface(id, controls) {
+	const ref = useRef(controls);
+	ref.current = controls;
+	useEffect(() => {
+		if (!id) return;
+		registry.set(id, () => ref.current);
+		notify();
+		return () => {
+			registry.delete(id);
+			notify();
+		};
+	}, [id]);
+}
+/** Look up a live control surface by id (returns null if no such widget is mounted). */
+function getControlSurface(id) {
+	const getControls = registry.get(id);
+	return getControls ? makeSurface(id, getControls) : null;
+}
+/** Every mounted control surface — for an agent to discover what's on the page. */
+function listControlSurfaces() {
+	return [...registry.entries()].map(([id, getControls]) => makeSurface(id, getControls));
+}
+/** Subscribe to registry changes (surfaces mounting/unmounting or values set). */
+function onControlChange(fn) {
+	listeners.add(fn);
+	return () => listeners.delete(fn);
+}
+
+//#endregion
+export { getControlSurface, listControlSurfaces, onControlChange, useControlSurface };

package/dist/core/coords.d.mts

@@ -0,0 +1,51 @@
+//#region src/core/coords.d.ts
+/**
+ * CoordinateSystem — the math↔pixel mapping that decouples mathematical
+ * coordinates from screen pixels. Primitives draw in math units; pan/zoom/resize
+ * are trivial because only the mapping changes.
+ *
+ * Convention: math y is UP (standard), screen y is DOWN — the mapping flips it.
+ * Every stage primitive emits PIXEL coordinates via toPx() into one space — there
+ * is no global CSS-matrix group (it would mirror text, scale strokes, and desync
+ * getScreenCTM-based pointer math under zoom).
+ */
+interface ViewBox {
+  /** Visible math range. */
+  xMin: number;
+  xMax: number;
+  yMin: number;
+  yMax: number;
+}
+interface CoordinateSystem {
+  readonly view: ViewBox;
+  readonly width: number;
+  readonly height: number;
+  /** math (x,y) → pixel (px,py). */
+  toPx(x: number, y: number): [number, number];
+  /** pixel (px,py) → math (x,y). */
+  toMath(px: number, py: number): [number, number];
+  /** Scale a math x-distance to pixels. */
+  sx(dx: number): number;
+  /** Scale a math y-distance to pixels (magnitude). */
+  sy(dy: number): number;
+}
+/**
+ * Round an emitted SVG coordinate to a stable precision (3 dp ≈ 1/1000 px, far
+ * below sub-pixel). Use this for EVERY pixel value written into SVG attributes —
+ * never for `toMath`/hit-testing math. It exists for SSR determinism: a
+ * coordinate derived from a transcendental (`Math.sin`, `pow`, the expr engine)
+ * can differ in its last bits between the server's V8 and the browser's V8,
+ * producing a React hydration mismatch on the raw float. Rounding makes the
+ * serialized string identical on both sides.
+ */
+declare const fmt: (n: number) => number;
+interface CoordsOptions {
+  /** Inner padding in pixels (keeps content off the edges). */
+  pad?: number;
+  /** Preserve aspect ratio (uses the smaller of x/y scales for both). Default true. */
+  preserveAspect?: boolean;
+}
+/** Build a CoordinateSystem for a viewport of `width`×`height` (CSS px) showing `view`. */
+declare function createCoords(width: number, height: number, view: ViewBox, options?: CoordsOptions): CoordinateSystem;
+//#endregion
+export { CoordinateSystem, CoordsOptions, ViewBox, createCoords, fmt };

package/dist/core/coords.mjs

@@ -0,0 +1,44 @@
+//#region src/core/coords.ts
+/**
+* Round an emitted SVG coordinate to a stable precision (3 dp ≈ 1/1000 px, far
+* below sub-pixel). Use this for EVERY pixel value written into SVG attributes —
+* never for `toMath`/hit-testing math. It exists for SSR determinism: a
+* coordinate derived from a transcendental (`Math.sin`, `pow`, the expr engine)
+* can differ in its last bits between the server's V8 and the browser's V8,
+* producing a React hydration mismatch on the raw float. Rounding makes the
+* serialized string identical on both sides.
+*/
+const fmt = (n) => Math.round(n * 1e3) / 1e3;
+/** Build a CoordinateSystem for a viewport of `width`×`height` (CSS px) showing `view`. */
+function createCoords(width, height, view, options = {}) {
+	const { pad = 0, preserveAspect = true } = options;
+	const w = Math.max(1, width - pad * 2);
+	const h = Math.max(1, height - pad * 2);
+	const spanX = view.xMax - view.xMin || 1;
+	const spanY = view.yMax - view.yMin || 1;
+	let scaleX = w / spanX;
+	let scaleY = h / spanY;
+	if (preserveAspect) {
+		const s = Math.min(scaleX, scaleY);
+		scaleX = s;
+		scaleY = s;
+	}
+	const drawW = spanX * scaleX;
+	const drawH = spanY * scaleY;
+	const offX = pad + (w - drawW) / 2;
+	const offY = pad + (h - drawH) / 2;
+	const toPx = (x, y) => [offX + (x - view.xMin) * scaleX, offY + (view.yMax - y) * scaleY];
+	const toMath = (px, py) => [view.xMin + (px - offX) / scaleX, view.yMax - (py - offY) / scaleY];
+	return {
+		view,
+		width,
+		height,
+		toPx,
+		toMath,
+		sx: (dx) => dx * scaleX,
+		sy: (dy) => dy * scaleY
+	};
+}
+
+//#endregion
+export { createCoords, fmt };

package/dist/core/index.d.mts

@@ -0,0 +1,8 @@
+import { Matrix, Vec2, mat, vec } from "./vec.mjs";
+import { CoordinateSystem, CoordsOptions, ViewBox, createCoords, fmt } from "./coords.mjs";
+import { ControlMap, ControlSpec, ControlSurface, getControlSurface, listControlSurfaces, onControlChange, useControlSurface } from "./control.mjs";
+import { CoordsContext, DragOverlayContext, StageRefContext, useCoords, useDragOverlay, useStageRef } from "./context.mjs";
+import { ClockProvider, ClockProviderProps, FrameDriver, FrameInfo, useFrameLoop } from "./clock.mjs";
+import { Learner, LearnerProvider, LearnerResult, PriorAttempts, useLearner } from "./learner.mjs";
+import { EaseFn, EaseName, Keyframe, OscillateOpts, SpringOpts, WaveShape, ease, lerp, oscillate, prefersReducedMotion, spring, timeline } from "./motion.mjs";
+export { ClockProvider, type ClockProviderProps, type ControlMap, type ControlSpec, type ControlSurface, type CoordinateSystem, CoordsContext, type CoordsOptions, DragOverlayContext, type EaseFn, type EaseName, type FrameDriver, type FrameInfo, type Keyframe, type Learner, LearnerProvider, type LearnerResult, type Matrix, type OscillateOpts, type PriorAttempts, type SpringOpts, StageRefContext, type Vec2, type ViewBox, type WaveShape, createCoords, ease, fmt, getControlSurface, lerp, listControlSurfaces, mat, onControlChange, oscillate, prefersReducedMotion, spring, timeline, useControlSurface, useCoords, useDragOverlay, useFrameLoop, useLearner, useStageRef, vec };

package/dist/core/index.mjs

@@ -0,0 +1,9 @@
+import { createCoords, fmt } from "./coords.mjs";
+import { mat, vec } from "./vec.mjs";
+import { CoordsContext, DragOverlayContext, StageRefContext, useCoords, useDragOverlay, useStageRef } from "./context.mjs";
+import { ClockProvider, useFrameLoop } from "./clock.mjs";
+import { getControlSurface, listControlSurfaces, onControlChange, useControlSurface } from "./control.mjs";
+import { LearnerProvider, useLearner } from "./learner.mjs";
+import { ease, lerp, oscillate, prefersReducedMotion, spring, timeline } from "./motion.mjs";
+
+export { ClockProvider, CoordsContext, DragOverlayContext, LearnerProvider, StageRefContext, createCoords, ease, fmt, getControlSurface, lerp, listControlSurfaces, mat, onControlChange, oscillate, prefersReducedMotion, spring, timeline, useControlSurface, useCoords, useDragOverlay, useFrameLoop, useLearner, useStageRef, vec };

package/dist/core/learner.d.mts

@@ -0,0 +1,44 @@
+import { ReactNode } from "react";
+
+//#region src/core/learner.d.ts
+interface LearnerResult {
+  /** Stable activity id for this interaction (e.g. a checkpoint key). */
+  activity: string;
+  /** Did the learner satisfy the goal? */
+  correct?: boolean;
+  /** Numeric score, when applicable. */
+  score?: {
+    raw: number;
+    max: number;
+  };
+  /** Free-form response (e.g. the chosen value). */
+  response?: string;
+  /** Mark the activity complete. */
+  completion?: boolean;
+  /** Pedagogy context (from the lab's LabMeta) — e.g. the objective this event
+   *  evidences. The host maps it into xAPI context.extensions. */
+  objectiveId?: string;
+  /** 1-based attempt number, when the host tracks tries. */
+  attempt?: number;
+}
+interface PriorAttempts {
+  bestPct: number;
+  attempts: number;
+}
+interface Learner {
+  /** Fire-and-forget: record an attempt/result. */
+  report(result: LearnerResult): void;
+  /** Optional: prior best for showing "Best: 3/4" etc. */
+  getPrior?(activity: string): PriorAttempts | null;
+}
+declare function LearnerProvider({
+  learner,
+  children
+}: {
+  learner: Learner;
+  children: ReactNode;
+}): ReactNode;
+/** `null` when no host is wired (stateless preview). */
+declare function useLearner(): Learner | null;
+//#endregion
+export { Learner, LearnerProvider, LearnerResult, PriorAttempts, useLearner };

package/dist/core/learner.mjs

@@ -0,0 +1,23 @@
+'use client';
+
+import { createContext, createElement, useContext } from "react";
+
+//#region src/core/learner.ts
+/**
+* Learner / assessment seam — a host-agnostic interface so a visualization can
+* report "the learner did X / got it right" without knowing how it's stored.
+* Mentora provides a `Learner` that maps `report()` to xAPI statements; a plain
+* docs/demo app provides none and the viz degrades to a stateless playground.
+* This is what powers Brilliant-style checkpoints + progress data.
+*/
+const LearnerContext = createContext(null);
+function LearnerProvider({ learner, children }) {
+	return createElement(LearnerContext.Provider, { value: learner }, children);
+}
+/** `null` when no host is wired (stateless preview). */
+function useLearner() {
+	return useContext(LearnerContext);
+}
+
+//#endregion
+export { LearnerProvider, useLearner };