@classytic/labs 0.1.0 → 0.3.0

package/dist/logic/ic.d.mts

@@ -0,0 +1,62 @@
+declare namespace ic_d_exports {
+  export { CHIPS, ChipGate, ChipId, ChipResult, ChipSpec, Diagnostic, GND_PIN, GateFn, Source, Terminal, VCC_PIN, Wire, behavesAs, evaluateChip, pin };
+}
+/**
+ * A 14-pin logic chip on a breadboard, wired pin by pin.
+ *
+ * The first practical session of a digital logic course is not about logic. The truth tables are
+ * already known; what goes wrong is the wiring. The chip was never powered. The LED was put on an
+ * input pin. A switch was wired straight onto a gate's output. An unused input was left floating.
+ * Pin 8 was counted as if it were next to pin 1. None of that can be learned from a truth table, and
+ * all of it can be simulated honestly, because it is about connections rather than electronics.
+ *
+ * So this model is a netlist. Every wire joins two terminals (a pin, a switch, a supply rail or the
+ * LED), terminals joined by wires form a net, and each net is driven by at most one thing. The chip
+ * works only when pin 14 is on the +5 V net and pin 7 on the ground net, which is true of the whole
+ * 7400 family and is the single most useful fact on the datasheet.
+ *
+ * The chips are the ones every lab kit has. Four of them share one pinout (quad two-input gates);
+ * the 7402 NOR puts its outputs on the other side of each gate, and the 7404 has six inverters.
+ * Floating inputs are treated as the modern 74HC parts treat them: undefined, not quietly high as
+ * the older 74LS parts happened to behave.
+ */
+type ChipId = '7400' | '7402' | '7404' | '7408' | '7432' | '7486';
+type GateFn = 'NAND' | 'NOR' | 'NOT' | 'AND' | 'OR' | 'XOR';
+interface ChipGate {
+  inputs: number[];
+  output: number;
+}
+interface ChipSpec {
+  id: ChipId;
+  name: string;
+  fn: GateFn;
+  gates: ChipGate[];
+}
+declare const VCC_PIN = 14;
+declare const GND_PIN = 7;
+declare const CHIPS: Record<ChipId, ChipSpec>;
+/** Terminals off the chip. Everything else is a pin, written `p1` to `p14`. */
+type Source = 'A' | 'B' | 'VCC' | 'GND' | 'LED';
+type Terminal = Source | `p${number}`;
+type Wire = [Terminal, Terminal];
+declare const pin: (n: number) => Terminal;
+interface Diagnostic {
+  code: 'unpowered' | 'reversed' | 'contention' | 'floating' | 'led-on-input' | 'led-on-supply' | 'led-unwired';
+  message: string;
+}
+interface ChipResult {
+  powered: boolean;
+  /** true / false, or null when the LED's net has no defined level. */
+  led: boolean | null;
+  /** Level on every pin, null where undefined. */
+  pins: Record<number, boolean | null>;
+  diagnostics: Diagnostic[];
+}
+declare function evaluateChip(chipId: ChipId, wires: Wire[], inputs: {
+  A: boolean;
+  B: boolean;
+}): ChipResult;
+/** Does the LED follow `rule` for all four switch combinations, with no warnings? */
+declare function behavesAs(chipId: ChipId, wires: Wire[], rule: (a: boolean, b: boolean) => boolean): boolean;
+//#endregion
+export { ChipId, ChipResult, Wire, ic_d_exports };

package/dist/logic/ic.mjs

@@ -0,0 +1,245 @@
+import { __exportAll } from "../_virtual/_rolldown/runtime.mjs";
+
+//#region src/logic/ic.ts
+var ic_exports = /* @__PURE__ */ __exportAll({
+	CHIPS: () => CHIPS,
+	GND_PIN: () => 7,
+	VCC_PIN: () => 14,
+	behavesAs: () => behavesAs,
+	evaluateChip: () => evaluateChip,
+	pin: () => pin
+});
+const VCC_PIN = 14;
+const GND_PIN = 7;
+/** 7400, 7408, 7432, 7486: gate n has inputs then output, pins 1-2→3, 4-5→6, 9-10→8, 12-13→11. */
+const QUAD_2_INPUT = [
+	{
+		inputs: [1, 2],
+		output: 3
+	},
+	{
+		inputs: [4, 5],
+		output: 6
+	},
+	{
+		inputs: [9, 10],
+		output: 8
+	},
+	{
+		inputs: [12, 13],
+		output: 11
+	}
+];
+const CHIPS = {
+	"7400": {
+		id: "7400",
+		name: "quad 2-input NAND",
+		fn: "NAND",
+		gates: QUAD_2_INPUT
+	},
+	"7408": {
+		id: "7408",
+		name: "quad 2-input AND",
+		fn: "AND",
+		gates: QUAD_2_INPUT
+	},
+	"7432": {
+		id: "7432",
+		name: "quad 2-input OR",
+		fn: "OR",
+		gates: QUAD_2_INPUT
+	},
+	"7486": {
+		id: "7486",
+		name: "quad 2-input XOR",
+		fn: "XOR",
+		gates: QUAD_2_INPUT
+	},
+	"7402": {
+		id: "7402",
+		name: "quad 2-input NOR",
+		fn: "NOR",
+		gates: [
+			{
+				inputs: [2, 3],
+				output: 1
+			},
+			{
+				inputs: [5, 6],
+				output: 4
+			},
+			{
+				inputs: [8, 9],
+				output: 10
+			},
+			{
+				inputs: [11, 12],
+				output: 13
+			}
+		]
+	},
+	"7404": {
+		id: "7404",
+		name: "hex inverter",
+		fn: "NOT",
+		gates: [
+			{
+				inputs: [1],
+				output: 2
+			},
+			{
+				inputs: [3],
+				output: 4
+			},
+			{
+				inputs: [5],
+				output: 6
+			},
+			{
+				inputs: [9],
+				output: 8
+			},
+			{
+				inputs: [11],
+				output: 10
+			},
+			{
+				inputs: [13],
+				output: 12
+			}
+		]
+	}
+};
+const apply = (fn, values) => {
+	switch (fn) {
+		case "AND": return values.every(Boolean);
+		case "NAND": return !values.every(Boolean);
+		case "OR": return values.some(Boolean);
+		case "NOR": return !values.some(Boolean);
+		case "XOR": return values.filter(Boolean).length % 2 === 1;
+		case "NOT": return !values[0];
+	}
+};
+const pin = (n) => `p${n}`;
+/** Union-find over terminals. */
+function netsOf(wires) {
+	const parent = /* @__PURE__ */ new Map();
+	const find = (t) => {
+		if (!parent.has(t)) parent.set(t, t);
+		let root = t;
+		while (parent.get(root) !== root) root = parent.get(root);
+		parent.set(t, root);
+		return root;
+	};
+	for (const [a, b] of wires) {
+		const ra = find(a);
+		const rb = find(b);
+		if (ra !== rb) parent.set(ra, rb);
+	}
+	const rootOf = /* @__PURE__ */ new Map();
+	for (const t of parent.keys()) rootOf.set(t, find(t));
+	return rootOf;
+}
+function evaluateChip(chipId, wires, inputs) {
+	const chip = CHIPS[chipId];
+	const rootOf = netsOf(wires);
+	const net = (t) => rootOf.get(t) ?? t;
+	const same = (a, b) => net(a) === net(b);
+	const diagnostics = [];
+	const reversed = same(pin(14), "GND") && same(pin(7), "VCC");
+	const powered = same(pin(14), "VCC") && same(pin(7), "GND") && !same("VCC", "GND");
+	if (reversed) diagnostics.push({
+		code: "reversed",
+		message: "+5 V is on pin 7 and ground on pin 14. The supply is backwards, which destroys a real chip."
+	});
+	else if (!powered) diagnostics.push({
+		code: "unpowered",
+		message: "The chip has no power. Every 74-series chip needs +5 V on pin 14 and ground on pin 7."
+	});
+	const outputPins = new Set(chip.gates.map((gate) => gate.output));
+	const fixedDrivers = /* @__PURE__ */ new Map();
+	const addDriver = (t, name, value) => {
+		const root = net(t);
+		fixedDrivers.set(root, [...fixedDrivers.get(root) ?? [], {
+			name,
+			value
+		}]);
+	};
+	if (rootOf.has("A")) addDriver("A", "switch A", inputs.A);
+	if (rootOf.has("B")) addDriver("B", "switch B", inputs.B);
+	if (rootOf.has("VCC")) addDriver("VCC", "+5 V", true);
+	if (rootOf.has("GND")) addDriver("GND", "ground", false);
+	const outputNets = powered ? chip.gates.map((gate) => ({
+		root: net(pin(gate.output)),
+		pinNo: gate.output
+	})) : [];
+	const driverCount = /* @__PURE__ */ new Map();
+	for (const [root, list] of fixedDrivers) driverCount.set(root, list.map((d) => d.name));
+	for (const { root, pinNo } of outputNets) driverCount.set(root, [...driverCount.get(root) ?? [], `output pin ${pinNo}`]);
+	for (const names of driverCount.values()) if (names.length > 1) diagnostics.push({
+		code: "contention",
+		message: `${names.join(" and ")} are wired together, so two outputs fight over one wire.`
+	});
+	const levels = /* @__PURE__ */ new Map();
+	for (const [root, list] of fixedDrivers) levels.set(root, list.length === 1 ? list[0].value : null);
+	const outputs = /* @__PURE__ */ new Map();
+	for (let pass = 0; pass < 8 && powered; pass++) {
+		let changed = false;
+		for (const gate of chip.gates) {
+			const values = gate.inputs.map((p) => levels.get(net(pin(p))) ?? null);
+			const out = values.every((v) => v !== null) ? apply(chip.fn, values) : null;
+			if (outputs.get(gate.output) !== out) {
+				outputs.set(gate.output, out);
+				changed = true;
+			}
+			const root = net(pin(gate.output));
+			if ((driverCount.get(root)?.length ?? 0) === 1) levels.set(root, out);
+		}
+		if (!changed) break;
+	}
+	const pins = {};
+	for (let p = 1; p <= 14; p++) pins[p] = outputPins.has(p) ? powered ? outputs.get(p) ?? null : null : levels.get(net(pin(p))) ?? null;
+	const ledRoot = rootOf.has("LED") ? net("LED") : null;
+	if (ledRoot === null) diagnostics.push({
+		code: "led-unwired",
+		message: "The LED is not connected to anything yet."
+	});
+	else {
+		const ledPins = Array.from({ length: 14 }, (_, i) => i + 1).filter((p) => net(pin(p)) === ledRoot);
+		if (same("LED", "VCC") || same("LED", "GND")) diagnostics.push({
+			code: "led-on-supply",
+			message: "The LED is wired straight to a supply rail, so it can only ever be on or off."
+		});
+		else if (ledPins.length && ledPins.every((p) => !outputPins.has(p))) diagnostics.push({
+			code: "led-on-input",
+			message: `The LED is on pin ${ledPins[0]}, which is an input. It will only show what is fed into that pin.`
+		});
+		if (powered) for (const gate of chip.gates) {
+			const reachesLed = net(pin(gate.output)) === ledRoot;
+			const floating = gate.inputs.filter((p) => (levels.get(net(pin(p))) ?? null) === null);
+			if (reachesLed && floating.length) diagnostics.push({
+				code: "floating",
+				message: `Pin ${floating.join(" and ")} ${floating.length > 1 ? "are" : "is"} not connected, so the input floats. A 74HC chip can read that as either level.`
+			});
+		}
+	}
+	return {
+		powered,
+		led: ledRoot === null ? null : levels.get(ledRoot) ?? null,
+		pins,
+		diagnostics
+	};
+}
+/** Does the LED follow `rule` for all four switch combinations, with no warnings? */
+function behavesAs(chipId, wires, rule) {
+	return [false, true].every((A) => [false, true].every((B) => {
+		const result = evaluateChip(chipId, wires, {
+			A,
+			B
+		});
+		return result.powered && result.diagnostics.length === 0 && result.led === rule(A, B);
+	}));
+}
+
+//#endregion
+export { CHIPS, behavesAs, evaluateChip, ic_exports, pin };

package/dist/logic/index.d.mts

@@ -0,0 +1,33 @@
+import { GateType } from "../kit/logic-gates/gate.mjs";
+import { GateDef, LogicDiagnostic, LogicDoc, LogicGate, LogicInput, LogicOutput, LogicSolution } from "./contract.mjs";
+import { LogicEditor, LogicEditorProps } from "./LogicEditor.mjs";
+import { PortRef, addNode, connect, deleteNode, disconnect, moveNode, relabel, setGoal, setInputValue, toggleInput } from "./edit-ops.mjs";
+import { LogicEditScene, LogicEditSceneProps } from "./LogicEditScene.mjs";
+import { LogicBuildLab, LogicBuildProps } from "./LogicBuildLab.mjs";
+import { getGate, listGates, registerGate } from "./registry.mjs";
+import { registerBuiltinGates } from "./gates.mjs";
+import { evaluate, truthTable } from "./evaluate.mjs";
+import { LogicScene, LogicSceneProps } from "./LogicScene.mjs";
+import { LogicGateLab, LogicGateProps } from "./lab.mjs";
+import { BinaryDisplayLab, BinaryDisplayProps } from "./display.mjs";
+import { LOGIC_PRESETS, LogicPresetKey, presetDoc } from "./presets.mjs";
+import { BooleanNetlist, netlistToDoc } from "./netlist.mjs";
+import { ClockEdge, CounterCell, DFlipFlopCell, DLatchCell, FsmCell, FsmTransition, JkFlipFlopCell, RegisterCell, SequentialCell, SequentialLogicDoc, SequentialSolution, SequentialState, SequentialTraceEntry, ShiftRegisterCell, SrLatchCell, TFlipFlopCell, createSequentialState, machineIs, observeSequential, readUnsigned, sequenceTable, stepSequential } from "./sequential.mjs";
+import { LatchInputs, LatchLevels, LatchMode, LatchSettle, RESET_STATE, SET_STATE, delaysToSettle, latchDelay, latchMode, runLatch, settleLatch } from "./latch.mjs";
+import { DEFAULT_D, DEFAULT_LENGTH, DEFAULT_PERIOD, JkAction, Wave, clockWave, dFlipFlop, dLatch, disagreement, jkActions, jkFlipFlop, risingEdges, setupViolations, waveFrom } from "./timing.mjs";
+import { CounterRun, MAX_WIDTH, detectBits, detectLabel, modCounterDoc, runCounter, stagesFor, toBinary, transitions } from "./counter.mjs";
+import { Detector, DetectorRun, DetectorState, MachineKind, backEdges, bitsToFireAgain, borderOf, buildDetector, partialFallbacks, runDetector } from "./detector.mjs";
+import { SHIFT_WIDTH, ShiftSnapshot, fromBits, runShift, sendOrderFor, toBits } from "./shift.mjs";
+import { twos_d_exports } from "./twos.mjs";
+import { ic_d_exports } from "./ic.mjs";
+import { ChipScene, ChipSceneProps } from "./ChipScene.mjs";
+import { TwosOperation, TwosScene, TwosSceneProps } from "./TwosScene.mjs";
+import { ShiftScene, ShiftSceneProps } from "./ShiftScene.mjs";
+import { DetectorScene, DetectorSceneProps } from "./DetectorScene.mjs";
+import { LatchScene, LatchSceneProps } from "./LatchScene.mjs";
+import { TimingScene, TimingSceneProps } from "./TimingScene.mjs";
+import { CounterScene, CounterSceneProps } from "./CounterScene.mjs";
+import { WaveMark, WaveRow, WaveScene, WaveSceneProps } from "./WaveScene.mjs";
+import { SEQUENTIAL_PRESETS, SequentialPreset, SequentialPresetKey, sequentialPreset } from "./sequential-presets.mjs";
+import { SequentialLogicLab, SequentialLogicLabProps } from "./SequentialLogicLab.mjs";
+export { BinaryDisplayLab, type BinaryDisplayProps, type BooleanNetlist, ChipScene, type ChipSceneProps, ClockEdge, CounterCell, CounterRun, CounterScene, type CounterSceneProps, DEFAULT_D, DEFAULT_LENGTH, DEFAULT_PERIOD, DFlipFlopCell, DLatchCell, Detector, DetectorRun, DetectorScene, type DetectorSceneProps, DetectorState, FsmCell, FsmTransition, type GateDef, type GateType, JkAction, JkFlipFlopCell, LOGIC_PRESETS, LatchInputs, LatchLevels, LatchMode, LatchScene, type LatchSceneProps, LatchSettle, LogicBuildLab, type LogicBuildProps, type LogicDiagnostic, type LogicDoc, LogicEditScene, type LogicEditSceneProps, LogicEditor, type LogicEditorProps, type LogicGate, LogicGateLab, type LogicGateProps, type LogicInput, type LogicOutput, type LogicPresetKey, LogicScene, type LogicSceneProps, type LogicSolution, MAX_WIDTH, MachineKind, type PortRef, RESET_STATE, RegisterCell, SEQUENTIAL_PRESETS, SET_STATE, SHIFT_WIDTH, SequentialCell, SequentialLogicDoc, SequentialLogicLab, type SequentialLogicLabProps, type SequentialPreset, type SequentialPresetKey, SequentialSolution, SequentialState, SequentialTraceEntry, ShiftRegisterCell, ShiftScene, type ShiftSceneProps, ShiftSnapshot, SrLatchCell, TFlipFlopCell, TimingScene, type TimingSceneProps, type TwosOperation, TwosScene, type TwosSceneProps, Wave, type WaveMark, type WaveRow, WaveScene, type WaveSceneProps, addNode, backEdges, bitsToFireAgain, borderOf, buildDetector, clockWave, connect, createSequentialState, dFlipFlop, dLatch, delaysToSettle, deleteNode, detectBits, detectLabel, disagreement, disconnect, evaluate, fromBits, getGate, ic_d_exports as ic, jkActions, jkFlipFlop, latchDelay, latchMode, listGates, machineIs, modCounterDoc, moveNode, netlistToDoc, observeSequential, partialFallbacks, presetDoc, readUnsigned, registerBuiltinGates, registerGate, relabel, risingEdges, runCounter, runDetector, runLatch, runShift, sendOrderFor, sequenceTable, sequentialPreset, setGoal, setInputValue, settleLatch, setupViolations, stagesFor, stepSequential, toBinary, toBits, toggleInput, transitions, truthTable, twos_d_exports as twos, waveFrom };

package/dist/logic/index.mjs

@@ -0,0 +1,32 @@
+import { getGate, listGates, registerGate } from "./registry.mjs";
+import { registerBuiltinGates } from "./gates.mjs";
+import { evaluate, truthTable } from "./evaluate.mjs";
+import { LogicScene } from "./LogicScene.mjs";
+import { LOGIC_PRESETS, presetDoc } from "./presets.mjs";
+import { LogicGateLab } from "./lab.mjs";
+import { BinaryDisplayLab } from "./display.mjs";
+import { LogicEditScene } from "./LogicEditScene.mjs";
+import { addNode, connect, deleteNode, disconnect, moveNode, relabel, setGoal, setInputValue, toggleInput } from "./edit-ops.mjs";
+import { LogicEditor } from "./LogicEditor.mjs";
+import { LogicBuildLab } from "./LogicBuildLab.mjs";
+import { netlistToDoc } from "./netlist.mjs";
+import { createSequentialState, machineIs, observeSequential, readUnsigned, sequenceTable, stepSequential } from "./sequential.mjs";
+import { RESET_STATE, SET_STATE, delaysToSettle, latchDelay, latchMode, runLatch, settleLatch } from "./latch.mjs";
+import { DEFAULT_D, DEFAULT_LENGTH, DEFAULT_PERIOD, clockWave, dFlipFlop, dLatch, disagreement, jkActions, jkFlipFlop, risingEdges, setupViolations, waveFrom } from "./timing.mjs";
+import { MAX_WIDTH, detectBits, detectLabel, modCounterDoc, runCounter, stagesFor, toBinary, transitions } from "./counter.mjs";
+import { backEdges, bitsToFireAgain, borderOf, buildDetector, partialFallbacks, runDetector } from "./detector.mjs";
+import { SHIFT_WIDTH, fromBits, runShift, sendOrderFor, toBits } from "./shift.mjs";
+import { twos_exports } from "./twos.mjs";
+import { ic_exports } from "./ic.mjs";
+import { ChipScene } from "./ChipScene.mjs";
+import { TwosScene } from "./TwosScene.mjs";
+import { ShiftScene } from "./ShiftScene.mjs";
+import { DetectorScene } from "./DetectorScene.mjs";
+import { LatchScene } from "./LatchScene.mjs";
+import { TimingScene } from "./TimingScene.mjs";
+import { CounterScene } from "./CounterScene.mjs";
+import { WaveScene } from "./WaveScene.mjs";
+import { SEQUENTIAL_PRESETS, sequentialPreset } from "./sequential-presets.mjs";
+import { SequentialLogicLab } from "./SequentialLogicLab.mjs";
+
+export { BinaryDisplayLab, ChipScene, CounterScene, DEFAULT_D, DEFAULT_LENGTH, DEFAULT_PERIOD, DetectorScene, LOGIC_PRESETS, LatchScene, LogicBuildLab, LogicEditScene, LogicEditor, LogicGateLab, LogicScene, MAX_WIDTH, RESET_STATE, SEQUENTIAL_PRESETS, SET_STATE, SHIFT_WIDTH, SequentialLogicLab, ShiftScene, TimingScene, TwosScene, WaveScene, addNode, backEdges, bitsToFireAgain, borderOf, buildDetector, clockWave, connect, createSequentialState, dFlipFlop, dLatch, delaysToSettle, deleteNode, detectBits, detectLabel, disagreement, disconnect, evaluate, fromBits, getGate, ic_exports as ic, jkActions, jkFlipFlop, latchDelay, latchMode, listGates, machineIs, modCounterDoc, moveNode, netlistToDoc, observeSequential, partialFallbacks, presetDoc, readUnsigned, registerBuiltinGates, registerGate, relabel, risingEdges, runCounter, runDetector, runLatch, runShift, sendOrderFor, sequenceTable, sequentialPreset, setGoal, setInputValue, settleLatch, setupViolations, stagesFor, stepSequential, toBinary, toBits, toggleInput, transitions, truthTable, twos_exports as twos, waveFrom };

package/dist/logic/lab.d.mts

@@ -0,0 +1,32 @@
+import { LabAskSpec } from "../kit/ask.mjs";
+import { LogicDoc } from "./contract.mjs";
+import { ReactNode } from "react";
+
+//#region src/logic/lab.d.ts
+interface LogicGateProps {
+  doc?: LogicDoc;
+  /** a named preset (and/or/xor/nand-not/nand-and/nand-or/half-adder/full-adder). */
+  preset?: string;
+  mode?: 'explore' | 'predict';
+  /** show the step control that lights the signal up level by level. */
+  steps?: boolean;
+  /** show the full truth table alongside. */
+  showTable?: boolean;
+  title?: string;
+  prompt?: string;
+  ask?: LabAskSpec;
+  activity?: string;
+}
+declare function LogicGateLab({
+  doc: doc0,
+  preset,
+  mode,
+  steps,
+  showTable,
+  title,
+  prompt,
+  ask,
+  activity
+}?: LogicGateProps): ReactNode;
+//#endregion
+export { LogicGateLab, LogicGateProps };

package/dist/logic/lab.mjs

@@ -0,0 +1,138 @@
+'use client';
+
+import { Slider, StatusPill } from "../kit/controls.mjs";
+import { Activity } from "../kit/activity.mjs";
+import { Field } from "../kit/frame.mjs";
+import { useCheckpoint } from "../kit/pedagogy.mjs";
+import { LabAsk } from "../kit/ask.mjs";
+import { evaluate, truthTable } from "./evaluate.mjs";
+import { LogicScene } from "./LogicScene.mjs";
+import { presetDoc } from "./presets.mjs";
+import { useState } from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+
+//#region src/logic/lab.tsx
+/**
+* LogicGateLab — the authorable digital-logic lesson. It renders a LogicDoc with the engine
+* (live wires show the propagating signal), lets the learner toggle inputs, and runs in two
+* modes: EXPLORE (drive the inputs to meet a goal) or PREDICT (the output is hidden behind a
+* '?', tap to guess 0/1, green ring + checkpoint when right). An optional step control lights
+* the signal up one propagation level at a time. A live truth table sits alongside.
+*/
+const cycle = (g) => g === "?" ? "1" : g === "1" ? "0" : "1";
+function LogicGateLab({ doc: doc0, preset = "and", mode = "explore", steps = false, showTable = true, title = "Logic gates: follow the signal", prompt, ask, activity = "logic-gate" } = {}) {
+	const [doc, setDoc] = useState(() => doc0 ?? presetDoc(preset));
+	const [guess, setGuess] = useState({});
+	const [step, setStep] = useState(steps ? 0 : void 0);
+	const sol = evaluate(doc);
+	const hasGoal = doc.outputs.some((o) => o.goal !== void 0);
+	const predicting = mode === "predict";
+	const allPredicted = predicting && doc.outputs.every((o) => guess[o.id] && guess[o.id] !== "?" && guess[o.id] === "1" === (sol.outputs[o.id] ?? false));
+	const solved = predicting ? allPredicted : hasGoal ? sol.allGoalsMet : false;
+	useCheckpoint({
+		solved,
+		activity
+	});
+	const toggleInput = (id) => setDoc((d) => ({
+		...d,
+		inputs: d.inputs.map((i) => i.id === id ? {
+			...i,
+			value: !i.value
+		} : i)
+	}));
+	const figure = /* @__PURE__ */ jsx(LogicScene, {
+		doc,
+		onToggleInput: predicting ? void 0 : toggleInput,
+		onOutputClick: predicting ? (id) => setGuess((g) => ({
+			...g,
+			[id]: cycle(g[id] ?? "?")
+		})) : void 0,
+		outputText: predicting ? (id, actual) => guess[id] && guess[id] !== "?" ? guess[id] : "?" : void 0,
+		outputState: predicting ? (id, actual) => {
+			const g = guess[id];
+			return !g || g === "?" ? void 0 : g === "1" === actual ? "ok" : "no";
+		} : void 0,
+		reveal: predicting && !solved ? 0 : step,
+		showValues: !predicting,
+		ariaLabel: `logic circuit, ${predicting ? "predict the output" : "toggle the inputs"}`
+	});
+	const rows = showTable ? truthTable(doc) : [];
+	const curKey = doc.inputs.map((i) => i.value ? 1 : 0).join("");
+	const table = showTable ? /* @__PURE__ */ jsx("div", {
+		className: "logic-table-scroll",
+		children: /* @__PURE__ */ jsxs("table", {
+			className: "logic-truth-table",
+			children: [/* @__PURE__ */ jsx("thead", { children: /* @__PURE__ */ jsxs("tr", { children: [doc.inputs.map((i) => /* @__PURE__ */ jsx("th", { children: i.label ?? i.id }, i.id)), doc.outputs.map((o) => /* @__PURE__ */ jsx("th", {
+				"data-output": true,
+				children: o.label ?? o.id
+			}, o.id))] }) }), /* @__PURE__ */ jsx("tbody", { children: rows.map((r, ri) => {
+				return /* @__PURE__ */ jsxs("tr", {
+					"data-current": r.inputs.map((b) => b ? 1 : 0).join("") === curKey || void 0,
+					children: [r.inputs.map((b, k) => /* @__PURE__ */ jsx("td", { children: b ? 1 : 0 }, k)), doc.outputs.map((o) => /* @__PURE__ */ jsx("td", {
+						"data-value": r.outputs[o.id] || void 0,
+						children: r.outputs[o.id] ? 1 : 0
+					}, o.id))]
+				}, ri);
+			}) })]
+		})
+	}) : null;
+	const controls = steps && !predicting ? /* @__PURE__ */ jsx("div", {
+		className: "lab-activity-fields",
+		children: /* @__PURE__ */ jsx(Field, {
+			label: "propagation step",
+			value: `${step ?? 0} / ${sol.levels.length - 1}`,
+			children: /* @__PURE__ */ jsx(Slider, {
+				value: step ?? 0,
+				min: 0,
+				max: sol.levels.length - 1,
+				step: 1,
+				onChange: setStep,
+				ariaLabel: "propagation step"
+			})
+		})
+	}) : void 0;
+	const aside = /* @__PURE__ */ jsxs("div", {
+		className: "logic-lab-inspector",
+		children: [/* @__PURE__ */ jsx(StatusPill, {
+			ok: solved,
+			className: "logic-lab-status",
+			role: "status",
+			children: predicting ? solved ? "✓ correct, that is the output" : "tap the output LED to predict 0 or 1" : hasGoal ? solved ? "✓ goal met" : "toggle the inputs to reach the goal" : "toggle the inputs and watch the signal"
+		}), showTable && /* @__PURE__ */ jsxs("div", {
+			className: "logic-table-panel",
+			children: [/* @__PURE__ */ jsx("span", { children: "Truth table (current row highlighted)" }), table]
+		})]
+	});
+	const description = prompt ?? (predicting ? "Work out the output for these inputs, then tap the LED to check." : "Tap the input switches. A glowing wire carries a 1, so you can follow the signal through each gate.");
+	return /* @__PURE__ */ jsxs(Activity.Root, { children: [
+		/* @__PURE__ */ jsxs(Activity.Header, { children: [/* @__PURE__ */ jsx(Activity.Heading, {
+			eyebrow: "Digital logic",
+			title,
+			description
+		}), /* @__PURE__ */ jsx(Activity.FocusButton, {})] }),
+		/* @__PURE__ */ jsxs(Activity.Status, { children: [
+			/* @__PURE__ */ jsx("strong", { children: predicting ? "Predict" : "Explore" }),
+			/* @__PURE__ */ jsxs("span", { children: [doc.inputs.length, " inputs"] }),
+			/* @__PURE__ */ jsxs("span", { children: [doc.gates.length, " gates"] }),
+			/* @__PURE__ */ jsxs("span", { children: [doc.outputs.length, " outputs"] })
+		] }),
+		/* @__PURE__ */ jsxs(Activity.Workspace, { children: [/* @__PURE__ */ jsxs(Activity.Canvas, {
+			label: "Interactive logic circuit",
+			children: [figure, controls && /* @__PURE__ */ jsx("div", {
+				className: "lab-activity-fields",
+				children: controls
+			})]
+		}), /* @__PURE__ */ jsx(Activity.Inspector, {
+			label: "Truth table and goal",
+			children: aside
+		})] }),
+		ask && /* @__PURE__ */ jsxs(Activity.Feedback, { children: [/* @__PURE__ */ jsx("span", { children: "Check understanding" }), /* @__PURE__ */ jsx(LabAsk, {
+			ask,
+			activity
+		})] }),
+		/* @__PURE__ */ jsx(Activity.LiveRegion, { children: predicting ? solved ? "The predicted outputs are correct." : "Predict each output." : solved ? "The circuit goal is met." : "Toggle inputs and observe the signal." })
+	] });
+}
+
+//#endregion
+export { LogicGateLab };

package/dist/logic/latch.d.mts

@@ -0,0 +1,70 @@
+//#region src/logic/latch.d.ts
+/**
+ * The SR latch, built from two NOR gates and simulated one gate delay at a time.
+ *
+ * The sequential engine already has an `sr-latch` cell, and it is correct, but it is a box: it
+ * stores a bit because the code says so. A student asked "why does it remember?" gets nothing from
+ * a box. This model is the circuit itself, two cross-coupled NOR gates, and the answer falls out
+ * of it: with both inputs low, each gate's output is decided by the OTHER gate's output, so
+ * whichever state the pair is already in keeps itself there.
+ *
+ * Two deliberate choices make the model honest rather than tidy.
+ *
+ * First, time moves in GATE DELAYS and both gates update together. Evaluating one gate and then
+ * the other (the natural way to write it) quietly resolves races by line order. Real gates switch
+ * at the same moment, so they are updated from the same previous values here.
+ *
+ * Second, that makes the forbidden input behave as it does on a bench. With S and R both high,
+ * both outputs are forced low. Release both at once and each gate sees two lows, so both rise,
+ * then each sees a high, so both fall, forever. Symmetric gates have no reason to settle, and in
+ * real hardware the winner is decided by whichever gate happens to be a few picoseconds faster.
+ * That is why the input is forbidden, and the lab can show it instead of asserting it.
+ */
+interface LatchLevels {
+  q: boolean;
+  nq: boolean;
+}
+interface LatchInputs {
+  s: boolean;
+  r: boolean;
+}
+type LatchMode = 'set' | 'reset' | 'hold' | 'forbidden';
+declare const latchMode: ({
+  s,
+  r
+}: LatchInputs) => LatchMode;
+/** One gate delay: both NOR gates read the same previous outputs and switch together. */
+declare const latchDelay: ({
+  s,
+  r
+}: LatchInputs, {
+  q,
+  nq
+}: LatchLevels) => LatchLevels;
+interface LatchSettle {
+  /** `steps[0]` is the state before the inputs changed; `steps[k]` is after k gate delays. */
+  steps: LatchLevels[];
+  stable: boolean;
+  /** The pair revisited a state that is not a resting one, so it will cycle forever. */
+  oscillating: boolean;
+  final: LatchLevels;
+  /** Q and Q̅ disagree, which is the one promise a latch makes. False only when both are equal. */
+  complementary: boolean;
+}
+/**
+ * Apply new input levels and run gate delays until the outputs stop changing, or until the pair
+ * repeats a state it has already left, which means it never will stop.
+ */
+declare function settleLatch(inputs: LatchInputs, from: LatchLevels, maxDelays?: number): LatchSettle;
+/** The two resting states of a latch with both inputs released. */
+declare const RESET_STATE: LatchLevels;
+declare const SET_STATE: LatchLevels;
+/**
+ * What a sequence of input changes does, one settle per change. Each entry starts from where the
+ * previous one ended, which is the whole point: a latch's output depends on its history.
+ */
+declare function runLatch(sequence: LatchInputs[], from?: LatchLevels): LatchSettle[];
+/** Gate delays until the outputs stop changing. Undefined when they never do. */
+declare const delaysToSettle: (result: LatchSettle) => number | undefined;
+//#endregion
+export { LatchInputs, LatchLevels, LatchMode, LatchSettle, RESET_STATE, SET_STATE, delaysToSettle, latchDelay, latchMode, runLatch, settleLatch };