@classytic/labs 0.1.0

package/dist/ml/knn/preset.mjs

@@ -0,0 +1,279 @@
+'use client';
+
+import { gaussian, mulberry32 } from "../../core/rng.mjs";
+import { Chip, Slider } from "../../kit/controls.mjs";
+import { Callout, ControlBar, Field, LabFrame } from "../../kit/frame.mjs";
+import { HintLadder, useHints } from "../../kit/pedagogy.mjs";
+import { useCallback, useMemo, useState } from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+import { CanvasLayer, useControlSurface } from "@classytic/stage";
+
+//#region src/ml/knn/preset.tsx
+/**
+* KNNBoundaryLab — the answer to "a line can't split XOR." k-nearest-neighbours
+* paints the whole plane by asking, at every point, "what are my k closest
+* labelled neighbours, and which class wins the vote?" The boundary it carves is
+* CURVY — it shrugs off XOR and even concentric rings that no straight line could
+* touch. Drag the ✦ test point to watch its k neighbours light up and cast their
+* votes; slide k to feel the trade-off: k=1 memorises every island (jagged,
+* overfit), big k smooths everything (and starts ignoring real structure).
+*
+* The decision regions are a CanvasLayer heatmap (one vote per cell — exactly the
+* high-element-count job canvas is for); points + neighbour spokes draw on top.
+*/
+const R = 5, A0 = "#1c7ed6", A1 = "#e8590c";
+const view = {
+	xMin: -5,
+	xMax: R,
+	yMin: -5,
+	yMax: R
+};
+function makeData(kind, seed) {
+	const rng = mulberry32(seed);
+	const pts = [];
+	const blob = (cx, cy, cls, k, sd = .8) => {
+		for (let i = 0; i < k; i++) pts.push({
+			x: gaussian(rng, cx, sd),
+			y: gaussian(rng, cy, sd),
+			cls
+		});
+	};
+	if (kind === "blobs") {
+		blob(-2, -1.5, 0, 16);
+		blob(2, 1.5, 1, 16);
+	} else if (kind === "xor") {
+		blob(-2.2, 2.2, 0, 9);
+		blob(2.2, -2.2, 0, 9);
+		blob(2.2, 2.2, 1, 9);
+		blob(-2.2, -2.2, 1, 9);
+	} else {
+		for (let i = 0; i < 16; i++) pts.push({
+			x: gaussian(rng, 0, .7),
+			y: gaussian(rng, 0, .7),
+			cls: 1
+		});
+		for (let i = 0; i < 22; i++) {
+			const a = rng() * Math.PI * 2, r = 3.4 + gaussian(rng, 0, .3);
+			pts.push({
+				x: Math.cos(a) * r,
+				y: Math.sin(a) * r,
+				cls: 0
+			});
+		}
+	}
+	return pts;
+}
+function KNNBoundaryLab({ dataset = "circles", k = 5, seed = 7, title = "k-nearest neighbours", prompt, objectives, hints: hintList, controlId, height = 330 }) {
+	const [kind, setKind] = useState(dataset);
+	const [pts, setPts] = useState(() => makeData(dataset, seed));
+	const [kk, setKk] = useState(k);
+	const [query, setQuery] = useState({
+		x: .6,
+		y: 1.2
+	});
+	const hints = useHints(hintList);
+	const nearest = useCallback((x, y, kn, exclude = -1) => {
+		const d = pts.map((p, i) => ({
+			i,
+			d2: (p.x - x) ** 2 + (p.y - y) ** 2
+		})).filter((o) => o.i !== exclude);
+		d.sort((a, b) => a.d2 - b.d2);
+		return d.slice(0, kn).map((o) => o.i);
+	}, [pts]);
+	const vote = useCallback((idxs) => {
+		let s = 0;
+		for (const i of idxs) s += pts[i].cls;
+		return s * 2 > idxs.length ? 1 : 0;
+	}, [pts]);
+	const acc = useMemo(() => {
+		if (!pts.length) return 0;
+		let ok = 0;
+		for (let i = 0; i < pts.length; i++) if (vote(nearest(pts[i].x, pts[i].y, kk, i)) === pts[i].cls) ok++;
+		return ok / pts.length;
+	}, [
+		pts,
+		kk,
+		nearest,
+		vote
+	]);
+	const qNbrs = nearest(query.x, query.y, kk);
+	const qCls = vote(qNbrs);
+	const qCount1 = qNbrs.reduce((a, i) => a + pts[i].cls, 0);
+	const draw = useCallback((ctx, c) => {
+		const css = getComputedStyle(ctx.canvas);
+		const tok = (s, fb) => css.getPropertyValue(s).trim() || fb;
+		const fg = tok("--stage-fg", "#222"), bg = tok("--stage-bg", "#fff");
+		const W = ctx.canvas.clientWidth || 640, H = height, CELL = 7;
+		ctx.clearRect(0, 0, W, H);
+		for (let px = 0; px < W; px += CELL) for (let py = 0; py < H; py += CELL) {
+			const [mx, my] = c.toMath(px + CELL / 2, py + CELL / 2);
+			ctx.fillStyle = vote(nearest(mx, my, kk)) ? A1 : A0;
+			ctx.globalAlpha = .16;
+			ctx.fillRect(px, py, 8, 8);
+		}
+		ctx.globalAlpha = 1;
+		for (const p of pts) {
+			const [x, y] = c.toPx(p.x, p.y);
+			ctx.fillStyle = p.cls ? A1 : A0;
+			ctx.strokeStyle = bg;
+			ctx.lineWidth = 1.5;
+			ctx.beginPath();
+			ctx.arc(x, y, 4.5, 0, Math.PI * 2);
+			ctx.fill();
+			ctx.stroke();
+		}
+		const [qx, qy] = c.toPx(query.x, query.y);
+		ctx.strokeStyle = fg;
+		ctx.globalAlpha = .45;
+		ctx.setLineDash([4, 3]);
+		ctx.lineWidth = 1.2;
+		for (const i of qNbrs) {
+			const [nx, ny] = c.toPx(pts[i].x, pts[i].y);
+			ctx.beginPath();
+			ctx.moveTo(qx, qy);
+			ctx.lineTo(nx, ny);
+			ctx.stroke();
+		}
+		ctx.setLineDash([]);
+		ctx.globalAlpha = 1;
+		ctx.fillStyle = qCls ? A1 : A0;
+		ctx.beginPath();
+		ctx.arc(qx, qy, 7.5, 0, Math.PI * 2);
+		ctx.fill();
+		ctx.strokeStyle = fg;
+		ctx.lineWidth = 2.5;
+		ctx.stroke();
+		ctx.fillStyle = bg;
+		ctx.font = "bold 11px ui-sans-serif";
+		ctx.textAlign = "center";
+		ctx.textBaseline = "middle";
+		ctx.fillText("?", qx, qy);
+	}, [
+		pts,
+		kk,
+		query,
+		qNbrs,
+		qCls,
+		height
+	]);
+	const loadData = useCallback((d) => {
+		setKind(d);
+		setPts(makeData(d, seed));
+	}, [seed]);
+	useControlSurface(controlId, {
+		dataset: {
+			type: "enum",
+			label: "dataset",
+			options: [
+				"blobs",
+				"xor",
+				"circles"
+			],
+			get: () => kind,
+			set: (v) => loadData(v)
+		},
+		k: {
+			type: "number",
+			label: "k (neighbours)",
+			min: 1,
+			max: 15,
+			step: 2,
+			get: () => kk,
+			set: setKk
+		}
+	});
+	const figure = /* @__PURE__ */ jsx(CanvasLayer, {
+		view: useMemo(() => view, []),
+		height,
+		draw,
+		onPointerMath: (m) => setQuery({
+			x: Math.max(-5, Math.min(R, m[0])),
+			y: Math.max(-5, Math.min(R, m[1]))
+		}),
+		ariaLabel: `k-NN boundary, k ${kk}, accuracy ${(acc * 100).toFixed(0)}%`
+	});
+	return /* @__PURE__ */ jsx(LabFrame, {
+		title,
+		prompt,
+		objectives,
+		aside: /* @__PURE__ */ jsxs(Callout, {
+			tone: "result",
+			children: [
+				/* @__PURE__ */ jsx("span", {
+					style: { color: A0 },
+					children: "● class A"
+				}),
+				"  ",
+				/* @__PURE__ */ jsx("span", {
+					style: { color: A1 },
+					children: "● class B"
+				}),
+				/* @__PURE__ */ jsxs("div", {
+					style: { color: "var(--stage-accent)" },
+					children: [
+						"✦ votes: ",
+						kk - qCount1,
+						" A vs ",
+						qCount1,
+						" B → ",
+						/* @__PURE__ */ jsx("span", {
+							style: { color: qCls ? A1 : A0 },
+							children: qCls ? "B" : "A"
+						})
+					]
+				}),
+				/* @__PURE__ */ jsxs("span", {
+					className: "lab-callout-big",
+					style: { color: acc === 1 ? "var(--stage-good)" : "var(--stage-accent)" },
+					children: [
+						"LOO accuracy ",
+						(acc * 100).toFixed(1),
+						"%"
+					]
+				})
+			]
+		}),
+		controls: /* @__PURE__ */ jsxs(ControlBar, { children: [
+			/* @__PURE__ */ jsx(Field, {
+				label: "k (neighbours)",
+				value: /* @__PURE__ */ jsx("b", { children: kk }),
+				children: /* @__PURE__ */ jsx(Slider, {
+					value: kk,
+					min: 1,
+					max: 15,
+					step: 2,
+					onChange: setKk,
+					ariaLabel: "number of neighbours"
+				})
+			}),
+			/* @__PURE__ */ jsx("span", {
+				style: {
+					fontSize: 12,
+					color: "var(--stage-muted)"
+				},
+				children: "data:"
+			}),
+			[
+				"blobs",
+				"xor",
+				"circles"
+			].map((d) => /* @__PURE__ */ jsx(Chip, {
+				selected: kind === d,
+				onClick: () => loadData(d),
+				children: d
+			}, d)),
+			/* @__PURE__ */ jsx("span", {
+				style: {
+					fontSize: 12,
+					color: "var(--stage-muted)"
+				},
+				children: "· drag the ✦ test point"
+			})
+		] }),
+		footer: /* @__PURE__ */ jsx(HintLadder, { hints }),
+		children: figure
+	});
+}
+
+//#endregion
+export { KNNBoundaryLab };

package/dist/ml/regression/index.d.mts

@@ -0,0 +1 @@
+import { RegressionLab, RegressionProps } from "./preset.mjs";

package/dist/ml/regression/preset.d.mts

@@ -0,0 +1,32 @@
+import { ReactNode } from "react";
+
+//#region src/ml/regression/preset.d.ts
+interface RegressionProps {
+  data?: {
+    x: number;
+    y: number;
+  }[];
+  showSquares?: boolean;
+  learnRate?: number;
+  m0?: number;
+  b0?: number;
+  span?: number;
+  title?: string;
+  prompt?: string;
+  objectives?: string[];
+  height?: number;
+}
+declare function RegressionLab({
+  data,
+  showSquares,
+  learnRate,
+  m0,
+  b0,
+  span,
+  title,
+  prompt,
+  objectives,
+  height
+}: RegressionProps): ReactNode;
+//#endregion
+export { RegressionLab, RegressionProps };

package/dist/ml/regression/preset.mjs

@@ -0,0 +1,394 @@
+'use client';
+
+import { clamp } from "../../core/util.mjs";
+import { CheckButton, Slider, StatusPill } from "../../kit/controls.mjs";
+import { Callout, ControlBar, Field, LabFrame, LiveRegion } from "../../kit/frame.mjs";
+import { useCheckpoint } from "../../kit/pedagogy.mjs";
+import { useMemo, useRef, useState } from "react";
+import { Fragment as Fragment$1, jsx, jsxs } from "react/jsx-runtime";
+import { Axes, Dot, Grid, Label, MovableDot, Polygon, Segment, Stage, useFrameLoop, useInView } from "@classytic/stage";
+
+//#region src/ml/regression/preset.tsx
+/**
+* RegressionLab — least squares you can FEEL, and gradient descent you can WATCH.
+*
+* Drag the line's two handles: every data point grows a SQUARE whose area is its
+* squared error, and the loss (mean squared error) updates live — "least squares"
+* is literally "make the total square area smallest". Then press Descend and watch
+* the line crawl downhill on its own, squares shrinking, loss tumbling. The
+* learning-rate slider lets you make it overshoot and DIVERGE — the #1 gradient-
+* descent intuition. Reveal snaps to the closed-form optimum to check yourself.
+*
+* The litmus test for ML/data labs on the stage engine: scatter + draggable fit +
+* frame-loop optimisation + live loss, all from the shared primitives. Isometric
+* view (preserveAspect + equal spans) so a data-unit square reads as a real
+* on-screen square — and stays SSR-deterministic.
+*/
+const DEFAULT_DATA = [
+	{
+		x: 1,
+		y: 2.1
+	},
+	{
+		x: 2,
+		y: 2.4
+	},
+	{
+		x: 3,
+		y: 4.2
+	},
+	{
+		x: 4,
+		y: 3.9
+	},
+	{
+		x: 5,
+		y: 5.6
+	},
+	{
+		x: 6,
+		y: 5.1
+	},
+	{
+		x: 7,
+		y: 7.2
+	},
+	{
+		x: 8,
+		y: 7
+	},
+	{
+		x: 9,
+		y: 8.3
+	}
+];
+function RegressionLab({ data = DEFAULT_DATA, showSquares = true, learnRate = .006, m0 = .3, b0 = 3.2, span = 10, title = "Least squares — drag the line, watch the error", prompt = "Each point grows a square of its squared error. Make the total area smallest — then press Descend and watch gradient descent do it for you.", objectives, height = 380 }) {
+	const view = {
+		xMin: 0,
+		xMax: span,
+		yMin: 0,
+		yMax: span
+	};
+	const n = data.length;
+	const mid = span / 2;
+	const [line, setLine] = useState({
+		m: m0,
+		b: b0
+	});
+	const [lr, setLr] = useState(learnRate);
+	const [running, setRunning] = useState(false);
+	const [iter, setIter] = useState(0);
+	const [history, setHistory] = useState([]);
+	const { ref: viewRef, inView } = useInView();
+	const opt = useMemo(() => {
+		const xb = data.reduce((s, p) => s + p.x, 0) / n;
+		const yb = data.reduce((s, p) => s + p.y, 0) / n;
+		let num = 0, den = 0;
+		for (const p of data) {
+			num += (p.x - xb) * (p.y - yb);
+			den += (p.x - xb) ** 2;
+		}
+		const m = den === 0 ? 0 : num / den;
+		return {
+			m,
+			b: yb - m * xb
+		};
+	}, [data, n]);
+	const mse = (ln) => data.reduce((s, p) => s + (ln.m * p.x + ln.b - p.y) ** 2, 0) / n;
+	const grad = (ln) => {
+		let dm = 0, db = 0;
+		for (const p of data) {
+			const e = ln.m * p.x + ln.b - p.y;
+			dm += e * p.x;
+			db += e;
+		}
+		return {
+			dm: 2 / n * dm,
+			db: 2 / n * db
+		};
+	};
+	const loss = mse(line);
+	const optLoss = mse(opt);
+	const loss0 = mse({
+		m: m0,
+		b: b0
+	});
+	const closeEnough = loss <= optLoss * 1.05 + 1e-6;
+	useCheckpoint({
+		solved: closeEnough,
+		activity: "regression"
+	});
+	const lineRef = useRef(line);
+	lineRef.current = line;
+	const iterRef = useRef(0);
+	iterRef.current = iter;
+	useFrameLoop(() => {
+		let nx = lineRef.current;
+		for (let i = 0; i < 3; i++) {
+			const g = grad(nx);
+			nx = {
+				m: nx.m - lr * g.dm,
+				b: nx.b - lr * g.db
+			};
+		}
+		setLine(nx);
+		setIter((i) => i + 3);
+		setHistory((h) => [...h.slice(-119), mse(nx)]);
+		const g = grad(nx);
+		if (Math.hypot(g.dm, g.db) < .001 || iterRef.current > 3e3 || !Number.isFinite(nx.m)) setRunning(false);
+	}, { running: running && inView });
+	const yAt = (x) => line.m * x + line.b;
+	const handleL = {
+		x: 0,
+		y: yAt(0)
+	};
+	const handleR = {
+		x: span,
+		y: yAt(span)
+	};
+	const setFromHandles = (l, r) => {
+		const m = (r.y - l.y) / (r.x - l.x || 1);
+		setLine({
+			m,
+			b: l.y - m * l.x
+		});
+	};
+	const dragL = (p) => {
+		setRunning(false);
+		setFromHandles({
+			x: 0,
+			y: clamp(p.y, view.yMin, view.yMax)
+		}, handleR);
+	};
+	const dragR = (p) => {
+		setRunning(false);
+		setFromHandles(handleL, {
+			x: span,
+			y: clamp(p.y, view.yMin, view.yMax)
+		});
+	};
+	const reset = () => {
+		setLine({
+			m: m0,
+			b: b0
+		});
+		setIter(0);
+		setHistory([]);
+		setRunning(false);
+	};
+	const reveal = () => {
+		setRunning(false);
+		setLine(opt);
+	};
+	const lossFrac = clamp(loss / (loss0 || 1), 0, 1);
+	const figure = /* @__PURE__ */ jsx("div", {
+		ref: viewRef,
+		className: "lab-playwrap",
+		children: /* @__PURE__ */ jsxs(Stage, {
+			view,
+			height,
+			ariaLabel: `Scatter with a fitted line; mean squared error ${loss.toFixed(2)}`,
+			children: [
+				/* @__PURE__ */ jsx(Grid, {}),
+				/* @__PURE__ */ jsx(Axes, {}),
+				showSquares && data.map((p, i) => {
+					const yhat = line.m * p.x + line.b;
+					const r = p.y - yhat;
+					const dir = p.x < mid ? 1 : -1;
+					const x2 = p.x + dir * Math.abs(r);
+					const col = r >= 0 ? "var(--stage-good)" : "var(--stage-danger)";
+					return /* @__PURE__ */ jsx(Polygon, {
+						points: [
+							{
+								x: p.x,
+								y: p.y
+							},
+							{
+								x: p.x,
+								y: yhat
+							},
+							{
+								x: x2,
+								y: yhat
+							},
+							{
+								x: x2,
+								y: p.y
+							}
+						],
+						color: col,
+						fill: col,
+						fillOpacity: .16,
+						weight: 1
+					}, i);
+				}),
+				/* @__PURE__ */ jsx(Segment, {
+					from: {
+						x: 0,
+						y: yAt(0)
+					},
+					to: {
+						x: span,
+						y: yAt(span)
+					},
+					color: "var(--stage-accent)",
+					weight: 3
+				}),
+				data.map((p, i) => /* @__PURE__ */ jsx(Dot, {
+					x: p.x,
+					y: p.y,
+					r: 5,
+					color: "var(--stage-accent-2)"
+				}, i)),
+				/* @__PURE__ */ jsx(MovableDot, {
+					value: handleL,
+					onMove: dragL,
+					constrain: "vertical",
+					range: {
+						min: view.yMin,
+						max: view.yMax
+					},
+					color: "var(--stage-accent)",
+					ariaLabel: "line left end"
+				}),
+				/* @__PURE__ */ jsx(MovableDot, {
+					value: handleR,
+					onMove: dragR,
+					constrain: "vertical",
+					range: {
+						min: view.yMin,
+						max: view.yMax
+					},
+					color: "var(--stage-accent)",
+					ariaLabel: "line right end"
+				}),
+				/* @__PURE__ */ jsx(Label, {
+					x: span - 1.4,
+					y: yAt(span - 1.4) + .6,
+					text: `y = ${line.m.toFixed(2)}x + ${line.b.toFixed(2)}`,
+					size: 12,
+					color: "var(--stage-accent)"
+				})
+			]
+		})
+	});
+	return /* @__PURE__ */ jsx(LabFrame, {
+		title,
+		prompt,
+		objectives,
+		aside: /* @__PURE__ */ jsxs(Fragment$1, { children: [/* @__PURE__ */ jsxs(Callout, {
+			tone: "result",
+			children: [
+				/* @__PURE__ */ jsxs("span", {
+					style: {
+						fontWeight: 700,
+						fontVariantNumeric: "tabular-nums"
+					},
+					children: ["MSE ", /* @__PURE__ */ jsx("b", {
+						style: {
+							color: closeEnough ? "var(--stage-good)" : "var(--stage-fg)",
+							fontSize: 18
+						},
+						children: loss.toFixed(3)
+					})]
+				}),
+				/* @__PURE__ */ jsx("div", {
+					style: {
+						minWidth: 120,
+						height: 10,
+						borderRadius: 999,
+						background: "color-mix(in oklab, var(--stage-fg) 10%, transparent)",
+						overflow: "hidden",
+						margin: "6px 0"
+					},
+					children: /* @__PURE__ */ jsx("div", { style: {
+						width: `${lossFrac * 100}%`,
+						height: "100%",
+						background: closeEnough ? "var(--stage-good)" : "var(--stage-warn)",
+						transition: "width .12s, background .2s"
+					} })
+				}),
+				/* @__PURE__ */ jsx(StatusPill, {
+					ok: closeEnough,
+					children: closeEnough ? "best fit!" : `optimum ${optLoss.toFixed(3)}`
+				})
+			]
+		}), history.length > 1 && /* @__PURE__ */ jsxs("svg", {
+			viewBox: "0 0 240 44",
+			width: "100%",
+			height: 44,
+			role: "img",
+			"aria-label": "loss decreasing over steps",
+			style: {
+				display: "block",
+				maxWidth: 360,
+				marginTop: 4
+			},
+			children: [/* @__PURE__ */ jsx("polyline", {
+				points: history.map((v, i) => `${i / (history.length - 1) * 240},${44 - clamp(v / (loss0 || 1), 0, 1) * 40 - 2}`).join(" "),
+				fill: "none",
+				stroke: "var(--stage-accent)",
+				strokeWidth: 2,
+				vectorEffect: "non-scaling-stroke"
+			}), /* @__PURE__ */ jsx("text", {
+				x: 2,
+				y: 10,
+				fill: "var(--stage-muted)",
+				fontSize: 9,
+				children: "loss ↓"
+			})]
+		})] }),
+		controls: /* @__PURE__ */ jsxs(ControlBar, { children: [
+			/* @__PURE__ */ jsx(CheckButton, {
+				onClick: () => {
+					if (!Number.isFinite(line.m)) reset();
+					setRunning((r) => !r);
+				},
+				children: running ? "⏸ Pause" : "▶ Descend"
+			}),
+			/* @__PURE__ */ jsx("button", {
+				type: "button",
+				className: "lab-chip",
+				onClick: reveal,
+				children: "Reveal best fit"
+			}),
+			/* @__PURE__ */ jsx("button", {
+				type: "button",
+				className: "lab-chip",
+				onClick: reset,
+				children: "Reset"
+			}),
+			/* @__PURE__ */ jsx(Field, {
+				label: "learning rate",
+				value: /* @__PURE__ */ jsxs("span", {
+					style: {
+						fontVariantNumeric: "tabular-nums",
+						color: lr > .02 ? "var(--stage-danger)" : "var(--stage-muted)"
+					},
+					children: [lr.toFixed(3), lr > .02 ? " ⚠" : ""]
+				}),
+				children: /* @__PURE__ */ jsx(Slider, {
+					value: lr,
+					min: .001,
+					max: .03,
+					step: .001,
+					onChange: setLr,
+					ariaLabel: "learning rate"
+				})
+			}),
+			/* @__PURE__ */ jsxs("span", {
+				style: {
+					marginLeft: "auto",
+					color: "var(--stage-muted)",
+					fontVariantNumeric: "tabular-nums"
+				},
+				children: ["step ", iter]
+			})
+		] }),
+		footer: /* @__PURE__ */ jsx(LiveRegion, { children: `Line y = ${line.m.toFixed(2)}x + ${line.b.toFixed(2)}. Mean squared error ${loss.toFixed(2)}. ${closeEnough ? "This is the best fit." : ""}` }),
+		children: figure
+	});
+}
+
+//#endregion
+export { RegressionLab };

package/dist/physics/atwood/index.d.mts

@@ -0,0 +1 @@
+import { AtwoodLab, AtwoodProps } from "./preset.mjs";