@classytic/labs 0.4.0 → 0.5.0

package/dist/algorithms/graph.mjs

@@ -1,4 +1,43 @@
+import { normalizeGraph } from "./normalize.mjs";
+
 //#region src/algorithms/graph.ts
+const weightOf = (edge) => edge.weight ?? 1;
+/** A number as a learner reads it: a real minus sign, and ∞ for unreached. */
+function formatWeight(value) {
+	if (!Number.isFinite(value)) return "∞";
+	return value < 0 ? `−${Math.abs(value)}` : String(value);
+}
+const namer = (graph) => {
+	const names = new Map(graph.nodes.map((node) => [node.id, node.label ?? node.id]));
+	return (id) => id === void 0 ? "" : names.get(id) ?? id;
+};
+const byId = (a, b) => a < b ? -1 : a > b ? 1 : 0;
+/**
+* Normalise an authored graph like `normalizeGraph`, but keep each edge's real weight: negative
+* weights survive (Bellman-Ford and the Dijkstra failure need them) and an edge with no weight
+* stays unweighted (drawn without a number, counted as 1).
+*/
+function prepareGraph(input) {
+	const safe = normalizeGraph(input);
+	if (!input?.edges?.length) return safe;
+	const authored = /* @__PURE__ */ new Map();
+	for (const edge of input.edges) if (!authored.has(edge.id)) authored.set(edge.id, edge);
+	return {
+		nodes: safe.nodes,
+		edges: safe.edges.map((edge) => {
+			const raw = authored.get(edge.id);
+			if (!raw) return edge;
+			const { weight: _clamped, ...rest } = edge;
+			return typeof raw.weight === "number" && Number.isFinite(raw.weight) ? {
+				...rest,
+				weight: raw.weight
+			} : rest;
+		})
+	};
+}
+/** True when any edge carries an explicit weight. */
+const isWeighted = (graph) => graph.edges.some((edge) => typeof edge.weight === "number");
+const hasNegativeEdge = (graph) => graph.edges.some((edge) => weightOf(edge) < 0);
 const adjacency = (graph, id) => graph.edges.flatMap((edge) => {
 	if (edge.from === id) return [{
 		edge,
@@ -9,7 +48,38 @@ const adjacency = (graph, id) => graph.edges.flatMap((edge) => {
 		next: edge.from
 	}];
 	return [];
-}).sort((a, b) => a.next.localeCompare(b.next) || a.edge.id.localeCompare(b.edge.id));
+}).sort((a, b) => byId(a.next, b.next) || byId(a.edge.id, b.edge.id));
+/** Every edge as if undirected (spanning trees). */
+const undirectedAdjacency = (graph, id) => graph.edges.flatMap((edge) => {
+	if (edge.from === id) return [{
+		edge,
+		next: edge.to
+	}];
+	if (edge.to === id) return [{
+		edge,
+		next: edge.from
+	}];
+	return [];
+}).sort((a, b) => byId(a.next, b.next) || byId(a.edge.id, b.edge.id));
+/** Every edge read as from → to (task dependencies). */
+const successors = (graph, id) => graph.edges.filter((edge) => edge.from === id).map((edge) => ({
+	edge,
+	next: edge.to
+})).sort((a, b) => byId(a.next, b.next) || byId(a.edge.id, b.edge.id));
+/** Directed arcs in relaxation order: edge id order, an undirected edge giving both directions. */
+const arcsOf = (graph) => [...graph.edges].sort((a, b) => byId(a.id, b.id)).flatMap((edge) => edge.directed ? [{
+	edge,
+	from: edge.from,
+	to: edge.to
+}] : [{
+	edge,
+	from: edge.from,
+	to: edge.to
+}, {
+	edge,
+	from: edge.to,
+	to: edge.from
+}]);
 function reconstructPath(previous, source, target) {
 	const path = [];
 	const seen = /* @__PURE__ */ new Set();
@@ -22,24 +92,68 @@ function reconstructPath(previous, source, target) {
 	}
 	return [];
 }
-function traverse(graph, source, mode) {
+/** Total weight along a node path (edges looked up in either direction when undirected). */
+function pathWeight(graph, path) {
+	let total = 0;
+	for (let index = 1; index < path.length; index++) {
+		const edge = findEdge(graph, path[index - 1], path[index]);
+		total += edge ? weightOf(edge) : Infinity;
+	}
+	return total;
+}
+/** The cheapest edge from `a` to `b` (respecting direction), when one exists. */
+function findEdge(graph, a, b) {
+	return graph.edges.filter((edge) => edge.from === a && edge.to === b || !edge.directed && edge.from === b && edge.to === a).sort((x, y) => weightOf(x) - weightOf(y) || byId(x.id, y.id))[0];
+}
+/** Edge ids along a node sequence; `closed` also joins the last node back to the first. */
+function edgesAlong(graph, nodes, closed = false) {
+	const ids = [];
+	const hops = closed ? nodes.length : nodes.length - 1;
+	for (let index = 0; index < hops; index++) {
+		const a = nodes[index];
+		const b = nodes[(index + 1) % nodes.length];
+		const edge = findEdge(graph, a, b) ?? graph.edges.find((e) => e.from === b && e.to === a);
+		if (edge) ids.push(edge.id);
+	}
+	return ids;
+}
+const plural = (count, word) => `${count} ${word}${count === 1 ? "" : "s"}`;
+function traverse(graph, source, mode, target) {
+	const name = namer(graph);
 	const events = [{
 		type: "start",
 		nodeId: source,
-		message: `Start at ${source}.`
+		message: `Start at ${name(source)}.`
 	}];
+	const decisions = [];
 	const frontier = [source];
 	const discovered = /* @__PURE__ */ new Set([source]);
 	const previous = {};
 	const order = [];
+	const container = mode === "bfs" ? "queue" : "stack";
 	while (frontier.length) {
-		const current = mode === "bfs" ? frontier.shift() : frontier.pop();
+		const current = mode === "bfs" ? frontier[0] : frontier.at(-1);
+		const choices = [...new Set(frontier)];
+		if (choices.length > 1) decisions.push({
+			step: events.length - 1,
+			kind: "node",
+			prompt: mode === "bfs" ? "Which node leaves the queue next?" : "Which node leaves the stack next?",
+			options: [...choices].sort(byId).map((id) => ({
+				value: id,
+				label: name(id)
+			})),
+			answer: current,
+			correct: mode === "bfs" ? "It has waited in the queue longest: first in, first out." : "It is the newest node on the stack: last in, first out.",
+			reasons: Object.fromEntries(choices.filter((id) => id !== current).map((id) => [id, mode === "bfs" ? `BFS takes the oldest node in the queue, which is ${name(current)}.` : `DFS takes the newest node on the stack, which is ${name(current)}.`]))
+		});
+		if (mode === "bfs") frontier.shift();
+		else frontier.pop();
 		order.push(current);
 		events.push({
 			type: "visit-node",
 			nodeId: current,
 			frontier: [...frontier],
-			message: `Visit ${current}; ${mode === "bfs" ? "queue" : "stack"} has ${frontier.length} item${frontier.length === 1 ? "" : "s"}.`
+			message: `Visit ${name(current)}; ${container} has ${plural(frontier.length, "item")}.`
 		});
 		const nextEdges = adjacency(graph, current);
 		if (mode === "dfs") nextEdges.reverse();
@@ -49,7 +163,7 @@ function traverse(graph, source, mode) {
 				edgeId: edge.id,
 				from: current,
 				to: next,
-				message: `Inspect ${current} → ${next}.`
+				message: `Inspect ${name(current)} → ${name(next)}.`
 			});
 			if (discovered.has(next)) continue;
 			discovered.add(next);
@@ -60,70 +174,198 @@ function traverse(graph, source, mode) {
 				nodeId: next,
 				via: edge.id,
 				frontier: [...frontier],
-				message: `Discover ${next} and add it to the ${mode === "bfs" ? "queue" : "stack"}.`
+				message: `Discover ${name(next)} and add it to the ${container}.`
 			});
 		}
 	}
+	const path = target ? reconstructPath(previous, source, target) : void 0;
+	const route = mode === "bfs" && path?.length && target !== source ? ` Fewest hops to ${name(target)}: ${plural(path.length - 1, "hop")} (${path.map(name).join(" → ")}).` : "";
 	events.push({
 		type: "complete",
 		order,
-		message: `${mode.toUpperCase()} complete: ${order.join(" → ")}.`
+		path: mode === "bfs" ? path : void 0,
+		message: `${mode.toUpperCase()} complete: ${order.map(name).join(" → ")}.${route}`
 	});
 	return {
 		algorithm: mode,
 		events,
 		order,
-		previous
+		previous,
+		path: mode === "bfs" ? path : void 0,
+		decisions
+	};
+}
+const bfs = (graph, source, target) => traverse(graph, source, "bfs", target);
+const dfs = (graph, source, order = "stack") => order === "recursive" ? recursiveDfs(graph, source) : traverse(graph, source, "dfs");
+/**
+* Recursive DFS. `frontier` on each event is the call stack (bottom first), so the lab shows the
+* path back to the start and `finish-node` is the backtrack.
+*/
+function recursiveDfs(graph, source) {
+	const name = namer(graph);
+	const events = [{
+		type: "start",
+		nodeId: source,
+		message: `Start at ${name(source)}: call dfs(${name(source)}).`
+	}];
+	const decisions = [];
+	const visited = /* @__PURE__ */ new Set();
+	const previous = {};
+	const order = [];
+	const calls = [];
+	const unvisitedNeighbours = (id) => adjacency(graph, id).map((arc) => arc.next).filter((next, index, all) => !visited.has(next) && all.indexOf(next) === index);
+	/** Ask before the tree edge into `answer` is followed from `parent`, the deepest call. */
+	const ask = (answer, parent) => {
+		const hangsOff = /* @__PURE__ */ new Map();
+		for (const call of [...calls].reverse()) for (const next of unvisitedNeighbours(call)) if (!hangsOff.has(next)) hangsOff.set(next, call);
+		if (hangsOff.size < 2) return;
+		decisions.push({
+			step: events.length - 1,
+			kind: "node",
+			prompt: "Which node does DFS visit next?",
+			options: [...hangsOff.keys()].sort(byId).map((id) => ({
+				value: id,
+				label: name(id)
+			})),
+			answer,
+			correct: `It is the first unvisited neighbour of ${name(parent)}, the deepest call still open, in alphabetical order.`,
+			reasons: Object.fromEntries([...hangsOff].filter(([id]) => id !== answer).map(([id, owner]) => [id, owner === parent ? `${name(parent)}'s neighbours are tried in alphabetical order, so ${name(answer)} comes before ${name(id)}.` : `${name(id)} hangs off ${name(owner)}; DFS only returns there after it has finished ${name(parent)}. It goes deeper from ${name(parent)} first, to ${name(answer)}.`]))
+		});
+	};
+	const visit = (node, parent) => {
+		visited.add(node);
+		calls.push(node);
+		order.push(node);
+		previous[node] = parent;
+		events.push({
+			type: "visit-node",
+			nodeId: node,
+			parent,
+			frontier: [...calls],
+			message: parent ? `Visit ${name(node)} (reached from ${name(parent)}). Call stack depth ${calls.length}.` : `Visit ${name(node)}. Call stack depth 1.`
+		});
+		for (const { edge, next } of adjacency(graph, node)) {
+			if (visited.has(next)) {
+				events.push({
+					type: "inspect-edge",
+					edgeId: edge.id,
+					from: node,
+					to: next,
+					message: `Inspect ${name(node)} → ${name(next)}: already visited, skip it.`
+				});
+				continue;
+			}
+			ask(next, node);
+			events.push({
+				type: "inspect-edge",
+				edgeId: edge.id,
+				from: node,
+				to: next,
+				message: `Inspect ${name(node)} → ${name(next)}: not visited yet, so go deeper.`
+			});
+			visit(next, node);
+		}
+		calls.pop();
+		const back = calls.at(-1);
+		events.push({
+			type: "finish-node",
+			nodeId: node,
+			message: back ? `${name(node)} has no unvisited neighbours left. Backtrack to ${name(back)}.` : `${name(node)} has no unvisited neighbours left, and the call stack is empty.`
+		});
+	};
+	visit(source);
+	events.push({
+		type: "complete",
+		order,
+		message: `DFS complete: ${order.map(name).join(" → ")}.`
+	});
+	return {
+		algorithm: "dfs",
+		events,
+		order,
+		previous,
+		decisions
 	};
 }
-const bfs = (graph, source) => traverse(graph, source, "bfs");
-const dfs = (graph, source) => traverse(graph, source, "dfs");
+/**
+* Textbook Dijkstra, run faithfully even on negative weights: a settled node is never reopened.
+* On a graph with a negative edge that is exactly how it goes wrong, and the trace says so with a
+* `skip-settled` event whenever a cheaper route reaches a node it has already settled.
+*/
 function dijkstra(graph, source, target) {
+	const name = namer(graph);
 	const ids = graph.nodes.map((node) => node.id);
 	const distance = Object.fromEntries(ids.map((id) => [id, id === source ? 0 : Infinity]));
 	const previous = {};
-	const previousEdge = {};
 	const pending = new Set(ids);
 	const order = [];
+	const decisions = [];
 	const events = [{
 		type: "start",
 		nodeId: source,
-		message: `Set ${source} to 0; every other distance starts at ∞.`
+		message: `Set ${name(source)} to 0; every other distance starts at ∞.`
 	}];
 	while (pending.size) {
-		const current = [...pending].sort((a, b) => distance[a] - distance[b] || a.localeCompare(b))[0];
+		const ranked = [...pending].filter((id) => Number.isFinite(distance[id])).sort((a, b) => distance[a] - distance[b] || byId(a, b));
+		const current = ranked[0];
+		if (current === void 0) break;
+		if (ranked.length > 1) {
+			const best = distance[current];
+			decisions.push({
+				step: events.length - 1,
+				kind: "node",
+				prompt: "Which tentative distance is smallest?",
+				options: [...ranked].sort(byId).map((id) => ({
+					value: id,
+					label: `${name(id)} · ${formatWeight(distance[id])}`
+				})),
+				answer: current,
+				correct: `It has the smallest tentative distance, ${formatWeight(best)}.`,
+				reasons: Object.fromEntries(ranked.filter((id) => id !== current).map((id) => [id, distance[id] === best ? `${name(id)} ties at ${formatWeight(best)}; ties go to the alphabetically first id, so ${name(current)} goes first.` : `${name(id)} is at ${formatWeight(distance[id])}, but ${name(current)} is closer at ${formatWeight(best)}.`]))
+			});
+		}
 		pending.delete(current);
-		if (!Number.isFinite(distance[current])) break;
 		order.push(current);
 		events.push({
 			type: "visit-node",
 			nodeId: current,
 			frontier: [...pending].filter((id) => Number.isFinite(distance[id])),
-			message: `Settle ${current} at distance ${distance[current]}.`
+			message: `Settle ${name(current)} at distance ${formatWeight(distance[current])}.`
 		});
 		if (current === target) break;
 		for (const { edge, next } of adjacency(graph, current)) {
-			if (!pending.has(next)) continue;
+			const weight = weightOf(edge);
+			const candidate = distance[current] + weight;
+			if (!pending.has(next)) {
+				if (candidate < distance[next]) events.push({
+					type: "skip-settled",
+					edgeId: edge.id,
+					from: current,
+					to: next,
+					candidate,
+					settled: distance[next],
+					message: `${name(current)} → ${name(next)} would give ${formatWeight(candidate)}, cheaper than ${formatWeight(distance[next])}, but ${name(next)} is already settled and Dijkstra never reopens it.`
+				});
+				continue;
+			}
 			events.push({
 				type: "inspect-edge",
 				edgeId: edge.id,
 				from: current,
 				to: next,
-				message: `Try ${current} → ${next} with weight ${edge.weight ?? 1}.`
+				message: `Try ${name(current)} → ${name(next)} with weight ${formatWeight(weight)}.`
 			});
-			const candidate = distance[current] + Math.max(0, edge.weight ?? 1);
 			if (candidate < distance[next]) {
 				const old = distance[next];
 				distance[next] = candidate;
 				previous[next] = current;
-				previousEdge[next] = edge.id;
 				events.push({
 					type: "relax-edge",
 					edgeId: edge.id,
 					nodeId: next,
 					previous: old,
 					next: candidate,
-					message: `Improve ${next}: ${Number.isFinite(old) ? old : "∞"} → ${candidate}.`
+					message: `Improve ${name(next)}: ${formatWeight(old)} → ${formatWeight(candidate)}.`
 				});
 			}
 		}
@@ -133,16 +375,800 @@ function dijkstra(graph, source, target) {
 		type: "complete",
 		order,
 		path,
-		message: path?.length ? `Shortest path: ${path.join(" → ")}; cost ${distance[target]}.` : "Dijkstra complete."
+		message: path?.length ? `Shortest path: ${path.map(name).join(" → ")}; cost ${formatWeight(distance[target])}.` : "Dijkstra complete."
 	});
 	return {
 		algorithm: "dijkstra",
 		events,
 		order,
 		distance,
-		previous
+		previous,
+		path,
+		decisions
+	};
+}
+/**
+* Bellman-Ford: rounds of relaxing every edge. Stops early after a round that changes nothing. If
+* round V (one more than V − 1) still improves a distance, a negative cycle is reachable and no
+* shortest route exists. Predictions: from round 2 on, "will this round change anything?", and
+* for each negative edge, "does it improve its end?".
+*/
+function bellmanFord(graph, source, target) {
+	const name = namer(graph);
+	const ids = graph.nodes.map((node) => node.id);
+	const n = ids.length;
+	const arcs = arcsOf(graph);
+	const distance = Object.fromEntries(ids.map((id) => [id, id === source ? 0 : Infinity]));
+	const previous = {};
+	const decisions = [];
+	const events = [{
+		type: "start",
+		nodeId: source,
+		message: `Set ${name(source)} to 0; every other distance starts at ∞. At most ${plural(Math.max(1, n - 1), "round")} over all ${plural(arcs.length, "edge")}.`
+	}];
+	let cycle;
+	let lastChanged = [];
+	for (let round = 1; round <= Math.max(1, n); round++) {
+		const check = round === n && n > 1;
+		const roundStep = events.length - 1;
+		events.push({
+			type: "round",
+			round,
+			message: check ? `Round ${round}: a check pass. After ${n - 1} rounds nothing can improve unless a negative cycle exists.` : `Round ${round}: relax every edge once, in edge order.`
+		});
+		const changed = [];
+		for (const { edge, from, to } of arcs) {
+			const weight = weightOf(edge);
+			const du = distance[from];
+			if (!Number.isFinite(du)) {
+				events.push({
+					type: "inspect-edge",
+					edgeId: edge.id,
+					from,
+					to,
+					message: `Skip ${name(from)} → ${name(to)}: ${name(from)} is not reached yet.`
+				});
+				continue;
+			}
+			const candidate = du + weight;
+			const dv = distance[to];
+			const improves = candidate < dv;
+			if (weight < 0 && !check) {
+				const sum = `${formatWeight(du)} + (${formatWeight(weight)}) = ${formatWeight(candidate)}`;
+				const verdict = improves ? `${sum}, which beats ${formatWeight(dv)}.` : `${sum}, which does not beat ${formatWeight(dv)}.`;
+				decisions.push({
+					step: events.length - 1,
+					kind: "yes-no",
+					prompt: `Does the ${formatWeight(weight)} edge ${name(from)} → ${name(to)} lower ${name(to)} (now ${formatWeight(dv)})?`,
+					options: [{
+						value: "yes",
+						label: "Yes, it improves"
+					}, {
+						value: "no",
+						label: "No change"
+					}],
+					answer: improves ? "yes" : "no",
+					correct: verdict,
+					reasons: { [improves ? "no" : "yes"]: verdict }
+				});
+			}
+			events.push({
+				type: "inspect-edge",
+				edgeId: edge.id,
+				from,
+				to,
+				message: `Try ${name(from)} → ${name(to)}: ${formatWeight(du)} + (${formatWeight(weight)}) = ${formatWeight(candidate)} vs ${formatWeight(dv)}.`
+			});
+			if (!improves) continue;
+			previous[to] = from;
+			distance[to] = candidate;
+			if (check) {
+				let cursor = to;
+				for (let index = 0; index < n && cursor; index++) cursor = previous[cursor];
+				const loop = [];
+				const seen = /* @__PURE__ */ new Set();
+				while (cursor && !seen.has(cursor)) {
+					seen.add(cursor);
+					loop.unshift(cursor);
+					cursor = previous[cursor];
+				}
+				cycle = loop;
+				events.push({
+					type: "negative-cycle",
+					edgeId: edge.id,
+					cycle: loop,
+					message: `Round ${round} still lowers ${name(to)}: the loop ${[...loop, loop[0]].map(name).join(" → ")} has negative total cost, so going round it again always saves more.`
+				});
+				break;
+			}
+			if (!changed.includes(to)) changed.push(to);
+			events.push({
+				type: "relax-edge",
+				edgeId: edge.id,
+				nodeId: to,
+				previous: dv,
+				next: candidate,
+				message: `Improve ${name(to)}: ${formatWeight(dv)} → ${formatWeight(candidate)}.`
+			});
+		}
+		if (round >= 2) {
+			const yes = changed.length > 0 || Boolean(cycle);
+			decisions.push({
+				step: roundStep,
+				kind: "yes-no",
+				prompt: `Will round ${round} lower any distance?`,
+				options: [{
+					value: "yes",
+					label: "Yes, something improves"
+				}, {
+					value: "no",
+					label: "No, nothing changes"
+				}],
+				answer: yes ? "yes" : "no",
+				correct: cycle ? "A negative cycle keeps lowering distances, round after round." : yes ? `Round ${round} lowers ${changed.map(name).join(", ")}.` : "Nothing improves, so every distance is final and Bellman-Ford can stop early.",
+				reasons: yes ? { no: `Round ${round - 1} lowered ${lastChanged.map(name).join(", ")}, and the edges out of them can pass that saving on.` } : { yes: "Every edge already satisfies d(to) ≤ d(from) + weight, so no distance can drop." }
+			});
+		}
+		if (cycle) break;
+		events.push({
+			type: "round-end",
+			round,
+			changed,
+			message: changed.length ? `Round ${round} lowered ${changed.map(name).join(", ")}.` : `Round ${round} changed nothing, so every distance is final.`
+		});
+		lastChanged = changed;
+		if (!changed.length) break;
+	}
+	const order = ids.filter((id) => Number.isFinite(distance[id])).sort((a, b) => distance[a] - distance[b] || byId(a, b));
+	const path = target && !cycle ? reconstructPath(previous, source, target) : void 0;
+	events.push({
+		type: "complete",
+		order,
+		path,
+		cycle,
+		message: cycle ? `Negative cycle ${[...cycle, cycle[0]].map(name).join(" → ")}: no shortest route exists.` : path?.length ? `Shortest path: ${path.map(name).join(" → ")}; cost ${formatWeight(distance[target])}.` : "Bellman-Ford complete."
+	});
+	return {
+		algorithm: "bellman-ford",
+		events,
+		order,
+		distance,
+		previous,
+		path,
+		cycle,
+		negativeCycle: Boolean(cycle),
+		decisions: decisions.sort((a, b) => a.step - b.step)
 	};
 }
+const edgeLabel = (name, edge) => `${name(edge.from)}–${name(edge.to)}`;
+/** Prim (eager, key-based): grow one tree, always adding the cheapest edge that leaves it. Edges read as undirected. */
+function prim(graph, source) {
+	const name = namer(graph);
+	const ids = graph.nodes.map((node) => node.id);
+	const key = Object.fromEntries(ids.map((id) => [id, id === source ? 0 : Infinity]));
+	const keyEdge = {};
+	const previous = {};
+	const inTree = /* @__PURE__ */ new Set([source]);
+	const order = [source];
+	const tree = [];
+	const decisions = [];
+	let total = 0;
+	const events = [{
+		type: "start",
+		nodeId: source,
+		message: `Start the tree at ${name(source)}. Every other node's cheapest link starts at ∞.`
+	}];
+	const offer = (from) => {
+		for (const { edge, next } of undirectedAdjacency(graph, from)) {
+			if (inTree.has(next)) continue;
+			const weight = weightOf(edge);
+			if (weight < key[next]) {
+				const old = key[next];
+				key[next] = weight;
+				keyEdge[next] = edge;
+				previous[next] = from;
+				events.push({
+					type: "relax-edge",
+					edgeId: edge.id,
+					nodeId: next,
+					previous: old,
+					next: weight,
+					message: `Cheapest link to ${name(next)} is now ${name(from)}–${name(next)} at ${formatWeight(weight)}.`
+				});
+			}
+		}
+	};
+	offer(source);
+	for (;;) {
+		const fringe = ids.filter((id) => !inTree.has(id) && Number.isFinite(key[id])).sort((a, b) => key[a] - key[b] || byId(a, b));
+		const pick = fringe[0];
+		if (pick === void 0) break;
+		const edge = keyEdge[pick];
+		const linkLabel = (id) => `${name(previous[id])}–${name(id)}`;
+		if (fringe.length > 1) decisions.push({
+			step: events.length - 1,
+			kind: "edge",
+			prompt: "Which edge joins the tree next?",
+			options: [...fringe].sort(byId).map((id) => ({
+				value: keyEdge[id].id,
+				label: `${linkLabel(id)} · ${formatWeight(key[id])}`
+			})),
+			answer: edge.id,
+			correct: `It is the cheapest edge leaving the tree, at ${formatWeight(key[pick])}.`,
+			reasons: Object.fromEntries(fringe.filter((id) => id !== pick).map((id) => [keyEdge[id].id, key[id] === key[pick] ? `${linkLabel(id)} ties at ${formatWeight(key[id])}; ties go to the alphabetically first node, ${name(pick)}.` : `Prim takes the cheapest edge leaving the tree: ${linkLabel(pick)} at ${formatWeight(key[pick])}.`]))
+		});
+		inTree.add(pick);
+		order.push(pick);
+		tree.push(edge.id);
+		total += key[pick];
+		events.push({
+			type: "accept-edge",
+			edgeId: edge.id,
+			from: previous[pick],
+			to: pick,
+			weight: key[pick],
+			nodeId: pick,
+			total,
+			message: `Add ${linkLabel(pick)} (${formatWeight(key[pick])}); tree cost ${formatWeight(total)}.`
+		});
+		offer(pick);
+	}
+	const spans = order.length === ids.length;
+	events.push({
+		type: "complete",
+		order,
+		message: spans ? `Minimum spanning tree: ${plural(tree.length, "edge")}, total ${formatWeight(total)}.` : `Only ${order.length} of ${ids.length} nodes are reachable; this tree spans that part, total ${formatWeight(total)}.`
+	});
+	return {
+		algorithm: "prim",
+		events,
+		order,
+		previous,
+		tree,
+		total,
+		decisions
+	};
+}
+/** Group node ids by union-find root: each set sorted by id, sets sorted by their first id. */
+function setsOf(ids, find) {
+	const groups = /* @__PURE__ */ new Map();
+	for (const id of [...ids].sort(byId)) {
+		const root = find(id);
+		groups.set(root, [...groups.get(root) ?? [], id]);
+	}
+	return [...groups.values()].sort((a, b) => byId(a[0], b[0]));
+}
+/** Kruskal: take edges cheapest first, skipping any whose ends already share a union-find set. */
+function kruskal(graph) {
+	const name = namer(graph);
+	const ids = graph.nodes.map((node) => node.id);
+	const parent = Object.fromEntries(ids.map((id) => [id, id]));
+	const find = (id) => {
+		let root = id;
+		while (parent[root] !== root) root = parent[root];
+		let cursor = id;
+		while (parent[cursor] !== root) {
+			const next = parent[cursor];
+			parent[cursor] = root;
+			cursor = next;
+		}
+		return root;
+	};
+	const union = (a, b) => {
+		const [ra, rb] = [find(a), find(b)];
+		if (ra === rb) return;
+		if (ra < rb) parent[rb] = ra;
+		else parent[ra] = rb;
+	};
+	const setLabel = (id) => `{${setsOf(ids, find).find((set) => set.includes(id)).map(name).join(", ")}}`;
+	const sorted = [...graph.edges].sort((a, b) => weightOf(a) - weightOf(b) || byId(a.id, b.id));
+	const decisions = [];
+	const tree = [];
+	const events = [{
+		type: "start",
+		nodeId: ids[0],
+		message: `Sort the ${plural(sorted.length, "edge")} by cost, cheapest first. Every node starts in its own set.`
+	}];
+	let total = 0;
+	let index = 0;
+	const needed = ids.length - 1;
+	while (index < sorted.length && tree.length < needed) {
+		let take = index;
+		while (take < sorted.length && find(sorted[take].from) === find(sorted[take].to)) take++;
+		const answer = sorted[take];
+		if (answer) {
+			const options = sorted.slice(index, Math.max(index + 4, take + 1));
+			if (options.length > 1) decisions.push({
+				step: events.length - 1,
+				kind: "edge",
+				prompt: "Which edge does Kruskal take next?",
+				options: options.map((edge) => ({
+					value: edge.id,
+					label: `${edgeLabel(name, edge)} · ${formatWeight(weightOf(edge))}`
+				})),
+				answer: answer.id,
+				correct: "It is the cheapest edge left that joins two separate sets.",
+				reasons: Object.fromEntries(options.filter((edge) => edge.id !== answer.id).map((edge) => [edge.id, find(edge.from) === find(edge.to) ? `${name(edge.from)} and ${name(edge.to)} are already in one set, so ${edgeLabel(name, edge)} would make a cycle.` : weightOf(edge) === weightOf(answer) ? `${edgeLabel(name, answer)} ties at ${formatWeight(weightOf(answer))} and comes first by edge id.` : `${edgeLabel(name, answer)} is cheaper and still joins two separate sets.`]))
+			});
+		}
+		for (; index < take; index++) {
+			const edge = sorted[index];
+			events.push({
+				type: "reject-edge",
+				edgeId: edge.id,
+				from: edge.from,
+				to: edge.to,
+				weight: weightOf(edge),
+				message: `Skip ${edgeLabel(name, edge)} (${formatWeight(weightOf(edge))}): both ends are already in ${setLabel(edge.from)}, so it would make a cycle.`
+			});
+		}
+		if (!answer) break;
+		const joined = `${setLabel(answer.from)} and ${setLabel(answer.to)}`;
+		union(answer.from, answer.to);
+		tree.push(answer.id);
+		total += weightOf(answer);
+		events.push({
+			type: "accept-edge",
+			edgeId: answer.id,
+			from: answer.from,
+			to: answer.to,
+			weight: weightOf(answer),
+			total,
+			sets: setsOf(ids, find),
+			message: `Take ${edgeLabel(name, answer)} (${formatWeight(weightOf(answer))}): joins ${joined}. Tree cost ${formatWeight(total)}.`
+		});
+		index = take + 1;
+	}
+	const left = sorted.length - index;
+	events.push({
+		type: "complete",
+		order: [...tree],
+		message: tree.length === needed ? `Minimum spanning tree: ${plural(tree.length, "edge")}, total ${formatWeight(total)}.${left ? ` ${left === 1 ? "The last edge is" : `The last ${left} edges are`} never needed.` : ""}` : `The graph is not connected: a spanning forest of ${plural(tree.length, "edge")}, total ${formatWeight(total)}.`
+	});
+	return {
+		algorithm: "kruskal",
+		events,
+		order: [...tree],
+		previous: {},
+		tree,
+		total,
+		decisions
+	};
+}
+/** Kahn's algorithm: repeatedly do a task with no unfinished prerequisites. */
+function topologicalSort(graph) {
+	const name = namer(graph);
+	const ids = graph.nodes.map((node) => node.id);
+	const indegree = Object.fromEntries(ids.map((id) => [id, 0]));
+	for (const edge of graph.edges) indegree[edge.to] = (indegree[edge.to] ?? 0) + 1;
+	const queue = ids.filter((id) => indegree[id] === 0).sort(byId);
+	const order = [];
+	const decisions = [];
+	const events = [{
+		type: "start",
+		nodeId: queue[0] ?? ids[0],
+		message: `Count each task's prerequisites. Ready now (none left): ${queue.map(name).join(", ") || "nothing"}.`
+	}];
+	const done = /* @__PURE__ */ new Set();
+	while (queue.length) {
+		const next = queue[0];
+		const remaining = ids.filter((id) => !done.has(id)).sort(byId);
+		if (remaining.length > 1) decisions.push({
+			step: events.length - 1,
+			kind: "node",
+			prompt: "Which task is done next?",
+			options: remaining.map((id) => ({
+				value: id,
+				label: name(id)
+			})),
+			answer: next,
+			correct: "It is at the front of the ready queue: nothing it depends on is left.",
+			reasons: Object.fromEntries(remaining.filter((id) => id !== next).map((id) => {
+				if (indegree[id] > 0) {
+					const waiting = graph.edges.filter((edge) => edge.to === id && !done.has(edge.from)).map((edge) => edge.from).sort(byId)[0];
+					return [id, `${name(id)} still waits on ${plural(indegree[id], "task")}, including ${name(waiting)}.`];
+				}
+				return [id, `${name(id)} is ready too, but ${name(next)} joined the queue first.`];
+			}))
+		});
+		queue.shift();
+		done.add(next);
+		order.push(next);
+		events.push({
+			type: "emit-node",
+			nodeId: next,
+			queue: [...queue],
+			message: `Do ${name(next)} (#${order.length}). Ready queue: ${queue.map(name).join(", ") || "empty"}.`
+		});
+		for (const { edge, next: after } of successors(graph, next)) {
+			indegree[after] = indegree[after] - 1;
+			if (indegree[after] === 0) queue.push(after);
+			events.push({
+				type: "in-degree",
+				edgeId: edge.id,
+				nodeId: after,
+				next: indegree[after],
+				queue: [...queue],
+				message: indegree[after] === 0 ? `${name(after)} has no prerequisites left, so it joins the ready queue.` : `${name(after)} still waits on ${plural(indegree[after], "task")}.`
+			});
+		}
+	}
+	const stuck = ids.filter((id) => !done.has(id)).sort(byId);
+	if (!stuck.length) {
+		events.push({
+			type: "complete",
+			order,
+			message: `Order: ${order.map(name).join(" → ")}.`
+		});
+		return {
+			algorithm: "topo",
+			events,
+			order,
+			previous: {},
+			decisions
+		};
+	}
+	const { loop, blocked, loops } = splitStuck(graph, stuck);
+	const list = (group) => {
+		const names = group.map(name);
+		return names.length < 2 ? names.join("") : `${names.slice(0, -1).join(", ")} and ${names.at(-1)}`;
+	};
+	const ringEdges = graph.edges.filter((edge) => loops.some((c) => c.includes(edge.from) && c.includes(edge.to))).length;
+	const through = loops.length > 1 ? `${loops.length} separate loops` : ringEdges > loop.length ? "interlocking loops" : "a loop";
+	const loopText = loop.length === 1 ? `${name(loop[0])} waits on itself` : `${list(loop)} wait on each other through ${through}`;
+	const blockedText = blocked.length ? `; ${list(blocked)} ${blocked.length === 1 ? "is" : "are"} not on it but ${blocked.length === 1 ? "waits" : "wait"} downstream of it, so ${blocked.length === 1 ? "it is" : "they are"} blocked too` : "";
+	events.push({
+		type: "complete",
+		order,
+		cycle: stuck,
+		loop,
+		blocked,
+		message: `Stuck after ${order.length} of ${ids.length} tasks: ${loopText}${blockedText}. No order exists.`
+	});
+	return {
+		algorithm: "topo",
+		events,
+		order,
+		previous: {},
+		cycle: stuck,
+		loop,
+		blocked,
+		decisions
+	};
+}
+/**
+* Split the tasks Kahn's algorithm could not place into those ON a loop (a strongly connected
+* component of two or more, or a task that waits on itself) and those only blocked downstream of
+* one. Both lists keep the authored node order, which is the order a story lists its tasks in.
+*/
+function splitStuck(graph, stuck) {
+	const inside = new Set(stuck);
+	const next = (id) => successors(graph, id).map((arc) => arc.next).filter((to) => inside.has(to));
+	const index = /* @__PURE__ */ new Map();
+	const low = /* @__PURE__ */ new Map();
+	const onStack = /* @__PURE__ */ new Set();
+	const stack = [];
+	const onLoop = /* @__PURE__ */ new Set();
+	const loops = [];
+	let counter = 0;
+	const connect = (id) => {
+		index.set(id, counter);
+		low.set(id, counter);
+		counter++;
+		stack.push(id);
+		onStack.add(id);
+		for (const to of next(id)) if (!index.has(to)) {
+			connect(to);
+			low.set(id, Math.min(low.get(id), low.get(to)));
+		} else if (onStack.has(to)) low.set(id, Math.min(low.get(id), index.get(to)));
+		if (low.get(id) !== index.get(id)) return;
+		const component = [];
+		let member;
+		do {
+			member = stack.pop();
+			onStack.delete(member);
+			component.push(member);
+		} while (member !== id);
+		if (component.length > 1 || next(id).includes(id)) {
+			for (const node of component) onLoop.add(node);
+			loops.push(component);
+		}
+	};
+	for (const id of [...stuck].sort(byId)) if (!index.has(id)) connect(id);
+	const authored = graph.nodes.map((node) => node.id).filter((id) => inside.has(id));
+	return {
+		loop: authored.filter((id) => onLoop.has(id)),
+		blocked: authored.filter((id) => !onLoop.has(id)),
+		loops: loops.map((component) => authored.filter((id) => component.includes(id)))
+	};
+}
+/**
+* Cycle search by DFS colours. White: not seen. Grey: on the current path. Black: finished. An
+* edge into a grey node closes a cycle. Searches start at `source`, then at each still-white node
+* in id order.
+*/
+function detectCycle(graph, source) {
+	const name = namer(graph);
+	const ids = graph.nodes.map((node) => node.id);
+	const colour = Object.fromEntries(ids.map((id) => [id, "white"]));
+	const previous = {};
+	const path = [];
+	const order = [];
+	const decisions = [];
+	const events = [{
+		type: "start",
+		nodeId: source,
+		message: `Every task starts white (unseen). Search from ${name(source)}.`
+	}];
+	let cycle;
+	const ask = (answer, parent) => {
+		const whites = ids.filter((id) => colour[id] === "white").sort(byId);
+		if (!order.length || whites.length < 2) return;
+		decisions.push({
+			step: events.length - 1,
+			kind: "node",
+			prompt: "Which task turns grey next?",
+			options: whites.map((id) => ({
+				value: id,
+				label: name(id)
+			})),
+			answer,
+			correct: parent ? `DFS goes deeper: ${name(answer)} is the first unvisited successor of ${name(parent)}.` : `Nothing grey has an unvisited successor, so DFS restarts at ${name(answer)}.`,
+			reasons: Object.fromEntries(whites.filter((id) => id !== answer).map((id) => [id, parent ? `DFS goes deeper from ${name(parent)}: ${name(answer)} is its first successor still unvisited.` : `Every grey task is finished, so DFS restarts at the first unvisited task, ${name(answer)}.`]))
+		});
+	};
+	const visit = (node, parent) => {
+		colour[node] = "grey";
+		path.push(node);
+		order.push(node);
+		previous[node] = parent;
+		events.push({
+			type: "visit-node",
+			nodeId: node,
+			parent,
+			frontier: [...path],
+			message: parent ? `Enter ${name(node)} from ${name(parent)}: grey, on the current path.` : `Start a search at ${name(node)}: grey, on the current path.`
+		});
+		for (const { edge, next } of successors(graph, node)) {
+			if (colour[next] === "grey") {
+				const loop = path.slice(path.indexOf(next));
+				cycle = loop;
+				events.push({
+					type: "back-edge",
+					edgeId: edge.id,
+					from: node,
+					to: next,
+					cycle: loop,
+					message: `${name(next)} is grey, still on the current path, so ${name(node)} → ${name(next)} closes a cycle: ${[...loop, next].map(name).join(" → ")}.`
+				});
+				return;
+			}
+			if (colour[next] === "black") {
+				events.push({
+					type: "inspect-edge",
+					edgeId: edge.id,
+					from: node,
+					to: next,
+					message: `${name(next)} is already finished (black), so ${name(node)} → ${name(next)} cannot close a cycle.`
+				});
+				continue;
+			}
+			ask(next, node);
+			events.push({
+				type: "inspect-edge",
+				edgeId: edge.id,
+				from: node,
+				to: next,
+				message: `Follow ${name(node)} → ${name(next)}.`
+			});
+			visit(next, node);
+			if (cycle) return;
+		}
+		colour[node] = "black";
+		path.pop();
+		events.push({
+			type: "finish-node",
+			nodeId: node,
+			message: `${name(node)} is finished (black): nothing beyond it loops back.`
+		});
+	};
+	for (const root of [source, ...ids.filter((id) => id !== source).sort(byId)]) {
+		if (colour[root] !== "white") continue;
+		ask(root);
+		visit(root);
+		if (cycle) break;
+	}
+	const found = cycle;
+	events.push({
+		type: "complete",
+		order,
+		cycle: found,
+		message: found ? `Cycle found: ${[...found, found[0]].map(name).join(" → ")}. These tasks can never be put in order.` : "No cycle: every task finished without meeting a grey task, so a valid order exists."
+	});
+	return {
+		algorithm: "cycle",
+		events,
+		order,
+		previous,
+		cycle: found,
+		decisions
+	};
+}
+function runGraphAlgorithm(algorithm, graph, source, target, options = {}) {
+	switch (algorithm) {
+		case "bfs": return bfs(graph, source, target);
+		case "dfs": return dfs(graph, source, options.dfsOrder);
+		case "bellman-ford": return bellmanFord(graph, source, target);
+		case "prim": return prim(graph, source);
+		case "kruskal": return kruskal(graph);
+		case "topo": return topologicalSort(graph);
+		case "cycle": return detectCycle(graph, source);
+		default: return dijkstra(graph, source, target);
+	}
+}
+/**
+* Dijkstra's answer beside the true shortest route (Bellman-Ford), for a graph with a negative
+* edge. `truth` is undefined when a negative cycle makes "shortest" meaningless.
+*/
+function compareShortest(graph, source, target) {
+	const greedy = dijkstra(graph, source);
+	const exact = bellmanFord(graph, source);
+	const dPath = reconstructPath(greedy.previous, source, target);
+	const answer = {
+		cost: greedy.distance?.[target] ?? Infinity,
+		path: dPath
+	};
+	if (exact.negativeCycle) return {
+		dijkstra: answer,
+		agree: false
+	};
+	const truth = {
+		cost: exact.distance?.[target] ?? Infinity,
+		path: reconstructPath(exact.previous, source, target)
+	};
+	return {
+		dijkstra: answer,
+		truth,
+		agree: answer.cost === truth.cost
+	};
+}
+function graphStateAt(trace, graph, step) {
+	const first = trace.events[0];
+	const source = first?.type === "start" ? first.nodeId : graph.nodes[0]?.id;
+	const ids = graph.nodes.map((node) => node.id);
+	const algorithm = trace.algorithm;
+	const state = {
+		current: algorithm === "kruskal" || algorithm === "topo" ? void 0 : source,
+		visited: [],
+		discovered: source && algorithm !== "kruskal" && algorithm !== "topo" ? [source] : [],
+		frontier: source && (algorithm === "bfs" || algorithm === "dfs") ? [source] : [],
+		distances: algorithm === "dijkstra" || algorithm === "bellman-ford" || algorithm === "prim" ? Object.fromEntries(ids.map((id) => [id, id === source ? 0 : Infinity])) : void 0,
+		tree: [],
+		rejected: [],
+		cycleEdges: [],
+		ignored: []
+	};
+	if (algorithm === "prim" && source) state.visited.push(source);
+	if (algorithm === "kruskal") state.sets = ids.map((id) => [id]).sort((a, b) => byId(a[0], b[0]));
+	if (algorithm === "topo") {
+		const indegree = Object.fromEntries(ids.map((id) => [id, 0]));
+		for (const edge of graph.edges) indegree[edge.to] = (indegree[edge.to] ?? 0) + 1;
+		state.inDegree = indegree;
+		state.frontier = ids.filter((id) => indegree[id] === 0).sort(byId);
+	}
+	if (algorithm === "cycle") state.colour = Object.fromEntries(ids.map((id) => [id, "white"]));
+	const add = (list, id) => {
+		if (!list.includes(id)) list.push(id);
+	};
+	for (const event of trace.events.slice(0, step + 1)) switch (event.type) {
+		case "visit-node":
+			state.current = event.nodeId;
+			state.scanning = event.nodeId;
+			add(state.visited, event.nodeId);
+			add(state.discovered, event.nodeId);
+			state.frontier = event.frontier;
+			if (state.colour) state.colour[event.nodeId] = "grey";
+			break;
+		case "inspect-edge":
+			state.activeEdge = event.edgeId;
+			state.scanning = event.from;
+			if (algorithm === "bellman-ford") state.current = event.from;
+			break;
+		case "discover-node":
+			add(state.discovered, event.nodeId);
+			state.frontier = event.frontier;
+			break;
+		case "relax-edge":
+			if (state.distances) state.distances[event.nodeId] = event.next;
+			state.activeEdge = event.edgeId;
+			add(state.discovered, event.nodeId);
+			break;
+		case "skip-settled":
+			state.activeEdge = event.edgeId;
+			state.scanning = event.from;
+			add(state.ignored, event.edgeId);
+			break;
+		case "round":
+			state.round = event.round;
+			break;
+		case "negative-cycle":
+			state.activeEdge = event.edgeId;
+			state.cycleEdges = edgesAlong(graph, event.cycle, true);
+			break;
+		case "accept-edge":
+			state.activeEdge = event.edgeId;
+			add(state.tree, event.edgeId);
+			state.total = event.total;
+			if (event.sets) state.sets = event.sets;
+			if (event.nodeId) {
+				state.current = event.nodeId;
+				state.scanning = event.nodeId;
+				add(state.visited, event.nodeId);
+			} else {
+				add(state.visited, event.from);
+				add(state.visited, event.to);
+			}
+			break;
+		case "reject-edge":
+			state.activeEdge = event.edgeId;
+			add(state.rejected, event.edgeId);
+			break;
+		case "emit-node":
+			state.current = event.nodeId;
+			state.scanning = event.nodeId;
+			add(state.visited, event.nodeId);
+			state.frontier = event.queue;
+			break;
+		case "in-degree":
+			state.activeEdge = event.edgeId;
+			if (state.inDegree) state.inDegree[event.nodeId] = event.next;
+			state.frontier = event.queue;
+			break;
+		case "finish-node":
+			if (state.colour) state.colour[event.nodeId] = "black";
+			state.frontier = state.frontier.filter((id) => id !== event.nodeId);
+			if (algorithm === "dfs" && state.frontier.length) {
+				state.current = state.frontier.at(-1);
+				state.scanning = state.current;
+			}
+			break;
+		case "back-edge":
+			state.activeEdge = event.edgeId;
+			state.cycleEdges = edgesAlong(graph, event.cycle, true);
+			break;
+		case "complete": if (event.loop?.length) {
+			const loop = new Set(event.loop);
+			state.cycleEdges = graph.edges.filter((edge) => loop.has(edge.from) && loop.has(edge.to)).map((edge) => edge.id);
+		}
+	}
+	if (algorithm === "dijkstra" || algorithm === "prim") state.frontier = ids.filter((id) => !state.visited.includes(id) && Number.isFinite(state.distances[id])).sort((a, b) => state.distances[a] - state.distances[b] || byId(a, b));
+	return state;
+}
+/** Adjacency list rows: each node with its outgoing neighbours (both directions for undirected edges). */
+function adjacencyList(graph, mode = "as-drawn") {
+	return graph.nodes.map((node) => ({
+		id: node.id,
+		neighbours: (mode === "directed" ? successors(graph, node.id) : adjacency(graph, node.id)).map(({ edge, next }) => ({
+			id: next,
+			edgeId: edge.id,
+			weight: edge.weight
+		}))
+	}));
+}
+/** Adjacency matrix: cell [row][col] is the edge from row to col, or undefined. */
+function adjacencyMatrix(graph, mode = "as-drawn") {
+	const index = new Map(graph.nodes.map((node, i) => [node.id, i]));
+	const rows = graph.nodes.map(() => graph.nodes.map(() => void 0));
+	for (const row of adjacencyList(graph, mode)) for (const cell of row.neighbours) {
+		const r = index.get(row.id);
+		const c = index.get(cell.id);
+		rows[r][c] ??= {
+			edgeId: cell.edgeId,
+			weight: cell.weight
+		};
+	}
+	return rows;
+}
 
 //#endregion
-export { bfs, dfs, dijkstra, reconstructPath };
+export { adjacencyList, adjacencyMatrix, bellmanFord, bfs, compareShortest, detectCycle, dfs, dijkstra, edgesAlong, findEdge, formatWeight, graphStateAt, hasNegativeEdge, isWeighted, kruskal, pathWeight, prepareGraph, prim, reconstructPath, runGraphAlgorithm, splitStuck, topologicalSort };