@classytic/labs 0.1.0 → 0.2.0

package/dist/ict/number-systems/wheel.mjs

@@ -8,10 +8,10 @@ import { useInView } from "@classytic/stage";
 //#region src/ict/number-systems/wheel.tsx
 /**
 * Shared building blocks for the number-system labs: base digit helpers + the
-* DigitWheel glyph (a mechanical odometer wheel). Tokenized SVG only — colours
+* DigitWheel glyph (a mechanical odometer wheel). Tokenized SVG only, colours
 * are `--stage-*` so the wheels retheme with the host. The roll is DATA: the lab
 * passes a 0..1 `roll` phase its frame loop decays, so the digit visibly slides
-* into place (no fake "press play" — the motion tracks the real value change).
+* into place (no fake "press play", the motion tracks the real value change).
 */
 /** Seconds for a wheel to settle after a digit changes. */
 const ROLL_DUR = .32;
@@ -133,7 +133,7 @@ function DigitWheel({ base, digit, roll = 0, dir = 1, active, onTap, ariaLabel }
 		]
 	});
 }
-/** A binary ON/OFF cell — the "lightbulb worth 2^n" picture for base-2 mode. */
+/** A binary ON/OFF cell, the "lightbulb worth 2^n" picture for base-2 mode. */
 function BitCell({ on, onTap, ariaLabel }) {
 	return /* @__PURE__ */ jsxs("svg", {
 		width: CELL_W,
@@ -183,7 +183,7 @@ function BitCell({ on, onTap, ariaLabel }) {
 }
 /**
 * A row of odometer wheels (or bit cells) for `value` in `base`, with the
-* carry-ripple roll animation OWNED here — the single reusable place-value
+* carry-ripple roll animation OWNED here, the single reusable place-value
 * primitive both PlaceValueDial and BaseOdometer compose, so the animation +
 * weight rendering live in exactly one spot.
 */

package/dist/kit/annotate.mjs

@@ -14,7 +14,7 @@ const charW = 6.4;
 /** A labelled pointer to (x,y): a dot, a leader line, and a tinted bubble offset by
 *  (dx,dy). Keep dx/dy pointing into open space so the bubble clears the figure.
 *  (Named `Pointer`, not Callout, to avoid clashing with frame.js's prose-box Callout
-*  and cms-ui's document-level Callout block — this one anchors to FIGURE geometry.) */
+*  and cms-ui's document-level Callout block, this one anchors to FIGURE geometry.) */
 function Pointer({ x, y, text, dx = 30, dy = -26, tone = "info", fontSize = 11 }) {
 	const col = TONE[tone];
 	const w = text.length * (charW * (fontSize / 11)) + 14, h = fontSize + 9;
@@ -59,7 +59,7 @@ function Pointer({ x, y, text, dx = 30, dy = -26, tone = "info", fontSize = 11 }
 		]
 	});
 }
-/** A pulsing attention ring at (cx,cy) — draws the eye to "look here". */
+/** A pulsing attention ring at (cx,cy), draws the eye to "look here". */
 function Spotlight({ cx, cy, r = 13, tone = "warn" }) {
 	const col = TONE[tone];
 	return /* @__PURE__ */ jsxs("g", {
@@ -87,7 +87,7 @@ function Spotlight({ cx, cy, r = 13, tone = "warn" }) {
 		})]
 	});
 }
-/** A span bracket from x1→x2 at height y with a centred label — "this range means …".
+/** A span bracket from x1→x2 at height y with a centred label, "this range means …".
 *  `side: 'below'` drops the ticks/label under y; 'above' lifts them over it. */
 function Bracket({ x1, x2, y, text, tone = "info", side = "below", fontSize = 11 }) {
 	const col = TONE[tone];

package/dist/kit/answer-check.d.mts

@@ -1,10 +1,10 @@
 //#region src/kit/answer-check.d.ts
 /**
- * answer-check — the "is the student right?" layer of the interactive-problem
+ * answer-check, the "is the student right?" layer of the interactive-problem
  * engine. Pure, built on @classytic/stage's expr engine. Two real modes (the ones
  * exams need): a NUMBER (value within tolerance, parsed so `pi/2` or `2*sqrt(5)`
  * count) and an EXPRESSION (any algebraically-EQUIVALENT form accepted, checked
- * BOTH symbolically — simplify(student − answer) → 0 — AND numerically by sampling,
+ * BOTH symbolically, simplify(student − answer) → 0, AND numerically by sampling,
  * so `(x+1)(x+2)` ≡ `x^2+3x+2`). No hand-marking, no "exact-string" brittleness.
  */
 /** Evaluate a numeric answer string (`3.14`, `pi/2`, `2*sqrt(5)`) → number (NaN if invalid). */

package/dist/kit/answer-check.mjs

@@ -2,11 +2,11 @@ import { compileExpr, parseExpr, simplify } from "@classytic/stage";
 
 //#region src/kit/answer-check.ts
 /**
-* answer-check — the "is the student right?" layer of the interactive-problem
+* answer-check, the "is the student right?" layer of the interactive-problem
 * engine. Pure, built on @classytic/stage's expr engine. Two real modes (the ones
 * exams need): a NUMBER (value within tolerance, parsed so `pi/2` or `2*sqrt(5)`
 * count) and an EXPRESSION (any algebraically-EQUIVALENT form accepted, checked
-* BOTH symbolically — simplify(student − answer) → 0 — AND numerically by sampling,
+* BOTH symbolically, simplify(student − answer) → 0, AND numerically by sampling,
 * so `(x+1)(x+2)` ≡ `x^2+3x+2`). No hand-marking, no "exact-string" brittleness.
 */
 /** Compile, returning the usable form or null (never the error union). */
@@ -17,9 +17,37 @@ function tryCompile(src) {
 }
 /** Evaluate a numeric answer string (`3.14`, `pi/2`, `2*sqrt(5)`) → number (NaN if invalid). */
 function parseValue(raw) {
-	const c = tryCompile(raw);
+	const c = tryCompile(normalizeMathInput(raw));
 	return c ? c.fn({}) : NaN;
 }
+/**
+* Make exam-natural input parse: accept implicit multiplication (`2x` → `2*x`,
+* `)(` → `)*(`) and a leading `y =` (`y = 2x − 3` → `2*x - 3`). Conservative , 
+* never inserts `*` before `(` after a letter, so function calls like `sin(x)`
+* survive. Unicode minus → ascii.
+*/
+const SUPERSCRIPT = {
+	"⁰": "0",
+	"¹": "1",
+	"²": "2",
+	"³": "3",
+	"⁴": "4",
+	"⁵": "5",
+	"⁶": "6",
+	"⁷": "7",
+	"⁸": "8",
+	"⁹": "9"
+};
+function normalizeMathInput(raw) {
+	let s = raw.trim().replace(/−/g, "-").replace(/×/g, "*").replace(/÷/g, "/");
+	s = s.replace(/[⁰¹²³⁴⁵⁶⁷⁸⁹]+/g, (m) => "^" + [...m].map((ch) => SUPERSCRIPT[ch]).join(""));
+	s = s.replace(/\*\*/g, "^");
+	s = s.replace(/\s+/g, "");
+	s = s.replace(/^y=/i, "");
+	s = s.replace(/(\d)([a-zA-Z(])/g, "$1*$2");
+	s = s.replace(/\)([a-zA-Z0-9(])/g, ")*$1");
+	return s;
+}
 /** Numeric match with a relative-ish tolerance (default ~1% of scale). */
 function checkNumber(student, value, tol = .01) {
 	if (!Number.isFinite(student) || !Number.isFinite(value)) return false;
@@ -28,11 +56,11 @@ function checkNumber(student, value, tol = .01) {
 const isZeroNode = (n, eps = 1e-9) => n.type === "num" && Math.abs(n.value) < eps;
 /** True if `student` is algebraically equivalent to `answer` (symbolic OR numeric). */
 function checkExpression(student, answer, opts = {}) {
-	const a = tryCompile(student);
-	const b = tryCompile(answer);
+	const a = tryCompile(normalizeMathInput(student));
+	const b = tryCompile(normalizeMathInput(answer));
 	if (!a || !b) return false;
 	try {
-		if (isZeroNode(simplify(parseExpr(`(${student}) - (${answer})`)), opts.tol ?? 1e-9)) return true;
+		if (isZeroNode(simplify(parseExpr(`(${normalizeMathInput(student)}) - (${normalizeMathInput(answer)})`)), opts.tol ?? 1e-9)) return true;
 	} catch {}
 	const vars = opts.vars ?? [...new Set([...a.vars, ...b.vars])];
 	const [lo, hi] = opts.domain ?? [-3.3, 3.7];

package/dist/kit/ask.d.mts

@@ -0,0 +1,19 @@
+import { ChallengeChoice } from "./pedagogy.mjs";
+import { AnswerSpec } from "./answer-check.mjs";
+import { ReactNode } from "react";
+
+//#region src/kit/ask.d.ts
+/** A serializable question spec an author attaches to a lab. */
+interface LabAskSpec {
+  prompt: ReactNode;
+  placeholder?: string;
+  /** Typed mode: grade the typed answer (a number, or an algebraic expression). */
+  answer?: AnswerSpec;
+  /** Multiple-choice mode: the options (set `correct` to one option's value). */
+  choices?: ChallengeChoice[];
+  correct?: string;
+  /** Shown when the right choice is picked. */
+  explain?: ReactNode;
+}
+//#endregion
+export { LabAskSpec };

package/dist/kit/ask.mjs

@@ -0,0 +1,46 @@
+'use client';
+
+import { AskBox, ChallengeCard, useChallenge, useCheckpoint } from "./pedagogy.mjs";
+import { checkAnswer } from "./answer-check.mjs";
+import { jsx } from "react/jsx-runtime";
+
+//#region src/kit/ask.tsx
+function McqAsk({ prompt, choices, answer, explain, activity }) {
+	const qs = [{
+		id: "q",
+		prompt,
+		choices,
+		answer,
+		explain
+	}];
+	const state = useChallenge(qs);
+	useCheckpoint({
+		solved: state.allCorrect,
+		activity
+	});
+	return /* @__PURE__ */ jsx(ChallengeCard, {
+		questions: qs,
+		state,
+		title: ""
+	});
+}
+/** Render a lab's question, MCQ when `choices` is given, otherwise a typed box. */
+function LabAsk({ ask, activity }) {
+	if (ask.choices && ask.choices.length) return /* @__PURE__ */ jsx(McqAsk, {
+		prompt: ask.prompt,
+		choices: ask.choices,
+		answer: ask.correct ?? "",
+		explain: ask.explain,
+		activity
+	});
+	if (ask.answer) return /* @__PURE__ */ jsx(AskBox, {
+		prompt: ask.prompt,
+		placeholder: ask.placeholder,
+		check: (r) => checkAnswer(ask.answer, r),
+		activity
+	});
+	return null;
+}
+
+//#endregion
+export { LabAsk };

package/dist/kit/bar-strip.mjs

@@ -0,0 +1,53 @@
+'use client';
+
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+import { Segment } from "@classytic/stage";
+
+//#region src/kit/bar-strip.tsx
+function BarStrip({ span, cells, shaded, y, color, weight = 32, trackColor = "var(--stage-grid)" }) {
+	const cw = span / cells;
+	const lines = [];
+	for (let i = 1; i < cells; i++) lines.push(/* @__PURE__ */ jsx(Segment, {
+		from: {
+			x: i * cw,
+			y: y - .5
+		},
+		to: {
+			x: i * cw,
+			y: y + .5
+		},
+		color: "var(--stage-bg)",
+		weight: 2
+	}, i));
+	return /* @__PURE__ */ jsxs(Fragment, { children: [
+		/* @__PURE__ */ jsx(Segment, {
+			from: {
+				x: 0,
+				y
+			},
+			to: {
+				x: span,
+				y
+			},
+			color: trackColor,
+			weight,
+			opacity: .55
+		}),
+		shaded > 0 && /* @__PURE__ */ jsx(Segment, {
+			from: {
+				x: 0,
+				y
+			},
+			to: {
+				x: shaded * cw,
+				y
+			},
+			color,
+			weight
+		}),
+		lines
+	] });
+}
+
+//#endregion
+export { BarStrip };

package/dist/kit/calc.d.mts

@@ -0,0 +1,33 @@
+//#region src/kit/calc.d.ts
+/**
+ * Worked-calculation core. A lab that just prints an answer teaches nothing; this
+ * makes a calculation SHOW ITS WORKING — every substitution and simplification as
+ * a rendered line — so an author can demonstrate HOW a rule computes, not just
+ * what it returns. Pure + dependency-free: the engine produces data (a value plus
+ * a list of LaTeX steps); a component renders it.
+ *
+ * Pair with kit/rule's <RuleCard> (formula + analogy + this calculation +
+ * derivation + tricks) to turn a bare formula into a smart, authorable concept.
+ */
+/** One line of a worked calculation: a LaTeX expression + an optional plain note. */
+interface CalcStep {
+  tex: string;
+  /** Why this step follows ("substitute n = 5", "the falling product"). */
+  note?: string;
+}
+/** The result of a worked calculation: the final value + the steps that got there. */
+interface Worked {
+  value: number;
+  steps: CalcStep[];
+}
+/** A tiny fluent builder: calc().step('…','…').step('…').done(value). */
+declare class Calc {
+  private readonly _steps;
+  step(tex: string, note?: string): this;
+  done(value: number): Worked;
+}
+declare const calc: () => Calc;
+/** Format a number for inline LaTeX (thin-space thousands so big counts read). */
+declare function texNum(n: number): string;
+//#endregion
+export { Calc, CalcStep, Worked, calc, texNum };

package/dist/kit/calc.mjs

@@ -0,0 +1,27 @@
+//#region src/kit/calc.ts
+/** A tiny fluent builder: calc().step('…','…').step('…').done(value). */
+var Calc = class {
+	_steps = [];
+	step(tex, note) {
+		this._steps.push(note === void 0 ? { tex } : {
+			tex,
+			note
+		});
+		return this;
+	}
+	done(value) {
+		return {
+			value,
+			steps: this._steps
+		};
+	}
+};
+const calc = () => new Calc();
+/** Format a number for inline LaTeX (thin-space thousands so big counts read). */
+function texNum(n) {
+	if (!Number.isFinite(n)) return "\\text{?}";
+	return Math.abs(n) >= 1e4 ? n.toLocaleString("en-US").replace(/,/g, "{,}") : String(n);
+}
+
+//#endregion
+export { Calc, calc, texNum };

package/dist/kit/carrier-engine.mjs

@@ -0,0 +1,147 @@
+'use client';
+
+import { useReducedMotion } from "./anim.mjs";
+import { useEffect, useRef, useState } from "react";
+import { useFrameLoop } from "@classytic/stage";
+
+//#region src/kit/carrier-engine.ts
+/**
+* Carrier engine, a small DETERMINISTIC charged-particle core shared by every
+* semiconductor / conduction lab. Carriers (electrons e⁻, holes h⁺) are real
+* entities with a position and a confinement box; each tick they drift under a
+* field (electrons and holes move opposite ways), jitter thermally, and reflect
+* off their region walls so nothing ever floats out of the device. Pairs that
+* meet recombine. Everything is seeded by an integer PRNG advanced by a global
+* step counter, so the simulation is bit-identical on the server and client
+* (no hydration drift) and fully replayable.
+*
+* The engine owns the PHYSICS OF MOTION. Each lab owns the SETUP, where the
+* regions are, which way the field points, how carriers are born and die.
+*/
+/** integer-only PRNG (no Math.sin/Math.random) → identical on server + client. */
+const rand = (a, b) => {
+	let x = (Math.imul(a + 1, 73856093) ^ Math.imul(b + 1, 19349663)) >>> 0;
+	x ^= x >>> 13;
+	x = Math.imul(x, 1274126177) >>> 0;
+	x ^= x >>> 16;
+	return x % 1e5 / 1e5;
+};
+/** A deterministic, EVENLY-spread point inside a box from a seed. Uses the R2 low-
+*  discrepancy sequence (plastic constant) so consecutive seeds (0,1,2,…) scatter across
+*  the whole box instead of clumping — a plain hash clusters consecutive seeds. */
+const inBox = (b, seed, pad = 8) => {
+	const fx = (.5 + .7548776662466927 * seed) % 1;
+	const fy = (.5 + .5698402909980532 * seed) % 1;
+	return {
+		x: b.x + pad + fx * Math.max(1, b.w - 2 * pad),
+		y: b.y + pad + fy * Math.max(1, b.h - 2 * pad)
+	};
+};
+/**
+* Advance carriers one tick with MOMENTUM: velocity persists and relaxes toward the drift
+* target while taking small random thermal kicks, then position integrates from velocity.
+* The persistent velocity is what makes carriers glide and wander smoothly instead of
+* vibrating in place. Walls bounce (velocity flips); everything stays inside its box. Pure.
+*/
+function stepCarriers(cs, step, bounds, f) {
+	const sp = f.speed ?? 1, jit = f.jitter ?? 0;
+	const dx = f.drift?.x ?? 0, dy = f.drift?.y ?? 0;
+	const signed = f.signed ?? true;
+	const damp = f.damp ?? .86;
+	const spring = f.spring ?? 0;
+	return cs.map((c) => {
+		if (c.fixed) return c;
+		const dir = !signed ? 1 : c.t === "e" ? 1 : -1;
+		let vx = (c.vx ?? 0) * damp + (1 - damp) * dx * dir + (rand(c.id, step) - .5) * jit;
+		let vy = (c.vy ?? 0) * damp + (1 - damp) * dy * dir + (rand(c.id, step * 2 + 7) - .5) * jit;
+		if (spring && c.hx !== void 0) vx += (c.hx - c.x) * spring;
+		if (spring && c.hy !== void 0) vy += (c.hy - c.y) * spring;
+		let x = c.x + vx * sp, y = c.y + vy * sp;
+		const b = c.box ?? bounds;
+		if (x < b.x) {
+			x = 2 * b.x - x;
+			vx = Math.abs(vx);
+		} else if (x > b.x + b.w) {
+			x = 2 * (b.x + b.w) - x;
+			vx = -Math.abs(vx);
+		}
+		if (y < b.y) {
+			y = 2 * b.y - y;
+			vy = Math.abs(vy);
+		} else if (y > b.y + b.h) {
+			y = 2 * (b.y + b.h) - y;
+			vy = -Math.abs(vy);
+		}
+		x = Math.max(b.x, Math.min(b.x + b.w, x));
+		y = Math.max(b.y, Math.min(b.y + b.h, y));
+		return {
+			...c,
+			x,
+			y,
+			vx,
+			vy
+		};
+	});
+}
+/** Tween every carrier's opacity toward active(1)/inactive(0) so the visible population
+*  changes by FADING, not by rebuilding the pool. A carrier is active when it has no slot
+*  or its slot < `target`. Call inside advance after stepCarriers. */
+function tweenOpacity(cs, target, rate = .1) {
+	return cs.map((c) => {
+		const want = c.slot === void 0 || c.slot < target ? 1 : 0;
+		return {
+			...c,
+			o: (c.o ?? want) + (want - (c.o ?? want)) * rate
+		};
+	});
+}
+/** Recombine free e⁻/h⁺ pairs within `r` px. With `respawn`, each partner is reborn at a
+*  fresh site (steady population, e.g. thermal generation⇄recombination); without it the
+*  pair is removed. */
+function recombine(cs, r, step, respawn) {
+	if (!r) return cs;
+	const r2 = r * r;
+	const hit = /* @__PURE__ */ new Set();
+	const es = cs.filter((c) => c.t === "e" && !c.fixed);
+	const hs = cs.filter((c) => c.t === "h" && !c.fixed);
+	for (const e of es) for (const h of hs) {
+		if (hit.has(e.id) || hit.has(h.id)) continue;
+		if ((e.x - h.x) ** 2 + (e.y - h.y) ** 2 < r2) {
+			hit.add(e.id);
+			hit.add(h.id);
+		}
+	}
+	if (!hit.size) return cs;
+	if (!respawn) return cs.filter((c) => !hit.has(c.id));
+	return cs.map((c) => hit.has(c.id) ? {
+		...c,
+		...respawn(c, step)
+	} : c);
+}
+/**
+* Drive a carrier simulation: holds the pool, advances it each frame via `advance`, and
+* RESETS to a fresh `init()` whenever `resetKey` changes (mode / dopant / topology). The
+* server and first client render both show step 0 of `init()` (deterministic) → no
+* hydration mismatch.
+*/
+function useCarrierSim(init, advance, running, resetKey) {
+	const reduce = useReducedMotion();
+	const [cs, setCs] = useState(init);
+	const stepRef = useRef(0);
+	const initRef = useRef(init);
+	const advanceRef = useRef(advance);
+	initRef.current = init;
+	advanceRef.current = advance;
+	useEffect(() => {
+		stepRef.current = 0;
+		setCs(initRef.current());
+	}, [resetKey]);
+	useFrameLoop(() => {
+		stepRef.current += 1;
+		setCs((prev) => advanceRef.current(prev, stepRef.current));
+	}, { running: running && !reduce });
+	return cs;
+}
+
+//#endregion
+export { inBox, rand, recombine, stepCarriers, tweenOpacity, useCarrierSim };

package/dist/kit/clue-scene.d.mts

@@ -0,0 +1,86 @@
+import { ReactNode } from "react";
+
+//#region src/kit/clue-scene.d.ts
+interface Unknown {
+  /** symbol shown on chips (an emoji like 🍍 or a letter like x). */
+  sym: string;
+  label?: string;
+  /** token colour for chips / buckets (default accent). */
+  color?: string;
+  /** the hidden value the learner solves for. */
+  answer: number;
+}
+interface Clue {
+  /** coefficient per unknown, aligned to the unknowns array (e.g. [2,1] → 2▲ + 1●). */
+  coeffs: number[];
+}
+type ClueSceneKind = 'tiles' | 'receipt' | 'balance';
+/** Total a clue evaluates to, given the unknowns' answers (kept consistent by construction). */
+declare function clueTotal(clue: Clue, unknowns: Unknown[]): number;
+/** A coloured token for an unknown (the reusable atom of every scene). */
+declare function UnknownChip({
+  u,
+  size,
+  withLabel
+}: {
+  u: Unknown;
+  size?: number;
+  withLabel?: boolean;
+}): ReactNode;
+interface SceneProps {
+  clue: Clue;
+  unknowns: Unknown[];
+  currency?: string;
+  unit?: string;
+  store?: string;
+}
+/** Tiles: "2▲ + 1● = 12". Universal, reads as the equation it is. */
+declare function ClueTiles({
+  clue,
+  unknowns,
+  currency,
+  unit
+}: SceneProps): ReactNode;
+/** Receipt: a shop bill listing quantities and the total (unit prices unknown). */
+declare function ClueReceipt({
+  clue,
+  unknowns,
+  currency,
+  store
+}: SceneProps): ReactNode;
+/** Balance: buckets (one per coeff, coloured by type) on the left pan vs a weight on the right. */
+declare function ClueBalance({
+  clue,
+  unknowns,
+  unit
+}: SceneProps): ReactNode;
+/** Bar model (tape diagram): each clue is one bar of unit cells grouped by unknown = total. */
+declare function ClueBar({
+  clue,
+  unknowns,
+  currency,
+  unit
+}: SceneProps): ReactNode;
+/** Coin piles: each unknown is a stack of coins (coloured by type) = a money total. */
+declare function ClueCoins({
+  clue,
+  unknowns,
+  currency
+}: SceneProps): ReactNode;
+interface ClueSceneMeta {
+  name: string;
+  label: string;
+  render: (q: SceneProps) => ReactNode;
+}
+declare function registerClueScene(meta: ClueSceneMeta): void;
+declare function getClueScene(name: string): ClueSceneMeta | undefined;
+declare function listClueScenes(): ClueSceneMeta[];
+/** Render one clue in the chosen scene (registry name). Creators extend via registerClueScene. */
+declare function ClueScene({
+  kind,
+  ...rest
+}: SceneProps & {
+  kind: string;
+}): ReactNode;
+//#endregion
+export { Clue, ClueBalance, ClueBar, ClueCoins, ClueReceipt, ClueScene, ClueSceneKind, ClueSceneMeta, ClueTiles, Unknown, UnknownChip, clueTotal, getClueScene, listClueScenes, registerClueScene };