@classytic/labs 0.2.0 → 0.3.0

package/dist/logic/TimingScene.mjs

@@ -0,0 +1,167 @@
+'use client';
+
+import { Figure, HUE, STROKE, alpha } from "../kit/figure/figure.mjs";
+import { FigText } from "../kit/figure/text.mjs";
+import { risingEdges } from "./timing.mjs";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+
+//#region src/logic/TimingScene.tsx
+const W = 680;
+const H = 336;
+const LABEL_X = 18;
+const WAVE_X = 172;
+const WAVE_RIGHT = 660;
+const AMP = 22;
+const ROWS = {
+	clock: 62,
+	d: 136,
+	latch: 222,
+	flipFlop: 302
+};
+const LIVE = "var(--stage-live)";
+/**
+* One colour, one meaning. D and the dots where the flip-flop reads it share a hue, because a dot
+* is "D, at this instant". Red is reserved for disagreement. Under the physics palette HUE[2] is red,
+* which made the D wave and the exam-answer shading the same colour, so this figure uses the math
+* palette's third hue instead.
+*/
+const D_INK = HUE[3];
+function TimingScene({ clock, d, latch, flipFlop, disagree, violations, revealed, onToggleD, label }) {
+	const slots = clock.length;
+	const slotW = (WAVE_RIGHT - WAVE_X) / slots;
+	const xAt = (t) => WAVE_X + t * slotW;
+	const edges = risingEdges(clock);
+	const path = (wave, base) => wave.map((level, t) => {
+		const y = level ? base - AMP : base;
+		return t === 0 ? `M${xAt(0)},${y} H${xAt(1)}` : `V${y} H${xAt(t + 1)}`;
+	}).join(" ");
+	const openWindows = [];
+	clock.forEach((level, t) => {
+		if (!level) return;
+		const last = openWindows[openWindows.length - 1];
+		if (last && last[1] === t - 1) last[1] = t;
+		else openWindows.push([t, t]);
+	});
+	const rowLabel = (y, title, rule) => /* @__PURE__ */ jsxs("g", { children: [/* @__PURE__ */ jsx(FigText, {
+		x: LABEL_X,
+		y: y - AMP / 2 + (rule ? -2 : 5),
+		size: "label",
+		tone: "ink",
+		children: title
+	}), rule && /* @__PURE__ */ jsx(FigText, {
+		x: LABEL_X,
+		y: y - AMP / 2 + 14,
+		size: "note",
+		tone: "soft",
+		children: rule
+	})] });
+	return /* @__PURE__ */ jsxs(Figure, {
+		viewBox: [W, H],
+		domain: "math",
+		label,
+		children: [
+			revealed && openWindows.map(([from, to]) => /* @__PURE__ */ jsx("rect", {
+				x: xAt(from),
+				y: ROWS.latch - AMP - 8,
+				width: (to - from + 1) * slotW,
+				height: 38,
+				fill: alpha(HUE[1], 10)
+			}, `open-${from}`)),
+			revealed && disagree.map((t) => /* @__PURE__ */ jsx("rect", {
+				x: xAt(t),
+				y: ROWS.latch - AMP - 8,
+				width: slotW,
+				height: ROWS.flipFlop - ROWS.latch + AMP + 16,
+				fill: alpha(HUE.hot, 18)
+			}, `diff-${t}`)),
+			edges.map((t) => /* @__PURE__ */ jsxs("g", { children: [/* @__PURE__ */ jsx("line", {
+				x1: xAt(t),
+				y1: ROWS.clock - AMP - 12,
+				x2: xAt(t),
+				y2: ROWS.flipFlop + 10,
+				stroke: alpha(D_INK, 55),
+				strokeWidth: STROKE.hair,
+				strokeDasharray: "4 3"
+			}), /* @__PURE__ */ jsx("circle", {
+				cx: xAt(t),
+				cy: d[t] ? ROWS.d - AMP : ROWS.d,
+				r: 4,
+				fill: D_INK
+			})] }, `edge-${t}`)),
+			violations.map((t) => /* @__PURE__ */ jsx(FigText, {
+				x: xAt(t) + 6,
+				y: ROWS.d - AMP - 8,
+				size: "note",
+				tone: "hot",
+				children: "D moved on the edge"
+			}, `viol-${t}`)),
+			rowLabel(ROWS.clock, "Clock"),
+			/* @__PURE__ */ jsx("path", {
+				d: path(clock, ROWS.clock),
+				fill: "none",
+				stroke: HUE.ink,
+				strokeWidth: STROKE.line
+			}),
+			rowLabel(ROWS.d, "D", "tap a slot to change it"),
+			onToggleD && d.map((_, t) => /* @__PURE__ */ jsx("rect", {
+				role: "switch",
+				"aria-checked": d[t],
+				"aria-label": `D at time ${t}`,
+				tabIndex: 0,
+				x: xAt(t),
+				y: ROWS.d - AMP - 6,
+				width: slotW,
+				height: 34,
+				fill: t % 2 === 0 ? alpha(HUE.soft, 4) : "transparent",
+				style: { cursor: "pointer" },
+				onClick: () => onToggleD(t),
+				onKeyDown: (event) => {
+					if (event.key === "Enter" || event.key === " ") {
+						event.preventDefault();
+						onToggleD(t);
+					}
+				}
+			}, `slot-${t}`)),
+			/* @__PURE__ */ jsx("path", {
+				d: path(d, ROWS.d),
+				fill: "none",
+				stroke: D_INK,
+				strokeWidth: STROKE.edge,
+				style: { pointerEvents: "none" }
+			}),
+			rowLabel(ROWS.latch, "Q, D latch", "open while clock is high"),
+			rowLabel(ROWS.flipFlop, "Q, flip-flop", "reads D at each rising edge"),
+			revealed ? /* @__PURE__ */ jsxs(Fragment, { children: [/* @__PURE__ */ jsx("path", {
+				d: path(latch, ROWS.latch),
+				fill: "none",
+				stroke: LIVE,
+				strokeWidth: STROKE.edge
+			}), /* @__PURE__ */ jsx("path", {
+				d: path(flipFlop, ROWS.flipFlop),
+				fill: "none",
+				stroke: LIVE,
+				strokeWidth: STROKE.edge
+			})] }) : /* @__PURE__ */ jsx(Fragment, { children: [ROWS.latch, ROWS.flipFlop].map((y) => /* @__PURE__ */ jsxs("g", { children: [/* @__PURE__ */ jsx("rect", {
+				x: WAVE_X,
+				y: y - AMP - 6,
+				width: WAVE_RIGHT - WAVE_X,
+				height: 34,
+				rx: 4,
+				fill: alpha(HUE.soft, 8),
+				stroke: alpha(HUE.soft, 30),
+				strokeWidth: STROKE.hair,
+				strokeDasharray: "4 3"
+			}), /* @__PURE__ */ jsx(FigText, {
+				x: xAt(edges.length > 1 ? (edges[0] + edges[1]) / 2 : slots / 2),
+				y: y - AMP / 2 + 4,
+				size: "note",
+				anchor: "middle",
+				tone: "soft",
+				children: "predict first"
+			})] }, `hidden-${y}`)) })
+		]
+	});
+}
+
+//#endregion
+export { TimingScene };

package/dist/logic/TwosScene.d.mts

@@ -0,0 +1,33 @@
+import { Pattern } from "./twos.mjs";
+import { ReactNode } from "react";
+
+//#region src/logic/TwosScene.d.ts
+type TwosOperation = 'add' | 'subtract' | 'negate';
+interface TwosSceneProps {
+  operation: TwosOperation;
+  a: Pattern;
+  /** The addend actually fed to the adder (b, or the negation of b when subtracting). */
+  addend: Pattern;
+  b: Pattern;
+  result: Pattern;
+  overflow: boolean;
+  carryOut: boolean;
+  inverted?: Pattern;
+  /** Hidden until the learner has predicted. */
+  revealed: boolean;
+  label: string;
+}
+declare function TwosScene({
+  operation,
+  a,
+  addend,
+  b,
+  result,
+  overflow,
+  carryOut,
+  inverted,
+  revealed,
+  label
+}: TwosSceneProps): ReactNode;
+//#endregion
+export { TwosOperation, TwosScene, TwosSceneProps };

package/dist/logic/TwosScene.mjs

@@ -0,0 +1,269 @@
+'use client';
+
+import { Figure, HUE, STROKE, alpha, tint } from "../kit/figure/figure.mjs";
+import { FigText } from "../kit/figure/text.mjs";
+import { bitsOf, toSigned } from "./twos.mjs";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+
+//#region src/logic/TwosScene.tsx
+const W = 680;
+const H = 360;
+const CX = 188;
+const CY = 180;
+const R_NODE = 132;
+const R_ARC = 92;
+const POS = HUE[1];
+const NEG = HUE[2];
+const LIVE = "var(--stage-live)";
+const angle = (pattern) => -Math.PI / 2 + pattern * Math.PI * 2 / 16;
+const at = (pattern, r) => [CX + r * Math.cos(angle(pattern)), CY + r * Math.sin(angle(pattern))];
+/** A real minus sign: a hyphen reads as a dash, and this is a number. */
+const fmt = (value) => value < 0 ? `−${-value}` : `${value}`;
+/** A radial line BETWEEN two neighbouring patterns, half a step round from each. */
+const boundary = (after, r1, r2) => {
+	const t = -Math.PI / 2 + (after + .5) * Math.PI * 2 / 16;
+	return {
+		x1: CX + r1 * Math.cos(t),
+		y1: CY + r1 * Math.sin(t),
+		x2: CX + r2 * Math.cos(t),
+		y2: CY + r2 * Math.sin(t)
+	};
+};
+function TwosScene({ operation, a, addend, b, result, overflow, carryOut, inverted, revealed, label }) {
+	/**
+	* The walk goes the way the SIGNED addend says: forward for a positive number, backward for a
+	* negative one. The adder cannot tell 11 steps forward from 5 back (same landing place), but only
+	* the signed walk makes the rule on the wheel true: it crosses the red line exactly when the
+	* answer overflows. Walking 11 forward for 2 − 5 crossed the line on a sum that fits.
+	*/
+	const signed = operation === "negate" ? 0 : toSigned(addend);
+	const steps = Math.abs(signed);
+	const direction = signed < 0 ? -1 : 1;
+	const walk = [];
+	for (let s = 0; s <= steps * 4; s++) {
+		const turn = angle(a) + direction * (s / 4) * (Math.PI / 8);
+		const [x, y] = [CX + R_ARC * Math.cos(turn), CY + R_ARC * Math.sin(turn)];
+		walk.push(`${s === 0 ? "M" : "L"}${x.toFixed(1)},${y.toFixed(1)}`);
+	}
+	const arcInk = overflow ? HUE.hot : LIVE;
+	const lift = operation === "subtract" ? 0 : 32;
+	const COL = 26;
+	const WX = 470;
+	const bitRow = (pattern, y, key, tone = "ink") => bitsOf(pattern).split("").map((bit, i) => /* @__PURE__ */ jsx(FigText, {
+		x: WX + i * COL,
+		y,
+		size: "label",
+		anchor: "middle",
+		tone,
+		children: bit
+	}, `${key}-${i}`));
+	const note = (text, y, key, tone = "soft") => /* @__PURE__ */ jsx(FigText, {
+		x: 582,
+		y,
+		size: "note",
+		tone,
+		children: text
+	}, key);
+	return /* @__PURE__ */ jsxs(Figure, {
+		viewBox: [W, H],
+		domain: "math",
+		label,
+		children: [
+			/* @__PURE__ */ jsx("line", {
+				...boundary(15, R_ARC - 14, 158),
+				stroke: alpha(HUE.soft, 60),
+				strokeWidth: STROKE.hair,
+				strokeDasharray: "3 3"
+			}),
+			/* @__PURE__ */ jsx(FigText, {
+				x: boundary(15, 0, 162).x2 - 6,
+				y: CY - R_NODE - 24,
+				size: "note",
+				anchor: "end",
+				tone: "soft",
+				children: "wraps here"
+			}),
+			/* @__PURE__ */ jsx("line", {
+				...boundary(7, R_ARC - 14, 158),
+				stroke: HUE.hot,
+				strokeWidth: STROKE.line
+			}),
+			/* @__PURE__ */ jsx(FigText, {
+				x: boundary(7, 0, 162).x2 + 6,
+				y: 346,
+				size: "note",
+				tone: "hot",
+				children: "overflow line"
+			}),
+			operation === "negate" && /* @__PURE__ */ jsx("line", {
+				x1: CX,
+				y1: CY - R_NODE,
+				x2: CX,
+				y2: 312,
+				stroke: alpha(HUE.ink, 45),
+				strokeWidth: STROKE.line,
+				strokeDasharray: "6 4"
+			}),
+			revealed && operation !== "negate" && steps > 0 && /* @__PURE__ */ jsxs("g", { children: [
+				/* @__PURE__ */ jsx("path", {
+					d: walk.join(" "),
+					fill: "none",
+					stroke: arcInk,
+					strokeWidth: STROKE.bold,
+					strokeLinecap: "round"
+				}),
+				(() => {
+					const end = angle(a) + direction * steps * (Math.PI / 8);
+					const [ex, ey] = [CX + R_ARC * Math.cos(end), CY + R_ARC * Math.sin(end)];
+					const [tx, ty] = [-Math.sin(end) * direction, Math.cos(end) * direction];
+					const [nx, ny] = [-ty, tx];
+					return /* @__PURE__ */ jsx("path", {
+						d: `M${ex + tx * 9},${ey + ty * 9} L${ex + nx * 6},${ey + ny * 6} L${ex - nx * 6},${ey - ny * 6} Z`,
+						fill: arcInk
+					});
+				})(),
+				/* @__PURE__ */ jsxs(FigText, {
+					x: CX,
+					y: 185,
+					size: "label",
+					anchor: "middle",
+					tone: "ink",
+					children: [
+						steps,
+						" step",
+						steps === 1 ? "" : "s",
+						" ",
+						direction > 0 ? "clockwise" : "anticlockwise"
+					]
+				})
+			] }),
+			revealed && operation === "negate" && /* @__PURE__ */ jsx("line", {
+				x1: at(a, R_NODE - 18)[0],
+				y1: at(a, R_NODE - 18)[1],
+				x2: at(result, R_NODE - 18)[0],
+				y2: at(result, R_NODE - 18)[1],
+				stroke: overflow ? HUE.hot : LIVE,
+				strokeWidth: STROKE.edge
+			}),
+			Array.from({ length: 16 }, (_, p) => {
+				const [x, y] = at(p, R_NODE);
+				const ink = p >= 8 ? NEG : POS;
+				const isA = p === a;
+				const isResult = revealed && p === result;
+				return /* @__PURE__ */ jsxs("g", { children: [
+					/* @__PURE__ */ jsx("circle", {
+						cx: x,
+						cy: y,
+						r: 19,
+						fill: isResult ? tint(overflow ? HUE.hot : LIVE, 45) : tint(ink, isA ? 45 : 18),
+						stroke: isResult ? overflow ? HUE.hot : LIVE : isA ? ink : alpha(ink, 45),
+						strokeWidth: isA || isResult ? STROKE.edge : STROKE.hair
+					}),
+					/* @__PURE__ */ jsx(FigText, {
+						x,
+						y: y + 1,
+						size: "label",
+						anchor: "middle",
+						tone: "ink",
+						halo: false,
+						children: fmt(toSigned(p))
+					}),
+					/* @__PURE__ */ jsx(FigText, {
+						x,
+						y: y + 13,
+						size: "note",
+						anchor: "middle",
+						tone: "soft",
+						halo: false,
+						children: bitsOf(p)
+					})
+				] }, p);
+			}),
+			/* @__PURE__ */ jsx(FigText, {
+				x: WX - 34,
+				y: 64,
+				size: "note",
+				tone: "soft",
+				children: operation === "negate" ? "negate a" : operation === "subtract" ? "a − b on the adder" : "a + b on the adder"
+			}),
+			/* @__PURE__ */ jsx(FigText, {
+				x: WX - 34,
+				y: 98,
+				size: "label",
+				tone: "ink",
+				children: "a"
+			}),
+			bitRow(a, 98, "a"),
+			note(fmt(toSigned(a)), 98, "na", "ink"),
+			operation === "subtract" && /* @__PURE__ */ jsxs(Fragment, { children: [
+				/* @__PURE__ */ jsx(FigText, {
+					x: WX - 34,
+					y: 130,
+					size: "note",
+					tone: "soft",
+					children: "b"
+				}),
+				bitRow(b, 130, "b", "soft"),
+				note(`invert, add 1`, 130, "nb")
+			] }),
+			operation === "negate" && inverted !== void 0 && /* @__PURE__ */ jsxs(Fragment, { children: [
+				/* @__PURE__ */ jsx(FigText, {
+					x: WX - 34,
+					y: 130,
+					size: "note",
+					tone: "soft",
+					children: "invert"
+				}),
+				bitRow(inverted, 130, "inv", "soft"),
+				note("then add 1", 130, "ninv")
+			] }),
+			operation !== "negate" && /* @__PURE__ */ jsxs(Fragment, { children: [
+				/* @__PURE__ */ jsx(FigText, {
+					x: WX - 34,
+					y: 162 - lift,
+					size: "label",
+					tone: "ink",
+					children: "+"
+				}),
+				bitRow(addend, 162 - lift, "add"),
+				note(fmt(toSigned(addend)), 162 - lift, "nadd", "ink")
+			] }),
+			/* @__PURE__ */ jsx("line", {
+				x1: WX - 34,
+				y1: 178 - lift,
+				x2: 614,
+				y2: 178 - lift,
+				stroke: HUE.ink,
+				strokeWidth: STROKE.line
+			}),
+			revealed ? /* @__PURE__ */ jsxs(Fragment, { children: [
+				bitRow(result, 204 - lift, "res", overflow ? "hot" : "ink"),
+				note(fmt(toSigned(result)), 204 - lift, "nres", overflow ? "hot" : "ink"),
+				operation !== "negate" && /* @__PURE__ */ jsxs(FigText, {
+					x: WX - 34,
+					y: 240 - lift,
+					size: "note",
+					tone: carryOut ? "ink" : "soft",
+					children: ["carry out ", carryOut ? "1, dropped" : "0"]
+				}),
+				/* @__PURE__ */ jsx(FigText, {
+					x: WX - 34,
+					y: 266 - lift,
+					size: "note",
+					tone: overflow ? "hot" : "soft",
+					children: overflow ? "overflow: the true answer does not fit in 4 bits" : "fits in 4 bits"
+				})
+			] }) : /* @__PURE__ */ jsx(FigText, {
+				x: 509,
+				y: 204 - lift,
+				size: "label",
+				anchor: "middle",
+				tone: "soft",
+				children: "predict first"
+			})
+		]
+	});
+}
+
+//#endregion
+export { TwosScene };

package/dist/logic/WaveScene.d.mts

@@ -0,0 +1,43 @@
+import { Wave } from "./timing.mjs";
+import { ReactNode } from "react";
+
+//#region src/logic/WaveScene.d.ts
+interface WaveRow {
+  key: string;
+  label: string;
+  /** The row's rule, said once and where it applies. */
+  rule?: string;
+  wave: Wave;
+  /** 'clock' draws in ink, 'input' in the input hue, 'output' in the live colour. */
+  role: 'clock' | 'input' | 'output';
+  editable?: boolean;
+  hidden?: boolean;
+}
+interface WaveMark {
+  t: number;
+  text: string;
+  tone?: 'ink' | 'soft' | 'hot';
+}
+interface WaveSceneProps {
+  rows: WaveRow[];
+  edges: number[];
+  /** Rows the edges read from: a dot is drawn on each of them at every edge. */
+  sampled?: string[];
+  /** Words written under the diagram at an edge, such as what a flip-flop did there. */
+  marks?: WaveMark[];
+  /** Edges to draw heavier, such as the ones where something changed. */
+  emphasis?: number[];
+  onToggle?: (row: string, slot: number) => void;
+  label: string;
+}
+declare function WaveScene({
+  rows,
+  edges,
+  sampled,
+  marks,
+  emphasis,
+  onToggle,
+  label
+}: WaveSceneProps): ReactNode;
+//#endregion
+export { WaveMark, WaveRow, WaveScene, WaveSceneProps };

package/dist/logic/WaveScene.mjs

@@ -0,0 +1,124 @@
+'use client';
+
+import { Figure, HUE, STROKE, alpha } from "../kit/figure/figure.mjs";
+import { FigText } from "../kit/figure/text.mjs";
+import { jsx, jsxs } from "react/jsx-runtime";
+
+//#region src/logic/WaveScene.tsx
+const W = 680;
+const LABEL_X = 18;
+const WAVE_X = 172;
+const WAVE_RIGHT = 660;
+const AMP = 22;
+const TOP = 58;
+const PITCH = 78;
+const INPUT_INK = HUE[3];
+const LIVE = "var(--stage-live)";
+function WaveScene({ rows, edges, sampled = [], marks = [], emphasis = [], onToggle, label }) {
+	const slots = rows[0]?.wave.length ?? 1;
+	const slotW = (WAVE_RIGHT - WAVE_X) / slots;
+	const xAt = (t) => WAVE_X + t * slotW;
+	const rowY = (index) => TOP + index * PITCH;
+	const lastY = rowY(rows.length - 1);
+	const H = lastY + (marks.length ? 52 : 24);
+	const path = (wave, base) => wave.map((level, t) => {
+		const y = level ? base - AMP : base;
+		return t === 0 ? `M${xAt(0)},${y} H${xAt(1)}` : `V${y} H${xAt(t + 1)}`;
+	}).join(" ");
+	return /* @__PURE__ */ jsxs(Figure, {
+		viewBox: [W, H],
+		domain: "math",
+		label,
+		children: [
+			edges.map((t) => /* @__PURE__ */ jsx("line", {
+				x1: xAt(t),
+				y1: TOP - AMP - 12,
+				x2: xAt(t),
+				y2: lastY + 10,
+				stroke: alpha(INPUT_INK, emphasis.includes(t) ? 90 : 50),
+				strokeWidth: emphasis.includes(t) ? STROKE.line : STROKE.hair,
+				strokeDasharray: emphasis.includes(t) ? void 0 : "4 3"
+			}, `edge-${t}`)),
+			rows.map((row, index) => {
+				const y = rowY(index);
+				const ink = row.role === "clock" ? HUE.ink : row.role === "input" ? INPUT_INK : LIVE;
+				return /* @__PURE__ */ jsxs("g", { children: [
+					/* @__PURE__ */ jsx(FigText, {
+						x: LABEL_X,
+						y: y - AMP / 2 + (row.rule ? -2 : 5),
+						size: "label",
+						tone: "ink",
+						children: row.label
+					}),
+					row.rule && /* @__PURE__ */ jsx(FigText, {
+						x: LABEL_X,
+						y: y - AMP / 2 + 14,
+						size: "note",
+						tone: "soft",
+						children: row.rule
+					}),
+					row.editable && onToggle && row.wave.map((level, t) => /* @__PURE__ */ jsx("rect", {
+						role: "switch",
+						"aria-checked": level,
+						"aria-label": `${row.label} at time ${t}`,
+						tabIndex: 0,
+						x: xAt(t),
+						y: y - AMP - 6,
+						width: slotW,
+						height: 34,
+						fill: t % 2 === 0 ? alpha(HUE.soft, 4) : "transparent",
+						style: { cursor: "pointer" },
+						onClick: () => onToggle(row.key, t),
+						onKeyDown: (event) => {
+							if (event.key === "Enter" || event.key === " ") {
+								event.preventDefault();
+								onToggle(row.key, t);
+							}
+						}
+					}, `${row.key}-${t}`)),
+					row.hidden ? /* @__PURE__ */ jsxs("g", { children: [/* @__PURE__ */ jsx("rect", {
+						x: WAVE_X,
+						y: y - AMP - 6,
+						width: WAVE_RIGHT - WAVE_X,
+						height: 34,
+						rx: 4,
+						fill: alpha(HUE.soft, 8),
+						stroke: alpha(HUE.soft, 30),
+						strokeWidth: STROKE.hair,
+						strokeDasharray: "4 3"
+					}), /* @__PURE__ */ jsx(FigText, {
+						x: xAt(edges.length > 1 ? (edges[0] + edges[1]) / 2 : slots / 2),
+						y: y - AMP / 2 + 4,
+						size: "note",
+						anchor: "middle",
+						tone: "soft",
+						children: "predict first"
+					})] }) : /* @__PURE__ */ jsx("path", {
+						d: path(row.wave, y),
+						fill: "none",
+						stroke: ink,
+						strokeWidth: row.role === "clock" ? STROKE.line : STROKE.edge,
+						style: { pointerEvents: "none" }
+					}),
+					sampled.includes(row.key) && !row.hidden && edges.map((t) => /* @__PURE__ */ jsx("circle", {
+						cx: xAt(t),
+						cy: row.wave[t] ? y - AMP : y,
+						r: 4,
+						fill: ink
+					}, `dot-${row.key}-${t}`))
+				] }, row.key);
+			}),
+			marks.map((mark) => /* @__PURE__ */ jsx(FigText, {
+				x: xAt(mark.t),
+				y: lastY + 30,
+				size: "note",
+				anchor: "middle",
+				tone: mark.tone ?? "ink",
+				children: mark.text
+			}, `mark-${mark.t}`))
+		]
+	});
+}
+
+//#endregion
+export { WaveScene };

package/dist/logic/contract.d.mts

@@ -1,4 +1,4 @@
-import { GateType } from "../kit/logic-gates.mjs";
+import { GateType } from "../kit/logic-gates/gate.mjs";
 
 //#region src/logic/contract.d.ts
 /** A primary input (a switch the learner can toggle). */
@@ -67,6 +67,26 @@ interface LogicSolution {
   outputs: Record<string, boolean>;
   /** every output matches its `goal` (a solved challenge). */
   allGoalsMet: boolean;
+  /** Structural problems found while evaluating. Dangling references, unknown gates and
+   * feedback that never settles are reported explicitly, never silently treated as logic. */
+  diagnostics: LogicDiagnostic[];
+  /** True when nothing was reported: the network is well formed and reached a stable state. */
+  valid: boolean;
+  /** Every gate's settled value. Feed this back as `evaluate`'s `seed` on the next
+   *  evaluation and a feedback circuit REMEMBERS: this is what turns two cross-coupled
+   *  NAND gates into a latch rather than a fresh guess each render. */
+  settled: Record<string, boolean>;
+  /** Did the network reach a stable state? False means it oscillates. */
+  stable: boolean;
+  /** Passes taken to settle. 1 means purely combinational with no propagation delay to show. */
+  settledIn: number;
+}
+interface LogicDiagnostic {
+  code: 'combinational-cycle' | 'unknown-node' | 'unknown-gate' | 'invalid-sr-input';
+  nodeId: string;
+  message: string;
+  /** For a cycle, the closed path that produced it. */
+  path?: string[];
 }
 //#endregion
-export { GateDef, LogicDoc, LogicGate, LogicInput, LogicOutput, LogicSolution };
+export { GateDef, LogicDiagnostic, LogicDoc, LogicGate, LogicInput, LogicOutput, LogicSolution };

package/dist/logic/counter.d.mts

@@ -0,0 +1,27 @@
+import { SequentialLogicDoc } from "./sequential.mjs";
+
+//#region src/logic/counter.d.ts
+declare const MAX_WIDTH = 4;
+/** Bit positions that are 1 in `modulus - 1`: the only inputs the terminal-count gate needs. */
+declare function detectBits(modulus: number): number[];
+/** A width-bit up counter that wraps after `modulus - 1`. Full-length counters need no gate. */
+declare function modCounterDoc(modulus: number, width?: number): SequentialLogicDoc;
+interface CounterRun {
+  /** Slot-level clock: low then high for every clock period. */
+  clock: boolean[];
+  /** `bits[b][t]` is Qb at slot t. */
+  bits: boolean[][];
+  /** The count held during each clock period, before that period's rising edge is applied. */
+  counts: number[];
+}
+/** Run `periods` clock periods through the engine, two slots per period (low, then high). */
+declare function runCounter(modulus: number, periods: number, width?: number): CounterRun;
+/** How many times a wave changes level. Each stage should change half as often as the one before. */
+declare const transitions: (wave: boolean[]) => number;
+/** Divide-by-two stages needed to bring `ratio` down to one, when `ratio` is a power of two. */
+declare function stagesFor(ratio: number): number | undefined;
+/** A readable name for the terminal-count condition, e.g. "Q3 and Q0". */
+declare const detectLabel: (modulus: number) => string;
+declare const toBinary: (value: number, width?: number) => string;
+//#endregion
+export { CounterRun, MAX_WIDTH, detectBits, detectLabel, modCounterDoc, runCounter, stagesFor, toBinary, transitions };