@classytic/labs 0.1.0 → 0.3.0

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

@@ -0,0 +1,92 @@
+import { GateType } from "../kit/logic-gates/gate.mjs";
+
+//#region src/logic/contract.d.ts
+/** A primary input (a switch the learner can toggle). */
+interface LogicInput {
+  id: string;
+  label?: string;
+  /** starting level (default low). */
+  value?: boolean;
+  /** free-placement position (builder canvas); omitted = auto-layout by LogicScene. */
+  x?: number;
+  y?: number;
+}
+/** A gate node: `kind` selects the GateDef, `in` lists the node ids feeding its inputs. */
+interface LogicGate {
+  id: string;
+  kind: string;
+  in: string[];
+  label?: string;
+  x?: number;
+  y?: number;
+}
+/** A circuit output (an LED). `in` is the node id driving it. `goal` is the expected value. */
+interface LogicOutput {
+  id: string;
+  in: string;
+  label?: string;
+  goal?: boolean;
+  /** LED colour token (default the live colour). */
+  color?: string;
+  x?: number;
+  y?: number;
+}
+/** The serializable logic circuit. */
+interface LogicDoc {
+  inputs: LogicInput[];
+  gates: LogicGate[];
+  outputs: LogicOutput[];
+  /** builder canvas size (free-placement editor). */
+  size?: {
+    w: number;
+    h: number;
+  };
+}
+/** The one extension point: register a gate kind once to make it evaluable + drawable. */
+interface GateDef {
+  kind: string;
+  label: string;
+  /** glyph shape drawn by GateGlyph. */
+  glyph: GateType;
+  /** number of inputs (1 for NOT/buffer, 2 default; n-input gates evaluate variadically). */
+  arity: number;
+  /** pure boolean function of the resolved input values. */
+  eval: (inputs: boolean[]) => boolean;
+}
+interface LogicSolution {
+  /** value at any node id (input or gate); false for unknown / cycles. */
+  value: (nodeId: string) => boolean;
+  /** propagation order: levels[0] = inputs, levels[k] = gates resolved at depth k. Drives
+   *  step-by-step "the signal flows through" reveals. */
+  levels: string[][];
+  /** the depth (level index) a node settles at. */
+  depthOf: (nodeId: string) => number;
+  /** is the wire leaving `nodeId` carrying a HIGH (for the propagation glow). */
+  high: (nodeId: string) => boolean;
+  /** resolved output values by output id. */
+  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, 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 };

package/dist/logic/counter.mjs

@@ -0,0 +1,90 @@
+import { sequenceTable } from "./sequential.mjs";
+
+//#region src/logic/counter.ts
+/**
+* A binary counter, and the one AND gate that turns it into a counter of any length.
+*
+* Two ideas carry a counter lesson, and both are pictures rather than definitions.
+*
+* The first is that counting in binary and dividing a frequency are the same circuit. Drawn as
+* waveforms, the ones bit flips on every clock edge, the twos bit on every second edge, the fours
+* bit on every fourth. With the ones bit drawn nearest the clock, read any column from the bottom
+* up and it is the count in binary; read any row left to right and it is the clock divided by a
+* power of two. That is how a quartz watch gets one tick a
+* second out of a crystal vibrating 32,768 times a second: 32,768 is 2 to the 15, so fifteen
+* stages divide it down.
+*
+* The second is how to stop at a number that is not a power of two. A decade counter is an
+* ordinary 4-bit counter plus a gate that notices the last count and resets it on the next edge.
+* That gate only needs to read the bits that are 1 in the last count, because no smaller number
+* can have all of those bits set. That is the moment students realise the design is small.
+*
+* Everything runs through the sequential engine as a real `counter` cell with a real AND gate on
+* its synchronous reset, so the reset timing here is the engine's, not a second opinion.
+*/
+const MAX_WIDTH = 4;
+/** Bit positions that are 1 in `modulus - 1`: the only inputs the terminal-count gate needs. */
+function detectBits(modulus) {
+	const last = modulus - 1;
+	const bits = [];
+	for (let bit = 0; 2 ** bit <= last; bit++) if (Math.floor(last / 2 ** bit) % 2 === 1) bits.push(bit);
+	return bits;
+}
+/** A width-bit up counter that wraps after `modulus - 1`. Full-length counters need no gate. */
+function modCounterDoc(modulus, width = 4) {
+	const full = modulus >= 2 ** width;
+	const bits = detectBits(modulus);
+	return {
+		inputs: [{
+			id: "clock",
+			label: "Clock",
+			value: false
+		}],
+		gates: full ? [] : [{
+			id: "tc",
+			kind: bits.length > 1 ? "AND" : "buffer",
+			in: bits.map((bit) => `count[${bit}]`),
+			label: "last count"
+		}],
+		cells: [{
+			id: "count",
+			kind: "counter",
+			width,
+			clock: "clock",
+			...full ? {} : {
+				reset: "tc",
+				resetMode: "synchronous"
+			}
+		}],
+		outputs: Array.from({ length: width }, (_, bit) => ({
+			id: `q${bit}`,
+			in: `count[${bit}]`,
+			label: `Q${bit}`
+		}))
+	};
+}
+/** Run `periods` clock periods through the engine, two slots per period (low, then high). */
+function runCounter(modulus, periods, width = 4) {
+	const doc = modCounterDoc(modulus, width);
+	const clock = Array.from({ length: periods * 2 }, (_, t) => t % 2 === 1);
+	const trace = sequenceTable(doc, clock.map((level) => ({ clock: level })));
+	const bits = Array.from({ length: width }, (_, bit) => trace.map((entry) => entry.state.bits.count?.[bit] ?? false));
+	return {
+		clock,
+		bits,
+		counts: Array.from({ length: periods }, (_, period) => bits.reduce((sum, wave, bit) => sum + (wave[period * 2] ? 2 ** bit : 0), 0))
+	};
+}
+/** How many times a wave changes level. Each stage should change half as often as the one before. */
+const transitions = (wave) => wave.filter((level, t) => t > 0 && level !== wave[t - 1]).length;
+/** Divide-by-two stages needed to bring `ratio` down to one, when `ratio` is a power of two. */
+function stagesFor(ratio) {
+	const stages = Math.log2(ratio);
+	return Number.isInteger(stages) ? stages : void 0;
+}
+/** A readable name for the terminal-count condition, e.g. "Q3 and Q0". */
+const detectLabel = (modulus) => detectBits(modulus).slice().reverse().map((bit) => `Q${bit}`).join(" and ");
+const toBinary = (value, width = 4) => value.toString(2).padStart(width, "0");
+
+//#endregion
+export { MAX_WIDTH, detectBits, detectLabel, modCounterDoc, runCounter, stagesFor, toBinary, transitions };

package/dist/logic/detector.d.mts

@@ -0,0 +1,72 @@
+//#region src/logic/detector.d.ts
+/**
+ * A sequence detector, generated from the pattern it detects.
+ *
+ * "Design a Moore machine that outputs 1 whenever the input has just ended in 101" is the state
+ * machine question of a first digital logic course. Students are taught to draw it by hand and
+ * usually get the states right and the backward arrows wrong: after a wrong bit they send the
+ * machine all the way back to the start, when some of what it has already seen may still be the
+ * beginning of the next match.
+ *
+ * So the machine here is BUILT from the pattern, by the rule the hand design is meant to follow:
+ * state k means "the last k bits are the first k bits of the pattern". Every transition goes to the
+ * longest part of the pattern that the bits seen so far could still be the start of. That is the
+ * same rule as the failure function in KMP string matching, which is worth knowing is the same idea
+ * when a student meets it again in an algorithms course.
+ *
+ * Overlapping and non-overlapping detection differ only in what happens after a match. Overlapping
+ * keeps the tail of the match as a possible head of the next one; non-overlapping throws it away.
+ */
+interface DetectorState {
+  id: number;
+  /** The part of the pattern matched so far. "" is the start state. */
+  matched: string;
+  /** Moore output: 1 only in the final state. */
+  output: boolean;
+}
+/**
+ * Moore puts the output in a STATE, so it needs a state that means "just found it". Mealy puts the
+ * output on the ARROW that completes the pattern, so it needs one fewer state and answers on the
+ * same clock as the last bit. Same input, same detections, different shape: which is exactly the
+ * comparison a first course asks for.
+ */
+type MachineKind = 'moore' | 'mealy';
+interface Detector {
+  kind: MachineKind;
+  pattern: string;
+  overlap: boolean;
+  states: DetectorState[];
+  /** `next[state][bit]`, bit being 0 or 1. */
+  next: [number, number][];
+  /** Mealy only: `outputs[state][bit]` is the output on that arrow. All false for Moore. */
+  outputs: [boolean, boolean][];
+}
+declare function buildDetector(pattern: string, overlap?: boolean, kind?: MachineKind): Detector;
+interface DetectorRun {
+  /** State before any input, then after each bit. */
+  path: number[];
+  /** Positions (0-based, into the input) at which the machine output a 1. */
+  detections: number[];
+}
+declare function runDetector(machine: Detector, bits: string): DetectorRun;
+/** Transitions that go backwards, excluding self-loops. These are the ones students get wrong. */
+declare const backEdges: (machine: Detector) => {
+  from: number;
+  bit: number;
+  to: number;
+}[];
+/**
+ * The longest proper prefix of the pattern that is also a suffix of it: the part of the end of a
+ * match that can start the next one. "1" for 101, "10" for 1010, "" for 110.
+ */
+declare function borderOf(pattern: string): string;
+/** Fewest further bits before the detector can output 1 again, straight after a match. */
+declare const bitsToFireAgain: (pattern: string, overlap: boolean) => number;
+/** Back edges that do NOT return to the start: the ones a naive design misses. */
+declare const partialFallbacks: (machine: Detector) => {
+  from: number;
+  bit: number;
+  to: number;
+}[];
+//#endregion
+export { Detector, DetectorRun, DetectorState, MachineKind, backEdges, bitsToFireAgain, borderOf, buildDetector, partialFallbacks, runDetector };

package/dist/logic/detector.mjs

@@ -0,0 +1,93 @@
+//#region src/logic/detector.ts
+/** Longest prefix of `pattern` that is also a suffix of `seen`, as a length. */
+function longestPrefixSuffix(pattern, seen) {
+	for (let length = Math.min(pattern.length, seen.length); length > 0; length--) if (seen.endsWith(pattern.slice(0, length))) return length;
+	return 0;
+}
+function buildDetector(pattern, overlap = true, kind = "moore") {
+	if (!/^[01]+$/.test(pattern)) throw new Error(`A pattern is a string of 0s and 1s, got "${pattern}".`);
+	const n = pattern.length;
+	if (kind === "mealy") {
+		const states = Array.from({ length: n }, (_, k) => ({
+			id: k,
+			matched: pattern.slice(0, k),
+			output: false
+		}));
+		const landing = overlap ? borderOf(pattern).length : 0;
+		const move = (k, bit) => {
+			const reached = longestPrefixSuffix(pattern, pattern.slice(0, k) + bit);
+			return reached === n ? {
+				to: landing,
+				out: true
+			} : {
+				to: reached,
+				out: false
+			};
+		};
+		const moves = states.map((state) => [move(state.id, "0"), move(state.id, "1")]);
+		return {
+			kind,
+			pattern,
+			overlap,
+			states,
+			next: moves.map(([zero, one]) => [zero.to, one.to]),
+			outputs: moves.map(([zero, one]) => [zero.out, one.out])
+		};
+	}
+	const states = Array.from({ length: n + 1 }, (_, k) => ({
+		id: k,
+		matched: pattern.slice(0, k),
+		output: k === n
+	}));
+	const step = (k, bit) => {
+		return longestPrefixSuffix(pattern, (k === n && !overlap ? "" : pattern.slice(0, k)) + bit);
+	};
+	return {
+		kind,
+		pattern,
+		overlap,
+		states,
+		next: states.map((state) => [step(state.id, "0"), step(state.id, "1")]),
+		outputs: states.map(() => [false, false])
+	};
+}
+function runDetector(machine, bits) {
+	const path = [0];
+	const detections = [];
+	for (let index = 0; index < bits.length; index++) {
+		const bit = bits[index] === "1" ? 1 : 0;
+		const from = path[path.length - 1];
+		const state = machine.next[from][bit];
+		path.push(state);
+		if (machine.kind === "mealy" ? machine.outputs[from][bit] : machine.states[state].output) detections.push(index);
+	}
+	return {
+		path,
+		detections
+	};
+}
+/** Transitions that go backwards, excluding self-loops. These are the ones students get wrong. */
+const backEdges = (machine) => machine.next.flatMap(([zero, one], from) => [{
+	from,
+	bit: 0,
+	to: zero
+}, {
+	from,
+	bit: 1,
+	to: one
+}].filter((edge) => edge.to < from));
+/**
+* The longest proper prefix of the pattern that is also a suffix of it: the part of the end of a
+* match that can start the next one. "1" for 101, "10" for 1010, "" for 110.
+*/
+function borderOf(pattern) {
+	for (let length = pattern.length - 1; length > 0; length--) if (pattern.endsWith(pattern.slice(0, length))) return pattern.slice(0, length);
+	return "";
+}
+/** Fewest further bits before the detector can output 1 again, straight after a match. */
+const bitsToFireAgain = (pattern, overlap) => overlap ? pattern.length - borderOf(pattern).length : pattern.length;
+/** Back edges that do NOT return to the start: the ones a naive design misses. */
+const partialFallbacks = (machine) => backEdges(machine).filter((edge) => edge.to > 0);
+
+//#endregion
+export { backEdges, bitsToFireAgain, borderOf, buildDetector, partialFallbacks, runDetector };

package/dist/logic/display.d.mts

@@ -0,0 +1,24 @@
+import { ReactNode } from "react";
+
+//#region src/logic/display.d.ts
+interface BinaryDisplayProps {
+  /** number of bits (2–4 → one hex digit). */
+  bits?: number;
+  /** starting value. */
+  start?: number;
+  /** a goal digit the learner must build; met → checkpoint. */
+  target?: number;
+  title?: string;
+  prompt?: string;
+  activity?: string;
+}
+declare function BinaryDisplayLab({
+  bits,
+  start,
+  target,
+  title,
+  prompt,
+  activity
+}?: BinaryDisplayProps): ReactNode;
+//#endregion
+export { BinaryDisplayLab, BinaryDisplayProps };