@classytic/labs 0.2.0 → 0.3.0

package/dist/algorithms/presets.mjs

@@ -0,0 +1,94 @@
+//#region src/algorithms/presets.ts
+const teachingGraph = {
+	nodes: [
+		{
+			id: "A",
+			label: "A",
+			x: 12,
+			y: 50
+		},
+		{
+			id: "B",
+			label: "B",
+			x: 31,
+			y: 22
+		},
+		{
+			id: "C",
+			label: "C",
+			x: 31,
+			y: 78
+		},
+		{
+			id: "D",
+			label: "D",
+			x: 55,
+			y: 18
+		},
+		{
+			id: "E",
+			label: "E",
+			x: 57,
+			y: 72
+		},
+		{
+			id: "F",
+			label: "F",
+			x: 84,
+			y: 48
+		}
+	],
+	edges: [
+		{
+			id: "ab",
+			from: "A",
+			to: "B",
+			weight: 4
+		},
+		{
+			id: "ac",
+			from: "A",
+			to: "C",
+			weight: 2
+		},
+		{
+			id: "bd",
+			from: "B",
+			to: "D",
+			weight: 5
+		},
+		{
+			id: "be",
+			from: "B",
+			to: "E",
+			weight: 2
+		},
+		{
+			id: "ce",
+			from: "C",
+			to: "E",
+			weight: 3
+		},
+		{
+			id: "de",
+			from: "D",
+			to: "E",
+			weight: 1
+		},
+		{
+			id: "df",
+			from: "D",
+			to: "F",
+			weight: 3
+		},
+		{
+			id: "ef",
+			from: "E",
+			to: "F",
+			weight: 6
+		}
+	]
+};
+
+//#endregion
+export { teachingGraph };

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

@@ -0,0 +1,9 @@
+import { GraphView, GraphViewProps } from "../GraphView.mjs";
+import { GraphAlgorithmLab, GraphAlgorithmLabProps } from "../GraphAlgorithmLab.mjs";
+import { GridPathLab, GridPathLabProps } from "../GridPathLab.mjs";
+import { TraceTransport, TraceTransportProps } from "../TraceTransport.mjs";
+import { TreeScene, TreeSceneProps } from "../TreeScene.mjs";
+import { TreeQuestLab, TreeQuestLabProps } from "../TreeQuestLab.mjs";
+import { HeapDualView } from "../HeapDualView.mjs";
+import { HeapQuestLab, HeapQuestLabProps } from "../HeapQuestLab.mjs";
+export { GraphAlgorithmLab, GraphAlgorithmLabProps, GraphView, GraphViewProps, GridPathLab, GridPathLabProps, HeapDualView, HeapQuestLab, HeapQuestLabProps, TraceTransport, TraceTransportProps, TreeQuestLab, TreeQuestLabProps, TreeScene, TreeSceneProps };

package/dist/algorithms/react/index.mjs

@@ -0,0 +1,12 @@
+'use client';
+
+import { GraphView } from "../GraphView.mjs";
+import { TraceTransport } from "../TraceTransport.mjs";
+import { GraphAlgorithmLab } from "../GraphAlgorithmLab.mjs";
+import { GridPathLab } from "../GridPathLab.mjs";
+import { TreeScene } from "../TreeScene.mjs";
+import { TreeQuestLab } from "../TreeQuestLab.mjs";
+import { HeapDualView } from "../HeapDualView.mjs";
+import { HeapQuestLab } from "../HeapQuestLab.mjs";
+
+export { GraphAlgorithmLab, GraphView, GridPathLab, HeapDualView, HeapQuestLab, TraceTransport, TreeQuestLab, TreeScene };

package/dist/algorithms/search.d.mts

@@ -0,0 +1,45 @@
+import { SequenceDecision } from "./sequence-contract.mjs";
+
+//#region src/algorithms/search.d.ts
+/** Which half survives a probe, or the probe that ends the search. */
+type SearchDecision = Extract<SequenceDecision, 'left' | 'right'> | 'found';
+interface SearchStep {
+  /** Inclusive window still being searched when this probe was made. */
+  lo: number;
+  hi: number;
+  mid: number;
+  decision: SearchDecision;
+  /** How many candidates remain AFTER acting on this probe. */
+  remaining: number;
+  message: string;
+}
+interface SearchTrace {
+  /** Sorted ascending: binary search is only defined on ordered data. */
+  values: number[];
+  target: number;
+  steps: SearchStep[];
+  /** Index in the sorted array, or -1 when the target is absent. */
+  foundIndex: number;
+  /** Probes binary search made. */
+  comparisons: number;
+  /** Comparisons a left-to-right scan would have made on the same array. */
+  linearComparisons: number;
+  /** The ceiling binary search cannot exceed: one probe per halving. */
+  worstCase: number;
+}
+declare const sortedCopy: (values: readonly number[]) => number[];
+/**
+ * Count a scan from the left. Absent targets cost a full pass, which is the honest worst case
+ * and the number that makes binary search look good.
+ */
+declare function linearSearchComparisons(values: readonly number[], target: number): number;
+/**
+ * Probe the middle of the surviving window until the target is found or the window is empty.
+ *
+ * One comparison is counted per probe. A three-way comparison is what the pseudocode assumes,
+ * and counting the equality test separately would double a number whose whole purpose is to be
+ * compared against the linear count.
+ */
+declare function binarySearchTrace(values: readonly number[], target: number): SearchTrace;
+//#endregion
+export { SearchDecision, SearchStep, SearchTrace, binarySearchTrace, linearSearchComparisons, sortedCopy };

package/dist/algorithms/search.mjs

@@ -0,0 +1,65 @@
+//#region src/algorithms/search.ts
+const sortedCopy = (values) => [...values].sort((a, b) => a - b);
+/**
+* Count a scan from the left. Absent targets cost a full pass, which is the honest worst case
+* and the number that makes binary search look good.
+*/
+function linearSearchComparisons(values, target) {
+	const index = values.findIndex((value) => value === target);
+	return index === -1 ? values.length : index + 1;
+}
+/**
+* Probe the middle of the surviving window until the target is found or the window is empty.
+*
+* One comparison is counted per probe. A three-way comparison is what the pseudocode assumes,
+* and counting the equality test separately would double a number whose whole purpose is to be
+* compared against the linear count.
+*/
+function binarySearchTrace(values, target) {
+	const sorted = sortedCopy(values);
+	const steps = [];
+	let lo = 0;
+	let hi = sorted.length - 1;
+	let foundIndex = -1;
+	while (lo <= hi) {
+		const mid = Math.floor((lo + hi) / 2);
+		const value = sorted[mid];
+		if (value === target) {
+			steps.push({
+				lo,
+				hi,
+				mid,
+				decision: "found",
+				remaining: 1,
+				message: `Probe position ${mid}: it holds ${value}, which is the target.`
+			});
+			foundIndex = mid;
+			break;
+		}
+		const goRight = value < target;
+		const nextLo = goRight ? mid + 1 : lo;
+		const nextHi = goRight ? hi : mid - 1;
+		steps.push({
+			lo,
+			hi,
+			mid,
+			decision: goRight ? "right" : "left",
+			remaining: Math.max(0, nextHi - nextLo + 1),
+			message: `Probe position ${mid}: ${value} is ${goRight ? "below" : "above"} ${target}, so discard the ${goRight ? "left" : "right"} half.`
+		});
+		lo = nextLo;
+		hi = nextHi;
+	}
+	return {
+		values: sorted,
+		target,
+		steps,
+		foundIndex,
+		comparisons: steps.length,
+		linearComparisons: linearSearchComparisons(sorted, target),
+		worstCase: sorted.length === 0 ? 0 : Math.floor(Math.log2(sorted.length)) + 1
+	};
+}
+
+//#endregion
+export { binarySearchTrace, linearSearchComparisons, sortedCopy };

package/dist/algorithms/sequence-contract.d.mts

@@ -0,0 +1,39 @@
+//#region src/algorithms/sequence-contract.d.ts
+interface SequenceItem {
+  id: string;
+  value: number;
+  seq: number;
+  label?: string;
+}
+type SequenceDecision = 'left' | 'right' | 'swap' | 'keep';
+type SequenceEvent = {
+  type: 'sequence-start';
+  items: SequenceItem[];
+  message: string;
+} | {
+  type: 'sequence-compare';
+  items: SequenceItem[];
+  indices: [number, number];
+  decision: SequenceDecision;
+  reason: 'choose-child' | 'heap-order' | 'algorithm';
+  message: string;
+} | {
+  type: 'sequence-swap';
+  items: SequenceItem[];
+  indices: [number, number];
+  itemIds: [string, string];
+  message: string;
+} | {
+  type: 'sequence-write';
+  items: SequenceItem[];
+  index: number;
+  itemId: string;
+  message: string;
+} | {
+  type: 'sequence-complete';
+  items: SequenceItem[];
+  message: string;
+};
+declare const snapshotItems: (items: readonly SequenceItem[]) => SequenceItem[];
+//#endregion
+export { SequenceDecision, SequenceEvent, SequenceItem, snapshotItems };

package/dist/algorithms/sequence-contract.mjs

@@ -0,0 +1,5 @@
+//#region src/algorithms/sequence-contract.ts
+const snapshotItems = (items) => items.map((item) => ({ ...item }));
+
+//#endregion
+export { snapshotItems };

package/dist/algorithms/sorting.d.mts

@@ -0,0 +1,30 @@
+import { SequenceEvent } from "./sequence-contract.mjs";
+
+//#region src/algorithms/sorting.d.ts
+type SortAlgorithm = 'bubble' | 'insertion' | 'selection' | 'merge' | 'quick';
+declare const SORT_ALGORITHMS: SortAlgorithm[];
+declare const SORT_LABEL: Record<SortAlgorithm, string>;
+/** Average-case growth, for the panel that compares the measured counts against theory. */
+declare const SORT_COMPLEXITY: Record<SortAlgorithm, string>;
+interface SortTrace {
+  algorithm: SortAlgorithm;
+  events: SequenceEvent[];
+  comparisons: number;
+  writes: number;
+  sorted: number[];
+}
+/** Trace one algorithm over one input. */
+declare function sortTrace(values: readonly number[], algorithm: SortAlgorithm): SortTrace;
+/**
+ * Every algorithm's cost on the SAME input, cheapest comparisons first.
+ *
+ * This is what turns a sorting animation into a complexity lesson: the learner is not told that
+ * merge sort scales better, they read both counts for the array in front of them.
+ */
+declare function sortCosts(values: readonly number[]): {
+  algorithm: SortAlgorithm;
+  comparisons: number;
+  writes: number;
+}[];
+//#endregion
+export { SORT_ALGORITHMS, SORT_COMPLEXITY, SORT_LABEL, SortAlgorithm, SortTrace, sortCosts, sortTrace };

package/dist/algorithms/sorting.mjs

@@ -0,0 +1,219 @@
+import { snapshotItems } from "./sequence-contract.mjs";
+
+//#region src/algorithms/sorting.ts
+/**
+* Sorting traces on the shared sequence event model.
+*
+* Every algorithm here reports the SAME two costs: comparisons and writes. That is the point.
+* A learner watching bubble sort has no reason to believe it is slow until the counter for the
+* same input sits beside merge sort's, so the counts are part of the trace rather than a claim
+* made in prose afterwards.
+*
+* Merge sort writes into the array rather than swapping, which is why `sequence-write` exists in
+* the contract. Reporting a write for both kinds keeps the cost of the two families comparable.
+*/
+const SORT_ALGORITHMS = [
+	"bubble",
+	"insertion",
+	"selection",
+	"merge",
+	"quick"
+];
+const SORT_LABEL = {
+	bubble: "Bubble sort",
+	insertion: "Insertion sort",
+	selection: "Selection sort",
+	merge: "Merge sort",
+	quick: "Quicksort"
+};
+/** Average-case growth, for the panel that compares the measured counts against theory. */
+const SORT_COMPLEXITY = {
+	bubble: "O(n²)",
+	insertion: "O(n²)",
+	selection: "O(n²)",
+	merge: "O(n log n)",
+	quick: "O(n log n)"
+};
+const toItems = (values) => values.map((value, index) => ({
+	id: `s${index}`,
+	value,
+	seq: index
+}));
+/** Collects events and costs while an algorithm runs over a live array of items. */
+function recorder(values, algorithm) {
+	const items = toItems(values);
+	const events = [{
+		type: "sequence-start",
+		items: snapshotItems(items),
+		message: `${SORT_LABEL[algorithm]} on ${items.length} values.`
+	}];
+	let comparisons = 0;
+	let writes = 0;
+	return {
+		items,
+		/** A comparison always costs one, whichever way it goes. */
+		compare(i, j, willAct, message) {
+			comparisons++;
+			events.push({
+				type: "sequence-compare",
+				items: snapshotItems(items),
+				indices: [i, j],
+				decision: willAct ? "swap" : "keep",
+				reason: "algorithm",
+				message
+			});
+		},
+		swap(i, j, message) {
+			const ids = [items[i].id, items[j].id];
+			const left = items[i];
+			items[i] = items[j];
+			items[j] = left;
+			writes += 2;
+			events.push({
+				type: "sequence-swap",
+				items: snapshotItems(items),
+				indices: [i, j],
+				itemIds: ids,
+				message
+			});
+		},
+		write(index, item, message) {
+			items[index] = item;
+			writes++;
+			events.push({
+				type: "sequence-write",
+				items: snapshotItems(items),
+				index,
+				itemId: item.id,
+				message
+			});
+		},
+		finish() {
+			events.push({
+				type: "sequence-complete",
+				items: snapshotItems(items),
+				message: `Sorted. ${comparisons} comparisons and ${writes} writes.`
+			});
+			return {
+				algorithm,
+				events,
+				comparisons,
+				writes,
+				sorted: items.map((item) => item.value)
+			};
+		}
+	};
+}
+function bubble(run) {
+	const { items } = run;
+	for (let end = items.length - 1; end > 0; end--) {
+		let swapped = false;
+		for (let i = 0; i < end; i++) {
+			const out = items[i].value > items[i + 1].value;
+			run.compare(i, i + 1, out, `Is ${items[i].value} greater than ${items[i + 1].value}?`);
+			if (out) {
+				run.swap(i, i + 1, `Swap, so the larger value moves right.`);
+				swapped = true;
+			}
+		}
+		if (!swapped) return;
+	}
+}
+function insertion(run) {
+	const { items } = run;
+	for (let i = 1; i < items.length; i++) {
+		let j = i;
+		while (j > 0) {
+			const out = items[j - 1].value > items[j].value;
+			run.compare(j - 1, j, out, `Does ${items[j].value} belong before ${items[j - 1].value}?`);
+			if (!out) break;
+			run.swap(j - 1, j, `Shift ${items[j - 1].value} left into place.`);
+			j--;
+		}
+	}
+}
+function selection(run) {
+	const { items } = run;
+	for (let start = 0; start < items.length - 1; start++) {
+		let best = start;
+		for (let i = start + 1; i < items.length; i++) {
+			const out = items[i].value < items[best].value;
+			run.compare(best, i, out, `Is ${items[i].value} smaller than the best so far, ${items[best].value}?`);
+			if (out) best = i;
+		}
+		if (best !== start) run.swap(start, best, `Move the smallest remaining value into position ${start}.`);
+	}
+}
+function merge(run) {
+	const { items } = run;
+	const sortRange = (lo, hi) => {
+		if (hi - lo < 2) return;
+		const mid = Math.floor((lo + hi) / 2);
+		sortRange(lo, mid);
+		sortRange(mid, hi);
+		const buffer = [];
+		let left = lo;
+		let right = mid;
+		while (left < mid && right < hi) {
+			const takeLeft = items[left].value <= items[right].value;
+			run.compare(left, right, takeLeft, `Merging: which is smaller, ${items[left].value} or ${items[right].value}?`);
+			buffer.push(takeLeft ? items[left++] : items[right++]);
+		}
+		while (left < mid) buffer.push(items[left++]);
+		while (right < hi) buffer.push(items[right++]);
+		buffer.forEach((item, offset) => run.write(lo + offset, item, `Write ${item.value} back into position ${lo + offset}.`));
+	};
+	sortRange(0, items.length);
+}
+function quick(run) {
+	const { items } = run;
+	const sortRange = (lo, hi) => {
+		if (lo >= hi) return;
+		const pivot = items[hi].value;
+		let boundary = lo;
+		for (let i = lo; i < hi; i++) {
+			const smaller = items[i].value < pivot;
+			run.compare(i, hi, smaller, `Is ${items[i].value} below the pivot ${pivot}?`);
+			if (smaller) {
+				if (i !== boundary) run.swap(boundary, i, `Move ${items[i].value} into the low partition.`);
+				boundary++;
+			}
+		}
+		if (boundary !== hi) run.swap(boundary, hi, `Place the pivot ${pivot} between the two partitions.`);
+		sortRange(lo, boundary - 1);
+		sortRange(boundary + 1, hi);
+	};
+	sortRange(0, items.length - 1);
+}
+const RUNNERS = {
+	bubble,
+	insertion,
+	selection,
+	merge,
+	quick
+};
+/** Trace one algorithm over one input. */
+function sortTrace(values, algorithm) {
+	const run = recorder(values, algorithm);
+	RUNNERS[algorithm](run);
+	return run.finish();
+}
+/**
+* Every algorithm's cost on the SAME input, cheapest comparisons first.
+*
+* This is what turns a sorting animation into a complexity lesson: the learner is not told that
+* merge sort scales better, they read both counts for the array in front of them.
+*/
+function sortCosts(values) {
+	return SORT_ALGORITHMS.map((algorithm) => {
+		const trace = sortTrace(values, algorithm);
+		return {
+			algorithm,
+			comparisons: trace.comparisons,
+			writes: trace.writes
+		};
+	}).sort((a, b) => a.comparisons - b.comparisons);
+}
+
+//#endregion
+export { SORT_ALGORITHMS, SORT_COMPLEXITY, SORT_LABEL, sortCosts, sortTrace };

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

@@ -0,0 +1,6 @@
+import { BinaryTree, BinaryTreeNode, TraversalOrder, TreeEvent, TreePosition, TreeTrace } from "../tree-contract.mjs";
+import { TREE_GAP_X, TREE_GAP_Y, layoutBinaryTree } from "../tree-layout.mjs";
+import { insertAVL, insertBST, searchBST, traverseTree } from "../tree.mjs";
+import { TreeBuildStrategy, buildTeachingTree } from "../tree-builder.mjs";
+import { BALANCED_BST, CLASSIC_BST } from "../tree-presets.mjs";
+export { BALANCED_BST, BinaryTree, BinaryTreeNode, CLASSIC_BST, TREE_GAP_X, TREE_GAP_Y, TraversalOrder, TreeBuildStrategy, TreeEvent, TreePosition, TreeTrace, buildTeachingTree, insertAVL, insertBST, layoutBinaryTree, searchBST, traverseTree };

package/dist/algorithms/tree/index.mjs

@@ -0,0 +1,6 @@
+import { TREE_GAP_X, TREE_GAP_Y, layoutBinaryTree } from "../tree-layout.mjs";
+import { insertAVL, insertBST, searchBST, traverseTree } from "../tree.mjs";
+import { BALANCED_BST, CLASSIC_BST } from "../tree-presets.mjs";
+import { buildTeachingTree } from "../tree-builder.mjs";
+
+export { BALANCED_BST, CLASSIC_BST, TREE_GAP_X, TREE_GAP_Y, buildTeachingTree, insertAVL, insertBST, layoutBinaryTree, searchBST, traverseTree };

package/dist/algorithms/tree-builder.d.mts

@@ -0,0 +1,8 @@
+import { BinaryTree } from "./tree-contract.mjs";
+
+//#region src/algorithms/tree-builder.d.ts
+type TreeBuildStrategy = 'insertion-order' | 'balanced' | 'skewed-left' | 'skewed-right';
+/** Generate a valid BST from the small amount of intent a lesson author supplies. */
+declare function buildTeachingTree(values: readonly number[], strategy?: TreeBuildStrategy): BinaryTree;
+//#endregion
+export { TreeBuildStrategy, buildTeachingTree };

package/dist/algorithms/tree-builder.mjs

@@ -0,0 +1,54 @@
+//#region src/algorithms/tree-builder.ts
+const uniqueFinite = (values) => [...new Set(values.filter(Number.isFinite).map(Math.trunc))].slice(0, 31);
+function insertionTree(values) {
+	const clean = uniqueFinite(values);
+	if (!clean.length) return { nodes: [] };
+	const nodes = [];
+	for (const value of clean) {
+		const node = {
+			id: `v-${value}`,
+			value
+		};
+		if (!nodes.length) {
+			nodes.push(node);
+			continue;
+		}
+		let current = nodes[0];
+		while (true) {
+			const side = value < current.value ? "left" : "right";
+			if (!current[side]) {
+				current[side] = node.id;
+				nodes.push(node);
+				break;
+			}
+			current = nodes.find((candidate) => candidate.id === current[side]);
+		}
+	}
+	return {
+		rootId: nodes[0].id,
+		nodes
+	};
+}
+/** Generate a valid BST from the small amount of intent a lesson author supplies. */
+function buildTeachingTree(values, strategy = "insertion-order") {
+	const clean = uniqueFinite(values);
+	if (strategy === "skewed-left") return insertionTree([...clean].sort((a, b) => b - a));
+	if (strategy === "skewed-right") return insertionTree([...clean].sort((a, b) => a - b));
+	if (strategy === "balanced") {
+		const sorted = [...clean].sort((a, b) => a - b);
+		const order = [];
+		const addMedian = (start, end) => {
+			if (start > end) return;
+			const middle = Math.floor((start + end) / 2);
+			order.push(sorted[middle]);
+			addMedian(start, middle - 1);
+			addMedian(middle + 1, end);
+		};
+		addMedian(0, sorted.length - 1);
+		return insertionTree(order);
+	}
+	return insertionTree(clean);
+}
+
+//#endregion
+export { buildTeachingTree };