@classytic/labs 0.3.0 → 0.5.0

package/dist/algorithms/HashLab.mjs

@@ -2,14 +2,19 @@
 
 import { AssessedChoiceGroup } from "../kit/controls.mjs";
 import { Activity } from "../kit/activity.mjs";
+import { FigText } from "../kit/figure/text.mjs";
+import { useCheckpoint } from "../kit/pedagogy.mjs";
+import { HASH_FUNCTION_LABEL, STRATEGY_LABEL, describeHash, hashTrace, lookupTrace } from "./hashing.mjs";
+import { resolveDataset } from "./worlds/index.mjs";
 import { TraceTransport } from "./TraceTransport.mjs";
 import { BinaryTransferCheck } from "./LearningChecks.mjs";
-import { hashTrace } from "./hashing.mjs";
+import { numericOptions, usePredictions } from "./ListLab.mjs";
 import { useEffect, useMemo, useState } from "react";
 import { Fragment as Fragment$1, jsx, jsxs } from "react/jsx-runtime";
 import { Check } from "lucide-react";
 
 //#region src/algorithms/HashLab.tsx
+const HASH_ACTIVITY_ID = "hash-table";
 const DEFAULT_KEYS = [
 	"mango",
 	"guava",
@@ -21,55 +26,168 @@ const DEFAULT_KEYS = [
 const SLOT_W = 104;
 const SLOT_H = 30;
 const LABEL_W = 34;
-function HashLab({ keys = DEFAULT_KEYS, buckets = 7, strategy = "chaining", predict = true, title, prompt }) {
-	const trace = useMemo(() => hashTrace(keys, buckets, strategy), [
-		keys,
+/** The prediction for one insertion: collide or not under FNV, where it lands under a hand hash. */
+function insertPrediction(step, index, fn, strategy) {
+	if (fn === "fnv" || step.slot === -1) return {
+		id: `insert-${index}`,
+		at: index,
+		prompt: `Next key is “${step.key}”. Its home is bucket ${step.home}. Will it collide?`,
+		options: [{
+			value: "yes",
+			label: "Yes"
+		}, {
+			value: "no",
+			label: "No"
+		}],
+		answer: step.collided ? "yes" : "no",
+		explain: (right) => right ? "Correct. Advance to place it." : `Look at whether bucket ${step.home} already holds something.`
+	};
+	const size = step.size;
+	const probing = strategy !== "chaining";
+	return {
+		id: `insert-${index}`,
+		at: index,
+		prompt: `Next key is “${step.key}”: ${describeHash(fn, step.key)}, and there are ${size} buckets. ${probing ? "Which bucket does it end up in?" : "Which bucket does it go in?"}`,
+		options: numericOptions(step.slot, [
+			step.home,
+			(step.home + 1) % size,
+			(step.slot + 1) % size,
+			step.hash % (size + 1),
+			0,
+			size - 1
+		]),
+		answer: String(step.slot),
+		explain: (right) => right ? step.collided ? `Correct. Its home ${step.home} was taken, so ${STRATEGY_LABEL[strategy]} put it in ${step.slot}.` : `Correct. ${step.hash} mod ${size} is ${step.home}.` : step.slot === step.home ? `It is ${step.home}: ${step.hash} mod ${size} is ${step.home}.` : `It is ${step.slot}: home ${step.home} (${step.hash} mod ${size}) was taken, and ${STRATEGY_LABEL[strategy]} tried ${step.path.join(", ")}.`
+	};
+}
+function lookupPrediction(found, trace, at) {
+	const chaining = trace.strategy === "chaining";
+	return {
+		id: "lookup",
+		at,
+		prompt: `Now look up “${found.key}”. How many ${chaining ? "keys in its chain" : "buckets"} are checked before the lookup ${found.found ? "finds it" : "can say it is absent"}?`,
+		options: numericOptions(found.probes, [
+			1,
+			found.probes + 1,
+			found.probes - 1,
+			trace.longestChain,
+			trace.size
+		]),
+		answer: String(found.probes),
+		explain: (right) => right ? `Correct. ${found.message}` : found.message
+	};
+}
+function HashLab({ keys: keysProp, dataset, buckets = 7, strategy = "chaining", hash = "fnv", resizeAt, lookup, predict = true, title, prompt }) {
+	const configKey = JSON.stringify([
+		keysProp,
+		dataset,
 		buckets,
-		strategy
+		strategy,
+		hash,
+		resizeAt,
+		lookup
+	]);
+	const found = resolveDataset(dataset, "keys");
+	const keys = keysProp ?? found?.keys ?? DEFAULT_KEYS;
+	const trace = useMemo(() => hashTrace(keys, buckets, strategy, {
+		hash,
+		resizeAt
+	}), [configKey]);
+	const search = useMemo(() => lookup ? lookupTrace(trace, lookup) : void 0, [trace, lookup]);
+	const total = trace.steps.length;
+	const lastStep = Math.max(0, total - 1);
+	const predictions = useMemo(() => {
+		if (!predict) return [];
+		const list = [];
+		trace.steps.forEach((step, index) => {
+			if (step.kind === "insert") list.push(insertPrediction(step, index, hash, strategy));
+		});
+		if (search) list.push(lookupPrediction(search, trace, lastStep));
+		return list;
+	}, [
+		trace,
+		search,
+		predict,
+		hash,
+		strategy,
+		lastStep
 	]);
 	const [step, setStep] = useState(0);
-	const [guess, setGuess] = useState();
+	const [attempt, setAttempt] = useState(0);
 	const [transferAnswer, setTransferAnswer] = useState();
+	const { picks, pick, right, allAnswered } = usePredictions(predictions, attempt);
 	useEffect(() => {
 		setStep(0);
-		setGuess(void 0);
 		setTransferAnswer(void 0);
-	}, [trace]);
-	useEffect(() => setGuess(void 0), [step]);
-	const total = trace.steps.length;
-	const current = trace.steps[Math.min(step, Math.max(0, total - 1))];
+		setAttempt((value) => value + 1);
+	}, [trace, predictions]);
+	const current = trace.steps[Math.min(step, lastStep)];
 	const complete = total === 0 || step >= total - 1;
-	const checkpoint = predict && !!current && step < total;
-	const shown = current?.buckets ?? trace.buckets;
-	const width = LABEL_W + Math.max(1, ...shown.map((bucket) => bucket.length)) * 110;
+	const insertQuestion = predictions.find((item) => item.id === `insert-${step}`);
+	const lookupQuestion = predictions.find((item) => item.id === "lookup");
+	const question = insertQuestion && picks[insertQuestion.id] === void 0 ? insertQuestion : complete && lookupQuestion ? lookupQuestion : insertQuestion;
+	const insertPending = insertQuestion !== void 0 && picks[insertQuestion.id] === void 0;
+	const before = step > 0 ? trace.steps[step - 1] : void 0;
+	const shownSize = insertPending ? before?.size ?? Math.max(1, Math.floor(buckets)) : current?.size ?? trace.size;
+	const shown = insertPending ? before?.buckets ?? Array.from({ length: shownSize }, () => []) : current?.buckets ?? trace.buckets;
+	const reveal = !insertPending;
+	const showLookup = complete && search && (!lookupQuestion || picks[lookupQuestion.id] !== void 0);
+	const lookupOrder = /* @__PURE__ */ new Map();
+	if (showLookup) search.path.forEach((look, order) => lookupOrder.has(look.slot) || lookupOrder.set(look.slot, order + 1));
+	const deepest = Math.max(1, ...shown.map((bucket) => bucket.length));
+	const width = LABEL_W + deepest * 110;
 	const height = shown.length * 36;
-	const placed = current ? trace.steps.indexOf(current) + 1 : 0;
-	const liveLoad = (placed / trace.size).toFixed(2);
+	const liveLoad = (shown.reduce((sum, bucket) => sum + bucket.length, 0) / Math.max(1, shown.length)).toFixed(2);
+	const collisionsSoFar = trace.steps.slice(0, reveal ? step + 1 : step).filter((item) => item.kind === "insert" && item.collided).length;
+	useCheckpoint({
+		solved: complete && allAnswered,
+		activity: HASH_ACTIVITY_ID,
+		score: predictions.length ? {
+			raw: right,
+			max: predictions.length
+		} : void 0,
+		response: `${keys.length} keys into ${Math.max(1, Math.floor(buckets))} buckets by ${HASH_FUNCTION_LABEL[hash]} with ${STRATEGY_LABEL[strategy]}: ${trace.collisions} collision${trace.collisions === 1 ? "" : "s"}, load factor ${trace.loadFactor.toFixed(2)}${trace.resizes ? `, ${trace.resizes} resize${trace.resizes === 1 ? "" : "s"}` : ""}${search ? `, lookup of ${search.key} took ${search.probes}` : ""}.${predictions.length ? ` ${right} of ${predictions.length} predictions right first time.` : ""}`,
+		attemptKey: attempt
+	});
+	const feedbackTitle = current?.kind === "resize" && reveal ? "Resize" : current?.collided && reveal ? "Collision" : complete ? "Result" : "Place";
+	const feedbackText = insertPending ? "Predict first, then advance to place it." : showLookup ? search.message : current?.message ?? "No keys to insert.";
 	return /* @__PURE__ */ jsxs(Activity.Root, {
 		className: "hash-quest algorithm-activity",
 		focusLayout: "immersive",
 		children: [
 			/* @__PURE__ */ jsxs(Activity.Header, { children: [/* @__PURE__ */ jsx(Activity.Heading, {
 				eyebrow: "Hash tables",
-				title: title ?? `${trace.size} buckets, ${keys.length} keys`,
-				description: prompt ?? "A hash turns a key into a bucket number. Watch what happens when two keys want the same bucket, and what that costs later."
+				title: title ?? `${Math.max(1, Math.floor(buckets))} buckets, ${keys.length} keys`,
+				description: prompt ?? found?.note ?? "A hash turns a key into a bucket number. Watch what happens when two keys want the same bucket, and what that costs later."
 			}), /* @__PURE__ */ jsx(Activity.FocusButton, {})] }),
 			/* @__PURE__ */ jsxs(Activity.Status, { children: [
+				hash !== "fnv" && /* @__PURE__ */ jsxs("span", {
+					className: "lab-chip",
+					children: ["Hash ", /* @__PURE__ */ jsx("strong", { children: HASH_FUNCTION_LABEL[hash] })]
+				}),
 				/* @__PURE__ */ jsxs("span", {
 					className: "lab-chip",
-					children: ["Strategy ", /* @__PURE__ */ jsx("strong", { children: strategy === "chaining" ? "chaining" : "linear probing" })]
+					children: ["Strategy ", /* @__PURE__ */ jsx("strong", { children: STRATEGY_LABEL[strategy] })]
 				}),
 				/* @__PURE__ */ jsxs("span", {
 					className: "lab-chip",
 					children: ["Load factor ", /* @__PURE__ */ jsx("strong", { children: liveLoad })]
 				}),
-				/* @__PURE__ */ jsxs("span", {
+				(resizeAt !== void 0 || shown.length !== buckets) && /* @__PURE__ */ jsxs("span", {
 					className: "lab-chip",
 					children: [
-						"Collisions so far",
-						" ",
-						/* @__PURE__ */ jsx("strong", { children: trace.steps.slice(0, placed).filter((item) => item.collided).length })
+						"Buckets ",
+						/* @__PURE__ */ jsx("strong", { children: shown.length }),
+						resizeAt !== void 0 && /* @__PURE__ */ jsxs(Fragment$1, { children: [
+							" (grows past ",
+							resizeAt,
+							")"
+						] })
 					]
+				}),
+				/* @__PURE__ */ jsxs("span", {
+					className: "lab-chip",
+					children: ["Collisions so far ", /* @__PURE__ */ jsx("strong", { children: collisionsSoFar })]
 				})
 			] }),
 			/* @__PURE__ */ jsxs(Activity.Workspace, { children: [/* @__PURE__ */ jsxs(Activity.Canvas, {
@@ -86,17 +204,28 @@ function HashLab({ keys = DEFAULT_KEYS, buckets = 7, strategy = "chaining", pred
 					"aria-label": shown.map((bucket, index) => `Bucket ${index}: ${bucket.length ? bucket.join(", ") : "empty"}`).join(". "),
 					children: shown.map((bucket, index) => {
 						const y = index * 36;
-						const isHome = current?.home === index;
-						const isSlot = current?.slot === index;
+						const isHome = current?.kind === "insert" && current.home === index && (reveal || hash === "fnv" || current.slot === -1);
+						const isSlot = reveal && current?.kind === "insert" && current.slot === index;
+						const order = lookupOrder.get(index);
+						const lit = isHome || order !== void 0;
 						return /* @__PURE__ */ jsxs("g", { children: [
-							/* @__PURE__ */ jsx("text", {
+							/* @__PURE__ */ jsx(FigText, {
 								x: 0,
 								y: y + SLOT_H / 2 + 4,
-								fontSize: 12,
-								fill: "currentColor",
+								size: "note",
+								color: "currentColor",
 								opacity: .6,
 								children: index
 							}),
+							order !== void 0 && /* @__PURE__ */ jsx(FigText, {
+								x: 28,
+								y: y + SLOT_H / 2 + 4,
+								anchor: "end",
+								size: "note",
+								weight: "bold",
+								color: "var(--stage-accent)",
+								children: order
+							}),
 							/* @__PURE__ */ jsx("rect", {
 								x: LABEL_W,
 								y,
@@ -104,57 +233,52 @@ function HashLab({ keys = DEFAULT_KEYS, buckets = 7, strategy = "chaining", pred
 								height: SLOT_H,
 								rx: 5,
 								fill: "none",
-								stroke: isHome ? "var(--stage-accent, #6366f1)" : "var(--stage-wire, #94a3b8)",
-								strokeWidth: isHome ? 2 : 1,
+								stroke: lit ? "var(--stage-accent)" : "var(--stage-wire)",
+								strokeWidth: lit ? 2 : 1,
 								strokeDasharray: bucket.length ? void 0 : "3 3",
-								opacity: isHome ? 1 : .5
+								opacity: lit ? 1 : .5
 							}),
 							bucket.map((key, depth) => {
 								const x = LABEL_W + depth * 110;
 								const fresh = isSlot && key === current?.key;
+								const looked = showLookup && order !== void 0 && key === search.key;
 								return /* @__PURE__ */ jsxs("g", { children: [/* @__PURE__ */ jsx("rect", {
 									x,
 									y,
 									width: SLOT_W,
 									height: SLOT_H,
 									rx: 5,
-									fill: fresh ? current?.collided ? "var(--stage-warn, #f59e0b)" : "var(--stage-live, #22c55e)" : "var(--stage-wire, #94a3b8)",
-									opacity: fresh ? 1 : .45
-								}), /* @__PURE__ */ jsx("text", {
+									fill: fresh ? current?.collided ? "var(--stage-warn)" : "var(--stage-live)" : looked ? "var(--stage-accent)" : "var(--stage-wire)",
+									opacity: fresh || looked ? 1 : .45
+								}), /* @__PURE__ */ jsx(FigText, {
 									x: x + SLOT_W / 2,
 									y: y + SLOT_H / 2 + 4,
-									textAnchor: "middle",
-									fontSize: 12,
-									fontWeight: fresh ? 700 : 500,
-									fill: "currentColor",
+									anchor: "middle",
+									size: "note",
+									weight: fresh || looked ? "bold" : "medium",
+									tone: "inverse",
 									children: key
 								})] }, key);
 							})
 						] }, index);
 					})
-				}), checkpoint && current && /* @__PURE__ */ jsxs("div", {
+				}), question && /* @__PURE__ */ jsxs("div", {
 					className: "tree-prediction",
 					children: [
-						/* @__PURE__ */ jsxs("span", { children: [
-							"Next key is “",
-							current.key,
-							"”. Its home is bucket ",
-							current.home,
-							". Will it collide?"
-						] }),
+						/* @__PURE__ */ jsx("span", { children: question.prompt }),
 						/* @__PURE__ */ jsx(AssessedChoiceGroup, {
-							value: guess,
-							onChange: setGuess,
-							ariaLabel: `Will ${current.key} collide in bucket ${current.home}?`,
-							options: ["yes", "no"].map((choice) => ({
-								value: choice,
-								label: choice === "yes" ? "Yes" : "No",
-								tone: guess === choice ? choice === "yes" === current.collided ? "correct" : "wrong" : void 0
+							value: picks[question.id],
+							onChange: (value) => pick(question, value),
+							ariaLabel: question.prompt,
+							options: question.options.map((option) => ({
+								value: option.value,
+								label: option.label,
+								tone: picks[question.id] === option.value ? option.value === question.answer ? "correct" : "wrong" : void 0
 							}))
 						}),
-						guess && /* @__PURE__ */ jsx("small", {
+						picks[question.id] !== void 0 && /* @__PURE__ */ jsxs("small", {
 							"aria-live": "polite",
-							children: guess === "yes" === current.collided ? /* @__PURE__ */ jsxs(Fragment$1, { children: [/* @__PURE__ */ jsx(Check, { "aria-hidden": "true" }), " Correct. Advance to place it."] }) : "Look at whether bucket " + current.home + " already holds something."
+							children: [picks[question.id] === question.answer && /* @__PURE__ */ jsx(Check, { "aria-hidden": "true" }), question.explain(picks[question.id] === question.answer)]
 						})
 					]
 				})]
@@ -166,8 +290,18 @@ function HashLab({ keys = DEFAULT_KEYS, buckets = 7, strategy = "chaining", pred
 						/* @__PURE__ */ jsxs("div", { children: [/* @__PURE__ */ jsx("dt", { children: "Load factor" }), /* @__PURE__ */ jsx("dd", { children: trace.loadFactor.toFixed(2) })] }),
 						/* @__PURE__ */ jsxs("div", { children: [/* @__PURE__ */ jsx("dt", { children: "Collisions" }), /* @__PURE__ */ jsx("dd", { children: trace.collisions })] }),
 						/* @__PURE__ */ jsxs("div", { children: [/* @__PURE__ */ jsx("dt", { children: strategy === "chaining" ? "Longest chain" : "Average probes" }), /* @__PURE__ */ jsx("dd", { children: strategy === "chaining" ? trace.longestChain : trace.averageProbes.toFixed(2) })] }),
+						trace.resizes > 0 && /* @__PURE__ */ jsxs("div", { children: [/* @__PURE__ */ jsx("dt", { children: "Resizes" }), /* @__PURE__ */ jsxs("dd", { children: [
+							trace.resizes,
+							", now ",
+							trace.size,
+							" buckets"
+						] })] }),
 						trace.dropped.length > 0 && /* @__PURE__ */ jsxs("div", { children: [/* @__PURE__ */ jsx("dt", { children: "Did not fit" }), /* @__PURE__ */ jsx("dd", { children: trace.dropped.join(", ") })] })
-					] })] }), /* @__PURE__ */ jsxs("section", { children: [/* @__PURE__ */ jsx("h4", { children: "Why it matters" }), /* @__PURE__ */ jsx("p", { children: strategy === "chaining" ? "A lookup checks one bucket, then walks its chain. The longest chain is the worst case, so it is the chain length, not the table size, that decides speed." : "A lookup probes forward until it finds the key or an empty slot. As the table fills, runs of full slots join up and probes climb sharply." })] })]
+					] })] }), /* @__PURE__ */ jsxs("section", { children: [
+						/* @__PURE__ */ jsx("h4", { children: "Why it matters" }),
+						/* @__PURE__ */ jsx("p", { children: strategy === "chaining" ? "A lookup checks one bucket, then walks its chain. The longest chain is the worst case, so it is the chain length, not the table size, that decides speed." : strategy === "linear-probing" ? "A lookup probes forward until it finds the key or an empty slot. As the table fills, runs of full slots join up and probes climb sharply." : strategy === "quadratic" ? "Quadratic probing jumps 1, 4, 9 slots from home, so runs of full slots stop joining up. The price: its jumps can miss free slots, so keep the table under half full." : "Double hashing steps by a second hash of the key, so two keys that collide at home usually part ways at once. Keys with the SAME hash value still share every step." }),
+						hash !== "fnv" && /* @__PURE__ */ jsx("p", { children: hash === "first-char" ? "A first-character hash has at most a few dozen outputs, and keys that share a prefix, like phone numbers that all start \"01\", share one bucket however large the table is." : hash === "length" ? "A length hash sends every key of the same length to the same bucket. Real keys cluster in length, so it clusters too." : "Reading the digits as a number and taking it mod the table size spreads keys well, if the table size is not a factor the numbers have in common." })
+					] })]
 				})
 			})] }),
 			complete && /* @__PURE__ */ jsx(BinaryTransferCheck, {
@@ -179,21 +313,21 @@ function HashLab({ keys = DEFAULT_KEYS, buckets = 7, strategy = "chaining", pred
 				correctFeedback: "Right. More buckets lowers the load factor and collisions fall on average, but a hash that spreads keys badly can still pile them into one bucket however large the table is.",
 				retryFeedback: "Think about a hash that returns the same number for every key. What would more buckets change?"
 			}),
-			/* @__PURE__ */ jsxs(Activity.Feedback, { children: [/* @__PURE__ */ jsx("strong", { children: current?.collided ? "Collision" : complete ? "Result" : "Place" }), /* @__PURE__ */ jsx("span", { children: current?.message ?? "No keys to insert." })] }),
-			/* @__PURE__ */ jsx(Activity.Transcript, { children: /* @__PURE__ */ jsx("ol", { children: trace.steps.map((item, index) => /* @__PURE__ */ jsx("li", {
+			/* @__PURE__ */ jsxs(Activity.Feedback, { children: [/* @__PURE__ */ jsx("strong", { children: feedbackTitle }), /* @__PURE__ */ jsx("span", { children: feedbackText })] }),
+			/* @__PURE__ */ jsx(Activity.Transcript, { children: /* @__PURE__ */ jsxs("ol", { children: [trace.steps.map((item, index) => /* @__PURE__ */ jsx("li", {
 				"data-current": index === step || void 0,
 				children: item.message
-			}, index)) }) }),
+			}, index)), search && /* @__PURE__ */ jsx("li", { children: search.message })] }) }),
 			/* @__PURE__ */ jsx(TraceTransport, {
 				step,
 				count: Math.max(total, 1),
-				message: current?.message ?? "",
+				message: feedbackText,
 				setStep,
-				canAdvance: !checkpoint || Boolean(guess)
+				canAdvance: !insertPending
 			})
 		]
 	});
 }
 
 //#endregion
-export { HashLab };
+export { HASH_ACTIVITY_ID, HashLab };

package/dist/algorithms/HeapDualView.d.mts

@@ -1,17 +1,29 @@
 import { SequenceItem } from "./sequence-contract.mjs";
 import { HeapEvent } from "./heap.mjs";
-
 //#region src/algorithms/HeapDualView.d.ts
-declare function HeapDualView({
-  items,
-  event,
-  selectedId,
-  onSelect
-}: {
+interface HeapTreeLayout {
+  width: number;
+  height: number;
+  points: {
+    x: number;
+    y: number;
+    depth: number;
+  }[];
+}
+/** Level-by-level positions for a heap of `count` items: slot i of depth d is centred in its span. */
+declare function heapTreeLayout(count: number): HeapTreeLayout;
+/**
+ * The short tag drawn under a tree node: the parcel kind or the area name. `#P105 oxygen, Gulshan`
+ * becomes `oxygen`; anything longer than 9 characters is cut with an ellipsis.
+ */
+declare function heapTag(label: string | undefined): string | undefined;
+declare function HeapDualView({ items, event, heapSize, selectedId, onSelect }: {
   items: SequenceItem[];
   event: HeapEvent;
+  /** Items at or beyond this index are the heapsort's sorted tail, drawn in the array only. */
+  heapSize?: number;
   selectedId?: string;
   onSelect: (id: string) => void;
 }): import("react").JSX.Element;
 //#endregion
-export { HeapDualView };
+export { HeapDualView, HeapTreeLayout, heapTag, heapTreeLayout };

package/dist/algorithms/HeapDualView.mjs

@@ -1,34 +1,62 @@
+import { FigText } from "../kit/figure/text.mjs";
 import { jsx, jsxs } from "react/jsx-runtime";
 import { Button } from "@/components/ui/button";
 
 //#region src/algorithms/HeapDualView.tsx
-const positionAt = (index, count) => {
-	const depth = Math.floor(Math.log2(index + 1));
-	const slot = index - (2 ** depth - 1);
-	const slots = 2 ** depth;
-	const maxDepth = Math.max(1, Math.floor(Math.log2(Math.max(1, count))));
+const R = 16;
+const SLOT = 64;
+const LEVEL = 70;
+const PAD_Y = 30;
+const TAG_CHARS = 9;
+/** Level-by-level positions for a heap of `count` items: slot i of depth d is centred in its span. */
+function heapTreeLayout(count) {
+	const maxDepth = count > 1 ? Math.floor(Math.log2(count)) : 0;
+	const width = Math.max(4, 2 ** maxDepth) * SLOT;
+	const points = Array.from({ length: count }, (_, index) => {
+		const depth = Math.floor(Math.log2(index + 1));
+		return {
+			x: (index - (2 ** depth - 1) + .5) / 2 ** depth * width,
+			y: PAD_Y + depth * LEVEL,
+			depth
+		};
+	});
 	return {
-		x: (slot + .5) / slots * 92 + 4,
-		y: 12 + depth / maxDepth * 72
+		width,
+		height: PAD_Y + maxDepth * LEVEL + 56,
+		points
 	};
-};
-function HeapDualView({ items, event, selectedId, onSelect }) {
-	const active = new Set(event.type === "sequence-compare" || event.type === "sequence-swap" ? event.indices : event.type === "heap-append" ? [event.index] : event.type === "heap-move-last" ? [event.to] : []);
+}
+/**
+* The short tag drawn under a tree node: the parcel kind or the area name. `#P105 oxygen, Gulshan`
+* becomes `oxygen`; anything longer than 9 characters is cut with an ellipsis.
+*/
+function heapTag(label) {
+	if (!label) return void 0;
+	const core = label.replace(/^#\S+\s+/, "").split(",")[0].trim() || label.trim();
+	return core.length > TAG_CHARS ? `${core.slice(0, 8)}…` : core;
+}
+function HeapDualView({ items, event, heapSize = items.length, selectedId, onSelect }) {
+	const active = new Set(event.type === "sequence-compare" || event.type === "sequence-swap" ? event.indices : event.type === "heap-append" || event.type === "heap-update" ? [event.index] : event.type === "heap-move-last" ? [event.to] : event.type === "heap-place-sorted" ? [0, event.to] : []);
+	const size = Math.max(0, Math.min(heapSize, items.length));
+	const heap = items.slice(0, size);
+	const layout = heapTreeLayout(Math.max(1, heap.length));
+	const labelled = items.some((item) => item.label);
 	return /* @__PURE__ */ jsxs("div", {
 		className: "heap-dual-view",
+		"data-labelled": labelled || void 0,
 		children: [
 			/* @__PURE__ */ jsx("div", {
 				className: "heap-tree",
 				children: /* @__PURE__ */ jsxs("svg", {
 					className: "algorithm-scene-svg",
-					viewBox: "0 0 100 100",
+					viewBox: `0 0 ${layout.width} ${layout.height}`,
 					role: "img",
-					"aria-label": `Heap tree with ${items.length} items`,
-					children: [items.slice(1).map((_item, index) => {
+					"aria-label": `Heap tree with ${heap.length} items`,
+					children: [heap.slice(1).map((_item, index) => {
 						const child = index + 1;
 						const parent = Math.floor((child - 1) / 2);
-						const a = positionAt(parent, items.length);
-						const b = positionAt(child, items.length);
+						const a = layout.points[parent];
+						const b = layout.points[child];
 						return /* @__PURE__ */ jsx("line", {
 							x1: a.x,
 							y1: a.y,
@@ -36,8 +64,9 @@ function HeapDualView({ items, event, selectedId, onSelect }) {
 							y2: b.y,
 							"data-active": active.has(parent) && active.has(child) || void 0
 						}, `edge-${child}`);
-					}), items.map((item, index) => {
-						const at = positionAt(index, items.length);
+					}), heap.map((item, index) => {
+						const at = layout.points[index];
+						const tag = heapTag(item.label);
 						return /* @__PURE__ */ jsxs("g", {
 							className: "heap-node",
 							transform: `translate(${at.x} ${at.y})`,
@@ -45,7 +74,7 @@ function HeapDualView({ items, event, selectedId, onSelect }) {
 							"data-selected": selectedId === item.id || void 0,
 							role: "button",
 							tabIndex: 0,
-							"aria-label": `Heap item ${item.value}, array index ${index}`,
+							"aria-label": `Heap item ${item.label ? `${item.label}, priority ` : ""}${item.value}, array index ${index}`,
 							onClick: () => onSelect(item.id),
 							onKeyDown: (key) => {
 								if (key.key === "Enter" || key.key === " ") {
@@ -54,22 +83,37 @@ function HeapDualView({ items, event, selectedId, onSelect }) {
 								}
 							},
 							children: [
-								/* @__PURE__ */ jsx("circle", { r: "6" }),
-								/* @__PURE__ */ jsx("text", {
+								/* @__PURE__ */ jsx("circle", { r: R }),
+								/* @__PURE__ */ jsx(FigText, {
+									x: 0,
+									y: 0,
 									className: "algorithm-scene-label",
-									textAnchor: "middle",
-									dominantBaseline: "central",
+									anchor: "middle",
+									baseline: "middle",
+									caps: false,
 									children: item.value
 								}),
-								/* @__PURE__ */ jsxs("text", {
+								/* @__PURE__ */ jsxs(FigText, {
+									x: 0,
+									y: 27,
 									className: "heap-node-index algorithm-scene-meta",
-									textAnchor: "middle",
-									y: "10.5",
+									anchor: "middle",
+									size: "note",
+									caps: false,
 									children: [
 										"[",
 										index,
 										"]"
 									]
+								}),
+								tag && /* @__PURE__ */ jsxs(FigText, {
+									x: 0,
+									y: 40,
+									className: "heap-node-tag",
+									anchor: "middle",
+									size: "note",
+									caps: false,
+									children: [/* @__PURE__ */ jsx("title", { children: item.label }), tag]
 								})
 							]
 						}, item.id);
@@ -86,16 +130,33 @@ function HeapDualView({ items, event, selectedId, onSelect }) {
 					size: "sm",
 					"data-active": active.has(index) || void 0,
 					"data-selected": selectedId === item.id || void 0,
+					"data-sorted": index >= size || void 0,
+					title: item.label,
 					onClick: () => onSelect(item.id),
-					children: [/* @__PURE__ */ jsx("small", { children: index }), /* @__PURE__ */ jsx("strong", { children: item.value })]
+					children: [
+						/* @__PURE__ */ jsx("small", { children: index }),
+						/* @__PURE__ */ jsx("strong", { children: item.value }),
+						item.label && /* @__PURE__ */ jsx("em", {
+							className: "heap-array-label",
+							children: heapTag(item.label)
+						})
+					]
 				}, item.id))
 			}),
 			/* @__PURE__ */ jsxs("div", {
 				className: "heap-relation",
 				children: [selectedId ? (() => {
 					const index = items.findIndex((item) => item.id === selectedId);
+					const item = items[index];
+					if (!item) return /* @__PURE__ */ jsx("span", { children: "Select a tree node or array cell to reveal its index relationship." });
+					if (index >= size) return /* @__PURE__ */ jsxs("span", { children: [
+						"index ",
+						index,
+						" · already in the sorted tail",
+						item.label ? ` · ${item.label}` : ""
+					] });
 					const parent = index > 0 ? Math.floor((index - 1) / 2) : void 0;
-					return parent == null ? /* @__PURE__ */ jsx("span", { children: "index 0 · root has no parent" }) : /* @__PURE__ */ jsxs("span", { children: [
+					return parent == null ? /* @__PURE__ */ jsxs("span", { children: ["index 0 · root has no parent", item.label ? ` · ${item.label}` : ""] }) : /* @__PURE__ */ jsxs("span", { children: [
 						"index ",
 						index,
 						" → parent ⌊(",
@@ -103,7 +164,8 @@ function HeapDualView({ items, event, selectedId, onSelect }) {
 						"−1)/2⌋ = ",
 						parent,
 						" → value ",
-						items[parent]?.value
+						items[parent]?.value,
+						item.label ? ` · ${item.label}` : ""
 					] });
 				})() : /* @__PURE__ */ jsx("span", { children: "Select a tree node or array cell to reveal its index relationship." }), /* @__PURE__ */ jsx("b", { children: "0-based" })]
 			})
@@ -112,4 +174,4 @@ function HeapDualView({ items, event, selectedId, onSelect }) {
 }
 
 //#endregion
-export { HeapDualView };
+export { HeapDualView, heapTag, heapTreeLayout };