@classytic/stage 0.1.0 → 0.3.0

package/dist/circuit/index.d.mts

@@ -0,0 +1,92 @@
+//#region src/circuit/index.d.ts
+/**
+ * @classytic/stage/circuit, a small, dependency-free circuit-solver kernel (a
+ * mini-SPICE) built on Modified Nodal Analysis (MNA). Like the `field` and `math`
+ * kernels it is pure, deterministic engine machinery: you describe a netlist of
+ * elements (resistors, sources, capacitors, inductors) and it returns the node
+ * voltages and branch currents, the correct numbers, so a current-electricity
+ * lab shows real results instead of hand-rolled per-lab arithmetic.
+ *
+ *   • solveDC       , DC operating point (capacitors open, inductors short).
+ *   • solveTransient, time-stepped response (RC / RL / RLC) via Backward-Euler
+ *                      companion models: each reactive element becomes a
+ *                      conductance Geq in parallel with a current source Ieq each
+ *                      step, exactly how real simulators integrate the ODEs.
+ *
+ * Node 0 is ground (the reference). MNA stamps are additive, so parallel elements
+ * just sum. Nonlinear devices (diodes / transistors via Newton-Raphson) are the
+ * next layer and slot into the same stamping helpers.
+ *
+ * Conventions (validated against the MNA / Qucs companion-model references):
+ *   • Resistor R between (n1,n2): conductance g = 1/R.
+ *   • Current source I: drives `value` amps from n1 to n2 (injected into n2).
+ *   • Voltage source V: value volts, n1 is + relative to n2 (adds a branch current
+ *     unknown). Its solved current is positive flowing n1 → n2 inside the source.
+ */
+type NodeId = number;
+interface Elem {
+  kind: 'R' | 'V' | 'I' | 'C' | 'L' | 'D' | 'M';
+  /** diode: n1=anode, n2=cathode. NMOS 'M': n1=drain, n2=source, n3=gate. */
+  n1: NodeId;
+  n2: NodeId;
+  /** gate node for an NMOS 'M'. */
+  n3?: NodeId;
+  /** ohms (R) / volts (V) / amps (I) / farads (C) / henries (L). Ignored for D / M. */
+  value: number;
+  /** diode saturation current Is (default 1e-12 A). */
+  is?: number;
+  /** diode ideality factor n (default 1). */
+  nIdeal?: number;
+  /** MOSFET threshold voltage Vth (default 2 V; for a PMOS the magnitude is used). */
+  vth?: number;
+  /** MOSFET transconductance parameter k = µCox·W/L (default 0.5 A/V²). */
+  k?: number;
+  /** P-channel MOSFET (conducts when the gate is LOW vs the source). Default NMOS. */
+  pmos?: boolean;
+  /** optional label, used to key the returned branch currents. */
+  id?: string;
+}
+/** Solve A x = b by Gaussian elimination with partial pivoting. Returns null if singular. */
+declare function solveLinear(A: number[][], b: number[]): number[] | null;
+interface DCResult {
+  /** node voltages indexed by node id; [0] is ground = 0. */
+  nodeV: number[];
+  /** current through each branch element (V sources, and inductors), keyed by id. */
+  current: Record<string, number>;
+  ok: boolean;
+}
+/** DC operating point: capacitors open, inductors short. Routes to the nonlinear solver for diodes / MOSFETs. */
+declare function solveDC(elems: readonly Elem[]): DCResult;
+/**
+ * Nonlinear DC via Newton-Raphson: each iteration linearizes every nonlinear device
+ * (diode Shockley with pnjlim limiting; NMOS square-law about the previous node
+ * voltages) into a companion conductance + current source, solves the linear system,
+ * and repeats until the solution settles.
+ */
+declare function solveDCNonlinear(elems: readonly Elem[], opts?: {
+  maxIter?: number;
+  tol?: number;
+}): DCResult;
+/** Current through an element given solved node voltages (R/I directly; C/L need state). */
+declare function elementCurrent(e: Elem, nodeV: number[]): number;
+interface TransientStep {
+  t: number;
+  nodeV: number[];
+}
+interface TransientOpts {
+  dt: number;
+  steps: number;
+  /** initial voltages across reactive elements, keyed by element index (default 0). */
+  initialV?: Map<number, number>;
+}
+/**
+ * Time-stepped transient (Backward Euler). Returns the node-voltage trajectory,
+ * including t = 0. Reactive elements use companion models rebuilt every step.
+ */
+declare function solveTransient(elems: readonly Elem[], opts: TransientOpts): TransientStep[];
+/** Equivalent resistance of resistors in series. */
+declare function seriesR(...rs: number[]): number;
+/** Equivalent resistance of resistors in parallel. */
+declare function parallelR(...rs: number[]): number;
+//#endregion
+export { DCResult, Elem, NodeId, TransientOpts, TransientStep, elementCurrent, parallelR, seriesR, solveDC, solveDCNonlinear, solveLinear, solveTransient };

package/dist/circuit/index.mjs

@@ -0,0 +1,333 @@
+//#region src/circuit/index.ts
+/** NMOS square-law operating point: drain current + its small-signal conductances. */
+function nmosOp(Vgs, Vds, vth, k) {
+	const Vov = Vgs - vth;
+	if (Vov <= 0) return {
+		Id: 0,
+		gm: 0,
+		gds: GMIN
+	};
+	if (Vds < Vov) return {
+		Id: k * (Vov * Vds - .5 * Vds * Vds),
+		gm: k * Vds,
+		gds: k * (Vov - Vds) + GMIN
+	};
+	return {
+		Id: .5 * k * Vov * Vov,
+		gm: k * Vov,
+		gds: GMIN
+	};
+}
+const VT = .025852;
+const GMIN = 1e-12;
+function nodeCount(elems) {
+	let max = 0;
+	for (const e of elems) max = Math.max(max, e.n1, e.n2, e.n3 ?? 0);
+	return max + 1;
+}
+/** Solve A x = b by Gaussian elimination with partial pivoting. Returns null if singular. */
+function solveLinear(A, b) {
+	const n = b.length;
+	const M = A.map((row, i) => [...row, b[i]]);
+	for (let col = 0; col < n; col++) {
+		let piv = col;
+		for (let r = col + 1; r < n; r++) if (Math.abs(M[r][col]) > Math.abs(M[piv][col])) piv = r;
+		if (Math.abs(M[piv][col]) < 1e-18) return null;
+		[M[col], M[piv]] = [M[piv], M[col]];
+		const pivVal = M[col][col];
+		for (let r = 0; r < n; r++) {
+			if (r === col) continue;
+			const f = M[r][col] / pivVal;
+			if (f === 0) continue;
+			for (let c = col; c <= n; c++) M[r][c] -= f * M[col][c];
+		}
+	}
+	const x = new Array(n);
+	for (let i = 0; i < n; i++) x[i] = M[i][n] / M[i][i];
+	return x;
+}
+/** Build the MNA system A x = z for one solve (DC if no dt, else one transient step). */
+function buildMNA(elems, opts) {
+	const N = nodeCount(elems);
+	const dc = opts.dt === void 0;
+	const vbranch = [];
+	elems.forEach((e) => {
+		if (e.kind === "V" || e.kind === "L" && dc) vbranch.push({
+			elem: e,
+			row: 0
+		});
+	});
+	const n = N - 1 + vbranch.length;
+	vbranch.forEach((vb, j) => {
+		vb.row = N - 1 + j;
+	});
+	const A = Array.from({ length: n }, () => new Array(n).fill(0));
+	const z = new Array(n).fill(0);
+	const ix = (node) => node - 1;
+	const stampG = (a, b, g) => {
+		if (a >= 0) A[a][a] += g;
+		if (b >= 0) A[b][b] += g;
+		if (a >= 0 && b >= 0) {
+			A[a][b] -= g;
+			A[b][a] -= g;
+		}
+	};
+	const stampI = (a, b, I) => {
+		if (a >= 0) z[a] -= I;
+		if (b >= 0) z[b] += I;
+	};
+	for (let k = 1; k < N; k++) A[ix(k)][ix(k)] += GMIN;
+	let vi = 0;
+	elems.forEach((e, idx) => {
+		const a = ix(e.n1), b = ix(e.n2);
+		if (e.kind === "R") stampG(a, b, 1 / e.value);
+		else if (e.kind === "I") stampI(a, b, e.value);
+		else if (e.kind === "V" || e.kind === "L" && dc) {
+			const row = vbranch[vi++].row;
+			const E = e.kind === "V" ? e.value : 0;
+			if (a >= 0) {
+				A[a][row] += 1;
+				A[row][a] += 1;
+			}
+			if (b >= 0) {
+				A[b][row] -= 1;
+				A[row][b] -= 1;
+			}
+			z[row] += E;
+		} else if (e.kind === "C" && !dc) {
+			const Geq = e.value / opts.dt;
+			const Ieq = -Geq * (opts.prevV?.get(idx) ?? 0);
+			stampG(a, b, Geq);
+			stampI(a, b, Ieq);
+		} else if (e.kind === "L" && !dc) {
+			const Geq = opts.dt / e.value;
+			const Ieq = opts.prevI?.get(idx) ?? 0;
+			stampG(a, b, Geq);
+			stampI(a, b, Ieq);
+		} else if (e.kind === "D") {
+			const Is = e.is ?? 1e-12, nvt = (e.nIdeal ?? 1) * VT;
+			const V = opts.diodeV?.get(idx) ?? 0;
+			const Id = Is * (Math.exp(Math.min(V / nvt, 80)) - 1);
+			const gd = (Id + Is) / nvt + GMIN;
+			const Ieq = Id - gd * V;
+			stampG(a, b, gd);
+			stampI(a, b, Ieq);
+		} else if (e.kind === "M") {
+			const D = a, S = b, G = ix(e.n3 ?? 0);
+			const nv = opts.prevNodeV;
+			const Vg = nv?.[e.n3 ?? 0] ?? 0, Vd = nv?.[e.n1] ?? 0, Vs = nv?.[e.n2] ?? 0;
+			if (e.pmos) {
+				const { Id, gm, gds } = nmosOp(Vs - Vg, Vs - Vd, Math.abs(e.vth ?? 2), e.k ?? .5);
+				const Ieq = Id - gm * (Vs - Vg) - gds * (Vs - Vd);
+				stampG(S, D, gds);
+				if (S >= 0) A[S][S] += gm;
+				if (S >= 0 && G >= 0) A[S][G] -= gm;
+				if (D >= 0 && S >= 0) A[D][S] -= gm;
+				if (D >= 0 && G >= 0) A[D][G] += gm;
+				stampI(S, D, Ieq);
+			} else {
+				const { Id, gm, gds } = nmosOp(Vg - Vs, Vd - Vs, e.vth ?? 2, e.k ?? .5);
+				const Ieq = Id - gm * (Vg - Vs) - gds * (Vd - Vs);
+				stampG(D, S, gds);
+				if (D >= 0 && G >= 0) A[D][G] += gm;
+				if (D >= 0 && S >= 0) A[D][S] -= gm;
+				if (S >= 0 && G >= 0) A[S][G] -= gm;
+				if (S >= 0) A[S][S] += gm;
+				stampI(D, S, Ieq);
+			}
+		}
+	});
+	return {
+		A,
+		z,
+		N,
+		vbranch
+	};
+}
+/** DC operating point: capacitors open, inductors short. Routes to the nonlinear solver for diodes / MOSFETs. */
+function solveDC(elems) {
+	if (elems.some((e) => e.kind === "D" || e.kind === "M")) return solveDCNonlinear(elems);
+	const { A, z, N, vbranch } = buildMNA(elems, {});
+	const x = solveLinear(A, z);
+	const nodeV = new Array(N).fill(0);
+	const current = {};
+	if (!x) return {
+		nodeV,
+		current,
+		ok: false
+	};
+	for (let k = 1; k < N; k++) nodeV[k] = x[k - 1];
+	vbranch.forEach((vb) => {
+		if (vb.elem.id) current[vb.elem.id] = x[vb.row];
+	});
+	return {
+		nodeV,
+		current,
+		ok: true
+	};
+}
+/**
+* Nonlinear DC via Newton-Raphson: each iteration linearizes every nonlinear device
+* (diode Shockley with pnjlim limiting; NMOS square-law about the previous node
+* voltages) into a companion conductance + current source, solves the linear system,
+* and repeats until the solution settles.
+*/
+function solveDCNonlinear(elems, opts = {}) {
+	const maxIter = opts.maxIter ?? 100, tol = opts.tol ?? 1e-7;
+	const N0 = nodeCount(elems);
+	const diodes = elems.map((e, i) => ({
+		e,
+		i
+	})).filter((x) => x.e.kind === "D");
+	const mosfets = elems.map((e, i) => ({
+		e,
+		i
+	})).filter((x) => x.e.kind === "M");
+	const diodeV = /* @__PURE__ */ new Map();
+	diodes.forEach((d) => diodeV.set(d.i, 0));
+	let prevNodeV = new Array(N0).fill(0);
+	let x = null;
+	let N = N0;
+	let vbranch = [];
+	let converged = false;
+	for (let iter = 0; iter < maxIter; iter++) {
+		const built = buildMNA(elems, {
+			diodeV,
+			prevNodeV
+		});
+		N = built.N;
+		vbranch = built.vbranch;
+		const sol = solveLinear(built.A, built.z);
+		if (!sol) break;
+		x = sol;
+		const newNodeV = new Array(N).fill(0);
+		for (let k = 1; k < N; k++) newNodeV[k] = sol[k - 1];
+		if (mosfets.length > 0) {
+			const VMAXSTEP = 2;
+			for (let k = 1; k < N; k++) {
+				const old = prevNodeV[k] ?? 0;
+				const dv = (newNodeV[k] ?? 0) - old;
+				if (Math.abs(dv) > VMAXSTEP) newNodeV[k] = old + Math.sign(dv) * VMAXSTEP;
+			}
+		}
+		let maxDelta = 0;
+		for (const d of diodes) {
+			let Vnew = (newNodeV[d.e.n1] ?? 0) - (newNodeV[d.e.n2] ?? 0);
+			const nvt = (d.e.nIdeal ?? 1) * VT, Is = d.e.is ?? 1e-12;
+			const Vold = diodeV.get(d.i);
+			const Vcrit = nvt * Math.log(nvt / (Is * Math.SQRT2));
+			if (Vnew > Vcrit && Vnew > Vold) Vnew = Vold + nvt * Math.log(1 + (Vnew - Vold) / nvt);
+			maxDelta = Math.max(maxDelta, Math.abs(Vnew - Vold));
+			diodeV.set(d.i, Vnew);
+		}
+		for (let k = 1; k < N; k++) maxDelta = Math.max(maxDelta, Math.abs((newNodeV[k] ?? 0) - (prevNodeV[k] ?? 0)));
+		prevNodeV = newNodeV;
+		if (maxDelta < tol) {
+			converged = true;
+			break;
+		}
+	}
+	const nodeV = new Array(N).fill(0);
+	const current = {};
+	if (!x || !converged) return {
+		nodeV,
+		current,
+		ok: false
+	};
+	for (let k = 1; k < N; k++) nodeV[k] = x[k - 1];
+	vbranch.forEach((vb) => {
+		if (vb.elem.id) current[vb.elem.id] = x[vb.row];
+	});
+	diodes.forEach((d) => {
+		if (!d.e.id) return;
+		const nvt = (d.e.nIdeal ?? 1) * VT, Is = d.e.is ?? 1e-12;
+		current[d.e.id] = Is * (Math.exp(Math.min((diodeV.get(d.i) ?? 0) / nvt, 80)) - 1);
+	});
+	mosfets.forEach((m) => {
+		if (!m.e.id) return;
+		const Vg = nodeV[m.e.n3 ?? 0] ?? 0, Vd = nodeV[m.e.n1] ?? 0, Vs = nodeV[m.e.n2] ?? 0;
+		current[m.e.id] = m.e.pmos ? nmosOp(Vs - Vg, Vs - Vd, Math.abs(m.e.vth ?? 2), m.e.k ?? .5).Id : nmosOp(Vg - Vs, Vd - Vs, m.e.vth ?? 2, m.e.k ?? .5).Id;
+	});
+	return {
+		nodeV,
+		current,
+		ok: true
+	};
+}
+/** Current through an element given solved node voltages (R/I directly; C/L need state). */
+function elementCurrent(e, nodeV) {
+	const v = (nodeV[e.n1] ?? 0) - (nodeV[e.n2] ?? 0);
+	if (e.kind === "R") return v / e.value;
+	if (e.kind === "I") return e.value;
+	return NaN;
+}
+/**
+* Time-stepped transient (Backward Euler). Returns the node-voltage trajectory,
+* including t = 0. Reactive elements use companion models rebuilt every step.
+*/
+function solveTransient(elems, opts) {
+	const { dt, steps } = opts;
+	const N = nodeCount(elems);
+	const prevV = /* @__PURE__ */ new Map();
+	const prevI = /* @__PURE__ */ new Map();
+	elems.forEach((e, i) => {
+		if (e.kind === "C" || e.kind === "L") prevV.set(i, opts.initialV?.get(i) ?? 0);
+		if (e.kind === "L") prevI.set(i, 0);
+	});
+	const out = [];
+	const record = (t, nodeV) => {
+		out.push({
+			t,
+			nodeV: [...nodeV]
+		});
+	};
+	let nodeV = new Array(N).fill(0);
+	if (!elems.some((e) => e.kind === "D" || e.kind === "M")) {
+		const { A, z } = buildMNA(elems.map((e, i) => e.kind === "C" ? {
+			...e,
+			kind: "V",
+			value: opts.initialV?.get(i) ?? 0
+		} : e.kind === "L" ? {
+			...e,
+			kind: "I",
+			value: prevI.get(i) ?? 0
+		} : e), {});
+		const x = solveLinear(A, z);
+		if (x) for (let k = 1; k < N; k++) nodeV[k] = x[k - 1] ?? 0;
+	}
+	record(0, nodeV);
+	for (let s = 1; s <= steps; s++) {
+		const { A, z } = buildMNA(elems, {
+			dt,
+			prevV,
+			prevI
+		});
+		const x = solveLinear(A, z);
+		if (!x) break;
+		nodeV = new Array(N).fill(0);
+		for (let k = 1; k < N; k++) nodeV[k] = x[k - 1];
+		elems.forEach((e, i) => {
+			if (e.kind === "C" || e.kind === "L") {
+				const v = (nodeV[e.n1] ?? 0) - (nodeV[e.n2] ?? 0);
+				prevV.set(i, v);
+				if (e.kind === "L") {
+					const Geq = dt / e.value;
+					prevI.set(i, Geq * v + (prevI.get(i) ?? 0));
+				}
+			}
+		});
+		record(s * dt, nodeV);
+	}
+	return out;
+}
+/** Equivalent resistance of resistors in series. */
+function seriesR(...rs) {
+	return rs.reduce((a, r) => a + r, 0);
+}
+/** Equivalent resistance of resistors in parallel. */
+function parallelR(...rs) {
+	return 1 / rs.reduce((a, r) => a + 1 / r, 0);
+}
+
+//#endregion
+export { elementCurrent, parallelR, seriesR, solveDC, solveDCNonlinear, solveLinear, solveTransient };

package/dist/core/clock.d.mts

@@ -30,7 +30,7 @@ declare function ClockProvider({
  * 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
+ * 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.
  */

package/dist/core/clock.mjs

@@ -7,12 +7,12 @@ import { createContext, createElement, useContext, useEffect, useRef } from "rea
 * 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
+* 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
+* receive (timeMs / frame), not a private accumulating counter, so the same
 * component renders identically at any frame.
 */
 const DriverContext = createContext(null);
@@ -26,7 +26,7 @@ const now = () => typeof performance !== "undefined" ? performance.now() : Date.
 * 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
+* 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.
 */

package/dist/core/control.d.mts

@@ -50,7 +50,7 @@ interface ControlSurface {
 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. */
+/** 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;

package/dist/core/control.mjs

@@ -4,7 +4,7 @@ import { useEffect, useRef } from "react";
 
 //#region src/core/control.ts
 /**
-* control — an addressable control surface so an external driver (a voice/AI
+* 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.
 *
@@ -99,7 +99,7 @@ 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. */
+/** 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));
 }

package/dist/core/coords.d.mts

@@ -1,11 +1,11 @@
 //#region src/core/coords.d.ts
 /**
- * CoordinateSystem — the math↔pixel mapping that decouples mathematical
+ * 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
+ * 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).
  */
@@ -31,7 +31,7 @@ interface CoordinateSystem {
 }
 /**
  * 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 —
+ * 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,

package/dist/core/coords.mjs

@@ -1,7 +1,7 @@
 //#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 —
+* 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,

package/dist/core/index.d.mts

@@ -5,4 +5,5 @@ import { CoordsContext, DragOverlayContext, StageRefContext, useCoords, useDragO
 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 };
+import { approxEq, clamp, clamp01, gcd, remap, round, snapTo, toDeg, toRad } from "./math.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, approxEq, clamp, clamp01, createCoords, ease, fmt, gcd, getControlSurface, lerp, listControlSurfaces, mat, onControlChange, oscillate, prefersReducedMotion, remap, round, snapTo, spring, timeline, toDeg, toRad, useControlSurface, useCoords, useDragOverlay, useFrameLoop, useLearner, useStageRef, vec };

package/dist/core/index.mjs

@@ -4,6 +4,7 @@ import { CoordsContext, DragOverlayContext, StageRefContext, useCoords, useDragO
 import { ClockProvider, useFrameLoop } from "./clock.mjs";
 import { getControlSurface, listControlSurfaces, onControlChange, useControlSurface } from "./control.mjs";
 import { LearnerProvider, useLearner } from "./learner.mjs";
+import { approxEq, clamp, clamp01, gcd, remap, round, snapTo, toDeg, toRad } from "./math.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 };
+export { ClockProvider, CoordsContext, DragOverlayContext, LearnerProvider, StageRefContext, approxEq, clamp, clamp01, createCoords, ease, fmt, gcd, getControlSurface, lerp, listControlSurfaces, mat, onControlChange, oscillate, prefersReducedMotion, remap, round, snapTo, spring, timeline, toDeg, toRad, useControlSurface, useCoords, useDragOverlay, useFrameLoop, useLearner, useStageRef, vec };

package/dist/core/learner.d.mts

@@ -15,7 +15,7 @@ interface LearnerResult {
   response?: string;
   /** Mark the activity complete. */
   completion?: boolean;
-  /** Pedagogy context (from the lab's LabMeta) — e.g. the objective this event
+  /** 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. */

package/dist/core/learner.mjs

@@ -4,7 +4,7 @@ import { createContext, createElement, useContext } from "react";
 
 //#region src/core/learner.ts
 /**
-* Learner / assessment seam — a host-agnostic interface so a visualization can
+* 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.

package/dist/core/math.d.mts

@@ -0,0 +1,26 @@
+//#region src/core/math.d.ts
+/**
+ * Small numeric kit shared by every consumer (labs re-exports these). One
+ * source of truth: labs presets used to hand-roll `clamp` 8+ different times.
+ * Pure, SSR-deterministic (no transcendental output is emitted directly into
+ * SVG — callers still `fmt()` pixel values).
+ */
+declare const clamp: (v: number, lo: number, hi: number) => number;
+/** Clamp to the unit interval [0, 1] — the ubiquitous "fraction / progress" guard. */
+declare const clamp01: (v: number) => number;
+/** Round to `dp` decimal places (default 2), as a number. */
+declare const round: (n: number, dp?: number) => number;
+/** Greatest common divisor (Euclid), 0→1 so a ratio/fraction can always reduce. */
+declare const gcd: (a: number, b: number) => number;
+/** Degrees → radians. */
+declare const toRad: (deg: number) => number;
+/** Radians → degrees. */
+declare const toDeg: (rad: number) => number;
+/** Are two numbers equal within a tolerance (default 1e-6)? */
+declare const approxEq: (a: number, b: number, eps?: number) => boolean;
+/** Map x from [inMin,inMax] to [outMin,outMax], optionally clamped. */
+declare function remap(x: number, inMin: number, inMax: number, outMin: number, outMax: number, doClamp?: boolean): number;
+/** Snap `v` to the nearest multiple of `step` (step <= 0 → identity). */
+declare const snapTo: (v: number, step: number) => number;
+//#endregion
+export { approxEq, clamp, clamp01, gcd, remap, round, snapTo, toDeg, toRad };

package/dist/core/math.mjs

@@ -0,0 +1,37 @@
+//#region src/core/math.ts
+/**
+* Small numeric kit shared by every consumer (labs re-exports these). One
+* source of truth: labs presets used to hand-roll `clamp` 8+ different times.
+* Pure, SSR-deterministic (no transcendental output is emitted directly into
+* SVG — callers still `fmt()` pixel values).
+*/
+const clamp = (v, lo, hi) => Math.min(hi, Math.max(lo, v));
+/** Clamp to the unit interval [0, 1] — the ubiquitous "fraction / progress" guard. */
+const clamp01 = (v) => v < 0 ? 0 : v > 1 ? 1 : v;
+/** Round to `dp` decimal places (default 2), as a number. */
+const round = (n, dp = 2) => Math.round(n * 10 ** dp) / 10 ** dp;
+/** Greatest common divisor (Euclid), 0→1 so a ratio/fraction can always reduce. */
+const gcd = (a, b) => {
+	a = Math.abs(a);
+	b = Math.abs(b);
+	while (b) [a, b] = [b, a % b];
+	return a || 1;
+};
+const DEG = Math.PI / 180;
+/** Degrees → radians. */
+const toRad = (deg) => deg * DEG;
+/** Radians → degrees. */
+const toDeg = (rad) => rad / DEG;
+/** Are two numbers equal within a tolerance (default 1e-6)? */
+const approxEq = (a, b, eps = 1e-6) => Math.abs(a - b) <= eps;
+/** Map x from [inMin,inMax] to [outMin,outMax], optionally clamped. */
+function remap(x, inMin, inMax, outMin, outMax, doClamp = false) {
+	const t = inMax === inMin ? 0 : (x - inMin) / (inMax - inMin);
+	const v = outMin + (outMax - outMin) * t;
+	return doClamp ? clamp(v, Math.min(outMin, outMax), Math.max(outMin, outMax)) : v;
+}
+/** Snap `v` to the nearest multiple of `step` (step <= 0 → identity). */
+const snapTo = (v, step) => step > 0 ? Math.round(v / step) * step : v;
+
+//#endregion
+export { approxEq, clamp, clamp01, gcd, remap, round, snapTo, toDeg, toRad };

package/dist/core/motion.d.mts

@@ -1,14 +1,14 @@
 //#region src/core/motion.d.ts
 /**
- * Motion core — the "physics of feel" layer. Pure, dependency-free functions that
+ * Motion core, the "physics of feel" layer. Pure, dependency-free functions that
  * turn time into eased / springy / oscillating values. They consume the `dtMs`
  * (or `timeMs`) you already receive from `useFrameLoop`; they do NOT own a loop,
- * schedule frames, or touch React — so they stay deterministic (same time → same
+ * schedule frames, or touch React, so they stay deterministic (same time → same
  * value) and work identically under a Remotion fixed-frame driver.
  *
  * Discipline (mirrors clock.ts): for video-determinism prefer the time-driven
  * helpers (`oscillate`, `timeline`) that are a pure function of `timeMs`. `spring`
- * is stateful (it integrates a velocity) — fine for interactive feel, but it will
+ * is stateful (it integrates a velocity), fine for interactive feel, but it will
  * not reproduce frame-for-frame across drivers, so don't use it for rendered video.
  */
 /** Snap-to-end gate: honor the user's reduced-motion preference (SSR-safe). */
@@ -20,8 +20,8 @@ declare const ease: {
   readonly cubicOut: (t: number) => number;
   readonly cubicInOut: (t: number) => number;
   readonly quintOut: (t: number) => number;
-  readonly sineInOut: (t: number) => number; /** Overshoots then settles — good for "pop" on appear. */
-  readonly backOut: (t: number) => number; /** Springy overshoot with decaying wobble — for playful reveals. */
+  readonly sineInOut: (t: number) => number; /** Overshoots then settles, good for "pop" on appear. */
+  readonly backOut: (t: number) => number; /** Springy overshoot with decaying wobble, for playful reveals. */
   readonly elasticOut: (t: number) => number;
 };
 type EaseName = keyof typeof ease;
@@ -53,7 +53,7 @@ interface OscillateOpts {
   phase?: number;
   shape?: WaveShape;
 }
-/** A pure periodic signal of `timeSec` — the engine under AC sources, pendulums, waves. */
+/** A pure periodic signal of `timeSec`, the engine under AC sources, pendulums, waves. */
 declare function oscillate(timeSec: number, opts?: OscillateOpts): number;
 interface Keyframe {
   /** Absolute time on the timeline, seconds. */