@classytic/stage 0.1.0 → 0.2.0

package/README.md

@@ -3,7 +3,7 @@
 **Domain‑neutral visual primitive engine for the web.** Declarative SVG diagram/math
 primitives, draggable handles, a math↔pixel coordinate system, theming, a parametric
 asset/glyph kit, a serializable `SceneDoc` graph (resolver + command/undo), and a
-`LessonDoc` sequence engine. Reactive, web‑native, SSR‑safe, and agent‑drivable — the
+stepped‑lesson sequence engine (`StepSpec`). Reactive, web‑native, SSR‑safe, and agent‑drivable — the
 render foundation under [`@classytic/labs`](https://github.com/classytic/labs).
 
 ```bash
@@ -27,7 +27,7 @@ your bundle pulls only what it uses (ESM, per‑file emit; `sideEffects` are sco
 | `@classytic/stage/builder` | `Editor`, `SceneBuilder`, `Palette`, construction `*_TOOLS` |
 | `@classytic/stage/assets` | `StageAssetDefs` + the glyph kit (`XBlockGlyph`, `WeightGlyph`, `BucketGlyph`, `HangerHook`) |
 | `@classytic/stage/math` | dependency‑free expression engine (`compileExpr`, `differentiate`, `toLatex`…) |
-| `@classytic/stage/lesson` | `LessonProvider`, `useLessonProgress`, `LessonStepScope` (sequence + gating + progress) |
+| `@classytic/stage/steps` | `StepProgressProvider`, `useStepProgress`, `StepScope` (step sequence + gating + progress) |
 | `@classytic/stage/styles.css` | theme tokens + control‑kit CSS (import once in global CSS) |
 
 ## Quick start

package/dist/assets/kit/glyphs.d.mts

@@ -8,7 +8,7 @@ interface GlyphBox {
   hpx: number;
   label: string;
 }
-/** The UNKNOWN — a crisp rounded tile with an italic label (e.g. "2x"). */
+/** The UNKNOWN, a crisp rounded tile with an italic label (e.g. "2x"). */
 declare function XBlockGlyph({
   cx,
   top,
@@ -16,7 +16,7 @@ declare function XBlockGlyph({
   hpx,
   label
 }: GlyphBox): ReactNode;
-/** A container of UNKNOWN amount — a pail, brand-colored (it IS an unknown, like
+/** A container of UNKNOWN amount, a pail, brand-colored (it IS an unknown, like
  *  the tile), labelled "?" until revealed. Built with real form: one light
  *  direction (top-left), 2-tone shading for volume (gradient body + a soft
  *  right-side shadow + a left specular streak), a rim with visible thickness
@@ -33,13 +33,13 @@ interface HangerHookProps {
   /** Attach point on the beam/arm (pixels). */
   topX: number;
   topY: number;
-  /** Attach point on the load — the top-centre of the glyph it carries (pixels). */
+  /** Attach point on the load, the top-centre of the glyph it carries (pixels). */
   botX: number;
   botY: number;
 }
 /**
  * A suspension: a thin eye on the beam, a taut thread, and an S-hook that grips
- * the load — the realistic way a weight hangs from an arm (replaces the old
+ * the load, the realistic way a weight hangs from an arm (replaces the old
  * bare "line + dot"). Pure pixel glyph: callers project math→px first. Layered
  * edge/metal/sheen strokes match the beam's metallic read.
  */
@@ -49,7 +49,7 @@ declare function HangerHook({
   botX,
   botY
 }: HangerHookProps): ReactNode;
-/** A KNOWN value — a clean flat coin with the number. */
+/** A KNOWN value, a clean flat coin with the number. */
 declare function WeightGlyph({
   cx,
   top,

package/dist/assets/kit/glyphs.mjs

@@ -3,7 +3,7 @@
 import { jsx, jsxs } from "react/jsx-runtime";
 
 //#region src/assets/kit/glyphs.tsx
-/** The UNKNOWN — a crisp rounded tile with an italic label (e.g. "2x"). */
+/** The UNKNOWN, a crisp rounded tile with an italic label (e.g. "2x"). */
 function XBlockGlyph({ cx, top, wpx, hpx, label }) {
 	const s = Math.min(wpx, hpx);
 	const x0 = cx - s / 2;
@@ -50,7 +50,7 @@ function XBlockGlyph({ cx, top, wpx, hpx, label }) {
 		})
 	] });
 }
-/** A container of UNKNOWN amount — a pail, brand-colored (it IS an unknown, like
+/** A container of UNKNOWN amount, a pail, brand-colored (it IS an unknown, like
 *  the tile), labelled "?" until revealed. Built with real form: one light
 *  direction (top-left), 2-tone shading for volume (gradient body + a soft
 *  right-side shadow + a left specular streak), a rim with visible thickness
@@ -156,7 +156,7 @@ function BucketGlyph({ cx, top, wpx, hpx, label }) {
 }
 /**
 * A suspension: a thin eye on the beam, a taut thread, and an S-hook that grips
-* the load — the realistic way a weight hangs from an arm (replaces the old
+* the load, the realistic way a weight hangs from an arm (replaces the old
 * bare "line + dot"). Pure pixel glyph: callers project math→px first. Layered
 * edge/metal/sheen strokes match the beam's metallic read.
 */
@@ -210,7 +210,7 @@ function HangerHook({ topX, topY, botX, botY }) {
 		})
 	] });
 }
-/** A KNOWN value — a clean flat coin with the number. */
+/** A KNOWN value, a clean flat coin with the number. */
 function WeightGlyph({ cx, top, wpx, hpx, label }) {
 	const r = Math.min(wpx, hpx) / 2;
 	const cy = top + r;

package/dist/builder/SceneBuilder.mjs

@@ -14,9 +14,9 @@ import { jsx, jsxs } from "react/jsx-runtime";
 
 //#region src/builder/SceneBuilder.tsx
 /**
-* <SceneBuilder> — the click-to-construct authoring surface. Pick a tool, click
+* <SceneBuilder>, the click-to-construct authoring surface. Pick a tool, click
 * the canvas: every action funnels through the Editor command stack (undo/redo +
-* the agent API). Output is a SceneDoc (onSave) — the same JSON the player
+* the agent API). Output is a SceneDoc (onSave), the same JSON the player
 * renders and the DB stores. Free points drag only in Select mode, so clicks in
 * other tools go to the tool, not a drag.
 */
@@ -236,7 +236,7 @@ function SceneBuilder({ initial, onSave, view, height = 440, tools, authoring =
 						cursor: "pointer",
 						fontWeight: 600
 					},
-					children: "Pedagogy — objectives · hints · difficulty"
+					children: "Pedagogy, objectives · hints · difficulty"
 				}), /* @__PURE__ */ jsxs("div", {
 					style: {
 						display: "grid",
@@ -306,7 +306,7 @@ function SceneBuilder({ initial, onSave, view, height = 440, tools, authoring =
 								},
 								children: [/* @__PURE__ */ jsx("option", {
 									value: "",
-									children: "—"
+									children: ", "
 								}), [
 									1,
 									2,

package/dist/builder/editor.d.mts

@@ -21,7 +21,8 @@ declare class Editor {
   getResolved(): Resolved;
   subscribe(fn: () => void): () => void;
   private emit;
-  /** Apply a command. The ONLY mutation entry point. */
+  /** Apply a command. The ONLY mutation entry point. Validates first: an invalid command (bad
+   *  id, dangling binding, missing target) is REJECTED with a reason and the doc is untouched. */
   dispatch(cmd: Command, opts?: DispatchOpts): CommandResult;
   /** Group boundary marker (label-only in this impl; batch commands group atomically). */
   mark(_label?: string): void;

package/dist/builder/editor.mjs

@@ -1,12 +1,12 @@
 'use client';
 
 import { resolve } from "../scene/resolve.mjs";
-import { applyCommand, inverse } from "../scene/commands.mjs";
+import { applyCommand, createdIds, inverse, validateCommand } from "../scene/commands.mjs";
 import { useEffect, useReducer, useRef, useState } from "react";
 
 //#region src/builder/editor.ts
 /**
-* Editor — the single funnel for ALL scene mutations (builder tools, agents,
+* Editor, the single funnel for ALL scene mutations (builder tools, agents,
 * undo/redo, the control-surface bridge). Commands ARE the agent action API:
 * dispatch(cmd) is exactly what a human tool, a voice agent, and an undo all call.
 * Drag is an ephemeral overlay layer; updateDrag writes no command (no undo, no
@@ -48,8 +48,14 @@ var Editor = class {
 	emit() {
 		this.listeners.forEach((l) => l());
 	}
-	/** Apply a command. The ONLY mutation entry point. */
+	/** Apply a command. The ONLY mutation entry point. Validates first: an invalid command (bad
+	*  id, dangling binding, missing target) is REJECTED with a reason and the doc is untouched. */
 	dispatch(cmd, opts = {}) {
+		const error = validateCommand(this.doc, cmd);
+		if (error) return {
+			ok: false,
+			error
+		};
 		const inv = inverse(cmd, this.doc);
 		this.doc = applyCommand(this.doc, cmd);
 		if (opts.history !== "ignore") {
@@ -60,7 +66,11 @@ var Editor = class {
 			this.redoStack = [];
 		}
 		this.emit();
-		return { ok: true };
+		const ids = createdIds(cmd);
+		return ids.length ? {
+			ok: true,
+			createdIds: ids
+		} : { ok: true };
 	}
 	/** Group boundary marker (label-only in this impl; batch commands group atomically). */
 	mark(_label) {}

package/dist/builder/tools.d.mts

@@ -36,7 +36,7 @@ declare const MIDPOINT: Tool;
 declare const INTERSECT: Tool;
 declare const MEASURE: Tool;
 declare const DELETE: Tool;
-/** A free scalar parameter — appears as a live slider in the authoring strip. */
+/** A free scalar parameter, appears as a live slider in the authoring strip. */
 declare const SCALAR: Tool;
 /** A free text note placed in the scene. */
 declare const NOTE: Tool;

package/dist/builder/tools.mjs

@@ -224,7 +224,7 @@ const DELETE = {
 		});
 	}
 };
-/** A free scalar parameter — appears as a live slider in the authoring strip. */
+/** A free scalar parameter, appears as a live slider in the authoring strip. */
 const SCALAR = {
 	id: "scalar",
 	icon: "scalar",

package/dist/chem/index.d.mts

@@ -1,6 +1,6 @@
 //#region src/chem/index.d.ts
 /**
- * `chem` — acid–base / pH AND electrochemistry / Nernst, as a PURE kernel (no
+ * `chem`, acid–base / pH AND electrochemistry / Nernst, as a PURE kernel (no
  * React, no pixels). The engine behind titration curves, pH problems, and galvanic
  * cells.
  *
@@ -11,8 +11,8 @@
  *
  * where n_a is the acid initially present, n_b the strong base added, V the total
  * volume. A strong acid is just the K_a → ∞ limit (fully dissociated). Solving the
- * balance (monotonic in h → bisection) is robust everywhere — initial point, buffer
- * region, equivalence, and past it — with no piecewise approximations to get wrong.
+ * balance (monotonic in h → bisection) is robust everywhere, initial point, buffer
+ * region, equivalence, and past it, with no piecewise approximations to get wrong.
  *
  * Concentrations in mol/L, volumes in litres. Currently models an ACID analyte
  * titrated by a STRONG BASE (covers strong-acid and weak-acid curves).
@@ -81,7 +81,7 @@ interface CellResult {
 declare function galvanicCell(x: HalfCell, y: HalfCell, T?: number): CellResult;
 /** Arrhenius rate constant k = A·e^(−Ea/RT). */
 declare function arrhenius(A: number, Ea: number, T: number): number;
-/** Ratio k(T)/k(Tref) at fixed Ea — the stable way to scale a rate without a raw A. */
+/** Ratio k(T)/k(Tref) at fixed Ea, the stable way to scale a rate without a raw A. */
 declare function arrheniusRatio(Ea: number, T: number, Tref?: number): number;
 /** Fraction of molecules with energy ≥ Ea (Boltzmann) ≈ e^(−Ea/RT). */
 declare function fractionAboveEa(Ea: number, T: number): number;
@@ -94,7 +94,7 @@ interface StoichSpecies {
   name: string;
   /** Stoichiometric coefficient in the balanced equation. */
   coeff: number;
-  /** Molar mass, g/mol (optional — enables grams in the result). */
+  /** Molar mass, g/mol (optional, enables grams in the result). */
   molarMass?: number;
 }
 interface StoichResult {

package/dist/chem/index.mjs

@@ -1,6 +1,6 @@
 //#region src/chem/index.ts
 /**
-* `chem` — acid–base / pH AND electrochemistry / Nernst, as a PURE kernel (no
+* `chem`, acid–base / pH AND electrochemistry / Nernst, as a PURE kernel (no
 * React, no pixels). The engine behind titration curves, pH problems, and galvanic
 * cells.
 *
@@ -11,8 +11,8 @@
 *
 * where n_a is the acid initially present, n_b the strong base added, V the total
 * volume. A strong acid is just the K_a → ∞ limit (fully dissociated). Solving the
-* balance (monotonic in h → bisection) is robust everywhere — initial point, buffer
-* region, equivalence, and past it — with no piecewise approximations to get wrong.
+* balance (monotonic in h → bisection) is robust everywhere, initial point, buffer
+* region, equivalence, and past it, with no piecewise approximations to get wrong.
 *
 * Concentrations in mol/L, volumes in litres. Currently models an ACID analyte
 * titrated by a STRONG BASE (covers strong-acid and weak-acid curves).
@@ -90,7 +90,7 @@ function galvanicCell(x, y, T = T_STD) {
 function arrhenius(A, Ea, T) {
 	return A * Math.exp(-Ea / (R * T));
 }
-/** Ratio k(T)/k(Tref) at fixed Ea — the stable way to scale a rate without a raw A. */
+/** Ratio k(T)/k(Tref) at fixed Ea, the stable way to scale a rate without a raw A. */
 function arrheniusRatio(Ea, T, Tref = T_STD) {
 	return Math.exp(-(Ea / R) * (1 / T - 1 / Tref));
 }

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