@classytic/labs 0.1.0 → 0.2.0

package/dist/logic/edit-ops.mjs

@@ -0,0 +1,177 @@
+import { getGate } from "./registry.mjs";
+
+//#region src/logic/edit-ops.ts
+/**
+* Pure, immutable transforms for the LogicEditor — every edit returns a NEW LogicDoc so the
+* editor stays undoable/serializable (mirrors the analog builder's editor-ops). A "node" is an
+* input, a gate, or an output. Wires are implicit: a gate input slot (or an output) simply
+* names the source node that feeds it, so connecting = writing that id and deleting a node =
+* clearing every reference to it.
+*/
+const LETTERS = "ABCDEFGHJKLMN";
+function freshId(doc, prefix) {
+	const used = new Set([
+		...doc.inputs,
+		...doc.gates,
+		...doc.outputs
+	].map((n) => n.id));
+	let k = 1;
+	while (used.has(`${prefix}${k}`)) k++;
+	return `${prefix}${k}`;
+}
+/** Add an input / output / gate (kind = 'input' | 'output' | a registered gate kind). */
+function addNode(doc, kind, at) {
+	if (kind === "input") {
+		const id = freshId(doc, "in");
+		const label = LETTERS[doc.inputs.length] ?? id;
+		return {
+			doc: {
+				...doc,
+				inputs: [...doc.inputs, {
+					id,
+					label,
+					value: false,
+					x: at.x,
+					y: at.y
+				}]
+			},
+			id
+		};
+	}
+	if (kind === "output") {
+		const id = freshId(doc, "out");
+		const label = doc.outputs.length === 0 ? "Y" : `Y${doc.outputs.length}`;
+		return {
+			doc: {
+				...doc,
+				outputs: [...doc.outputs, {
+					id,
+					in: "",
+					label,
+					x: at.x,
+					y: at.y
+				}]
+			},
+			id
+		};
+	}
+	const arity = getGate(kind)?.arity ?? 2;
+	const id = freshId(doc, "g");
+	return {
+		doc: {
+			...doc,
+			gates: [...doc.gates, {
+				id,
+				kind,
+				in: Array(arity).fill(""),
+				x: at.x,
+				y: at.y
+			}]
+		},
+		id
+	};
+}
+/** Move any node to a new position. */
+function moveNode(doc, id, at) {
+	const set = (n) => n.id === id ? {
+		...n,
+		x: at.x,
+		y: at.y
+	} : n;
+	return {
+		...doc,
+		inputs: doc.inputs.map(set),
+		gates: doc.gates.map(set),
+		outputs: doc.outputs.map(set)
+	};
+}
+/** Wire a source node into a sink (a gate input slot, or an output). No-op for invalid pairs. */
+function connect(doc, fromId, sink) {
+	if (!fromId || fromId === sink.nodeId) return doc;
+	if (!(doc.inputs.some((i) => i.id === fromId) || doc.gates.some((g) => g.id === fromId))) return doc;
+	return {
+		...doc,
+		gates: doc.gates.map((g) => g.id === sink.nodeId ? {
+			...g,
+			in: g.in.map((v, i) => i === (sink.slot ?? 0) ? fromId : v)
+		} : g),
+		outputs: doc.outputs.map((o) => o.id === sink.nodeId ? {
+			...o,
+			in: fromId
+		} : o)
+	};
+}
+/** Clear the wire feeding a sink slot. */
+function disconnect(doc, sink) {
+	return {
+		...doc,
+		gates: doc.gates.map((g) => g.id === sink.nodeId ? {
+			...g,
+			in: g.in.map((v, i) => i === (sink.slot ?? 0) ? "" : v)
+		} : g),
+		outputs: doc.outputs.map((o) => o.id === sink.nodeId ? {
+			...o,
+			in: ""
+		} : o)
+	};
+}
+/** Delete a node and clear every reference to it. */
+function deleteNode(doc, id) {
+	return {
+		...doc,
+		inputs: doc.inputs.filter((i) => i.id !== id),
+		gates: doc.gates.filter((g) => g.id !== id).map((g) => ({
+			...g,
+			in: g.in.map((v) => v === id ? "" : v)
+		})),
+		outputs: doc.outputs.filter((o) => o.id !== id).map((o) => o.in === id ? {
+			...o,
+			in: ""
+		} : o)
+	};
+}
+/** Toggle / set a primary input's value. */
+function setInputValue(doc, id, value) {
+	return {
+		...doc,
+		inputs: doc.inputs.map((i) => i.id === id ? {
+			...i,
+			value
+		} : i)
+	};
+}
+function toggleInput(doc, id) {
+	return {
+		...doc,
+		inputs: doc.inputs.map((i) => i.id === id ? {
+			...i,
+			value: !i.value
+		} : i)
+	};
+}
+/** Rename a node's label (any node type). */
+function relabel(doc, id, label) {
+	const set = (n) => n.id === id ? {
+		...n,
+		label
+	} : n;
+	return {
+		...doc,
+		inputs: doc.inputs.map(set),
+		gates: doc.gates.map(set),
+		outputs: doc.outputs.map(set)
+	};
+}
+/** Set / clear an output's goal value (for graded build challenges). */
+function setGoal(doc, outId, goal) {
+	return {
+		...doc,
+		outputs: doc.outputs.map((o) => o.id === outId ? {
+			...o,
+			goal
+		} : o)
+	};
+}
+
+//#endregion
+export { addNode, connect, deleteNode, disconnect, moveNode, relabel, setGoal, setInputValue, toggleInput };

package/dist/logic/evaluate.d.mts

@@ -0,0 +1,11 @@
+import { LogicDoc, LogicSolution } from "./contract.mjs";
+
+//#region src/logic/evaluate.d.ts
+declare function evaluate(doc: LogicDoc): LogicSolution;
+/** The full truth table for a doc: every input combination → output values. */
+declare function truthTable(doc: LogicDoc): {
+  inputs: boolean[];
+  outputs: Record<string, boolean>;
+}[];
+//#endregion
+export { evaluate, truthTable };

package/dist/logic/evaluate.mjs

@@ -0,0 +1,93 @@
+import { getGate } from "./registry.mjs";
+import { registerBuiltinGates } from "./gates.mjs";
+
+//#region src/logic/evaluate.ts
+/**
+* Evaluate a LogicDoc in one pass: resolve every node's boolean value (memoised, with a
+* cycle guard) and compute the propagation LEVELS (inputs at level 0, each gate one level
+* past its deepest input). The levels let a lesson light the signal up step by step, and
+* `high(nodeId)` tells the renderer which wires are carrying a 1.
+*/
+registerBuiltinGates();
+function evaluate(doc) {
+	const inputVal = new Map(doc.inputs.map((i) => [i.id, !!i.value]));
+	const gateById = new Map(doc.gates.map((g) => [g.id, g]));
+	const memo = /* @__PURE__ */ new Map();
+	const visiting = /* @__PURE__ */ new Set();
+	const value = (id) => {
+		if (inputVal.has(id)) return inputVal.get(id);
+		if (memo.has(id)) return memo.get(id);
+		if (visiting.has(id)) return false;
+		const g = gateById.get(id);
+		if (!g) return false;
+		visiting.add(id);
+		const def = getGate(g.kind);
+		const out = def ? def.eval(g.in.map(value)) : false;
+		visiting.delete(id);
+		memo.set(id, out);
+		return out;
+	};
+	for (const g of doc.gates) value(g.id);
+	const depth = /* @__PURE__ */ new Map();
+	for (const i of doc.inputs) depth.set(i.id, 0);
+	let changed = true;
+	let guard = 0;
+	while (changed && guard++ < doc.gates.length + 2) {
+		changed = false;
+		for (const g of doc.gates) {
+			const d = Math.max(0, ...g.in.map((x) => depth.get(x) ?? 0)) + 1;
+			if (depth.get(g.id) !== d) {
+				depth.set(g.id, d);
+				changed = true;
+			}
+		}
+	}
+	const maxD = Math.max(0, ...depth.values());
+	const levels = Array.from({ length: maxD + 1 }, () => []);
+	for (const [id, d] of depth) (levels[d] ??= []).push(id);
+	const outputs = {};
+	let goalCount = 0;
+	let goalsMet = true;
+	for (const o of doc.outputs) {
+		outputs[o.id] = value(o.in);
+		if (o.goal !== void 0) {
+			goalCount++;
+			if (outputs[o.id] !== o.goal) goalsMet = false;
+		}
+	}
+	return {
+		value,
+		levels,
+		depthOf: (id) => depth.get(id) ?? 0,
+		high: value,
+		outputs,
+		allGoalsMet: goalCount > 0 && goalsMet
+	};
+}
+/** A truth table is 2^n rows; past this it is both impractical to show and unsafe
+*  for 32-bit bit shifts. Callers should guard before rendering one. */
+const MAX_TRUTH_TABLE_VARS = 12;
+/** The full truth table for a doc: every input combination → output values. */
+function truthTable(doc) {
+	const n = doc.inputs.length;
+	if (n > 12) throw new RangeError(`truthTable: ${n} inputs exceeds the ${12}-variable limit (${2 ** n} rows).`);
+	const rows = [];
+	for (let m = 0; m < 2 ** n; m++) {
+		const bits = doc.inputs.map((_, k) => Boolean(m >> n - 1 - k & 1));
+		const probe = {
+			...doc,
+			inputs: doc.inputs.map((inp, k) => ({
+				...inp,
+				value: bits[k]
+			}))
+		};
+		rows.push({
+			inputs: bits,
+			outputs: evaluate(probe).outputs
+		});
+	}
+	return rows;
+}
+
+//#endregion
+export { evaluate, truthTable };

package/dist/logic/gates.d.mts

@@ -0,0 +1,10 @@
+//#region src/logic/gates.d.ts
+/**
+ * The built-in logic gates. Each is ONE GateDef: its boolean function + its glyph.
+ * AND/OR are variadic (n inputs); NOT/buffer take one. NAND is the universal gate —
+ * every other gate can be built from NANDs (the lessons lean on this).
+ */
+/** Register the built-in gates (idempotent). Imported for its side effect. */
+declare function registerBuiltinGates(): void;
+//#endregion
+export { registerBuiltinGates };

package/dist/logic/gates.mjs

@@ -0,0 +1,73 @@
+import { registerGate } from "./registry.mjs";
+
+//#region src/logic/gates.ts
+const parity = (i) => i.filter(Boolean).length % 2;
+const GATES = [
+	{
+		kind: "AND",
+		label: "AND",
+		glyph: "AND",
+		arity: 2,
+		eval: (i) => i.length > 0 && i.every(Boolean)
+	},
+	{
+		kind: "OR",
+		label: "OR",
+		glyph: "OR",
+		arity: 2,
+		eval: (i) => i.some(Boolean)
+	},
+	{
+		kind: "NOT",
+		label: "NOT",
+		glyph: "NOT",
+		arity: 1,
+		eval: (i) => !i[0]
+	},
+	{
+		kind: "NAND",
+		label: "NAND",
+		glyph: "NAND",
+		arity: 2,
+		eval: (i) => !(i.length > 0 && i.every(Boolean))
+	},
+	{
+		kind: "NOR",
+		label: "NOR",
+		glyph: "NOR",
+		arity: 2,
+		eval: (i) => !i.some(Boolean)
+	},
+	{
+		kind: "XOR",
+		label: "XOR",
+		glyph: "XOR",
+		arity: 2,
+		eval: (i) => parity(i) === 1
+	},
+	{
+		kind: "XNOR",
+		label: "XNOR",
+		glyph: "XNOR",
+		arity: 2,
+		eval: (i) => parity(i) === 0
+	},
+	{
+		kind: "buffer",
+		label: "BUF",
+		glyph: "NOT",
+		arity: 1,
+		eval: (i) => !!i[0]
+	}
+];
+let registered = false;
+/** Register the built-in gates (idempotent). Imported for its side effect. */
+function registerBuiltinGates() {
+	if (registered) return;
+	registered = true;
+	GATES.forEach(registerGate);
+}
+registerBuiltinGates();
+
+//#endregion
+export { registerBuiltinGates };

package/dist/logic/index.d.mts

@@ -0,0 +1,14 @@
+import { GateType } from "../kit/logic-gates.mjs";
+import { GateDef, LogicDoc, LogicGate, LogicInput, LogicOutput, LogicSolution } from "./contract.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 { 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 { LOGIC_PRESETS, LogicPresetKey, presetDoc } from "./presets.mjs";
+export { BinaryDisplayLab, type BinaryDisplayProps, type GateDef, type GateType, LOGIC_PRESETS, LogicBuildLab, type LogicBuildProps, type LogicDoc, LogicEditScene, type LogicEditSceneProps, LogicEditor, type LogicEditorProps, type LogicGate, LogicGateLab, type LogicGateProps, type LogicInput, type LogicOutput, type LogicPresetKey, LogicScene, type LogicSceneProps, type LogicSolution, type PortRef, addNode, connect, deleteNode, disconnect, evaluate, getGate, listGates, moveNode, presetDoc, registerBuiltinGates, registerGate, relabel, setGoal, setInputValue, toggleInput, truthTable };

package/dist/logic/index.mjs

@@ -0,0 +1,13 @@
+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";
+
+export { BinaryDisplayLab, LOGIC_PRESETS, LogicBuildLab, LogicEditScene, LogicEditor, LogicGateLab, LogicScene, addNode, connect, deleteNode, disconnect, evaluate, getGate, listGates, moveNode, presetDoc, registerBuiltinGates, registerGate, relabel, setGoal, setInputValue, toggleInput, truthTable };

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,160 @@
+'use client';
+
+import { Callout, ControlBar, Field, LabFrame } 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", {
+		style: { overflowX: "auto" },
+		children: /* @__PURE__ */ jsxs("table", {
+			style: {
+				borderCollapse: "collapse",
+				fontSize: 12,
+				fontVariantNumeric: "tabular-nums"
+			},
+			children: [/* @__PURE__ */ jsx("thead", { children: /* @__PURE__ */ jsxs("tr", { children: [doc.inputs.map((i) => /* @__PURE__ */ jsx("th", {
+				style: {
+					padding: "3px 7px",
+					color: "var(--stage-fg)",
+					borderBottom: "1px solid var(--stage-grid)"
+				},
+				children: i.label ?? i.id
+			}, i.id)), doc.outputs.map((o) => /* @__PURE__ */ jsx("th", {
+				style: {
+					padding: "3px 7px",
+					color: "var(--stage-accent)",
+					borderBottom: "1px solid var(--stage-grid)"
+				},
+				children: o.label ?? o.id
+			}, o.id))] }) }), /* @__PURE__ */ jsx("tbody", { children: rows.map((r, ri) => {
+				return /* @__PURE__ */ jsxs("tr", {
+					style: { background: r.inputs.map((b) => b ? 1 : 0).join("") === curKey ? "color-mix(in oklab, var(--stage-accent) 14%, transparent)" : "transparent" },
+					children: [r.inputs.map((b, k) => /* @__PURE__ */ jsx("td", {
+						style: {
+							padding: "3px 7px",
+							textAlign: "center",
+							color: "var(--stage-muted)"
+						},
+						children: b ? 1 : 0
+					}, k)), doc.outputs.map((o) => /* @__PURE__ */ jsx("td", {
+						style: {
+							padding: "3px 7px",
+							textAlign: "center",
+							fontWeight: 700,
+							color: r.outputs[o.id] ? "var(--stage-good)" : "var(--stage-fg)"
+						},
+						children: r.outputs[o.id] ? 1 : 0
+					}, o.id))]
+				}, ri);
+			}) })]
+		})
+	}) : null;
+	const controls = steps && !predicting ? /* @__PURE__ */ jsx(ControlBar, { children: /* @__PURE__ */ jsx(Field, {
+		label: "propagation step",
+		value: `${step ?? 0} / ${sol.levels.length - 1}`,
+		children: /* @__PURE__ */ jsx("input", {
+			type: "range",
+			min: 0,
+			max: sol.levels.length - 1,
+			step: 1,
+			value: step ?? 0,
+			onChange: (e) => setStep(Number(e.target.value)),
+			"aria-label": "propagation step"
+		})
+	}) }) : void 0;
+	return /* @__PURE__ */ jsx(LabFrame, {
+		title,
+		prompt: prompt ?? (predicting ? "Work out the output for these inputs, then tap the LED to check." : "Tap the input switches. A wire glows when it carries a 1, so you can watch the signal flow through the gates."),
+		controls,
+		aside: /* @__PURE__ */ jsxs("div", {
+			style: {
+				display: "flex",
+				flexDirection: "column",
+				gap: 10
+			},
+			children: [/* @__PURE__ */ jsx("div", {
+				className: "lab-pill",
+				"data-state": solved ? "ok" : "no",
+				role: "status",
+				style: { alignSelf: "flex-start" },
+				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__ */ jsx(Callout, {
+				tone: "result",
+				children: /* @__PURE__ */ jsxs("div", {
+					style: {
+						display: "flex",
+						flexDirection: "column",
+						gap: 6
+					},
+					children: [/* @__PURE__ */ jsx("span", {
+						style: {
+							fontSize: 12,
+							color: "var(--stage-muted)"
+						},
+						children: "truth table (current row highlighted)"
+					}), table]
+				})
+			})]
+		}),
+		footer: ask ? /* @__PURE__ */ jsx(LabAsk, {
+			ask,
+			activity
+		}) : void 0,
+		children: figure
+	});
+}
+
+//#endregion
+export { LogicGateLab };

package/dist/logic/presets.d.mts

@@ -0,0 +1,12 @@
+import { LogicDoc } from "./contract.mjs";
+
+//#region src/logic/presets.d.ts
+declare const LOGIC_PRESETS: Record<string, {
+  title: string;
+  doc: LogicDoc;
+}>;
+type LogicPresetKey = keyof typeof LOGIC_PRESETS;
+/** Deep-clone a preset doc so the lab can mutate input values without touching the library. */
+declare function presetDoc(key: string): LogicDoc;
+//#endregion
+export { LOGIC_PRESETS, LogicPresetKey, presetDoc };