@classytic/stage 0.1.0 → 0.2.0

package/dist/math/ast.mjs

@@ -2,7 +2,7 @@ import { CONSTANTS, FN1, FN2 } from "./defs.mjs";
 
 //#region src/math/ast.ts
 /**
-* expr/ast — the Abstract Syntax Tree: node types, evaluation, free-variable
+* expr/ast, the Abstract Syntax Tree: node types, evaluation, free-variable
 * collection, and small builder helpers. The AST is the shared representation
 * that evaluation, differentiation, simplification, and LaTeX printing all
 * operate on.

package/dist/math/calculus.mjs

@@ -3,7 +3,7 @@ import { add, call, div, mul, neg, num, pow, sub } from "./ast.mjs";
 
 //#region src/math/calculus.ts
 /**
-* expr/calculus — symbolic differentiation + algebraic simplification on the AST.
+* expr/calculus, symbolic differentiation + algebraic simplification on the AST.
 *
 * `differentiate(node, x)` returns the exact derivative as a new AST, or `null`
 * when the expression contains something not symbolically differentiable
@@ -71,6 +71,72 @@ function differentiate(node, x) {
 	}
 }
 const isNum = (n, v) => n.type === "num" && (v === void 0 || n.value === v);
+/** A stable structural key, so identical cores group (x and x; x² and x²). */
+function nodeKey(n) {
+	switch (n.type) {
+		case "num": return `#${n.value}`;
+		case "var": return `$${n.name}`;
+		case "neg": return `-${nodeKey(n.arg)}`;
+		case "binary": return `(${nodeKey(n.left)}${n.op}${nodeKey(n.right)})`;
+		case "call": return `${n.fn}(${n.args.map(nodeKey).join(",")})`;
+		default: return "?";
+	}
+}
+/** Split a term into (numeric coefficient, the rest); core null = a pure number. */
+function splitCoeff(n) {
+	if (n.type === "num") return [n.value, null];
+	if (n.type === "neg") {
+		const [c, core] = splitCoeff(n.arg);
+		return [-c, core];
+	}
+	if (n.type === "binary" && n.op === "*") {
+		if (n.left.type === "num") return [n.left.value, n.right];
+		if (n.right.type === "num") return [n.right.value, n.left];
+	}
+	return [1, n];
+}
+/** Flatten a +/- chain into signed (coeff, core) terms. */
+function flattenTerms(node, s, out) {
+	if (node.type === "binary" && (node.op === "+" || node.op === "-")) {
+		flattenTerms(node.left, s, out);
+		flattenTerms(node.right, node.op === "-" ? -s : s, out);
+		return;
+	}
+	if (node.type === "neg") {
+		flattenTerms(node.arg, -s, out);
+		return;
+	}
+	const [coeff, core] = splitCoeff(node);
+	out.push({
+		coeff: coeff * s,
+		core
+	});
+}
+/** Combine like terms across `l op r`: 2x + 3x → 5x, x − x → 0, constants merge. */
+function combineLikeTerms(l, r, op) {
+	const list = [];
+	flattenTerms(l, 1, list);
+	flattenTerms(r, op === "-" ? -1 : 1, list);
+	const groups = /* @__PURE__ */ new Map();
+	for (const t of list) {
+		const k = t.core ? nodeKey(t.core) : "";
+		const g = groups.get(k);
+		if (g) g.coeff += t.coeff;
+		else groups.set(k, {
+			coeff: t.coeff,
+			core: t.core
+		});
+	}
+	let result = null;
+	for (const { coeff, core } of groups.values()) {
+		if (Math.abs(coeff) < 1e-12) continue;
+		const mag = Math.abs(coeff);
+		const body = core === null ? num(mag) : mag === 1 ? core : mul(num(mag), core);
+		if (result === null) result = coeff < 0 ? neg(body) : body;
+		else result = coeff < 0 ? sub(result, body) : add(result, body);
+	}
+	return result ?? num(0);
+}
 /** Fold constants and trivial identities so derivative output is readable. */
 function simplify(node) {
 	switch (node.type) {
@@ -90,15 +156,8 @@ function simplify(node) {
 				const v = fold(op, l.value, r.value);
 				if (v !== null && Number.isFinite(v)) return num(v);
 			}
+			if (op === "+" || op === "-") return combineLikeTerms(l, r, op);
 			switch (op) {
-				case "+":
-					if (isNum(l, 0)) return r;
-					if (isNum(r, 0)) return l;
-					break;
-				case "-":
-					if (isNum(r, 0)) return l;
-					if (isNum(l, 0)) return simplify(neg(r));
-					break;
 				case "*":
 					if (isNum(l, 0) || isNum(r, 0)) return num(0);
 					if (isNum(l, 1)) return r;

package/dist/math/compile.d.mts

@@ -0,0 +1,8 @@
+import { Node } from "./ast.mjs";
+
+//#region src/math/compile.d.ts
+type CompiledFn = (scope?: Record<string, number>) => number;
+/** Compile an AST to a fast `(scope) => number`. */
+declare function compile(node: Node): CompiledFn;
+//#endregion
+export { CompiledFn, compile };

package/dist/math/compile.mjs

@@ -0,0 +1,40 @@
+import { CONSTANTS, FN1, FN2 } from "./defs.mjs";
+
+//#region src/math/compile.ts
+const JS_OP = {
+	"+": "+",
+	"-": "-",
+	"*": "*",
+	"/": "/",
+	"%": "%",
+	"^": "**"
+};
+/** Emit a JS expression string (every node fully parenthesised, so `**` and unary
+*  minus never collide — `(-x)**2` is valid, `-x**2` is a JS SyntaxError). */
+function gen(node) {
+	switch (node.type) {
+		case "num": return `(${node.value})`;
+		case "var": {
+			const lc = node.name.toLowerCase();
+			if (lc in CONSTANTS) return `(${CONSTANTS[lc]})`;
+			return `(s[${JSON.stringify(node.name)}]??NaN)`;
+		}
+		case "neg": return `(-${gen(node.arg)})`;
+		case "binary": return `(${gen(node.left)}${JS_OP[node.op] ?? "+"}${gen(node.right)})`;
+		case "call": {
+			const a = node.args.map(gen);
+			if (node.fn in FN1 && a[0]) return `F1[${JSON.stringify(node.fn)}](${a[0]})`;
+			if (node.fn in FN2 && a[0] && a[1]) return `F2[${JSON.stringify(node.fn)}](${a[0]},${a[1]})`;
+			return "NaN";
+		}
+		default: return "NaN";
+	}
+}
+/** Compile an AST to a fast `(scope) => number`. */
+function compile(node) {
+	const f = new Function("s", "F1", "F2", `return ${gen(node)};`);
+	return (scope = {}) => f(scope, FN1, FN2);
+}
+
+//#endregion
+export { compile };

package/dist/math/defs.mjs

@@ -1,6 +1,6 @@
 //#region src/math/defs.ts
 /**
-* expr/defs — the function & constant tables shared by the tokenizer, evaluator,
+* expr/defs, the function & constant tables shared by the tokenizer, evaluator,
 * differentiator, and LaTeX printer. Pure data; no AST knowledge here.
 */
 const CONSTANTS = {

package/dist/math/index.d.mts

@@ -1,6 +1,7 @@
 import { BinOp, Node, compileNode, evaluate, freeVars } from "./ast.mjs";
 import { parse } from "./parse.mjs";
 import { differentiate, simplify } from "./calculus.mjs";
+import { CompiledFn, compile } from "./compile.mjs";
 import { toLatex } from "./latex.mjs";
 
 //#region src/math/index.d.ts
@@ -9,7 +10,7 @@ interface CompiledExpr {
   readonly fn: (scope: Record<string, number>) => number;
   /** Free variables referenced (excludes constants & functions), e.g. `['x','a']`. */
   readonly vars: string[];
-  /** The parsed syntax tree — for differentiation, LaTeX, or analysis. */
+  /** The parsed syntax tree, for differentiation, LaTeX, or analysis. */
   readonly ast: Node;
   readonly error?: undefined;
 }
@@ -20,7 +21,7 @@ interface ExprError {
   readonly ast?: undefined;
 }
 type ExprResult = CompiledExpr | ExprError;
-/** Compile a formula string. Returns `{ fn, vars, ast }` or `{ error }` — never throws. */
+/** Compile a formula string. Returns `{ fn, vars, ast }` or `{ error }`, never throws. */
 declare function compileExpr(src: string): ExprResult;
 //#endregion
-export { type BinOp, CompiledExpr, ExprError, ExprResult, type Node, compileExpr, compileNode, differentiate, evaluate, freeVars, parse, simplify, toLatex };
+export { type BinOp, CompiledExpr, type CompiledFn, ExprError, ExprResult, type Node, compile, compileExpr, compileNode, differentiate, evaluate, freeVars, parse, simplify, toLatex };

package/dist/math/index.mjs

@@ -1,11 +1,12 @@
 import { compileNode, evaluate, freeVars } from "./ast.mjs";
 import { parse } from "./parse.mjs";
 import { differentiate, simplify } from "./calculus.mjs";
+import { compile } from "./compile.mjs";
 import { toLatex } from "./latex.mjs";
 
 //#region src/math/index.ts
 /**
-* expr — a tiny, safe, dependency-free symbolic math engine.
+* expr, a tiny, safe, dependency-free symbolic math engine.
 *
 * Pipeline: `tokenize → parse (AST) → evaluate`. On top of the AST it offers
 * exact `differentiate`, `simplify`, and `toLatex`, so the same typed formula
@@ -22,7 +23,7 @@ import { toLatex } from "./latex.mjs";
 * csc asin acos atan sinh cosh tanh sqrt cbrt abs exp ln log log2 log10 floor
 * ceil round sign` (+ 2-arg `pow atan2 min max mod hypot`).
 */
-/** Compile a formula string. Returns `{ fn, vars, ast }` or `{ error }` — never throws. */
+/** Compile a formula string. Returns `{ fn, vars, ast }` or `{ error }`, never throws. */
 function compileExpr(src) {
 	if (!src || !src.trim()) return { error: "Empty expression" };
 	let ast;
@@ -39,4 +40,4 @@ function compileExpr(src) {
 }
 
 //#endregion
-export { compileExpr, compileNode, differentiate, evaluate, freeVars, parse, simplify, toLatex };
+export { compile, compileExpr, compileNode, differentiate, evaluate, freeVars, parse, simplify, toLatex };

package/dist/math/parse.mjs

@@ -4,11 +4,11 @@ import { bin, call, neg, num, variable } from "./ast.mjs";
 
 //#region src/math/parse.ts
 /**
-* expr/parse — token stream → AST, via precedence-climbing (Pratt).
+* expr/parse, token stream → AST, via precedence-climbing (Pratt).
 *
 * Binary precedence: `+ -` < `* / %` < `^` (right-assoc). Unary minus binds
 * looser than `^` (so `-2^2 = -(2^2) = -4`) but tighter than `*`. Throws a
-* descriptive Error on malformed input — the parser is the single source of
+* descriptive Error on malformed input, the parser is the single source of
 * truth for "is this expression well-formed?".
 */
 const BIN_PREC = {

package/dist/math/tokenize.mjs

@@ -2,7 +2,7 @@ import { isFunction } from "./defs.mjs";
 
 //#region src/math/tokenize.ts
 /**
-* expr/tokenize — source string → token stream.
+* expr/tokenize, source string → token stream.
 *
 * Handles numbers (incl. `1.5e3`, rejecting malformed `2..3`), identifiers
 * (classified as function vs variable), operators, parens, and commas. Inserts

package/dist/primitives/CanvasLayer.mjs

@@ -7,16 +7,16 @@ import { jsx } from "react/jsx-runtime";
 
 //#region src/primitives/CanvasLayer.tsx
 /**
-* <CanvasLayer> — the engine's HIGH-ELEMENT-COUNT escape hatch: a zero-dependency
+* <CanvasLayer>, the engine's HIGH-ELEMENT-COUNT escape hatch: a zero-dependency
 * HiDPI <canvas> that shares the engine's coordinate system + clock. Use it when
 * a lab needs a heatmap, a particle/gas sim, or thousands of moving dots at 60fps
-* — cases where one retained SVG node per element would drop frames. Declarative,
+*, cases where one retained SVG node per element would drop frames. Declarative,
 * low-count, accessible figures should stay on <Stage> (SVG); this is the
 * deliberate, bundle-free alternative to a WebGL engine (no Pixi/three dependency)
 * until a lab MEASURABLY needs shaders/tens-of-thousands of textured sprites.
 *
 * `draw(ctx, coords)` runs in CSS-pixel space (the context is pre-scaled for dpr)
-* on mount, on resize, and whenever `draw`'s identity changes — so memoize it on
+* on mount, on resize, and whenever `draw`'s identity changes, so memoize it on
 * your state (or bump it from a useFrameLoop tick) to drive animation. Overlay a
 * sibling <Stage> with the SAME view for accessible SVG handles/labels on top.
 */

package/dist/primitives/Grid.d.mts

@@ -5,18 +5,27 @@ import { ReactNode } from "react";
 declare function niceStep(span: number, target?: number): number;
 interface GridProps {
   step?: number;
+  /** Per-axis overrides (win over `step`); keeps a tall-thin or short-wide plot
+   *  from inheriting the other axis's spacing. */
+  stepX?: number;
+  stepY?: number;
   color?: string;
 }
 declare function Grid({
   step,
+  stepX,
+  stepY,
   color
 }: GridProps): ReactNode;
 interface AxesProps {
   color?: string;
   ticks?: boolean;
   step?: number;
+  /** Per-axis tick spacing overrides (win over `step`). */
+  stepX?: number;
+  stepY?: number;
   /** Show the numeric value at each tick (and a "0" at the origin) so learners
-   *  can READ coordinates off the grid — needed for graphs where the answer is a
+   *  can READ coordinates off the grid, needed for graphs where the answer is a
    *  point (systems, plotting). Default off (most figures want a clean axis). */
   labels?: boolean;
 }
@@ -24,6 +33,8 @@ declare function Axes({
   color,
   ticks,
   step,
+  stepX,
+  stepY,
   labels
 }: AxesProps): ReactNode;
 //#endregion

package/dist/primitives/Grid.mjs

@@ -17,11 +17,12 @@ function tickValues(min, max, step) {
 	for (let v = start; v <= max + step * 1e-6; v += step) out.push(Math.round(v / step) * step);
 	return out;
 }
-function Grid({ step, color = "var(--stage-grid)" }) {
+function Grid({ step, stepX, stepY, color = "var(--stage-grid)" }) {
 	const c = useCoords();
-	const s = step ?? niceStep(c.view.xMax - c.view.xMin);
+	const sx = stepX ?? step ?? niceStep(c.view.xMax - c.view.xMin);
+	const sy = stepY ?? step ?? niceStep(c.view.yMax - c.view.yMin);
 	const lines = [];
-	for (const x of tickValues(c.view.xMin, c.view.xMax, s)) {
+	for (const x of tickValues(c.view.xMin, c.view.xMax, sx)) {
 		const a = c.toPx(x, c.view.yMin);
 		const b = c.toPx(x, c.view.yMax);
 		lines.push(/* @__PURE__ */ jsx("line", {
@@ -33,7 +34,7 @@ function Grid({ step, color = "var(--stage-grid)" }) {
 			strokeWidth: 1
 		}, `gx${x}`));
 	}
-	for (const y of tickValues(c.view.yMin, c.view.yMax, s)) {
+	for (const y of tickValues(c.view.yMin, c.view.yMax, sy)) {
 		const a = c.toPx(c.view.xMin, y);
 		const b = c.toPx(c.view.xMax, y);
 		lines.push(/* @__PURE__ */ jsx("line", {
@@ -47,10 +48,15 @@ function Grid({ step, color = "var(--stage-grid)" }) {
 	}
 	return /* @__PURE__ */ jsx("g", { children: lines });
 }
-const fmtTick = (v) => Number.isInteger(v) ? String(v) : v.toFixed(1);
-function Axes({ color = "var(--stage-axis)", ticks = true, step, labels = false }) {
+const fmtTick = (v) => {
+	if (Number.isInteger(v)) return String(v);
+	const r = Math.round(v * 100) / 100;
+	return String(r);
+};
+function Axes({ color = "var(--stage-axis)", ticks = true, step, stepX, stepY, labels = false }) {
 	const c = useCoords();
-	const s = step ?? niceStep(c.view.xMax - c.view.xMin);
+	const sx = stepX ?? step ?? niceStep(c.view.xMax - c.view.xMin);
+	const sy = stepY ?? step ?? niceStep(c.view.yMax - c.view.yMin);
 	const xAxisA = c.toPx(c.view.xMin, 0);
 	const xAxisB = c.toPx(c.view.xMax, 0);
 	const yAxisA = c.toPx(0, c.view.yMin);
@@ -87,7 +93,7 @@ function Axes({ color = "var(--stage-axis)", ticks = true, step, labels = false
 		strokeWidth: 1.5
 	}, "ay")];
 	if (ticks) {
-		for (const x of tickValues(c.view.xMin, c.view.xMax, s)) {
+		for (const x of tickValues(c.view.xMin, c.view.xMax, sx)) {
 			if (Math.abs(x) < 1e-9) continue;
 			const p = c.toPx(x, 0);
 			nodes.push(/* @__PURE__ */ jsx("line", {
@@ -100,7 +106,7 @@ function Axes({ color = "var(--stage-axis)", ticks = true, step, labels = false
 			}, `tx${x}`));
 			if (labels) nodes.push(num(`lx${x}`, p[0], p[1] + 14, fmtTick(x), "middle"));
 		}
-		for (const y of tickValues(c.view.yMin, c.view.yMax, s)) {
+		for (const y of tickValues(c.view.yMin, c.view.yMax, sy)) {
 			if (Math.abs(y) < 1e-9) continue;
 			const p = c.toPx(0, y);
 			nodes.push(/* @__PURE__ */ jsx("line", {

package/dist/primitives/Label.d.mts

@@ -16,7 +16,7 @@ interface LabelProps {
 }
 /** Upright pixel-space text with a background-colored outline for legibility.
  *  Renders `_`/`^` as real SVG sub/superscripts via the shared `parseRichText`
- *  grammar (the same one labs' HTML `<RichText>` uses — one source of truth). */
+ *  grammar (the same one labs' HTML `<RichText>` uses, one source of truth). */
 declare function Label({
   x,
   y,

package/dist/primitives/Label.mjs

@@ -8,7 +8,7 @@ import { jsx } from "react/jsx-runtime";
 //#region src/primitives/Label.tsx
 /** Upright pixel-space text with a background-colored outline for legibility.
 *  Renders `_`/`^` as real SVG sub/superscripts via the shared `parseRichText`
-*  grammar (the same one labs' HTML `<RichText>` uses — one source of truth). */
+*  grammar (the same one labs' HTML `<RichText>` uses, one source of truth). */
 function Label({ x, y, text, color = "var(--stage-fg)", size = 14, dx = 0, dy = 0, anchor = "middle", baseline = "middle", weight = 600 }) {
 	const [px, py] = useCoords().toPx(x, y);
 	const spans = parseRichText(text);

package/dist/primitives/Tex.mjs

@@ -8,11 +8,11 @@ import katex from "katex";
 
 //#region src/primitives/Tex.tsx
 /**
-* Tex — KaTeX maths in a <foreignObject>, rendered AT RENDER TIME (not in an
+* Tex, KaTeX maths in a <foreignObject>, rendered AT RENDER TIME (not in an
 * effect) so the markup is identical on the server and the client: SSR/static
 * exports show real maths (not raw `\left…\right`), there's no raw-then-hydrate
 * flash, and hydration matches. KaTeX is a static import kept in its OWN module so
-* only Tex's importers pull it (stage's neverBundle leaves `katex` external — the
+* only Tex's importers pull it (stage's neverBundle leaves `katex` external, the
 * consumer resolves the peer; non-Tex consumers never bundle it).
 *
 * Needs the consumer to load `katex/dist/katex.min.css` for proper glyphs.

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

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';