@classytic/stage 0.1.0 → 0.2.0

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/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/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. */

package/dist/core/motion.mjs

@@ -1,14 +1,14 @@
 //#region src/core/motion.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). */
@@ -30,14 +30,14 @@ const ease = {
 	},
 	quintOut: (t) => 1 - (1 - clamp01(t)) ** 5,
 	sineInOut: (t) => -(Math.cos(Math.PI * clamp01(t)) - 1) / 2,
-	/** Overshoots then settles — good for "pop" on appear. */
+	/** Overshoots then settles, good for "pop" on appear. */
 	backOut: (t) => {
 		const c1 = 1.70158;
 		const c3 = 2.70158;
 		t = clamp01(t);
 		return 1 + c3 * (t - 1) ** 3 + c1 * (t - 1) ** 2;
 	},
-	/** Springy overshoot with decaying wobble — for playful reveals. */
+	/** Springy overshoot with decaying wobble, for playful reveals. */
 	elasticOut: (t) => {
 		t = clamp01(t);
 		if (t === 0 || t === 1) return t;
@@ -63,7 +63,7 @@ function spring(current, target, vel, dtSec, opts = {}) {
 	vel.current += accel * dt;
 	return current + vel.current * dt;
 }
-/** 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. */
 function oscillate(timeSec, opts = {}) {
 	const { amp = 1, freq = 1, phase = 0, shape = "sine" } = opts;
 	const turns = freq * timeSec + phase;

package/dist/core/richText.d.mts

@@ -1,6 +1,6 @@
 //#region src/core/richText.d.ts
 /**
- * richText — the ONE grammar for inline subscript/superscript markup, shared by
+ * richText, the ONE grammar for inline subscript/superscript markup, shared by
  * every renderer so the parsing lives in a single place and can't drift:
  *   • stage's SVG `<Label>` turns spans into <tspan> (baseline-shifted), and
  *   • labs' HTML `<RichText>` turns them into <sub>/<sup>.
@@ -9,7 +9,7 @@
  *   `_x` / `^x`        → a run of the SAME character class as the char right
  *                        after the marker (all-letters OR all-digits). So
  *                        `V_RC` → subscript "RC", `H_2O` → subscript "2" then
- *                        base "O", `v_max` → subscript "max" — no braces needed.
+ *                        base "O", `v_max` → subscript "max", no braces needed.
  *   `_{abc}` / `^{ab}` → an explicit group, taken verbatim (use for mixed runs
  *                        or symbols, e.g. `10^{-3}`, `x^{n+1}`)
  *   a lone `_` or `^`  → stays literal

package/dist/core/vec.d.mts

@@ -3,7 +3,7 @@
  * 2D vector + affine-matrix algebra. Points are {x,y} objects (serialize cleanly
  * in the scene JSON). Matrices are SVG-order tuples [a,b,c,d,e,f] mapping
  * (x,y) → (a·x + c·y + e, b·x + d·y + f), so `mat.toSvg` is a direct
- * `matrix(a b c d e f)` attribute string — never a CSS variable (a CSS transform
+ * `matrix(a b c d e f)` attribute string, never a CSS variable (a CSS transform
  * is not reliably composed into getScreenCTM()).
  */
 interface Vec2 {

package/dist/field/index.d.mts

@@ -23,6 +23,14 @@ interface Bounds {
 /** Net field vector at point `p` from all sources (superposition). */
 declare function fieldAt(sources: readonly FieldSource[], p: Vec2): Vec2;
 declare function fieldMag(sources: readonly FieldSource[], p: Vec2): number;
+/**
+ * Scalar electric potential at `p`: V = Σ k·q / r (superposition). This is the
+ * companion to `fieldAt` for potential / equipotential / work labs, where the work
+ * to move a charge Q from A to B is W = Q·(V_A − V_B), path-independent. `wire`
+ * sources have no scalar potential and are skipped. Same softening as `fieldAt`,
+ * so V stays finite at a source.
+ */
+declare function potentialAt(sources: readonly FieldSource[], p: Vec2, k?: number): number;
 interface TraceOpts {
   /** Follow the field (+1) or run against it (−1). Default +1. */
   dir?: number;
@@ -41,13 +49,13 @@ interface FieldLinesOpts extends TraceOpts {
   /** Seed radius around a source. Default 0.2. */
   seed?: number;
 }
-/** Convenience: a full set of field lines — radial from each charge/pole, circular
+/** Convenience: a full set of field lines, radial from each charge/pole, circular
  *  loops around each wire. Each line carries the sign of its originating source. */
 declare function fieldLines(sources: readonly FieldSource[], opts?: FieldLinesOpts): {
   points: Vec2[];
   sign: number;
 }[];
-/** Sample the field on a regular grid — for a quiver / arrow plot. */
+/** Sample the field on a regular grid, for a quiver / arrow plot. */
 declare function fieldGrid(sources: readonly FieldSource[], bounds: Bounds, nx: number, ny: number): {
   at: Vec2;
   v: Vec2;
@@ -55,4 +63,4 @@ declare function fieldGrid(sources: readonly FieldSource[], bounds: Bounds, nx:
 /** Build a bar magnet as an N(+)/S(−) pole pair, centred at `center` along `dir`. */
 declare function barMagnet(center: Vec2, dir: Vec2, strength?: number, length?: number): [PointCharge, PointCharge];
 //#endregion
-export { Bounds, FieldLinesOpts, FieldSource, LineCurrent, PointCharge, TraceOpts, barMagnet, fieldAt, fieldGrid, fieldLines, fieldMag, traceLine };
+export { Bounds, FieldLinesOpts, FieldSource, LineCurrent, PointCharge, TraceOpts, barMagnet, fieldAt, fieldGrid, fieldLines, fieldMag, potentialAt, traceLine };

package/dist/field/index.mjs

@@ -26,6 +26,23 @@ function fieldMag(sources, p) {
 	const v = fieldAt(sources, p);
 	return Math.hypot(v.x, v.y);
 }
+/**
+* Scalar electric potential at `p`: V = Σ k·q / r (superposition). This is the
+* companion to `fieldAt` for potential / equipotential / work labs, where the work
+* to move a charge Q from A to B is W = Q·(V_A − V_B), path-independent. `wire`
+* sources have no scalar potential and are skipped. Same softening as `fieldAt`,
+* so V stays finite at a source.
+*/
+function potentialAt(sources, p, k = 1) {
+	let v = 0;
+	for (const s of sources) {
+		if (s.kind !== "point") continue;
+		const dx = p.x - s.at.x, dy = p.y - s.at.y;
+		const r = Math.sqrt(dx * dx + dy * dy + SOFT);
+		v += k * s.q / r;
+	}
+	return v;
+}
 function unit(v, dir) {
 	const m = Math.hypot(v.x, v.y);
 	if (m < 1e-9) return null;
@@ -64,7 +81,7 @@ function traceLine(sources, start, opts = {}) {
 	}
 	return pts;
 }
-/** Convenience: a full set of field lines — radial from each charge/pole, circular
+/** Convenience: a full set of field lines, radial from each charge/pole, circular
 *  loops around each wire. Each line carries the sign of its originating source. */
 function fieldLines(sources, opts = {}) {
 	const { perSource = 12, seed = .2, ...trace } = opts;
@@ -114,7 +131,7 @@ function fieldLines(sources, opts = {}) {
 	}
 	return out;
 }
-/** Sample the field on a regular grid — for a quiver / arrow plot. */
+/** Sample the field on a regular grid, for a quiver / arrow plot. */
 function fieldGrid(sources, bounds, nx, ny) {
 	const out = [];
 	const dx = (bounds.xMax - bounds.xMin) / (nx + 1);
@@ -153,4 +170,4 @@ function barMagnet(center, dir, strength = 1, length = 1.6) {
 }
 
 //#endregion
-export { barMagnet, fieldAt, fieldGrid, fieldLines, fieldMag, traceLine };
+export { barMagnet, fieldAt, fieldGrid, fieldLines, fieldMag, potentialAt, traceLine };