@classytic/labs 0.2.0 → 0.3.0

package/dist/algorithms/cost-derivation/core.mjs

@@ -0,0 +1,93 @@
+//#region src/algorithms/cost-derivation/core.ts
+/**
+* Comparisons per pass of a selection-style sort over `n` items: n-1, n-2, ... 1.
+*
+* Drawn as rows, this is a triangle, and the triangle is the argument: two copies of
+* it make an (n-1) by n rectangle, so one copy is n(n-1)/2.
+*/
+function triangleRows(n) {
+	const rows = [];
+	for (let i = n - 1; i >= 1; i--) rows.push(i);
+	return rows;
+}
+/** The closed form for those rows. MUST equal their sum; the test asserts exactly that. */
+const triangleTotal = (n) => n < 2 ? 0 : n * (n - 1) / 2;
+/**
+* The pairing that proves it: first with last, second with second-last. Every pair
+* sums to n, and there are (n-1)/2 of them.
+*/
+function trianglePairs(n) {
+	const rows = triangleRows(n);
+	const out = [];
+	for (let i = 0, j = rows.length - 1; i < j; i++, j--) out.push({
+		a: rows[i],
+		b: rows[j],
+		sum: rows[i] + rows[j]
+	});
+	return out;
+}
+/**
+* The sizes left after each halving: n, n/2, n/4, ... down to 1.
+*
+* The course used to assert "a thousand need at most ten probes" and never show why.
+* The chain IS the why: count its steps, and the count is the logarithm.
+*/
+function halvingChain(n) {
+	const out = [];
+	let size = Math.max(1, Math.floor(n));
+	out.push(size);
+	while (size > 1) {
+		size = Math.floor(size / 2);
+		out.push(size);
+	}
+	return out;
+}
+/** Halvings needed to reach 1: the exact answer the chain shows, as ceil(log2 n). */
+const halvingSteps = (n) => n < 2 ? 0 : Math.ceil(Math.log2(n));
+/**
+* T(n) = 2T(n/2) + n, drawn level by level.
+*
+* The point the picture makes and the formula hides: the work per LEVEL barely
+* changes, because twice as many calls each handle half as much. So the total is
+* "work on one level" times "number of levels", and the number of levels is the
+* halving count above. That is the whole of n log n.
+*/
+function recursionLevels(n) {
+	const out = [];
+	const depth = halvingSteps(n);
+	for (let d = 0; d <= depth; d++) {
+		const calls = 2 ** d;
+		const sizeEach = n / calls;
+		out.push({
+			depth: d,
+			calls,
+			sizeEach,
+			workHere: calls * sizeEach
+		});
+	}
+	return out;
+}
+/** Total comparisons for the merge-sort recurrence: n per level, over log2 n levels. */
+const recursionTotal = (n) => n * halvingSteps(n);
+function readout(mode, n) {
+	switch (mode) {
+		case "nested": return {
+			steps: triangleTotal(n),
+			formula: "n(n − 1) / 2",
+			bigO: "O(n²)"
+		};
+		case "halving": return {
+			steps: halvingSteps(n),
+			formula: "log₂ n",
+			bigO: "O(log n)"
+		};
+		case "recursion": return {
+			steps: recursionTotal(n),
+			formula: "n × log₂ n",
+			bigO: "O(n log n)"
+		};
+	}
+}
+
+//#endregion
+export { halvingChain, halvingSteps, readout, recursionLevels, trianglePairs, triangleRows, triangleTotal };

package/dist/algorithms/cost-derivation/index.d.mts

@@ -0,0 +1,2 @@
+import { CostMode, TreeLevel, halvingChain, halvingSteps, readout, recursionLevels, triangleRows, triangleTotal } from "./core.mjs";
+import { CostDerivationLab, CostDerivationProps } from "./preset.mjs";

package/dist/algorithms/cost-derivation/preset.d.mts

@@ -0,0 +1,19 @@
+import { CostMode } from "./core.mjs";
+import { ReactNode } from "react";
+
+//#region src/algorithms/cost-derivation/preset.d.ts
+interface CostDerivationProps {
+  mode?: CostMode;
+  /** Items. Small by default: the triangle has to be countable before it is trusted. */
+  n?: number;
+  title?: string;
+  prompt?: string;
+}
+declare function CostDerivationLab({
+  mode: startMode,
+  n: startN,
+  title,
+  prompt
+}?: CostDerivationProps): ReactNode;
+//#endregion
+export { CostDerivationLab, CostDerivationProps };

package/dist/algorithms/cost-derivation/preset.mjs

@@ -0,0 +1,371 @@
+'use client';
+
+import { Segmented, Slider } from "../../kit/controls.mjs";
+import { Activity } from "../../kit/activity.mjs";
+import { Field, LiveRegion } from "../../kit/frame.mjs";
+import { ChallengeCard, useChallenge, useCheckpoint } from "../../kit/pedagogy.mjs";
+import { Figure, HUE, STROKE, tint } from "../../kit/figure/figure.mjs";
+import { FigText } from "../../kit/figure/text.mjs";
+import { halvingChain, halvingSteps, readout, recursionLevels, trianglePairs, triangleRows, triangleTotal } from "./core.mjs";
+import { useState } from "react";
+import { Fragment as Fragment$1, jsx, jsxs } from "react/jsx-runtime";
+
+//#region src/algorithms/cost-derivation/preset.tsx
+/**
+* Three derivations, drawn. Where a running time comes FROM.
+*
+* A learner can recognise O(n log n) and still not be able to produce it, and producing
+* it is what the exam asks. Each mode draws the one picture that makes a formula
+* obvious, and the formula is shown beside the picture rather than instead of it:
+*
+*   nested     the triangle of comparisons, paired end to end into n(n-1)/2
+*   halving    the chain down to 1, counted, so 2^k = n and k = log2 n
+*   recursion  the tree, whose every level does the same n work
+*
+* The slider is the argument. Drag n and the picture redraws with the count, so the
+* formula is something a learner watched hold rather than something they were given.
+*/
+const W = 460;
+const H = 200;
+const MODES = [
+	{
+		value: "nested",
+		label: "Two loops"
+	},
+	{
+		value: "halving",
+		label: "Halving"
+	},
+	{
+		value: "recursion",
+		label: "Divide"
+	}
+];
+/**
+* One question per mode. A single shared question asked about halving while the figure
+* drew a triangle, which is exactly the disconnect this lab exists to close.
+*/
+const QUESTIONS = {
+	nested: [{
+		id: "why-n-squared",
+		prompt: "The rows of comparisons are n−1, n−2, down to 1. Why does that add up to about n²/2?",
+		choices: [
+			{
+				value: "pair",
+				label: "Pairing the ends gives n each time, and there are about n/2 pairs"
+			},
+			{
+				value: "longest",
+				label: "Because the longest row has n−1 in it"
+			},
+			{
+				value: "rows",
+				label: "Because there are n rows"
+			},
+			{
+				value: "double",
+				label: "Because each item is compared twice"
+			}
+		],
+		answer: "pair",
+		explain: "First row plus last is (n−1) + 1 = n. Second plus second-last is (n−2) + 2 = n. About n/2 pairs, each worth n, so n²/2. The exact total is n(n−1)/2, and the /2 is dropped at the end."
+	}],
+	halving: [{
+		id: "where-log-comes-from",
+		prompt: "Halving 1000 items down to 1 takes about ten steps. Where does the ten come from?",
+		choices: [
+			{
+				value: "log",
+				label: "1000 is about 2^10, so ten halvings undo it"
+			},
+			{
+				value: "root",
+				label: "It is roughly the square root of 1000"
+			},
+			{
+				value: "tenth",
+				label: "Each step removes a tenth of the data"
+			},
+			{
+				value: "guess",
+				label: "It is measured, not calculated"
+			}
+		],
+		answer: "log",
+		explain: "Each halving divides by 2, so after k steps you have n / 2^k left. Reaching 1 means 2^k = n, and k = log₂ n. For 1000 that is just under 10, because 2^10 = 1024."
+	}],
+	recursion: [{
+		id: "why-n-log-n",
+		prompt: "Going down the tree, the calls double while each handles half as much. What does that do to the work on each level?",
+		choices: [
+			{
+				value: "same",
+				label: "It stays about the same, roughly n on every level"
+			},
+			{
+				value: "doubles",
+				label: "It doubles, because the calls double"
+			},
+			{
+				value: "halves",
+				label: "It halves, because the pieces halve"
+			},
+			{
+				value: "grows",
+				label: "It grows as n², because both change at once"
+			}
+		],
+		answer: "same",
+		explain: "Twice as many calls, each doing half as much, multiply back to the same n. So the total is n per level times the number of levels, and the number of levels is the halving count log₂ n. That is n log n."
+	}]
+};
+function CostDerivationLab({ mode: startMode = "nested", n: startN = 8, title, prompt } = {}) {
+	const [mode, setMode] = useState(startMode);
+	const [n, setN] = useState(Math.max(2, Math.min(64, startN)));
+	const questions = QUESTIONS[mode];
+	const challenge = useChallenge(questions);
+	useCheckpoint({
+		solved: challenge.allCorrect,
+		activity: "cost-derivation"
+	});
+	const read = readout(mode, n);
+	const figure = /* @__PURE__ */ jsxs(Figure, {
+		viewBox: [W, H],
+		domain: "math",
+		label: `${mode} cost derivation for ${n} items`,
+		children: [
+			mode === "nested" && /* @__PURE__ */ jsx(Triangle, { n }),
+			mode === "halving" && /* @__PURE__ */ jsx(Halving, { n }),
+			mode === "recursion" && /* @__PURE__ */ jsx(Tree, { n })
+		]
+	});
+	return /* @__PURE__ */ jsxs(Activity.Root, {
+		className: "algorithms-cost-derivation",
+		children: [
+			/* @__PURE__ */ jsxs(Activity.Header, { children: [/* @__PURE__ */ jsx(Activity.Heading, {
+				eyebrow: "Where the cost comes from",
+				title: title ?? "Deriving a running time",
+				description: prompt ?? "Count the picture, then read the formula it forces. Drag n and watch both move together."
+			}), /* @__PURE__ */ jsx(Activity.FocusButton, {})] }),
+			/* @__PURE__ */ jsxs(Activity.Workspace, { children: [/* @__PURE__ */ jsx(Activity.Canvas, {
+				label: "Cost derivation",
+				children: figure
+			}), /* @__PURE__ */ jsxs(Activity.Dock, { children: [/* @__PURE__ */ jsx(Field, {
+				label: "method",
+				children: /* @__PURE__ */ jsx(Segmented, {
+					value: mode,
+					options: MODES,
+					onChange: (v) => setMode(v),
+					ariaLabel: "which derivation"
+				})
+			}), /* @__PURE__ */ jsx(Field, {
+				label: "items",
+				value: String(n),
+				children: /* @__PURE__ */ jsx(Slider, {
+					value: n,
+					min: 2,
+					max: 64,
+					step: 1,
+					onChange: setN,
+					ariaLabel: "number of items",
+					valueText: `${n} items`
+				})
+			})] })] }),
+			/* @__PURE__ */ jsx(ChallengeCard, {
+				questions,
+				state: challenge
+			}),
+			/* @__PURE__ */ jsxs(Activity.Feedback, { children: [/* @__PURE__ */ jsx("span", { children: "What to notice" }), /* @__PURE__ */ jsx("div", { children: "Every one of these drops its constants at the end. Half of n² is still n², because doubling the data still quadruples the work, and that is the only thing the growth class promises." })] }),
+			/* @__PURE__ */ jsx(LiveRegion, { children: `${read.steps} steps for ${n} items, which is ${read.formula}, or ${read.bigO}.` })
+		]
+	});
+}
+function Triangle({ n }) {
+	const rows = triangleRows(n);
+	const maxRows = rows.length;
+	const cell = Math.max(3, Math.min(12, 150 / Math.max(maxRows, 1)));
+	const x0 = 26;
+	const y0 = 30;
+	const firstPair = trianglePairs(n)[0];
+	return /* @__PURE__ */ jsxs(Fragment$1, { children: [
+		/* @__PURE__ */ jsx(FigText, {
+			x: x0,
+			y: 18,
+			size: "label",
+			tone: "soft",
+			anchor: "start",
+			children: "one dot per comparison"
+		}),
+		rows.map((len, r) => /* @__PURE__ */ jsx("g", { children: Array.from({ length: len }, (_, c) => /* @__PURE__ */ jsx("circle", {
+			cx: x0 + c * cell + cell / 2,
+			cy: y0 + r * cell + cell / 2,
+			r: Math.max(1.2, cell * .28),
+			fill: r === 0 || r === maxRows - 1 ? HUE[2] : tint(HUE[1], 55)
+		}, c)) }, r)),
+		firstPair && maxRows > 1 && /* @__PURE__ */ jsx(FigText, {
+			x: 186,
+			y: 44,
+			size: "label",
+			anchor: "start",
+			children: `${firstPair.a} + ${firstPair.b} = ${firstPair.sum}`
+		}),
+		/* @__PURE__ */ jsx(FigText, {
+			x: 186,
+			y: 68,
+			size: "label",
+			tone: "soft",
+			anchor: "start",
+			children: "every pair of rows sums to n"
+		}),
+		/* @__PURE__ */ jsx(FigText, {
+			x: 186,
+			y: 104,
+			size: "measure",
+			anchor: "start",
+			children: triangleTotal(n).toLocaleString()
+		}),
+		/* @__PURE__ */ jsx(FigText, {
+			x: 186,
+			y: 128,
+			size: "label",
+			tone: "soft",
+			anchor: "start",
+			children: "= n(n − 1) / 2"
+		}),
+		/* @__PURE__ */ jsx(FigText, {
+			x: 186,
+			y: 156,
+			size: "label",
+			tone: "hue-2",
+			anchor: "start",
+			children: "grows like n²"
+		})
+	] });
+}
+function Halving({ n }) {
+	const chain = halvingChain(n);
+	const k = halvingSteps(n);
+	const unit = 300 / Math.max(chain[0] ?? 1, 1);
+	const rowH = Math.max(10, Math.min(22, 170 / chain.length));
+	return /* @__PURE__ */ jsxs(Fragment$1, { children: [
+		/* @__PURE__ */ jsx(FigText, {
+			x: 26,
+			y: 18,
+			size: "label",
+			tone: "soft",
+			anchor: "start",
+			children: "what is left after each halving"
+		}),
+		chain.map((size, i) => /* @__PURE__ */ jsxs("g", { children: [/* @__PURE__ */ jsx("rect", {
+			x: 26,
+			y: 28 + i * rowH,
+			width: Math.max(2, size * unit),
+			height: rowH - 4,
+			rx: 2,
+			fill: i === chain.length - 1 ? HUE[2] : tint(HUE[1], 60 - i * 4)
+		}), /* @__PURE__ */ jsx(FigText, {
+			x: 20,
+			y: 28 + i * rowH + rowH / 2 + 3,
+			size: "label",
+			tone: "soft",
+			anchor: "end",
+			children: String(size)
+		})] }, i)),
+		/* @__PURE__ */ jsx(FigText, {
+			x: 346,
+			y: 54,
+			size: "label",
+			anchor: "start",
+			children: `n / 2^k = 1`
+		}),
+		/* @__PURE__ */ jsx(FigText, {
+			x: 346,
+			y: 76,
+			size: "label",
+			anchor: "start",
+			children: `2^k = ${n}`
+		}),
+		/* @__PURE__ */ jsx(FigText, {
+			x: 346,
+			y: 108,
+			size: "measure",
+			anchor: "start",
+			children: String(k)
+		}),
+		/* @__PURE__ */ jsx(FigText, {
+			x: 346,
+			y: 130,
+			size: "label",
+			tone: "soft",
+			anchor: "start",
+			children: `k = log₂ n`
+		}),
+		/* @__PURE__ */ jsx(FigText, {
+			x: 346,
+			y: 156,
+			size: "label",
+			tone: "hue-2",
+			anchor: "start",
+			children: "grows like log n"
+		})
+	] });
+}
+function Tree({ n }) {
+	const levels = recursionLevels(n);
+	const rowH = Math.max(9, Math.min(24, (H - 34 - 46) / levels.length));
+	return /* @__PURE__ */ jsxs(Fragment$1, { children: [
+		/* @__PURE__ */ jsx(FigText, {
+			x: 26,
+			y: 18,
+			size: "label",
+			tone: "soft",
+			anchor: "start",
+			children: "twice the calls, each half the size"
+		}),
+		levels.map((lv) => {
+			const boxes = Math.min(lv.calls, 16);
+			const w = 260 / boxes;
+			return /* @__PURE__ */ jsxs("g", { children: [Array.from({ length: boxes }, (_, i) => /* @__PURE__ */ jsx("rect", {
+				x: 26 + i * w + 1,
+				y: 28 + lv.depth * rowH,
+				width: Math.max(1.5, w - 2),
+				height: rowH - 5,
+				rx: 2,
+				fill: tint(HUE[1], 30 + lv.depth * 8)
+			}, i)), /* @__PURE__ */ jsx(FigText, {
+				x: 296,
+				y: 28 + lv.depth * rowH + rowH / 2 + 2,
+				size: "label",
+				tone: "soft",
+				anchor: "start",
+				children: `${lv.calls} × ${Math.round(lv.sizeEach)} = ${Math.round(lv.workHere)}`
+			})] }, lv.depth);
+		}),
+		/* @__PURE__ */ jsx("line", {
+			x1: 288,
+			y1: 26,
+			x2: 288,
+			y2: 28 + levels.length * rowH,
+			stroke: HUE.soft,
+			strokeWidth: STROKE.hair
+		}),
+		/* @__PURE__ */ jsx(FigText, {
+			x: 26,
+			y: 28 + levels.length * rowH + 18,
+			size: "label",
+			anchor: "start",
+			children: `${levels.length - 1} levels, about ${n} work on each`
+		}),
+		/* @__PURE__ */ jsx(FigText, {
+			x: 26,
+			y: 28 + levels.length * rowH + 38,
+			size: "label",
+			tone: "hue-2",
+			anchor: "start",
+			children: "n × log₂ n"
+		})
+	] });
+}
+
+//#endregion
+export { CostDerivationLab };

package/dist/algorithms/dp/index.d.mts

@@ -0,0 +1,3 @@
+import { DPCellEvent, DPTrace } from "../contract.mjs";
+import { gridPaths } from "../dp.mjs";
+export { type DPCellEvent, type DPTrace, gridPaths };

package/dist/algorithms/dp/index.mjs

@@ -0,0 +1,3 @@
+import { gridPaths } from "../dp.mjs";
+
+export { gridPaths };

package/dist/algorithms/dp.d.mts

@@ -0,0 +1,7 @@
+import { DPTrace } from "./contract.mjs";
+
+//#region src/algorithms/dp.d.ts
+/** Count monotone paths through a rows×cols grid, moving only right or down. */
+declare function gridPaths(rows: number, cols: number): DPTrace;
+//#endregion
+export { gridPaths };

package/dist/algorithms/dp.mjs

@@ -0,0 +1,32 @@
+//#region src/algorithms/dp.ts
+/** Count monotone paths through a rows×cols grid, moving only right or down. */
+function gridPaths(rows, cols) {
+	const r = Math.max(1, Math.floor(rows));
+	const c = Math.max(1, Math.floor(cols));
+	const table = Array.from({ length: r }, () => Array(c).fill(0));
+	const events = [];
+	for (let row = 0; row < r; row++) for (let col = 0; col < c; col++) {
+		const dependencies = [];
+		if (row > 0) dependencies.push([row - 1, col]);
+		if (col > 0) dependencies.push([row, col - 1]);
+		const value = row === 0 && col === 0 ? 1 : dependencies.reduce((sum, [dr, dc]) => sum + table[dr][dc], 0);
+		table[row][col] = value;
+		events.push({
+			type: "set-cell",
+			row,
+			col,
+			value,
+			dependencies,
+			message: dependencies.length ? `Cell (${row + 1}, ${col + 1}) = ${dependencies.map(([dr, dc]) => table[dr][dc]).join(" + ")} = ${value}.` : "The starting cell has one path."
+		});
+	}
+	return {
+		rows: r,
+		cols: c,
+		table,
+		events
+	};
+}
+
+//#endregion
+export { gridPaths };

package/dist/algorithms/graph/index.d.mts

@@ -0,0 +1,5 @@
+import { AlgorithmEdge, AlgorithmEvent, AlgorithmGraph, AlgorithmNode, AlgorithmTrace, DPCellEvent, DPTrace } from "../contract.mjs";
+import { bfs, dfs, dijkstra, reconstructPath } from "../graph.mjs";
+import { normalizeGraph } from "../normalize.mjs";
+import { teachingGraph } from "../presets.mjs";
+export { AlgorithmEdge, AlgorithmEvent, AlgorithmGraph, AlgorithmNode, AlgorithmTrace, DPCellEvent, DPTrace, bfs, dfs, dijkstra, normalizeGraph, reconstructPath, teachingGraph };

package/dist/algorithms/graph/index.mjs

@@ -0,0 +1,5 @@
+import { bfs, dfs, dijkstra, reconstructPath } from "../graph.mjs";
+import { teachingGraph } from "../presets.mjs";
+import { normalizeGraph } from "../normalize.mjs";
+
+export { bfs, dfs, dijkstra, normalizeGraph, reconstructPath, teachingGraph };

package/dist/algorithms/graph.d.mts

@@ -0,0 +1,9 @@
+import { AlgorithmGraph, AlgorithmTrace } from "./contract.mjs";
+
+//#region src/algorithms/graph.d.ts
+declare function reconstructPath(previous: Record<string, string | undefined>, source: string, target: string): string[];
+declare const bfs: (graph: AlgorithmGraph, source: string) => AlgorithmTrace;
+declare const dfs: (graph: AlgorithmGraph, source: string) => AlgorithmTrace;
+declare function dijkstra(graph: AlgorithmGraph, source: string, target?: string): AlgorithmTrace;
+//#endregion
+export { bfs, dfs, dijkstra, reconstructPath };