@classytic/labs 0.1.0 → 0.2.0

package/dist/logic/LogicScene.d.mts

@@ -0,0 +1,32 @@
+import { LogicDoc } from "./contract.mjs";
+import { ReactNode } from "react";
+
+//#region src/logic/LogicScene.d.ts
+interface LogicSceneProps {
+  doc: LogicDoc;
+  /** tap an input switch to toggle it. */
+  onToggleInput?: (id: string) => void;
+  /** tap an output LED (e.g. to cycle a predicted value in a challenge). */
+  onOutputClick?: (id: string) => void;
+  /** what to show on each output (default its actual 0/1); a challenge can return '?' or a guess. */
+  outputText?: (id: string, actual: boolean) => string;
+  /** mark each output correct/incorrect/neutral (a challenge ring). */
+  outputState?: (id: string, actual: boolean) => 'ok' | 'no' | undefined;
+  /** light the signal only through this many propagation levels (step-by-step). Default: all. */
+  reveal?: number;
+  /** print 0/1 beside inputs and gates. */
+  showValues?: boolean;
+  ariaLabel?: string;
+}
+declare function LogicScene({
+  doc,
+  onToggleInput,
+  onOutputClick,
+  outputText,
+  outputState,
+  reveal,
+  showValues,
+  ariaLabel
+}: LogicSceneProps): ReactNode;
+//#endregion
+export { LogicScene, LogicSceneProps };

package/dist/logic/LogicScene.mjs

@@ -0,0 +1,277 @@
+'use client';
+
+import { JunctionDot, Wire } from "../kit/electronics.mjs";
+import { GateGlyph, Lamp, ToggleSwitch, gatePorts } from "../kit/logic-gates.mjs";
+import { getGate } from "./registry.mjs";
+import { evaluate } from "./evaluate.mjs";
+import { jsx, jsxs } from "react/jsx-runtime";
+
+//#region src/logic/LogicScene.tsx
+const COL = 128, ROW = 66, MX = 34, MY = 30;
+const SW_W = 50, SW_H = 26, GATE = 48, LED_R = 16;
+const NET_HUES = [
+	"oklch(0.62 0.19 255)",
+	"oklch(0.70 0.17 50)",
+	"oklch(0.62 0.20 320)",
+	"oklch(0.68 0.16 160)",
+	"oklch(0.62 0.21 25)",
+	"oklch(0.66 0.15 200)",
+	"oklch(0.64 0.18 290)",
+	"oklch(0.72 0.16 110)"
+];
+function LogicScene({ doc, onToggleInput, onOutputClick, outputText, outputState, reveal, showValues, ariaLabel = "logic circuit" }) {
+	const sol = evaluate(doc);
+	const levelOf = (id) => sol.depthOf(id);
+	const lit = (id) => sol.high(id) && (reveal === void 0 || levelOf(id) < reveal);
+	const cols = sol.levels.length;
+	const colCount = Math.max(1, ...sol.levels.map((l) => l.length), doc.outputs.length);
+	const slotC = (n, i) => (colCount - n) * ROW / 2 + i * ROW + ROW / 2;
+	const halfH = (gate) => (gate ? GATE : SW_H) / 2;
+	const raw = /* @__PURE__ */ new Map();
+	sol.levels.forEach((ids, lvl) => ids.forEach((id, i) => raw.set(id, {
+		x: MX + lvl * COL,
+		y: slotC(ids.length, i),
+		gate: lvl > 0
+	})));
+	const outRaw = doc.outputs.map((o, i) => ({
+		id: o.id,
+		y: slotC(doc.outputs.length, i)
+	}));
+	let top = Infinity, bot = -Infinity;
+	raw.forEach((p) => {
+		top = Math.min(top, p.y - halfH(p.gate));
+		bot = Math.max(bot, p.y + halfH(p.gate));
+	});
+	outRaw.forEach((o) => {
+		top = Math.min(top, o.y - LED_R);
+		bot = Math.max(bot, o.y + LED_R);
+	});
+	const vOff = MY - top;
+	const pos = /* @__PURE__ */ new Map();
+	raw.forEach((p, id) => pos.set(id, {
+		x: p.x,
+		y: p.y + vOff,
+		gate: p.gate
+	}));
+	const outX = MX + cols * COL;
+	const outY = new Map(outRaw.map((o) => [o.id, o.y + vOff]));
+	const outPort = (id) => {
+		const p = pos.get(id);
+		if (!p) return null;
+		if (!p.gate) return {
+			x: p.x + SW_W,
+			y: p.y
+		};
+		const g = doc.gates.find((q) => q.id === id);
+		return gatePorts((g && getGate(g.kind)?.glyph) ?? "AND", p.x, p.y - GATE / 2, GATE).output;
+	};
+	const W = outX + 80, H = bot - top + MY * 2;
+	const sinkPorts = /* @__PURE__ */ new Map();
+	const addSink = (src, p) => {
+		if (!src || !p) return;
+		const arr = sinkPorts.get(src) ?? [];
+		arr.push(p);
+		sinkPorts.set(src, arr);
+	};
+	for (const g of doc.gates) {
+		const p = pos.get(g.id);
+		if (!p) continue;
+		const ins = gatePorts(getGate(g.kind)?.glyph ?? "AND", p.x, p.y - GATE / 2, GATE).inputs;
+		g.in.forEach((src, k) => addSink(src, ins[k] ?? null));
+	}
+	for (const o of doc.outputs) addSink(o.in, {
+		x: outX - LED_R - 4,
+		y: outY.get(o.id) ?? MY
+	});
+	const order = /* @__PURE__ */ new Map();
+	let oi = 0;
+	doc.inputs.forEach((i) => order.set(i.id, oi++));
+	doc.gates.forEach((g) => order.set(g.id, oi++));
+	const hue = (src) => NET_HUES[(order.get(src) ?? 0) % NET_HUES.length];
+	const byCol = /* @__PURE__ */ new Map();
+	for (const src of sinkPorts.keys()) {
+		const sp = outPort(src);
+		if (!sp) continue;
+		const k = Math.round(sp.x);
+		const a = byCol.get(k) ?? [];
+		a.push(src);
+		byCol.set(k, a);
+	}
+	const trunkX = /* @__PURE__ */ new Map();
+	byCol.forEach((srcs) => {
+		srcs.sort((a, b) => (outPort(a)?.y ?? 0) - (outPort(b)?.y ?? 0));
+		srcs.forEach((src, i) => {
+			const sp = outPort(src);
+			const near = Math.min(...sinkPorts.get(src).map((s) => s.x));
+			trunkX.set(src, sp.x + Math.min(14 + i * 11, Math.max(8, near - sp.x - 8)));
+		});
+	});
+	const wires = [];
+	const junctions = [];
+	sinkPorts.forEach((list, src) => {
+		const sp = outPort(src);
+		if (!sp) return;
+		const on = lit(src), col = hue(src), tx = trunkX.get(src) ?? sp.x + 14;
+		const ys = [sp.y, ...list.map((s) => s.y)];
+		const lo = Math.min(...ys), hi = Math.max(...ys);
+		wires.push(/* @__PURE__ */ jsx(Wire, {
+			points: [[sp.x, sp.y], [tx, sp.y]],
+			live: on,
+			color: col
+		}, `e-${src}`));
+		if (hi - lo > 1) wires.push(/* @__PURE__ */ jsx(Wire, {
+			points: [[tx, lo], [tx, hi]],
+			live: on,
+			color: col
+		}, `t-${src}`));
+		list.forEach((s, i) => wires.push(/* @__PURE__ */ jsx(Wire, {
+			points: [[tx, s.y], [s.x, s.y]],
+			live: on,
+			color: col
+		}, `b-${src}-${i}`)));
+		const tap = (yy, k) => {
+			if (yy > lo + .5 && yy < hi - .5) junctions.push(/* @__PURE__ */ jsx(JunctionDot, {
+				x: tx,
+				y: yy,
+				r: 3,
+				live: on,
+				color: col
+			}, `j-${src}-${k}`));
+		};
+		tap(sp.y, "s");
+		list.forEach((s, i) => tap(s.y, `${i}`));
+	});
+	return /* @__PURE__ */ jsx("div", {
+		style: {
+			borderRadius: 12,
+			overflow: "hidden",
+			background: "var(--stage-bg)",
+			border: "1px solid var(--stage-grid)",
+			maxWidth: W,
+			margin: "0 auto"
+		},
+		children: /* @__PURE__ */ jsxs("svg", {
+			viewBox: `0 0 ${W} ${H}`,
+			width: "100%",
+			role: "img",
+			"aria-label": ariaLabel,
+			children: [
+				wires,
+				junctions,
+				doc.inputs.map((inp) => {
+					const p = pos.get(inp.id);
+					if (!p) return null;
+					return /* @__PURE__ */ jsxs("g", {
+						role: onToggleInput ? "button" : void 0,
+						tabIndex: onToggleInput ? 0 : void 0,
+						"aria-label": onToggleInput ? `toggle ${inp.label ?? inp.id}` : void 0,
+						style: { cursor: onToggleInput ? "pointer" : "default" },
+						onClick: onToggleInput ? () => onToggleInput(inp.id) : void 0,
+						onKeyDown: onToggleInput ? (e) => {
+							if (e.key === "Enter" || e.key === " ") {
+								e.preventDefault();
+								onToggleInput(inp.id);
+							}
+						} : void 0,
+						children: [/* @__PURE__ */ jsx(ToggleSwitch, {
+							x: p.x,
+							y: p.y - SW_H / 2,
+							w: SW_W,
+							h: SW_H,
+							on: sol.value(inp.id),
+							label: inp.label
+						}), showValues && (() => {
+							const on = sol.value(inp.id);
+							return /* @__PURE__ */ jsx("text", {
+								x: on ? p.x + SW_H * .55 : p.x + SW_W - SW_H * .55,
+								y: p.y,
+								fill: "var(--stage-fg)",
+								fontSize: 11,
+								fontWeight: 800,
+								textAnchor: "middle",
+								dominantBaseline: "central",
+								style: { pointerEvents: "none" },
+								children: on ? "1" : "0"
+							});
+						})()]
+					}, inp.id);
+				}),
+				doc.gates.map((g) => {
+					const p = pos.get(g.id);
+					if (!p) return null;
+					const gl = getGate(g.kind)?.glyph ?? "AND";
+					const op = gatePorts(gl, p.x, p.y - GATE / 2, GATE).output;
+					return /* @__PURE__ */ jsxs("g", { children: [/* @__PURE__ */ jsx(GateGlyph, {
+						x: p.x,
+						y: p.y - GATE / 2,
+						size: GATE,
+						type: gl,
+						live: lit(g.id),
+						label: g.label ?? getGate(g.kind)?.label
+					}), showValues && /* @__PURE__ */ jsx("text", {
+						x: op.x + 4,
+						y: op.y - 6,
+						fill: lit(g.id) ? hue(g.id) : "var(--stage-muted)",
+						fontSize: 11,
+						fontWeight: 800,
+						textAnchor: "start",
+						dominantBaseline: "auto",
+						style: { pointerEvents: "none" },
+						children: sol.value(g.id) ? "1" : "0"
+					})] }, g.id);
+				}),
+				doc.outputs.map((o) => {
+					const oy = outY.get(o.id) ?? MY;
+					const actual = sol.outputs[o.id] ?? false;
+					const st = outputState?.(o.id, actual);
+					const txt = outputText?.(o.id, actual) ?? (actual ? "1" : "0");
+					return /* @__PURE__ */ jsxs("g", {
+						role: onOutputClick ? "button" : void 0,
+						tabIndex: onOutputClick ? 0 : void 0,
+						"aria-label": onOutputClick ? `set ${o.label ?? o.id}` : void 0,
+						style: { cursor: onOutputClick ? "pointer" : "default" },
+						onClick: onOutputClick ? () => onOutputClick(o.id) : void 0,
+						onKeyDown: onOutputClick ? (e) => {
+							if (e.key === "Enter" || e.key === " ") {
+								e.preventDefault();
+								onOutputClick(o.id);
+							}
+						} : void 0,
+						children: [
+							st && /* @__PURE__ */ jsx("circle", {
+								cx: outX,
+								cy: oy,
+								r: 22,
+								fill: "none",
+								stroke: st === "ok" ? "var(--stage-good)" : "var(--stage-danger, #e03131)",
+								strokeWidth: 2
+							}),
+							/* @__PURE__ */ jsx(Lamp, {
+								cx: outX,
+								cy: oy,
+								r: LED_R,
+								on: lit(o.in),
+								color: o.color,
+								label: o.label
+							}),
+							/* @__PURE__ */ jsx("text", {
+								x: outX,
+								y: oy,
+								fill: lit(o.in) ? "var(--stage-bg)" : "var(--stage-fg)",
+								fontSize: 14,
+								fontWeight: 800,
+								textAnchor: "middle",
+								dominantBaseline: "central",
+								style: { pointerEvents: "none" },
+								children: txt
+							})
+						]
+					}, o.id);
+				})
+			]
+		})
+	});
+}
+
+//#endregion
+export { LogicScene };

package/dist/logic/contract.d.mts

@@ -0,0 +1,72 @@
+import { GateType } from "../kit/logic-gates.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;
+}
+//#endregion
+export { GateDef, LogicDoc, LogicGate, LogicInput, LogicOutput, LogicSolution };

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 };

package/dist/logic/display.mjs

@@ -0,0 +1,127 @@
+'use client';
+
+import { LabFrame } from "../kit/frame.mjs";
+import { useCheckpoint } from "../kit/pedagogy.mjs";
+import { SevenSegment, ToggleSwitch } from "../kit/logic-gates.mjs";
+import { useState } from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+
+//#region src/logic/display.tsx
+/**
+* BinaryDisplayLab — the "number LED" for digital-logic / DLD projects. A row of weighted
+* bit switches (8 4 2 1 …) drives a seven-segment display: flip bits and watch the digit
+* form, with live binary / decimal / hex readouts. A decoder sits between the bits and the
+* segments (bits → number → lit segments), so this is the payoff block where learners build
+* a number out of ones and zeros. Optional `target` turns it into a "make this digit" goal.
+*/
+const FG = "var(--stage-fg)";
+const MUT = "var(--stage-muted)";
+function BinaryDisplayLab({ bits = 4, start = 0, target, title = "Build a number from bits", prompt, activity = "binary-display" } = {}) {
+	const n = Math.max(1, Math.min(4, bits));
+	const max = (1 << n) - 1;
+	const [value, setValue] = useState(() => Math.max(0, Math.min(max, start)));
+	const solved = target !== void 0 && value === (target % (max + 1) + (max + 1)) % (max + 1);
+	useCheckpoint({
+		solved,
+		activity
+	});
+	const toggleBit = (i) => setValue((v) => v ^ 1 << i);
+	const SW_W = 50, SW_H = 26, COL = 66, X0 = 40, ROWY = 150;
+	const width = X0 * 2 + (n - 1) * COL + SW_W;
+	const dispX = width / 2 - 23;
+	const bitGlyphs = [];
+	for (let k = 0; k < n; k++) {
+		const i = n - 1 - k;
+		const on = (value >> i & 1) === 1;
+		const x = X0 + k * COL;
+		bitGlyphs.push(/* @__PURE__ */ jsxs("g", {
+			onClick: () => toggleBit(i),
+			style: { cursor: "pointer" },
+			role: "button",
+			tabIndex: 0,
+			onKeyDown: (e) => {
+				if (e.key === "Enter" || e.key === " ") {
+					e.preventDefault();
+					toggleBit(i);
+				}
+			},
+			"aria-label": `bit value ${1 << i}, ${on ? "on" : "off"}`,
+			children: [
+				/* @__PURE__ */ jsx("text", {
+					x: x + SW_W / 2,
+					y: ROWY - 14,
+					fill: MUT,
+					fontSize: 11,
+					fontWeight: 700,
+					textAnchor: "middle",
+					children: 1 << i
+				}),
+				/* @__PURE__ */ jsx(ToggleSwitch, {
+					x,
+					y: ROWY,
+					w: SW_W,
+					h: SW_H,
+					on
+				}),
+				/* @__PURE__ */ jsx("text", {
+					x: x + SW_W / 2,
+					y: 192,
+					fill: on ? "var(--stage-live)" : MUT,
+					fontSize: 14,
+					fontWeight: 800,
+					textAnchor: "middle",
+					children: on ? 1 : 0
+				})
+			]
+		}, i));
+	}
+	const binStr = value.toString(2).padStart(n, "0");
+	const hexStr = value.toString(16).toUpperCase();
+	return /* @__PURE__ */ jsx(LabFrame, {
+		title,
+		prompt: prompt ?? (target !== void 0 ? `Flip the switches so the display reads ${target.toString(16).toUpperCase()}.` : "Each switch is one bit, worth the number above it. Flip them and the decoder lights the matching digit."),
+		children: /* @__PURE__ */ jsxs("svg", {
+			viewBox: `0 0 ${width} 240`,
+			width: "100%",
+			style: {
+				maxWidth: width,
+				display: "block",
+				margin: "0 auto"
+			},
+			role: "img",
+			"aria-label": `seven-segment display showing ${hexStr}, binary ${binStr}`,
+			children: [
+				/* @__PURE__ */ jsx(SevenSegment, {
+					x: dispX,
+					y: 26,
+					w: 46,
+					h: 80,
+					value
+				}),
+				bitGlyphs,
+				/* @__PURE__ */ jsx("text", {
+					x: width / 2,
+					y: 224,
+					fill: FG,
+					fontSize: 13,
+					fontWeight: 700,
+					textAnchor: "middle",
+					style: { fontVariantNumeric: "tabular-nums" },
+					children: `binary ${binStr}  =  decimal ${value}  =  hex ${hexStr}`
+				}),
+				solved && /* @__PURE__ */ jsxs("text", {
+					x: width / 2,
+					y: 18,
+					fill: "var(--stage-good)",
+					fontSize: 13,
+					fontWeight: 800,
+					textAnchor: "middle",
+					children: ["✓ that is ", hexStr]
+				})
+			]
+		})
+	});
+}
+
+//#endregion
+export { BinaryDisplayLab };

package/dist/logic/edit-ops.d.mts

@@ -0,0 +1,44 @@
+import { LogicDoc } from "./contract.mjs";
+
+//#region src/logic/edit-ops.d.ts
+/** A point on a node where a wire attaches. `dir:'out'` is a source; `dir:'in'` is a sink. */
+interface PortRef {
+  nodeId: string;
+  dir: 'out' | 'in';
+  /** which input slot, for a multi-input gate sink. */
+  slot?: number;
+}
+/** Add an input / output / gate (kind = 'input' | 'output' | a registered gate kind). */
+declare function addNode(doc: LogicDoc, kind: string, at: {
+  x: number;
+  y: number;
+}): {
+  doc: LogicDoc;
+  id: string;
+};
+/** Move any node to a new position. */
+declare function moveNode(doc: LogicDoc, id: string, at: {
+  x: number;
+  y: number;
+}): LogicDoc;
+/** Wire a source node into a sink (a gate input slot, or an output). No-op for invalid pairs. */
+declare function connect(doc: LogicDoc, fromId: string, sink: {
+  nodeId: string;
+  slot?: number;
+}): LogicDoc;
+/** Clear the wire feeding a sink slot. */
+declare function disconnect(doc: LogicDoc, sink: {
+  nodeId: string;
+  slot?: number;
+}): LogicDoc;
+/** Delete a node and clear every reference to it. */
+declare function deleteNode(doc: LogicDoc, id: string): LogicDoc;
+/** Toggle / set a primary input's value. */
+declare function setInputValue(doc: LogicDoc, id: string, value: boolean): LogicDoc;
+declare function toggleInput(doc: LogicDoc, id: string): LogicDoc;
+/** Rename a node's label (any node type). */
+declare function relabel(doc: LogicDoc, id: string, label: string): LogicDoc;
+/** Set / clear an output's goal value (for graded build challenges). */
+declare function setGoal(doc: LogicDoc, outId: string, goal: boolean | undefined): LogicDoc;
+//#endregion
+export { PortRef, addNode, connect, deleteNode, disconnect, moveNode, relabel, setGoal, setInputValue, toggleInput };