@classytic/labs 0.2.0 → 0.3.0

package/dist/domains/ml/embedding-space/runtime.mjs

@@ -0,0 +1,366 @@
+'use client';
+
+import { Segmented, Slider } from "../../../kit/controls.mjs";
+import { Field, LiveRegion } from "../../../kit/frame.mjs";
+import { ChallengeCard, HintLadder, useChallenge, useCheckpoint, useHints } from "../../../kit/pedagogy.mjs";
+import { MLActivity, MLResetTransport } from "../activity.mjs";
+import { DEFAULT_EMBEDDING_ITEMS, analogyTarget, rankBy } from "./embedding.mjs";
+import { useCallback, useMemo, useState } from "react";
+import { Fragment as Fragment$1, jsx, jsxs } from "react/jsx-runtime";
+
+//#region src/domains/ml/embedding-space/runtime.tsx
+/**
+* EmbeddingSpaceLab — meaning as geometry, which is the idea the whole modern stack rests on.
+*
+* The most-downloaded model on Hugging Face is not a chatbot. It is all-MiniLM-L6-v2, an 80MB
+* model whose only job is to turn a piece of text into a list of numbers so that similar text
+* lands nearby. Semantic search, RAG and recommendation all run on that one trick, so a student
+* who understands this picture understands the plumbing of most AI products they touch.
+*
+* The map here is 2D so it can be seen. A real embedding has hundreds of dimensions, and the lab
+* says so rather than pretending otherwise. What survives the reduction is the part that matters:
+* similarity is distance, and direction carries meaning, which is why vector arithmetic works.
+*
+* Both metrics are shown at once on purpose. Production uses cosine because vector length carries
+* no meaning there, and a learner who only ever sees one number cannot tell which property of the
+* picture is doing the work.
+*/
+const DEFAULT_ITEMS = DEFAULT_EMBEDDING_ITEMS;
+const GROUP_COLOR = {
+	people: "#6366f1",
+	animals: "#16a34a",
+	vehicles: "#ea580c",
+	food: "#c026d3"
+};
+const colorOf = (group) => GROUP_COLOR[group ?? ""] ?? "#64748b";
+const TRANSFER = [{
+	id: "why-cosine",
+	prompt: "A search engine embeds a one-line question and a long article. Why is cosine used rather than distance?",
+	choices: [
+		{
+			value: "angle",
+			label: "cosine compares direction, so length does not count against the long text"
+		},
+		{
+			value: "fast",
+			label: "cosine is faster to compute"
+		},
+		{
+			value: "accurate",
+			label: "cosine is always more accurate"
+		}
+	],
+	answer: "angle",
+	explain: "A long document tends to produce a longer vector. Distance would push it away from a short query for a reason that has nothing to do with meaning, while the angle between them is unaffected."
+}];
+function EmbeddingSpaceLab({ items = DEFAULT_ITEMS, query = "cat", k = 3, mode = "nearest", analogy = [
+	"king",
+	"man",
+	"woman"
+], metric = "cosine", title = "Meaning as a place on a map", prompt, objectives, hints: hintList, height = 340 }) {
+	const pool = items.length ? items : DEFAULT_ITEMS;
+	const [current, setCurrent] = useState(mode);
+	const [selected, setSelected] = useState(() => pool.find((i) => i.label === query)?.label ?? pool[0].label);
+	const [kk, setKk] = useState(k);
+	const [metricNow, setMetricNow] = useState(metric);
+	const [moved, setMoved] = useState(false);
+	const hints = useHints(hintList);
+	const challenge = useChallenge(TRANSFER);
+	const byLabel = useMemo(() => new Map(pool.map((i) => [i.label, i])), [pool]);
+	const queryItem = byLabel.get(selected) ?? pool[0];
+	const [aLabel, bLabel, cLabel] = analogy;
+	const resolved = useMemo(() => analogyTarget(pool, aLabel ?? "", bLabel ?? "", cLabel ?? ""), [
+		pool,
+		aLabel,
+		bLabel,
+		cLabel
+	]);
+	const a = byLabel.get(aLabel ?? "");
+	const b = byLabel.get(bLabel ?? "");
+	const c = byLabel.get(cLabel ?? "");
+	const analogyOk = current === "analogy" && !!resolved;
+	const target = analogyOk ? resolved.target : queryItem;
+	const exclude = analogyOk ? resolved.exclude : [selected];
+	const ranked = useMemo(() => rankBy(pool, target, metricNow, exclude), [
+		pool,
+		target,
+		metricNow,
+		exclude.join("|")
+	]);
+	const top = ranked.slice(0, Math.max(1, kk));
+	const best = top[0];
+	useCheckpoint({
+		solved: moved && challenge.allCorrect,
+		activity: `embedding:${title}`,
+		hintsUsed: hints.count
+	});
+	const pad = 1.4;
+	const xs = pool.map((i) => i.x).concat(target.x);
+	const ys = pool.map((i) => i.y).concat(target.y);
+	const xMin = Math.min(...xs) - pad;
+	const xMax = Math.max(...xs) + pad;
+	const yMin = Math.min(...ys) - pad;
+	const yMax = Math.max(...ys) + pad;
+	const W = 560;
+	const H = height;
+	const PAD_L = 14;
+	const PAD_R = 118;
+	const PAD_Y = 18;
+	const px = (x) => PAD_L + (x - xMin) / (xMax - xMin) * (W - PAD_L - PAD_R);
+	const py = (y) => H - PAD_Y - (y - yMin) / (yMax - yMin) * (H - PAD_Y * 2);
+	/**
+	* In analogy mode only the winner gets a link. The runners-up are correct by cosine and are
+	* visual noise: long dashed lines reaching across the map to unrelated words, which read as a
+	* claim that those words are related when the point being made is about one landing place.
+	*/
+	const linked = analogyOk ? ranked.slice(0, 1) : ranked.slice(0, Math.max(1, kk));
+	const select = useCallback((label) => {
+		setSelected(label);
+		setMoved(true);
+	}, []);
+	const figure = /* @__PURE__ */ jsx("div", {
+		className: "ml-interactive-scene",
+		children: /* @__PURE__ */ jsxs("svg", {
+			viewBox: `0 0 ${W} ${H}`,
+			style: {
+				width: "100%",
+				maxWidth: W,
+				margin: "0 auto",
+				display: "block"
+			},
+			role: "img",
+			"aria-label": `Embedding map. ${analogyOk ? `Analogy target ${target.label}` : `Query ${selected}`}. Nearest: ${top.map((t) => t.item.label).join(", ")}.`,
+			children: [
+				/* @__PURE__ */ jsx("line", {
+					x1: px(xMin),
+					y1: py(0),
+					x2: px(xMax),
+					y2: py(0),
+					stroke: "currentColor",
+					opacity: .15
+				}),
+				/* @__PURE__ */ jsx("line", {
+					x1: px(0),
+					y1: py(yMin),
+					x2: px(0),
+					y2: py(yMax),
+					stroke: "currentColor",
+					opacity: .15
+				}),
+				linked.map((entry) => /* @__PURE__ */ jsx("line", {
+					x1: px(target.x),
+					y1: py(target.y),
+					x2: px(entry.item.x),
+					y2: py(entry.item.y),
+					stroke: "currentColor",
+					strokeDasharray: "4 3",
+					opacity: .45
+				}, `link-${entry.item.label}`)),
+				analogyOk && /* @__PURE__ */ jsxs(Fragment$1, { children: [/* @__PURE__ */ jsx("line", {
+					x1: px(b.x),
+					y1: py(b.y),
+					x2: px(a.x),
+					y2: py(a.y),
+					stroke: "var(--stage-accent, #6366f1)",
+					strokeWidth: 2
+				}), /* @__PURE__ */ jsx("line", {
+					x1: px(c.x),
+					y1: py(c.y),
+					x2: px(target.x),
+					y2: py(target.y),
+					stroke: "var(--stage-accent, #6366f1)",
+					strokeWidth: 2,
+					strokeDasharray: "5 3"
+				})] }),
+				pool.map((item) => {
+					const isTop = top.some((t) => t.item.label === item.label);
+					const isQuery = !analogyOk && item.label === selected;
+					const isInput = analogyOk && exclude.includes(item.label);
+					return /* @__PURE__ */ jsxs("g", {
+						onClick: () => select(item.label),
+						style: { cursor: "pointer" },
+						children: [/* @__PURE__ */ jsx("circle", {
+							cx: px(item.x),
+							cy: py(item.y),
+							r: isQuery ? 8 : 5.5,
+							fill: colorOf(item.group),
+							opacity: isQuery || isTop || isInput ? 1 : .45,
+							stroke: isQuery ? "currentColor" : "none",
+							strokeWidth: 2
+						}), /* @__PURE__ */ jsx("text", {
+							x: px(item.x) + 9,
+							y: py(item.y) + 4,
+							fontSize: 12,
+							fill: "currentColor",
+							fontWeight: isQuery || isTop ? 700 : 400,
+							opacity: isQuery || isTop || isInput ? 1 : .6,
+							stroke: "var(--stage-bg, #fff)",
+							strokeWidth: 3.5,
+							paintOrder: "stroke",
+							children: item.label
+						})]
+					}, item.label);
+				}),
+				analogyOk && /* @__PURE__ */ jsxs(Fragment$1, { children: [/* @__PURE__ */ jsx("circle", {
+					cx: px(target.x),
+					cy: py(target.y),
+					r: 9,
+					fill: "none",
+					stroke: "var(--stage-accent, #6366f1)",
+					strokeWidth: 2.5
+				}), /* @__PURE__ */ jsx("text", {
+					x: px(target.x),
+					y: py(target.y) - 16,
+					textAnchor: "middle",
+					fontSize: 11,
+					fill: "var(--stage-accent, #6366f1)",
+					fontWeight: 700,
+					stroke: "var(--stage-bg, #fff)",
+					strokeWidth: 3.5,
+					paintOrder: "stroke",
+					children: "landing point"
+				})] })
+			]
+		})
+	});
+	const instruments = /* @__PURE__ */ jsxs("div", {
+		className: "ml-readout",
+		children: [
+			/* @__PURE__ */ jsx("span", {
+				className: "lab-field-label",
+				children: analogyOk ? "Nearest to the landing point" : `Nearest to “${selected}”`
+			}),
+			/* @__PURE__ */ jsx("ol", {
+				style: {
+					margin: "4px 0 8px",
+					paddingLeft: 18
+				},
+				children: top.map((entry) => /* @__PURE__ */ jsxs("li", {
+					style: { fontSize: 13 },
+					children: [
+						/* @__PURE__ */ jsx("strong", { children: entry.item.label }),
+						" ",
+						/* @__PURE__ */ jsxs("span", {
+							style: { opacity: .7 },
+							children: [
+								"cos ",
+								entry.cos.toFixed(3),
+								" · dist ",
+								entry.dist.toFixed(2)
+							]
+						})
+					]
+				}, entry.item.label))
+			}),
+			/* @__PURE__ */ jsx("p", {
+				className: "ml-control-hint",
+				children: "Both numbers are shown so you can see which one the ranking is using. Cosine compares direction from the origin; distance compares position."
+			}),
+			/* @__PURE__ */ jsx("p", {
+				className: "ml-control-hint",
+				children: "This map is 2D so it can be drawn. A real embedding from a model like all-MiniLM-L6-v2 has 384 dimensions, and the same two measurements are used there."
+			})
+		]
+	});
+	const controls = /* @__PURE__ */ jsxs(Fragment$1, { children: [
+		/* @__PURE__ */ jsxs("div", {
+			className: "lab-segmented-field",
+			children: [/* @__PURE__ */ jsx("span", {
+				className: "lab-field-label",
+				children: "Question"
+			}), /* @__PURE__ */ jsx(Segmented, {
+				ariaLabel: "question",
+				value: current,
+				onChange: (value) => {
+					setCurrent(value);
+					setMoved(true);
+				},
+				options: [{
+					value: "nearest",
+					label: "nearest"
+				}, {
+					value: "analogy",
+					label: "analogy"
+				}]
+			})]
+		}),
+		/* @__PURE__ */ jsxs("div", {
+			className: "lab-segmented-field",
+			children: [/* @__PURE__ */ jsx("span", {
+				className: "lab-field-label",
+				children: "Rank by"
+			}), /* @__PURE__ */ jsx(Segmented, {
+				ariaLabel: "metric",
+				value: metricNow,
+				onChange: (value) => {
+					setMetricNow(value);
+					setMoved(true);
+				},
+				options: [{
+					value: "cosine",
+					label: "cosine"
+				}, {
+					value: "euclidean",
+					label: "distance"
+				}]
+			})]
+		}),
+		/* @__PURE__ */ jsx(Field, {
+			label: "how many neighbours",
+			value: /* @__PURE__ */ jsx("b", { children: kk }),
+			children: /* @__PURE__ */ jsx(Slider, {
+				value: kk,
+				min: 1,
+				max: 5,
+				step: 1,
+				onChange: setKk,
+				ariaLabel: "number of neighbours"
+			})
+		}),
+		/* @__PURE__ */ jsx("p", {
+			className: "ml-control-hint",
+			children: current === "nearest" ? "Click any word on the map to ask what is closest to it." : "The solid arrow is the step from one word to another. The dashed arrow repeats that same step somewhere else."
+		})
+	] });
+	const reset = () => {
+		setCurrent(mode);
+		setSelected(pool.find((i) => i.label === query)?.label ?? pool[0].label);
+		setKk(k);
+		setMetricNow(metric);
+		setMoved(false);
+		challenge.reset();
+	};
+	return /* @__PURE__ */ jsx(MLActivity, {
+		className: "ml-embedding-space",
+		eyebrow: "Embeddings",
+		title,
+		prompt: prompt ?? "Every word here is a pair of numbers, so meaning becomes a position. Words used in similar ways end up in similar places, and that is the whole mechanism behind semantic search.",
+		status: /* @__PURE__ */ jsxs(Fragment$1, { children: [
+			/* @__PURE__ */ jsx("strong", { children: analogyOk ? target.label : `nearest to ${selected}` }),
+			/* @__PURE__ */ jsxs("span", { children: ["→ ", best?.item.label ?? "none"] }),
+			/* @__PURE__ */ jsxs("span", { children: ["cos ", best?.cos.toFixed(3) ?? "0"] }),
+			/* @__PURE__ */ jsxs("span", { children: ["ranked by ", metricNow === "cosine" ? "cosine" : "distance"] })
+		] }),
+		figure,
+		instruments: /* @__PURE__ */ jsxs(Fragment$1, { children: [instruments, /* @__PURE__ */ jsx(LiveRegion, { children: analogyOk ? `${target.label} lands nearest ${best?.item.label}, cosine ${best?.cos.toFixed(3)}.` : `Nearest to ${selected} is ${best?.item.label}, cosine ${best?.cos.toFixed(3)}.` })] }),
+		controls,
+		feedback: analogyOk ? `Direction carries meaning. The step that turns ${bLabel} into ${aLabel} is the same step that turns ${cLabel} into ${best?.item.label}, so the arithmetic lands on it.` : moved ? "Words from the same group sit together, because they get used in the same contexts. Nothing here was labelled by hand." : "Click a word to ask what is nearest to it, then switch the question to analogy.",
+		objectives,
+		transport: /* @__PURE__ */ jsx(MLResetTransport, {
+			onReset: reset,
+			state: moved ? "Compare the two metrics" : "Pick a word on the map",
+			detail: `${top.length} neighbour${top.length === 1 ? "" : "s"} shown`
+		}),
+		challenge: /* @__PURE__ */ jsx(ChallengeCard, {
+			questions: TRANSFER,
+			state: challenge,
+			title: "Transfer it to a real system"
+		}),
+		support: /* @__PURE__ */ jsx(HintLadder, { hints }),
+		canvasLabel: "Word embedding map with nearest neighbours and analogy arrows",
+		inspectorLabel: "Similarity scores"
+	});
+}
+
+//#endregion
+export { EmbeddingSpaceLab, EmbeddingSpaceLab as default };

package/dist/domains/ml/kmeans/manifest.mjs

@@ -0,0 +1,78 @@
+import { defineLab } from "../../../lab-def/define-lab.mjs";
+import { commonLabProps } from "../../../blocks/lab-block.mjs";
+import { z } from "zod";
+
+//#region src/domains/ml/kmeans/manifest.ts
+const point = z.object({
+	x: z.number().finite(),
+	y: z.number().finite()
+});
+var manifest_default = defineLab({
+	id: "kmeans",
+	domain: "ml",
+	group: "Machine learning",
+	tag: "KMeans",
+	title: "k-means clustering",
+	description: "Unsupervised clustering you watch converge: drag the k centroids to seed them, Step or Run Lloyd’s algorithm (points recolour to nearest centroid, centroids jump to their cluster mean), and the inertia drops. Bad seeds → a worse local minimum. Author the points + k.",
+	schema: z.object({
+		points: z.array(point).min(3).max(200).optional(),
+		k: z.number().int().min(1).max(5).default(3),
+		seeds: z.array(point).min(1).max(5).optional(),
+		span: z.number().finite().min(2).max(100).default(10),
+		showLines: z.boolean().default(true),
+		...commonLabProps
+	}).superRefine((props, context) => {
+		if (props.points && props.points.length < props.k) context.addIssue({
+			code: "custom",
+			path: ["points"],
+			message: "The dataset needs at least one point per cluster"
+		});
+		if (props.seeds && props.seeds.length !== props.k) context.addIssue({
+			code: "custom",
+			path: ["seeds"],
+			message: "Provide exactly k centroid seeds"
+		});
+		for (const key of ["points", "seeds"]) props[key]?.forEach((value, index) => {
+			if (value.x < 0 || value.x > props.span || value.y < 0 || value.y > props.span) context.addIssue({
+				code: "custom",
+				path: [key, index],
+				message: "Coordinates must sit inside the plotting span"
+			});
+		});
+	}),
+	taxonomy: {
+		grades: ["11", "12"],
+		outcomes: [
+			"machine-learning",
+			"clustering",
+			"k-means"
+		],
+		durationMinutes: 15,
+		interaction: "explorer",
+		authorability: "moderate"
+	},
+	experience: {
+		objectives: [
+			"Predict how centroid seeds affect clustering",
+			"Follow the assignment and centroid-update steps of Lloyd’s algorithm",
+			"Explain why convergence does not guarantee the lowest possible inertia"
+		],
+		phases: [
+			"predict",
+			"act",
+			"observe",
+			"explain",
+			"transfer"
+		],
+		responses: ["choice"],
+		accessibility: {
+			keyboard: true,
+			textAlternative: true,
+			reducedMotion: true
+		}
+	},
+	loadRuntime: () => import("./runtime.mjs")
+});
+
+//#endregion
+export { manifest_default as default };

package/dist/{ml/kmeans/preset.d.mts → domains/ml/kmeans/runtime.d.mts}

@@ -1,6 +1,6 @@
 import { ReactNode } from "react";
 
-//#region src/ml/kmeans/preset.d.ts
+//#region src/domains/ml/kmeans/runtime.d.ts
 interface KMeansProps {
   points?: {
     x: number;

package/dist/{ml/kmeans/preset.mjs → domains/ml/kmeans/runtime.mjs}

@@ -1,13 +1,13 @@
 'use client';
 
-import { CheckButton, StatusPill } from "../../kit/controls.mjs";
-import { ControlBar, LabFrame, LiveRegion } from "../../kit/frame.mjs";
-import { useCheckpoint } from "../../kit/pedagogy.mjs";
+import { Stat, StatList } from "../../../kit/frame.mjs";
+import { ChallengeCard, useChallenge, useCheckpoint } from "../../../kit/pedagogy.mjs";
+import { MLActivity, MLRunTransport } from "../activity.mjs";
 import { useMemo, useRef, useState } from "react";
-import { jsx, jsxs } from "react/jsx-runtime";
+import { Fragment as Fragment$1, jsx, jsxs } from "react/jsx-runtime";
 import { Circle, Dot, Grid, MovableDot, Segment, Stage, useFrameLoop, useInView } from "@classytic/stage";
 
-//#region src/ml/kmeans/preset.tsx
+//#region src/domains/ml/kmeans/runtime.tsx
 /**
 * KMeansLab, unsupervised clustering you can watch converge. Points sit in a few
 * blobs; you drag the k centroids to seed them, then Step (Lloyd's algorithm):
@@ -56,8 +56,36 @@ const DEFAULT_SEEDS = [
 	{
 		x: 5,
 		y: 4
+	},
+	{
+		x: 2,
+		y: 2
+	},
+	{
+		x: 8,
+		y: 2
 	}
 ];
+const TRANSFER = [{
+	id: "local-minimum",
+	prompt: "A run has converged but its inertia is higher than another run. What should you try?",
+	choices: [
+		{
+			value: "reseed",
+			label: "restart from different centroid seeds"
+		},
+		{
+			value: "accept",
+			label: "accept it because convergence guarantees the best answer"
+		},
+		{
+			value: "more",
+			label: "keep stepping the unchanged centroids"
+		}
+	],
+	answer: "reseed",
+	explain: "Convergence only means this run has reached a local minimum. Different seeds can lead Lloyd’s algorithm to a lower-inertia clustering."
+}];
 const d2 = (a, b) => (a.x - b.x) ** 2 + (a.y - b.y) ** 2;
 function KMeansLab({ points = DEFAULT_POINTS, k = 3, seeds, span = 10, showLines = true, title = "k-means: watch the clusters form", prompt = "Drag the centroids to seed them, then Step: points recolour to the nearest centroid, centroids jump to their cluster mean. Seed them badly and you get stuck in a worse answer.", objectives, height = 380 }) {
 	const view = {
@@ -70,9 +98,10 @@ function KMeansLab({ points = DEFAULT_POINTS, k = 3, seeds, span = 10, showLines
 	const [running, setRunning] = useState(false);
 	const [iter, setIter] = useState(0);
 	const [converged, setConverged] = useState(false);
+	const challenge = useChallenge(TRANSFER);
 	const { ref: viewRef, inView } = useInView();
 	useCheckpoint({
-		solved: converged,
+		solved: converged && challenge.allCorrect,
 		activity: "kmeans"
 	});
 	const assign = (cs) => points.map((p) => {
@@ -128,6 +157,7 @@ function KMeansLab({ points = DEFAULT_POINTS, k = 3, seeds, span = 10, showLines
 		setIter(0);
 		setRunning(false);
 		setConverged(false);
+		challenge.reset();
 	};
 	const dragCent = (j, p) => {
 		setRunning(false);
@@ -184,53 +214,58 @@ function KMeansLab({ points = DEFAULT_POINTS, k = 3, seeds, span = 10, showLines
 			]
 		})
 	});
-	return /* @__PURE__ */ jsx(LabFrame, {
+	const phase = converged ? "Converged" : running ? "Updating clusters" : iter > 0 ? "Paused" : "Seed centroids";
+	const feedback = converged ? "The centroids stopped moving. Try a different seed: k-means can converge cleanly and still land in a different local minimum." : iter > 0 ? "Each step first assigns every point to its nearest centroid, then moves each centroid to the mean of its assigned points." : "Initialization matters. Drag the centroid rings into deliberately different positions, then compare the final inertia.";
+	return /* @__PURE__ */ jsx(MLActivity, {
+		className: "ml-kmeans",
 		title,
 		prompt,
-		objectives,
-		controls: /* @__PURE__ */ jsxs(ControlBar, { children: [
-			/* @__PURE__ */ jsx(CheckButton, {
-				onClick: () => setRunning((r) => !r),
-				children: running ? "⏸ Pause" : "▶ Run"
-			}),
-			/* @__PURE__ */ jsx("button", {
-				type: "button",
-				className: "lab-chip",
-				onClick: step,
-				children: "Step"
-			}),
-			/* @__PURE__ */ jsx("button", {
-				type: "button",
-				className: "lab-chip",
-				onClick: reset,
-				children: "Reset"
-			}),
-			/* @__PURE__ */ jsxs("span", {
-				style: {
-					fontWeight: 700,
-					fontVariantNumeric: "tabular-nums"
-				},
-				children: ["inertia ", /* @__PURE__ */ jsx("b", {
-					style: { fontSize: 17 },
-					children: inertia.toFixed(1)
-				})]
-			}),
-			/* @__PURE__ */ jsx(StatusPill, {
-				ok: !running && iter > 0,
-				children: !running && iter > 0 ? "converged" : `step ${iter}`
-			}),
-			/* @__PURE__ */ jsx("span", {
-				style: {
-					marginLeft: "auto",
-					color: "var(--stage-muted)"
-				},
-				children: "drag a centroid to re-seed"
-			})
+		status: /* @__PURE__ */ jsxs(Fragment$1, { children: [
+			/* @__PURE__ */ jsx("strong", { children: phase }),
+			/* @__PURE__ */ jsxs("span", { children: ["iteration ", iter] }),
+			/* @__PURE__ */ jsxs("span", { children: [k, " clusters"] })
 		] }),
-		footer: /* @__PURE__ */ jsx(LiveRegion, { children: `Step ${iter}. Inertia ${inertia.toFixed(1)}.` }),
-		children: figure
+		figure,
+		instruments: /* @__PURE__ */ jsxs(StatList, {
+			tone: "info",
+			children: [
+				/* @__PURE__ */ jsx(Stat, {
+					label: "Within-cluster inertia",
+					value: inertia.toFixed(1),
+					tone: converged ? "good" : void 0
+				}),
+				/* @__PURE__ */ jsx(Stat, {
+					label: "Lloyd iteration",
+					value: iter
+				}),
+				/* @__PURE__ */ jsx(Stat, {
+					label: "Centroids",
+					value: cents.length
+				})
+			]
+		}),
+		controls: /* @__PURE__ */ jsx("p", { children: "Drag a centroid ring to choose a new seed. The faint spokes show which centroid currently owns each point." }),
+		feedback,
+		challenge: /* @__PURE__ */ jsx(ChallengeCard, {
+			questions: TRANSFER,
+			state: challenge,
+			title: "Transfer the result"
+		}),
+		objectives,
+		transport: /* @__PURE__ */ jsx(MLRunTransport, {
+			running,
+			onReset: reset,
+			onStep: step,
+			onToggle: () => setRunning((value) => !value),
+			state: phase,
+			detail: `iteration ${iter} · inertia ${inertia.toFixed(1)}`,
+			disabled: converged,
+			runLabel: "Run Lloyd’s algorithm"
+		}),
+		canvasLabel: "K-means clustering scene with draggable centroids",
+		inspectorLabel: "Convergence evidence and seeding guidance"
 	});
 }
 
 //#endregion
-export { KMeansLab };
+export { KMeansLab, KMeansLab as default };

package/dist/domains/ml/knn/manifest.mjs

@@ -0,0 +1,58 @@
+import { defineLab } from "../../../lab-def/define-lab.mjs";
+import { commonLabProps } from "../../../blocks/lab-block.mjs";
+import { z } from "zod";
+
+//#region src/domains/ml/knn/manifest.ts
+var manifest_default = defineLab({
+	id: "knn",
+	domain: "ml",
+	group: "Machine learning",
+	tag: "KnnBoundary",
+	title: "k-nearest neighbours boundary",
+	description: "The answer to “a line can’t split XOR”: choose a generated dataset, drag the test point to see its nearest neighbours vote, and vary k to compare jagged overfit with oversmoothing.",
+	schema: z.object({
+		dataset: z.enum([
+			"blobs",
+			"xor",
+			"circles"
+		]).default("circles"),
+		k: z.number().int().min(1).max(15).refine((value) => value % 2 === 1, "Use an odd k to avoid tied votes").default(5),
+		seed: z.number().int().min(0).max(2147483647).default(7),
+		...commonLabProps
+	}),
+	taxonomy: {
+		grades: ["11", "12"],
+		outcomes: [
+			"machine-learning",
+			"classification",
+			"knn"
+		],
+		durationMinutes: 15,
+		interaction: "explorer",
+		authorability: "moderate"
+	},
+	experience: {
+		objectives: [
+			"Predict a query class from its nearest labelled neighbours",
+			"Compare how k and dataset shape the decision regions",
+			"Distinguish a query prediction from leave-one-out model validation"
+		],
+		phases: [
+			"predict",
+			"act",
+			"observe",
+			"explain",
+			"transfer"
+		],
+		responses: ["choice"],
+		accessibility: {
+			keyboard: true,
+			textAlternative: true,
+			reducedMotion: true
+		}
+	},
+	loadRuntime: () => import("./runtime.mjs")
+});
+
+//#endregion
+export { manifest_default as default };