@classytic/stage 0.1.0 → 0.3.0

package/dist/scene/Scene.d.mts

@@ -15,6 +15,9 @@ interface SceneProps {
   /** Author opt-in: start a sim running immediately (ambient motion) instead of
    *  the default "press Play". A SceneDoc with no `meta.sims` is always static. */
   autoPlay?: boolean;
+  /** Optional controlled playback for hosts that provide their own transport. */
+  playing?: boolean;
+  onPlayingChange?: (playing: boolean) => void;
 }
 declare function Scene({
   doc,
@@ -25,7 +28,9 @@ declare function Scene({
   height,
   view,
   ariaLabel,
-  autoPlay
+  autoPlay,
+  playing: playingProp,
+  onPlayingChange
 }: SceneProps): ReactNode;
 //#endregion
 export { Scene, SceneProps };

package/dist/scene/Scene.mjs

@@ -14,7 +14,7 @@ import { jsx, jsxs } from "react/jsx-runtime";
 
 //#region src/scene/Scene.tsx
 /**
-* <Scene> — renders a SceneDoc (read/play): resolve() → shared element renderer.
+* <Scene>, renders a SceneDoc (read/play): resolve() → shared element renderer.
 * Free draggable points commit one `mutate` via onChange on pointer-up; live drag
 * uses an ephemeral overlay (descendants re-resolve without mutating the doc).
 */
@@ -45,7 +45,7 @@ function autoView(resolved) {
 		yMax: Math.max(...ys) + pad
 	};
 }
-function Scene({ doc, onChange, interactive = true, showGrid = true, showAxes = true, height, view, ariaLabel = "Interactive figure", autoPlay = false }) {
+function Scene({ doc, onChange, interactive = true, showGrid = true, showAxes = true, height, view, ariaLabel = "Interactive figure", autoPlay = false, playing: playingProp, onPlayingChange }) {
 	const [overlay, setOverlay] = useState(/* @__PURE__ */ new Map());
 	const prevRef = useRef(void 0);
 	const sims = doc.meta?.sims;
@@ -55,14 +55,22 @@ function Scene({ doc, onChange, interactive = true, showGrid = true, showAxes =
 	const [frame, setFrame] = useState(0);
 	const { ref: rootRef, inView } = useInView();
 	const [done, setDone] = useState(false);
-	const [playing, setPlaying] = useState(autoPlay);
+	const [internalPlaying, setInternalPlaying] = useState(autoPlay);
+	const playing = playingProp ?? internalPlaying;
+	const setPlaying = (next) => {
+		if (playingProp === void 0) setInternalPlaying(next);
+		onPlayingChange?.(next);
+	};
 	useFrameLoop((f) => {
 		if (!sims?.length || !simStates.current) return;
 		const next = stepSims(sims, simStates.current, Math.min(.05, f.dtMs / 1e3));
 		simStates.current = next.states;
 		simScalars.current = next.scalars;
 		setFrame((n) => (n + 1) % 1e6);
-		if (next.done) setDone(true);
+		if (next.done) {
+			setDone(true);
+			setPlaying(false);
+		}
 	}, { running: !!sims?.length && inView && playing && !done });
 	const merged = useMemo(() => {
 		const scalars = simScalars.current;
@@ -95,7 +103,7 @@ function Scene({ doc, onChange, interactive = true, showGrid = true, showAxes =
 	const hasSims = !!sims?.length;
 	return /* @__PURE__ */ jsxs("div", {
 		ref: rootRef,
-		style: { position: "relative" },
+		className: "stage-scene",
 		children: [
 			/* @__PURE__ */ jsxs(Stage, {
 				view: v,
@@ -114,30 +122,9 @@ function Scene({ doc, onChange, interactive = true, showGrid = true, showAxes =
 				type: "button",
 				onClick: () => setPlaying(true),
 				"aria-label": "Play simulation",
-				style: {
-					position: "absolute",
-					inset: 0,
-					display: "flex",
-					alignItems: "center",
-					justifyContent: "center",
-					background: "color-mix(in oklab, var(--stage-bg) 38%, transparent)",
-					border: "none",
-					borderRadius: 12,
-					cursor: "pointer"
-				},
+				className: "stage-scene__play-overlay",
 				children: /* @__PURE__ */ jsx("span", {
-					style: {
-						display: "inline-flex",
-						alignItems: "center",
-						gap: 8,
-						padding: "11px 26px",
-						borderRadius: 999,
-						background: "var(--stage-accent)",
-						color: "#fff",
-						fontWeight: 800,
-						fontSize: 16,
-						boxShadow: "0 6px 18px rgba(0,0,0,.28)"
-					},
+					className: "stage-scene__play-label",
 					children: "▶ Play"
 				})
 			}),
@@ -145,19 +132,7 @@ function Scene({ doc, onChange, interactive = true, showGrid = true, showAxes =
 				type: "button",
 				onClick: () => setPlaying(false),
 				"aria-label": "Pause simulation",
-				style: {
-					position: "absolute",
-					top: 10,
-					right: 10,
-					width: 34,
-					height: 34,
-					borderRadius: 999,
-					border: "1px solid var(--stage-grid)",
-					background: "color-mix(in oklab, var(--stage-bg) 80%, transparent)",
-					color: "var(--stage-fg)",
-					cursor: "pointer",
-					fontSize: 13
-				},
+				className: "stage-scene__pause",
 				children: "⏸"
 			})
 		]

package/dist/scene/assets.d.mts

@@ -21,13 +21,13 @@ declare function registerAsset(name: string, spec: AssetSpec): void;
 declare function getAsset(name: string): AssetSpec | undefined;
 declare function listAssets(): string[];
 /**
- * Typed read of an asset's `meta` — write `const m = assetMeta<MyMeta>(geom)` in a
+ * Typed read of an asset's `meta`, write `const m = assetMeta<MyMeta>(geom)` in a
  * Component instead of an inline `(geom.meta ?? {}) as MyMeta` cast everywhere.
  *
  * We deliberately keep `AssetGeometry` NON-generic: `parts` must stay
  * `Vec2 | Vec2[] | number` so it remains a clean member of the resolver's `Val`
  * union, and a fully generic `AssetGeometry<TParts, TMeta>` would force `AssetSpec`,
- * `registerAsset`, `resolve()`, and the render path to be generic too — and a
+ * `registerAsset`, `resolve()`, and the render path to be generic too, and a
  * specific `TMeta` interface isn't assignable to `Record<string, unknown>` without
  * index-signature friction. This helper gives the type-safety at the read site
  * with none of that ripple. (Asset domain data lives in `meta`; `parts` is geometry.)

package/dist/scene/assets.mjs

@@ -12,13 +12,13 @@ function listAssets() {
 	return [...ASSETS.keys()];
 }
 /**
-* Typed read of an asset's `meta` — write `const m = assetMeta<MyMeta>(geom)` in a
+* Typed read of an asset's `meta`, write `const m = assetMeta<MyMeta>(geom)` in a
 * Component instead of an inline `(geom.meta ?? {}) as MyMeta` cast everywhere.
 *
 * We deliberately keep `AssetGeometry` NON-generic: `parts` must stay
 * `Vec2 | Vec2[] | number` so it remains a clean member of the resolver's `Val`
 * union, and a fully generic `AssetGeometry<TParts, TMeta>` would force `AssetSpec`,
-* `registerAsset`, `resolve()`, and the render path to be generic too — and a
+* `registerAsset`, `resolve()`, and the render path to be generic too, and a
 * specific `TMeta` interface isn't assignable to `Record<string, unknown>` without
 * index-signature friction. This helper gives the type-safety at the read site
 * with none of that ripple. (Asset domain data lives in `meta`; `parts` is geometry.)

package/dist/scene/commands.d.mts

@@ -41,7 +41,16 @@ declare function collectRemoved(doc: SceneDoc, id: Id): {
   elements: SceneElement[];
   bindings: Binding[];
 };
+/**
+ * Validate a command against the current doc; returns an error string, or null if it is safe to
+ * apply. The Editor runs this BEFORE mutating, so a bad command (from an agent or a tool) fails
+ * loudly with a reason instead of silently corrupting the scene: duplicate ids, missing mutate /
+ * remove targets, bindings to elements that do not exist, double binds, unbinding nothing.
+ */
+declare function validateCommand(doc: SceneDoc, cmd: Command): string | null;
+/** The element ids a command (or batch) creates, for `CommandResult.createdIds`. */
+declare function createdIds(cmd: Command): Id[];
 declare function applyCommand(doc: SceneDoc, cmd: Command): SceneDoc;
 declare function inverse(cmd: Command, prev: SceneDoc): Command;
 //#endregion
-export { Command, CommandResult, MutatePatch, applyCommand, collectRemoved, inverse };
+export { Command, CommandResult, MutatePatch, applyCommand, collectRemoved, createdIds, inverse, validateCommand };

package/dist/scene/commands.mjs

@@ -3,7 +3,7 @@ import { parentIds } from "./schema.mjs";
 
 //#region src/scene/commands.ts
 /**
-* Commands — JSON, agent-emittable mutations. ALL changes funnel through these
+* Commands, JSON, agent-emittable mutations. ALL changes funnel through these
 * (builder, agent, undo, control-surface bridge). GeoGebra create-vs-mutate split.
 * `applyCommand` is a pure reducer; `inverse` produces the undo command, including
 * a concrete cascading-remove inverse that re-creates descendants + bindings in
@@ -48,6 +48,46 @@ function collectRemoved(doc, id) {
 		bindings: doc.bindings.filter((b) => removed.has(b.from.ref) || removed.has(b.to.ref))
 	};
 }
+/**
+* Validate a command against the current doc; returns an error string, or null if it is safe to
+* apply. The Editor runs this BEFORE mutating, so a bad command (from an agent or a tool) fails
+* loudly with a reason instead of silently corrupting the scene: duplicate ids, missing mutate /
+* remove targets, bindings to elements that do not exist, double binds, unbinding nothing.
+*/
+function validateCommand(doc, cmd) {
+	const hasEl = (id) => doc.elements.some((e) => e.id === id);
+	switch (cmd.op) {
+		case "create":
+			if (hasEl(cmd.id)) return `create: element id '${cmd.id}' already exists`;
+			if (cmd.element.id !== cmd.id) return `create: element.id '${cmd.element.id}' does not match command id '${cmd.id}'`;
+			return null;
+		case "mutate": return hasEl(cmd.id) ? null : `mutate: no element '${cmd.id}'`;
+		case "remove": return hasEl(cmd.id) ? null : `remove: no element '${cmd.id}'`;
+		case "bind": {
+			const b = cmd.binding;
+			if ((doc.bindings ?? []).some((x) => x.id === b.id)) return `bind: binding id '${b.id}' already exists`;
+			if (!hasEl(b.from.ref)) return `bind: 'from' references unknown element '${b.from.ref}'`;
+			if (!hasEl(b.to.ref)) return `bind: 'to' references unknown element '${b.to.ref}'`;
+			return null;
+		}
+		case "unbind": return (doc.bindings ?? []).some((b) => b.id === cmd.id) ? null : `unbind: no binding '${cmd.id}'`;
+		case "batch": {
+			let cur = doc;
+			for (const c of cmd.commands) {
+				const err = validateCommand(cur, c);
+				if (err) return `batch '${cmd.label}': ${err}`;
+				cur = applyCommand(cur, c);
+			}
+			return null;
+		}
+	}
+}
+/** The element ids a command (or batch) creates, for `CommandResult.createdIds`. */
+function createdIds(cmd) {
+	if (cmd.op === "create") return [cmd.id];
+	if (cmd.op === "batch") return cmd.commands.flatMap(createdIds);
+	return [];
+}
 function applyCommand(doc, cmd) {
 	switch (cmd.op) {
 		case "create": {
@@ -159,4 +199,4 @@ function inverse(cmd, prev) {
 }
 
 //#endregion
-export { applyCommand, collectRemoved, inverse };
+export { applyCommand, collectRemoved, createdIds, inverse, validateCommand };

package/dist/scene/evaluators.mjs

@@ -8,7 +8,7 @@ import { compileExpr } from "../math/index.mjs";
 * Evaluator registry, keyed by def.op. Each evaluator turns a derived def into a
 * Val, reading parent values through `ctx`. Geometry intersection math is ported
 * from the legacy labs GeometryBoard; intersect picks the solution nearest the previous
-* frame's resolved point (continuity — never swaps P/Q on drag).
+* frame's resolved point (continuity, never swaps P/Q on drag).
 */
 const exprCache = /* @__PURE__ */ new Map();
 function compiledExpr(src) {
@@ -182,7 +182,7 @@ const EVALUATORS = {
 	expr: (d, ctx) => {
 		const def = d;
 		const compiled = compiledExpr(def.fn);
-		if (!compiled) return NaN;
+		if (!compiled) throw new Error(`expr: cannot parse formula "${def.fn}"`);
 		const scope = {};
 		for (const [name, ref] of Object.entries(def.inputs)) scope[name] = numOf(ctx.get(ref));
 		return compiled.fn(scope);

package/dist/scene/index.d.mts

@@ -1,6 +1,6 @@
 import { Vec2 } from "../core/vec.mjs";
 import { AssetGeometry, Binding, CircleVal, DerivedDef, DerivedElement, DerivedKind, ElementBase, ElementStyle, FreeElement, FreeNote, FreePoint, FreeScalar, Id, LabMeta, NumOrRef, Op, Ref, SceneDoc, SceneElement, SceneMeta, ShapeLineVal, SimDecl, Val, isAssetGeom, isCircleVal, isDerived, isFree, isLineVal, isVec2, numOf } from "./types.mjs";
-import { Command, CommandResult, MutatePatch, applyCommand, collectRemoved, inverse } from "./commands.mjs";
+import { Command, CommandResult, MutatePatch, applyCommand, collectRemoved, createdIds, inverse, validateCommand } from "./commands.mjs";
 import { Resolved, resolve } from "./resolve.mjs";
 import { OP_REFS, isRef, parentIds } from "./schema.mjs";
 import { EVALUATORS, EvalCtx } from "./evaluators.mjs";
@@ -10,4 +10,4 @@ import { Scene, SceneProps } from "./Scene.mjs";
 import { RenderOpts, renderElements } from "./render.mjs";
 import { AssetResolveArgs, AssetSpec, assetMeta, getAsset, listAssets, registerAsset } from "./assets.mjs";
 import { SimStates, initSims, stepSims } from "./sims.mjs";
-export { type AssetGeometry, type AssetResolveArgs, type AssetSpec, type Binding, CURRENT_SCHEMA_VERSION, type CircleVal, type Command, type CommandResult, type DerivedDef, type DerivedElement, type DerivedKind, EVALUATORS, type ElementBase, type ElementStyle, type EvalCtx, type FreeElement, type FreeNote, type FreePoint, type FreeScalar, type Id, type InstanceState, type LabMeta, type MutatePatch, type NumOrRef, OP_REFS, type Op, type Ref, type RenderOpts, type Resolved, Scene, type SceneDoc, type SceneElement, type SceneMeta, type SceneProps, SceneStore, type Vec2 as SceneVec2, type ShapeLineVal, type SimDecl, type SimStates, type Val, applyCommand, assetMeta, collectRemoved, emptyDoc, getAsset, initSims, inverse, isAssetGeom, isCircleVal, isDerived, isFree, isLineVal, isRef, isVec2, listAssets, migrate, numOf, parentIds, parse, registerAsset, renderElements, resolve, serialize, stepSims };
+export { type AssetGeometry, type AssetResolveArgs, type AssetSpec, type Binding, CURRENT_SCHEMA_VERSION, type CircleVal, type Command, type CommandResult, type DerivedDef, type DerivedElement, type DerivedKind, EVALUATORS, type ElementBase, type ElementStyle, type EvalCtx, type FreeElement, type FreeNote, type FreePoint, type FreeScalar, type Id, type InstanceState, type LabMeta, type MutatePatch, type NumOrRef, OP_REFS, type Op, type Ref, type RenderOpts, type Resolved, Scene, type SceneDoc, type SceneElement, type SceneMeta, type SceneProps, SceneStore, type Vec2 as SceneVec2, type ShapeLineVal, type SimDecl, type SimStates, type Val, applyCommand, assetMeta, collectRemoved, createdIds, emptyDoc, getAsset, initSims, inverse, isAssetGeom, isCircleVal, isDerived, isFree, isLineVal, isRef, isVec2, listAssets, migrate, numOf, parentIds, parse, registerAsset, renderElements, resolve, serialize, stepSims, validateCommand };

package/dist/scene/index.mjs

@@ -3,11 +3,11 @@ import { OP_REFS, isRef, parentIds } from "./schema.mjs";
 import { assetMeta, getAsset, listAssets, registerAsset } from "./assets.mjs";
 import { EVALUATORS } from "./evaluators.mjs";
 import { resolve } from "./resolve.mjs";
-import { applyCommand, collectRemoved, inverse } from "./commands.mjs";
+import { applyCommand, collectRemoved, createdIds, inverse, validateCommand } from "./commands.mjs";
 import { CURRENT_SCHEMA_VERSION, emptyDoc, migrate, parse, serialize } from "./migrate.mjs";
 import { SceneStore } from "./store.mjs";
 import { renderElements } from "./render.mjs";
 import { initSims, stepSims } from "./sims.mjs";
 import { Scene } from "./Scene.mjs";
 
-export { CURRENT_SCHEMA_VERSION, EVALUATORS, OP_REFS, Scene, SceneStore, applyCommand, assetMeta, collectRemoved, emptyDoc, getAsset, initSims, inverse, isAssetGeom, isCircleVal, isDerived, isFree, isLineVal, isRef, isVec2, listAssets, migrate, numOf, parentIds, parse, registerAsset, renderElements, resolve, serialize, stepSims };
+export { CURRENT_SCHEMA_VERSION, EVALUATORS, OP_REFS, Scene, SceneStore, applyCommand, assetMeta, collectRemoved, createdIds, emptyDoc, getAsset, initSims, inverse, isAssetGeom, isCircleVal, isDerived, isFree, isLineVal, isRef, isVec2, listAssets, migrate, numOf, parentIds, parse, registerAsset, renderElements, resolve, serialize, stepSims, validateCommand };

package/dist/scene/migrate.mjs

@@ -9,7 +9,7 @@ function emptyDoc() {
 	};
 }
 function migrate(raw) {
-	if (Array.isArray(raw)) throw new Error("legacy GeoElement[] array — use the geoToScene codec (Phase 6)");
+	if (Array.isArray(raw)) throw new Error("legacy GeoElement[] array, use the geoToScene codec (Phase 6)");
 	if (!raw || typeof raw !== "object") return emptyDoc();
 	const doc = raw;
 	return {

package/dist/scene/sims.mjs

@@ -10,7 +10,7 @@ import { getSim } from "../sim/registry.mjs";
 * resolver stays a pure function of its inputs.
 *
 * Non-finite outputs (NaN/Inf from a diverging core) are dropped, not propagated
-* (graceful failure — a bad sim never blanks the canvas).
+* (graceful failure, a bad sim never blanks the canvas).
 */
 /** Seed each declared core from its params. */
 function initSims(decls) {

package/dist/scene/types.d.mts

@@ -165,7 +165,7 @@ interface Binding {
   props?: Record<string, unknown>;
 }
 /**
- * Structured pedagogy for a lab — first-class learning data, NOT prose buried in
+ * Structured pedagogy for a lab, first-class learning data, NOT prose buried in
  * UI text. Authored alongside the scene, surfaced to the learner seam + xAPI.
  */
 interface LabMeta {
@@ -187,7 +187,7 @@ interface LabMeta {
 }
 /**
  * A time-stepped sim wired into a scene: a registered core advances each frame and
- * its named output fields drive `scalar` elements (by id) as external inputs — so
+ * its named output fields drive `scalar` elements (by id) as external inputs, so
  * the pure resolver re-evaluates with live values without knowing about time.
  */
 interface SimDecl {
@@ -201,12 +201,12 @@ interface SimDecl {
   /** Map: scalar-element id → core-state field that feeds it. */
   drives: Record<Id, string>;
 }
-/** SceneDoc.meta — `pedagogy` + `sims` are typed; the rest stays open for domain use. */
+/** SceneDoc.meta, `pedagogy` + `sims` are typed; the rest stays open for domain use. */
 type SceneMeta = {
   pedagogy?: LabMeta;
   sims?: SimDecl[];
 } & Record<string, unknown>;
-/** Canonical persisted form. `commands[]` is NOT stored — history lives in the Editor. */
+/** Canonical persisted form. `commands[]` is NOT stored, history lives in the Editor. */
 interface SceneDoc {
   schemaVersion: 2;
   type: 'stage-scene';

package/dist/sim/particles.d.mts

@@ -28,14 +28,14 @@ interface ParticlesState {
   py: number[];
   vx: number[];
   vy: number[];
-  /** 0 or 1 — two populations (for diffusion / colour). */
+  /** 0 or 1, two populations (for diffusion / colour). */
   group: number[];
   tSec: number;
   /** Mean kinetic energy ∝ temperature. */
   temp: number;
   /** Smoothed pressure (wall-collision momentum per unit time per unit perimeter). */
   pressure: number;
-  /** Mixing index 0 (separated) → 1 (uniform) — fraction-based, for diffusion. */
+  /** Mixing index 0 (separated) → 1 (uniform), fraction-based, for diffusion. */
   mixed: number;
 }
 declare const ParticlesCore: SimCore<ParticlesState, ParticlesParams>;

package/dist/sim/rate.d.mts

@@ -8,7 +8,7 @@ interface RateParams {
   value0?: number;
   /** Asymptote the value relaxes toward. Default 0 (pure decay). */
   target?: number;
-  /** Time constant τ (seconds) — the e-folding time. Default 1. */
+  /** Time constant τ (seconds), the e-folding time. Default 1. */
   tau?: number;
   /** Stop after this many seconds (essentially relaxed) so it doesn't run forever. Default ∞. */
   maxTime?: number;
@@ -21,15 +21,15 @@ interface RateState {
   tau: number;
   /** Seconds elapsed on this core's timeline. */
   tSec: number;
-  /** Rolling history of `value`, oldest-first — for the curve. */
+  /** Rolling history of `value`, oldest-first, for the curve. */
   samples: number[];
   cap: number;
   maxTime: number;
-  /** True once tSec ≥ maxTime — the runtime stops the loop. */
+  /** True once tSec ≥ maxTime, the runtime stops the loop. */
   done: boolean;
 }
 declare const RateCore: SimCore<RateState, RateParams>;
-/** τ from a half-life (and back) — t½ = τ·ln2. */
+/** τ from a half-life (and back), t½ = τ·ln2. */
 declare const halfLifeToTau: (halfLife: number) => number;
 declare const tauToHalfLife: (tau: number) => number;
 //#endregion

package/dist/sim/rate.mjs

@@ -31,7 +31,7 @@ const RateCore = {
 		};
 	}
 };
-/** τ from a half-life (and back) — t½ = τ·ln2. */
+/** τ from a half-life (and back), t½ = τ·ln2. */
 const halfLifeToTau = (halfLife) => halfLife / Math.LN2;
 const tauToHalfLife = (tau) => tau * Math.LN2;
 

package/dist/sim/registry.d.mts

@@ -1,7 +1,7 @@
 import { SimCore } from "./types.mjs";
 
 //#region src/sim/registry.d.ts
-/** A core with its specifics erased — the runtime reads state fields by name. */
+/** A core with its specifics erased, the runtime reads state fields by name. */
 type AnySim = SimCore<Record<string, unknown>, Record<string, unknown>>;
 declare function registerSim<S extends Record<string, unknown>, P>(name: string, core: SimCore<S, P>): void;
 declare function getSim(name: string): AnySim | undefined;

package/dist/sim/sampler.d.mts

@@ -8,7 +8,7 @@ interface SamplerParams {
   perStep?: number;
   /** PRNG seed. Default 1. */
   seed?: number;
-  /** Stop drawing once `n` reaches this — a converged sim shouldn't run forever. Default ∞. */
+  /** Stop drawing once `n` reaches this, a converged sim shouldn't run forever. Default ∞. */
   maxDraws?: number;
   /** History ring-buffer capacity for the headline estimate p[0]. Default 240. */
   trace?: number;
@@ -20,7 +20,7 @@ interface SamplerState {
    * Current PRNG state (advances every draw). Deliberately NOT named `seed`: the
    * Scene runtime merges the SimDecl `params` (which carries the initial `seed`)
    * onto the state each frame, so an evolving field sharing a param name would be
-   * clobbered back to its initial value — freezing the RNG. Keep evolving state
+   * clobbered back to its initial value, freezing the RNG. Keep evolving state
    * fields disjoint from param names.
    */
   rng: number;
@@ -30,16 +30,16 @@ interface SamplerState {
   counts: number[];
   /** Running frequency estimate per outcome (counts / n). */
   p: number[];
-  /** True (normalized) probabilities — for convergence comparison. */
+  /** True (normalized) probabilities, for convergence comparison. */
   p0: number[];
   /** Index of the most recent draw (-1 before the first). */
   last: number;
-  /** Rolling history of p[0], oldest-first — for an LLN convergence plot. */
+  /** Rolling history of p[0], oldest-first, for an LLN convergence plot. */
   samples: number[];
   cap: number;
   /** Draw cap; step() becomes a no-op once n reaches it. */
   maxDraws: number;
-  /** True once n ≥ maxDraws — the runtime stops the loop. */
+  /** True once n ≥ maxDraws, the runtime stops the loop. */
   done: boolean;
 }
 declare const SamplerCore: SimCore<SamplerState, SamplerParams>;

package/dist/sim/thermal.d.mts

@@ -21,10 +21,10 @@ interface Substance {
   /** Liquid colour token (for the skin). */
   color: string;
 }
-/** Real water — the canonical example (note: latent vaporisation ≫ everything,
+/** Real water, the canonical example (note: latent vaporisation ≫ everything,
  *  so the boiling plateau dwarfs the rest, which is exactly the lesson). */
 declare const WATER: Substance;
-/** Ethanol — lower boiling point, smaller latent heats; a contrasting curve. */
+/** Ethanol, lower boiling point, smaller latent heats; a contrasting curve. */
 declare const ETHANOL: Substance;
 type Phase = 'solid' | 'melting' | 'liquid' | 'boiling' | 'gas';
 /** One run of the energy ladder. `kind:'heat'` is a sloped temperature rise
@@ -58,7 +58,7 @@ interface ThermalState {
   powerW: number;
   tStart: number;
   tMax: number;
-  /** The full energy ladder — the heating curve, as data. */
+  /** The full energy ladder, the heating curve, as data. */
   segs: ThermalSeg[];
   /** Total heat to walk the whole ladder, J. */
   totalJ: number;

package/dist/sim/thermal.mjs

@@ -1,6 +1,6 @@
 //#region src/sim/thermal.ts
 const clamp01 = (v) => Math.max(0, Math.min(1, v));
-/** Real water — the canonical example (note: latent vaporisation ≫ everything,
+/** Real water, the canonical example (note: latent vaporisation ≫ everything,
 *  so the boiling plateau dwarfs the rest, which is exactly the lesson). */
 const WATER = {
 	name: "Water",
@@ -16,7 +16,7 @@ const WATER = {
 	tBoil: 100,
 	color: "var(--stage-accent, #3b82f6)"
 };
-/** Ethanol — lower boiling point, smaller latent heats; a contrasting curve. */
+/** Ethanol, lower boiling point, smaller latent heats; a contrasting curve. */
 const ETHANOL = {
 	name: "Ethanol",
 	solidName: "solid",

package/dist/sim/types.d.mts

@@ -1,12 +1,12 @@
 //#region src/sim/types.d.ts
 /**
- * Sim cores — the "physics engine" half of a lab: pure, time-stepped simulators
+ * Sim cores, the "physics engine" half of a lab: pure, time-stepped simulators
  * with NO React and NO pixels. A core is `reset(params) → state`, then
  * `step(state, dt) → state` once per frame. Because a core is a pure function of
  * (params, elapsed time), a lab built on one is deterministic: it replays
  * identically under a Remotion fixed-frame clock (→ video) and is unit-testable
  * with no DOM. Rendering (glyphs) READS the returned state; drawing never lives
- * in here. Live controls write their target fields onto `state` between steps —
+ * in here. Live controls write their target fields onto `state` between steps ,
  * so a core's mutable inputs (e.g. `volts`, `mode`) live IN its state, which is
  * also why those fields are readable by name from a binding.
  */

package/dist/sim/wave.d.mts

@@ -22,9 +22,9 @@ interface WaveState {
   tSec: number;
   /** Instantaneous signed voltage; sign = current direction. */
   v: number;
-  /** ∫v·dt — accumulated charge displacement; what flow position (electrons / water) reads. */
+  /** ∫v·dt, accumulated charge displacement; what flow position (electrons / water) reads. */
   charge: number;
-  /** Rolling history of `v`, oldest-first, length ≤ `cap` — for the live trace. */
+  /** Rolling history of `v`, oldest-first, length ≤ `cap`, for the live trace. */
   samples: number[];
   /** Fixed capacity of `samples`. */
   cap: number;

package/dist/sim/wave.mjs

@@ -2,9 +2,9 @@ import { oscillate } from "../core/motion.mjs";
 
 //#region src/sim/wave.ts
 /**
-* `wave` — the AC/DC signal source. One core drives a whole scene: a DC source
+* `wave`, the AC/DC signal source. One core drives a whole scene: a DC source
 * holds a steady voltage; an AC source oscillates. Either way it exposes the
-* instantaneous voltage `v` (signed — sign IS current direction) plus a rolling
+* instantaneous voltage `v` (signed, sign IS current direction) plus a rolling
 * `samples` buffer for a live scrolling trace. The SAME `v` can skin many ways at
 * once (a lamp's brightness, electrons in a wire, water sloshing in a pipe), which
 * is the point: sim ≠ render, so one signal feeds every visual metaphor in sync.

package/dist/steps/index.d.mts

@@ -1,7 +1,7 @@
 import { ReactNode } from "react";
 
 //#region src/steps/index.d.ts
-/** One step in the sequence — identity + gating only. Its TITLE, PROSE, and the
+/** One step in the sequence, identity + gating only. Its TITLE, PROSE, and the
  *  interactive itself live in the authored Section block, not here. */
 interface StepSpec {
   id: string;

package/dist/steps/index.mjs

@@ -5,14 +5,14 @@ import { createContext, createElement, useContext, useMemo, useRef, useSyncExter
 
 //#region src/steps/index.ts
 /**
-* Step progress + gating — the runtime that turns an ordered sequence of lesson
+* Step progress + gating, the runtime that turns an ordered sequence of lesson
 * STEPS into "unlock the next when this one is solved" + aggregated completion.
 *
-* ONE SOURCE OF TRUTH for the step sequence is the authored content itself — the
+* ONE SOURCE OF TRUTH for the step sequence is the authored content itself, the
 * @classytic/cms-ui `Section`/`Step` blocks a creator orders in the editor
 * (serialized in the MDX). This engine deliberately does NOT model an authored
 * "LessonDoc": that would be a SECOND, competing definition of the same steps
-* (and creators never hand-write one — they build Section blocks). The host's
+* (and creators never hand-write one, they build Section blocks). The host's
 * Section player derives a `StepSpec[]` from the section order, wraps each
 * section's interactive in `<StepScope id>`, and reads `useStepProgress` to gate
 * reveal. Each lab's `useLearner().report` flows into step completion AND

package/dist/thermo/index.d.mts

@@ -1,6 +1,6 @@
 //#region src/thermo/index.d.ts
 /**
- * `thermo` — ideal-gas thermodynamic processes, as a PURE kernel (like `field`:
+ * `thermo`, ideal-gas thermodynamic processes, as a PURE kernel (like `field`:
  * no React, no pixels, no time-stepping). A lab drives it with a slider/progress
  * fraction; the kernel returns the full P–V path of a quasi-static process plus the
  * first-law bookkeeping along it (work, heat, internal energy, entropy).

package/dist/thermo/index.mjs

@@ -1,6 +1,6 @@
 //#region src/thermo/index.ts
 /**
-* `thermo` — ideal-gas thermodynamic processes, as a PURE kernel (like `field`:
+* `thermo`, ideal-gas thermodynamic processes, as a PURE kernel (like `field`:
 * no React, no pixels, no time-stepping). A lab drives it with a slider/progress
 * fraction; the kernel returns the full P–V path of a quasi-static process plus the
 * first-law bookkeeping along it (work, heat, internal energy, entropy).

package/dist/view/Stage.mjs

@@ -8,10 +8,10 @@ import { jsx, jsxs } from "react/jsx-runtime";
 
 //#region src/view/Stage.tsx
 /**
-* <Stage> — the SVG root. SSR-safe: builds a CoordinateSystem from explicit
+* <Stage>, the SVG root. SSR-safe: builds a CoordinateSystem from explicit
 * width/height/aspectRatio (or a default) so children render on first paint;
 * after mount a ResizeObserver swaps in the measured width. There is ONE content
-* group with no transform — every primitive self-positions via coords.toPx().
+* group with no transform, every primitive self-positions via coords.toPx().
 * A pixel-space overlay group hosts selection halos/handles (builder phase).
 */
 const DEFAULT_VIEW = {
@@ -31,7 +31,7 @@ function Stage({ view = DEFAULT_VIEW, width, height, aspectRatio, pad = 12, pres
 	}), [
 		w,
 		h,
-		view,
+		`${view.xMin} ${view.xMax} ${view.yMin} ${view.yMax}`,
 		pad,
 		preserveAspect
 	]);
@@ -43,8 +43,7 @@ function Stage({ view = DEFAULT_VIEW, width, height, aspectRatio, pad = 12, pres
 	} : void 0;
 	return /* @__PURE__ */ jsx("div", {
 		ref: wrapRef,
-		className,
-		style: { width: "100%" },
+		className: ["stage-root", className].filter(Boolean).join(" "),
 		children: /* @__PURE__ */ jsxs("svg", {
 			ref: svgRef,
 			width: w,
@@ -53,14 +52,8 @@ function Stage({ view = DEFAULT_VIEW, width, height, aspectRatio, pad = 12, pres
 			role: "group",
 			"aria-label": ariaLabel,
 			onPointerDown: handlePointer,
-			style: {
-				display: "block",
-				background,
-				borderRadius: 12,
-				border: "1px solid var(--stage-grid)",
-				userSelect: "none",
-				touchAction: "none"
-			},
+			className: "stage-canvas",
+			style: { background },
 			children: [/* @__PURE__ */ jsx("defs", { children: /* @__PURE__ */ jsx("marker", {
 				id: "stage-arrow",
 				viewBox: "0 0 10 10",

package/dist/view/useInView.mjs

@@ -4,7 +4,7 @@ import { useEffect, useRef, useState } from "react";
 
 //#region src/view/useInView.ts
 /**
-* useInView — pause work when a lab scrolls off-screen. Sim labs drive an
+* useInView, pause work when a lab scrolls off-screen. Sim labs drive an
 * unbounded requestAnimationFrame loop; without this, every sim on a page runs
 * forever even when nobody can see it (and a gallery of labs pins the CPU). Gate
 * `useFrameLoop({ running: inView })` on this. SSR-safe; if IntersectionObserver