@classytic/labs 0.1.0 → 0.3.0

package/dist/logic/timing.mjs

@@ -0,0 +1,147 @@
+import { sequenceTable } from "./sequential.mjs";
+
+//#region src/logic/timing.ts
+/**
+* Timing diagrams: one D waveform, one clock, and the two circuits that read them differently.
+*
+* "Draw Q for a D latch and for a positive-edge-triggered D flip-flop" is the most reliable exam
+* question in a first digital logic course, and it is reliably answered wrong, because the two
+* circuits share a letter and a symbol and differ only in WHEN they look at D. A latch looks the
+* whole time the clock is high. A flip-flop looks for one instant, at the rising edge.
+*
+* So everything here is built to make that difference land on specific slots. Both circuits run
+* through the same sequential engine, so there is one definition of time rather than two that
+* might drift apart, and `disagreement` reports exactly the slots where their Q differs. Those
+* slots are the exam answer, and the lab shades them.
+*
+* `setupViolations` is the honest footnote. The engine samples D at the edge slot itself, which
+* is a modelling choice. When D changes at that very instant, real hardware is not guaranteed to
+* capture either value, so those edges are reported rather than silently resolved.
+*/
+/** A clock that is low for `period / 2` slots, then high for `period / 2`, starting low. */
+function clockWave(length, period = 4) {
+	const half = Math.max(1, Math.floor(period / 2));
+	return Array.from({ length }, (_, t) => Math.floor(t / half) % 2 === 1);
+}
+const risingEdges = (clock) => clock.flatMap((level, t) => level && !(clock[t - 1] ?? false) ? [t] : []);
+const LATCH_DOC = {
+	inputs: [{
+		id: "d",
+		label: "D",
+		value: false
+	}, {
+		id: "clock",
+		label: "Clock",
+		value: false
+	}],
+	gates: [],
+	cells: [{
+		id: "q",
+		kind: "d-latch",
+		d: "d",
+		enable: "clock"
+	}],
+	outputs: []
+};
+const FLIP_FLOP_DOC = {
+	inputs: [{
+		id: "d",
+		label: "D",
+		value: false
+	}, {
+		id: "clock",
+		label: "Clock",
+		value: false
+	}],
+	gates: [],
+	cells: [{
+		id: "q",
+		kind: "d-flip-flop",
+		d: "d",
+		clock: "clock"
+	}],
+	outputs: []
+};
+function run(doc, clock, d) {
+	return sequenceTable(doc, clock.map((level, t) => ({
+		clock: level,
+		d: d[t] ?? false
+	}))).map((entry) => entry.state.bits.q?.[0] ?? false);
+}
+/** Transparent while the clock is high: Q follows D, including any glitch inside that window. */
+const dLatch = (clock, d) => run(LATCH_DOC, clock, d);
+/** Samples D at each rising edge and holds it until the next one, whatever D does in between. */
+const dFlipFlop = (clock, d) => run(FLIP_FLOP_DOC, clock, d);
+const JK_DOC = {
+	inputs: [
+		{
+			id: "j",
+			label: "J",
+			value: false
+		},
+		{
+			id: "k",
+			label: "K",
+			value: false
+		},
+		{
+			id: "clock",
+			label: "Clock",
+			value: false
+		}
+	],
+	gates: [],
+	cells: [{
+		id: "q",
+		kind: "jk-flip-flop",
+		j: "j",
+		k: "k",
+		clock: "clock"
+	}],
+	outputs: []
+};
+/** A positive-edge JK flip-flop on the engine. With K tied to J it is a T flip-flop. */
+function jkFlipFlop(clock, j, k) {
+	return sequenceTable(JK_DOC, clock.map((level, t) => ({
+		clock: level,
+		j: j[t] ?? false,
+		k: k[t] ?? false
+	}))).map((entry) => entry.state.bits.q?.[0] ?? false);
+}
+/** What the flip-flop did at each rising edge, read from the levels there: the characteristic table. */
+const jkActions = (clock, j, k) => risingEdges(clock).map((t) => {
+	const jj = j[t] ?? false;
+	const kk = k[t] ?? false;
+	return {
+		t,
+		action: jj && kk ? "toggle" : jj ? "set" : kk ? "reset" : "hold"
+	};
+});
+/** Slots where the two circuits' Q differ. These are the exam answer. */
+const disagreement = (latch, flipFlop) => latch.flatMap((level, t) => level !== flipFlop[t] ? [t] : []);
+/** Rising edges at which D changed at the same instant, so real hardware could capture either. */
+const setupViolations = (clock, d) => risingEdges(clock).filter((t) => t > 0 && d[t] !== d[t - 1]);
+/** A wave that is high over each inclusive `[from, to]` range and low elsewhere. */
+const waveFrom = (length, ranges) => Array.from({ length }, (_, t) => ranges.some(([from, to]) => t >= from && t <= to));
+/**
+* The default waveform is chosen, not random. With a period-8 clock the rising edges fall at 4, 12
+* and 20, and each high stretch of D is placed to carry exactly one idea:
+*
+* - 2 to 9: D rises BEFORE the edge at 4 and is still high at it, so both circuits capture a 1 and
+*   agree. It falls at 10 while the clock is low, which neither circuit notices.
+* - 13 to 14: a pulse entirely inside the high window 12 to 15, touching no edge. The latch is
+*   transparent and passes it straight through; the flip-flop never looks. This is the one that
+*   separates students who understand edge triggering from those who memorised the symbol.
+* - 18 to 21: captured by both at the edge at 20, then D falls at 22 while the clock is still
+*   high. The latch follows it back down; the flip-flop holds its 1.
+*/
+const DEFAULT_LENGTH = 24;
+const DEFAULT_PERIOD = 8;
+const DEFAULT_D = waveFrom(24, [
+	[2, 9],
+	[13, 14],
+	[18, 21]
+]);
+
+//#endregion
+export { DEFAULT_D, DEFAULT_LENGTH, DEFAULT_PERIOD, clockWave, dFlipFlop, dLatch, disagreement, jkActions, jkFlipFlop, risingEdges, setupViolations, waveFrom };

package/dist/logic/twos.d.mts

@@ -0,0 +1,65 @@
+declare namespace twos_d_exports {
+  export { Negation, Pattern, RANGE, Sum, WIDTH, add, bitsOf, crossesOverflowLine, fromSigned, inRange, negate, subtract, toSigned };
+}
+/**
+ * Two's complement on four bits: negative numbers without a minus sign.
+ *
+ * Put the sixteen 4-bit patterns round a circle, like the hours on a clock. Adding is walking
+ * clockwise, and the circle wraps, because a 4-bit adder simply drops the fifth bit. Two's
+ * complement is nothing more than a choice of how to NAME the patterns: the half from 1000 to 1111
+ * is read as −8 to −1 instead of 8 to 15, so that walking clockwise past 1111 into 0000 is just
+ * −1 + 1 = 0. The adder never changes. That is the whole reason every processor uses it.
+ *
+ * Three facts fall out, and each is pinned by a test:
+ *
+ * - Inverting a pattern and adding it to itself always gives 1111, which is −1. So −x is the
+ *   inverse plus one. That is the rule students memorise, derived in one line.
+ * - Subtraction is addition of the negation, on the SAME adder.
+ * - The range is −8 to 7, not −7 to 7, because zero sits in the non-negative half. −8 is the one
+ *   pattern with no positive partner: negating it gives it back, which is an overflow.
+ *
+ * Overflow is reported the way hardware detects it, carry into the top bit disagreeing with carry
+ * out of it, and checked against the arithmetic answer for every pair.
+ */
+declare const WIDTH = 4;
+/** The pattern read as an unsigned number, 0 to 15. */
+type Pattern = number;
+declare const toSigned: (pattern: Pattern) => number;
+declare const fromSigned: (value: number) => Pattern;
+declare const bitsOf: (pattern: Pattern) => string;
+declare const inRange: (value: number) => boolean;
+declare const RANGE: {
+  min: number;
+  max: number;
+};
+interface Negation {
+  inverted: Pattern;
+  result: Pattern;
+  /** Negating −8 gives −8 back: there is no +8 to give. */
+  overflow: boolean;
+}
+declare function negate(pattern: Pattern): Negation;
+interface Sum {
+  a: Pattern;
+  b: Pattern;
+  result: Pattern;
+  /** The carry out of the top bit, which a 4-bit adder drops. */
+  carryOut: boolean;
+  carryIntoTop: boolean;
+  /** Carry into the top bit differs from carry out: the signed answer does not fit. */
+  overflow: boolean;
+}
+/** A 4-bit ripple adder, bit by bit, so the carries are real rather than inferred. */
+declare function add(a: Pattern, b: Pattern): Sum;
+/**
+ * Does walking from `a` by the SIGNED value of `b` (forward if positive, back if negative) cross the
+ * line between 7 and −8? That is the rule the wheel draws, and it must agree with the adder's
+ * overflow flag for every pair, or the picture is teaching something the hardware does not do.
+ */
+declare function crossesOverflowLine(a: Pattern, b: Pattern): boolean;
+/** a − b on the same adder: add the negation of b. */
+declare function subtract(a: Pattern, b: Pattern): Sum & {
+  negated: Negation;
+};
+//#endregion
+export { Pattern, twos_d_exports };

package/dist/logic/twos.mjs

@@ -0,0 +1,95 @@
+import { __exportAll } from "../_virtual/_rolldown/runtime.mjs";
+
+//#region src/logic/twos.ts
+var twos_exports = /* @__PURE__ */ __exportAll({
+	RANGE: () => RANGE,
+	WIDTH: () => 4,
+	add: () => add,
+	bitsOf: () => bitsOf,
+	crossesOverflowLine: () => crossesOverflowLine,
+	fromSigned: () => fromSigned,
+	inRange: () => inRange,
+	negate: () => negate,
+	subtract: () => subtract,
+	toSigned: () => toSigned
+});
+/**
+* Two's complement on four bits: negative numbers without a minus sign.
+*
+* Put the sixteen 4-bit patterns round a circle, like the hours on a clock. Adding is walking
+* clockwise, and the circle wraps, because a 4-bit adder simply drops the fifth bit. Two's
+* complement is nothing more than a choice of how to NAME the patterns: the half from 1000 to 1111
+* is read as −8 to −1 instead of 8 to 15, so that walking clockwise past 1111 into 0000 is just
+* −1 + 1 = 0. The adder never changes. That is the whole reason every processor uses it.
+*
+* Three facts fall out, and each is pinned by a test:
+*
+* - Inverting a pattern and adding it to itself always gives 1111, which is −1. So −x is the
+*   inverse plus one. That is the rule students memorise, derived in one line.
+* - Subtraction is addition of the negation, on the SAME adder.
+* - The range is −8 to 7, not −7 to 7, because zero sits in the non-negative half. −8 is the one
+*   pattern with no positive partner: negating it gives it back, which is an overflow.
+*
+* Overflow is reported the way hardware detects it, carry into the top bit disagreeing with carry
+* out of it, and checked against the arithmetic answer for every pair.
+*/
+const WIDTH = 4;
+const MOD = 2 ** 4;
+const MIN = -8;
+const MAX = 2 ** (4 - 1) - 1;
+const toSigned = (pattern) => pattern >= MOD / 2 ? pattern - MOD : pattern;
+const fromSigned = (value) => (value % MOD + MOD) % MOD;
+const bitsOf = (pattern) => pattern.toString(2).padStart(4, "0");
+const inRange = (value) => value >= MIN && value <= MAX;
+const RANGE = {
+	min: MIN,
+	max: MAX
+};
+function negate(pattern) {
+	const inverted = ~pattern & MOD - 1;
+	return {
+		inverted,
+		result: (inverted + 1) % MOD,
+		overflow: toSigned(pattern) === MIN
+	};
+}
+/** A 4-bit ripple adder, bit by bit, so the carries are real rather than inferred. */
+function add(a, b) {
+	let carry = 0;
+	let result = 0;
+	let carryIntoTop = false;
+	for (let bit = 0; bit < 4; bit++) {
+		if (bit === 4 - 1) carryIntoTop = carry === 1;
+		const total = (a >> bit & 1) + (b >> bit & 1) + carry;
+		result |= (total & 1) << bit;
+		carry = total >> 1;
+	}
+	const carryOut = carry === 1;
+	return {
+		a,
+		b,
+		result,
+		carryOut,
+		carryIntoTop,
+		overflow: carryIntoTop !== carryOut
+	};
+}
+/**
+* Does walking from `a` by the SIGNED value of `b` (forward if positive, back if negative) cross the
+* line between 7 and −8? That is the rule the wheel draws, and it must agree with the adder's
+* overflow flag for every pair, or the picture is teaching something the hardware does not do.
+*/
+function crossesOverflowLine(a, b) {
+	return !inRange(toSigned(a) + toSigned(b));
+}
+/** a − b on the same adder: add the negation of b. */
+function subtract(a, b) {
+	const negated = negate(b);
+	return {
+		...add(a, negated.result),
+		negated
+	};
+}
+
+//#endregion
+export { add, bitsOf, fromSigned, negate, subtract, toSigned, twos_exports };

package/dist/math/activity.mjs

@@ -0,0 +1,90 @@
+import { IconButton } from "../kit/controls.mjs";
+import { Activity, RunTransport } from "../kit/activity.mjs";
+import { ControlPolicy } from "../kit/frame.mjs";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+import { RotateCcw } from "lucide-react";
+
+//#region src/math/activity.tsx
+function MathExpressionError({ title, expression, error }) {
+	return /* @__PURE__ */ jsxs("div", {
+		className: "not-prose math-expression-error",
+		role: "alert",
+		children: [/* @__PURE__ */ jsx("strong", { children: title }), /* @__PURE__ */ jsxs("p", { children: [expression ? /* @__PURE__ */ jsxs(Fragment, { children: [
+			"“",
+			expression,
+			"”, "
+		] }) : null, error] })]
+	});
+}
+/** Canvas-first composition for graphs, constructions, and symbolic experiments. */
+function MathActivity({ className, eyebrow = "Mathematics", title, description, status, figure, measurements, controls, conclusion, transport, details, graphLabel, inspectorLabel = "Values and controls", controlConfig, focusLayout = "standard" }) {
+	return /* @__PURE__ */ jsx(ControlPolicy, {
+		config: controlConfig,
+		children: /* @__PURE__ */ jsxs(Activity.Root, {
+			className: `math-activity ${className}`,
+			focusLayout,
+			children: [
+				/* @__PURE__ */ jsxs(Activity.Header, { children: [/* @__PURE__ */ jsx(Activity.Heading, {
+					eyebrow,
+					title,
+					description
+				}), /* @__PURE__ */ jsx(Activity.FocusButton, {})] }),
+				/* @__PURE__ */ jsx(Activity.Status, { children: status }),
+				/* @__PURE__ */ jsxs(Activity.Workspace, { children: [/* @__PURE__ */ jsx(Activity.Canvas, {
+					label: graphLabel,
+					children: /* @__PURE__ */ jsx("div", {
+						className: "math-scene",
+						children: figure
+					})
+				}), /* @__PURE__ */ jsx(Activity.Inspector, {
+					label: inspectorLabel,
+					children: /* @__PURE__ */ jsxs("div", {
+						className: "lab-activity-inspector-section",
+						children: [/* @__PURE__ */ jsx("div", {
+							className: "math-measurements",
+							children: measurements
+						}), controls ? /* @__PURE__ */ jsx("div", {
+							className: "lab-activity-fields math-controls",
+							children: controls
+						}) : null]
+					})
+				})] }),
+				/* @__PURE__ */ jsxs(Activity.Feedback, { children: [/* @__PURE__ */ jsx("span", { children: "Conclusion" }), /* @__PURE__ */ jsx("p", { children: conclusion })] }),
+				/* @__PURE__ */ jsx(Activity.Transport, { children: transport }),
+				details ? /* @__PURE__ */ jsx(Activity.Transcript, {
+					label: "Calculation details",
+					children: details
+				}) : null
+			]
+		})
+	});
+}
+function MathResetTransport({ onReset, state, detail }) {
+	return /* @__PURE__ */ jsxs(Fragment, { children: [/* @__PURE__ */ jsx(IconButton, {
+		label: "Reset experiment",
+		onClick: onReset,
+		children: /* @__PURE__ */ jsx(RotateCcw, { "aria-hidden": "true" })
+	}), /* @__PURE__ */ jsxs("div", {
+		className: "lab-transport-state",
+		"aria-live": "polite",
+		children: [/* @__PURE__ */ jsx("strong", { children: state }), detail ? /* @__PURE__ */ jsx("span", { children: detail }) : null]
+	})] });
+}
+/** Shared numerical-method transport: reset, single-step, live state, and run/pause. */
+function MathRunTransport({ running, onReset, onStep, onToggle, state, detail, disabled, resetLabel = "Reset", stepLabel = "Take one step", runLabel = "Run" }) {
+	return /* @__PURE__ */ jsx(RunTransport, {
+		running,
+		onReset,
+		onStep,
+		onToggle,
+		state,
+		detail,
+		disabled,
+		resetLabel,
+		stepLabel,
+		runLabel
+	});
+}
+
+//#endregion
+export { MathActivity, MathExpressionError, MathResetTransport, MathRunTransport };

package/dist/math/area-model/asset.mjs

@@ -133,17 +133,26 @@ function resolver({ params, bound }) {
 		}
 	};
 }
-const FILL = {
-	x2: "url(#stage-grad-weight)",
-	xterm: "url(#stage-grad-weight-2)",
-	const: "url(#stage-grad-metal)"
+const ROLE_STYLE = {
+	x2: {
+		fill: "color-mix(in oklab, var(--stage-accent) 15%, var(--stage-bg))",
+		stroke: "color-mix(in oklab, var(--stage-accent) 42%, var(--stage-bg))"
+	},
+	xterm: {
+		fill: "color-mix(in oklab, var(--stage-accent-2) 20%, var(--stage-bg))",
+		stroke: "color-mix(in oklab, var(--stage-accent-2) 46%, var(--stage-bg))"
+	},
+	const: {
+		fill: "color-mix(in oklab, var(--stage-muted) 14%, var(--stage-bg))",
+		stroke: "color-mix(in oklab, var(--stage-muted) 38%, var(--stage-bg))"
+	}
 };
 function Component({ geom }) {
 	const c = useCoords();
 	const p = geom.parts;
 	const m = geom.meta ?? {};
 	const P = (v) => c.toPx(v.x, v.y);
-	const good = m.solved ? "var(--stage-good)" : "var(--stage-metal)";
+	const good = m.solved ? "var(--stage-good)" : "color-mix(in oklab, var(--stage-fg) 26%, transparent)";
 	const renderRegion = (r, i) => {
 		const [lx, ty] = P({
 			x: r.x0,
@@ -156,16 +165,18 @@ function Component({ geom }) {
 		const wpx = Math.abs(rx - lx);
 		const hpx = Math.abs(by - ty);
 		const fs = Math.max(11, Math.min(22, Math.min(wpx, hpx) * .4));
+		const st = ROLE_STYLE[r.role];
 		return /* @__PURE__ */ jsxs("g", { children: [/* @__PURE__ */ jsx("rect", {
 			x: lx,
 			y: ty,
 			width: wpx,
 			height: hpx,
-			rx: Math.min(6, Math.min(wpx, hpx) * .12),
-			fill: FILL[r.role],
-			stroke: "color-mix(in oklab, var(--stage-sheen) 32%, transparent)",
-			strokeWidth: 1
+			rx: Math.min(8, Math.min(wpx, hpx) * .14),
+			fill: st.fill,
+			stroke: st.stroke,
+			strokeWidth: 1.5
 		}), /* @__PURE__ */ jsx("text", {
+			className: "math-svg-passive",
 			x: lx + wpx / 2,
 			y: ty + hpx / 2,
 			fill: "var(--stage-fg)",
@@ -173,7 +184,6 @@ function Component({ geom }) {
 			fontWeight: 700,
 			textAnchor: "middle",
 			dominantBaseline: "central",
-			style: { pointerEvents: "none" },
 			children: r.label
 		})] }, `r${i}`);
 	};
@@ -199,7 +209,7 @@ function Component({ geom }) {
 				y1,
 				x2,
 				y2,
-				stroke: "color-mix(in oklab, var(--stage-sheen) 16%, transparent)",
+				stroke: "color-mix(in oklab, var(--stage-fg) 9%, transparent)",
 				strokeWidth: 1
 			}, `g${i}`);
 		}),
@@ -213,7 +223,7 @@ function Component({ geom }) {
 				y1,
 				x2,
 				y2,
-				stroke: "color-mix(in oklab, var(--stage-sheen) 50%, transparent)",
+				stroke: "color-mix(in oklab, var(--stage-fg) 20%, transparent)",
 				strokeWidth: 1.5
 			}, key);
 		}),
@@ -222,10 +232,10 @@ function Component({ geom }) {
 			y: Math.min(oy0, oy2),
 			width: Math.abs(ox2 - ox0),
 			height: Math.abs(oy2 - oy0),
-			rx: 4,
+			rx: 6,
 			fill: "none",
 			stroke: good,
-			strokeWidth: 3
+			strokeWidth: 2
 		}),
 		m.solved && /* @__PURE__ */ jsx("rect", {
 			x: Math.min(ox0, ox2),