@classytic/labs 0.1.0

package/dist/math/trig-explorer.mjs

@@ -0,0 +1,209 @@
+'use client';
+
+import { toDeg, toRad } from "../core/util.mjs";
+import { Tex as Tex$1 } from "../core/tex.mjs";
+import { CheckButton } from "../kit/controls.mjs";
+import { ControlBar, LabFrame } from "../kit/frame.mjs";
+import { useEffect, useState } from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+import { Axes, Circle, Dot, Grid, MovableDot, Polyline, Segment, Stage, Vector, useFrameLoop, useInView } from "@classytic/stage";
+
+//#region src/math/trig-explorer.tsx
+/**
+* TrigExplorer — the unit circle ↔ sine wave connection (3Blue1Brown style),
+* but interactive: drag the angle (or press play) and watch sin/cos trace out.
+*
+* Now on the @classytic/stage engine (SVG, accessible, themed) — the unit circle,
+* radius, projections, and unrolled wave are real primitives, the angle handle is
+* a `MovableDot` (keyboard + aria), and animation runs on the engine clock.
+*
+* Deliberately FOCUSED on one idea — "sin and cos are the shadows of a point
+* going around a circle." Plotting arbitrary trig (tan, y=a·sin(b·x), …) is the
+* job of the general `Grapher`; this widget stays clean. Configurable only in
+* which of sin/cos to show.
+*/
+const TWO_PI = Math.PI * 2;
+const VIEW = {
+	xMin: -1.5,
+	xMax: 5,
+	yMin: -1.4,
+	yMax: 1.4
+};
+const WAVE_X0 = 1.5;
+const WAVE_W = 3.3;
+const waveX = (theta) => WAVE_X0 + theta / TWO_PI * WAVE_W;
+const TRIG_FNS = ["sin", "cos"];
+const FN_COLOR = {
+	sin: "var(--stage-accent)",
+	cos: "var(--stage-good)"
+};
+const FN_EVAL = {
+	sin: Math.sin,
+	cos: Math.cos
+};
+function normalizeFns(input) {
+	const picked = ((Array.isArray(input) ? input : typeof input === "string" ? input.split(",") : null) ?? []).map((s) => String(s).trim().toLowerCase()).filter((s) => TRIG_FNS.includes(s));
+	return picked.length ? Array.from(new Set(picked)) : ["sin", "cos"];
+}
+function TrigExplorer({ functions, startDeg = 30 } = {}) {
+	const fns = normalizeFns(functions);
+	const [theta, setTheta] = useState(toRad(startDeg));
+	const [playing, setPlaying] = useState(false);
+	const { ref: viewRef, inView } = useInView();
+	useEffect(() => {
+		setTheta(toRad(startDeg));
+	}, [startDeg]);
+	useFrameLoop((f) => {
+		setTheta((prev) => (prev + f.dtMs / 1e3 * .9) % TWO_PI);
+	}, { running: playing && inView });
+	const cosT = Math.cos(theta);
+	const sinT = Math.sin(theta);
+	const waveOf = (fn) => {
+		const pts = [];
+		for (let a = 0; a <= theta + 1e-6; a += TWO_PI / 240) pts.push({
+			x: waveX(a),
+			y: FN_EVAL[fn](a)
+		});
+		pts.push({
+			x: waveX(theta),
+			y: FN_EVAL[fn](theta)
+		});
+		return pts;
+	};
+	const lead = fns[0] ?? "sin";
+	const deg = toDeg(theta);
+	const figure = /* @__PURE__ */ jsx("div", {
+		ref: viewRef,
+		className: "lab-playwrap",
+		children: /* @__PURE__ */ jsxs(Stage, {
+			view: VIEW,
+			height: 320,
+			ariaLabel: `Unit circle and unrolled ${fns.join(" & ")} wave at θ = ${deg.toFixed(0)} degrees`,
+			children: [
+				/* @__PURE__ */ jsx(Grid, {}),
+				/* @__PURE__ */ jsx(Axes, {}),
+				/* @__PURE__ */ jsx(Circle, {
+					center: {
+						x: 0,
+						y: 0
+					},
+					r: 1,
+					color: "var(--stage-fg)",
+					opacity: .3,
+					weight: 1.5
+				}),
+				fns.includes("cos") && /* @__PURE__ */ jsx(Segment, {
+					from: {
+						x: 0,
+						y: 0
+					},
+					to: {
+						x: cosT,
+						y: 0
+					},
+					color: FN_COLOR.cos,
+					weight: 2.5
+				}),
+				fns.includes("sin") && /* @__PURE__ */ jsx(Segment, {
+					from: {
+						x: cosT,
+						y: sinT
+					},
+					to: {
+						x: cosT,
+						y: 0
+					},
+					color: FN_COLOR.sin,
+					weight: 2.5,
+					dashed: true
+				}),
+				fns.map((fn) => /* @__PURE__ */ jsx(Polyline, {
+					points: waveOf(fn),
+					color: FN_COLOR[fn],
+					weight: 2.5
+				}, fn)),
+				fns.map((fn) => /* @__PURE__ */ jsx(Dot, {
+					x: waveX(theta),
+					y: FN_EVAL[fn](theta),
+					r: 3.5,
+					color: FN_COLOR[fn]
+				}, `d-${fn}`)),
+				/* @__PURE__ */ jsx(Segment, {
+					from: {
+						x: cosT,
+						y: lead === "cos" ? 0 : sinT
+					},
+					to: {
+						x: waveX(theta),
+						y: FN_EVAL[lead](theta)
+					},
+					color: "var(--stage-fg)",
+					opacity: .4,
+					weight: 1,
+					dashed: true
+				}),
+				/* @__PURE__ */ jsx(Vector, {
+					tail: {
+						x: 0,
+						y: 0
+					},
+					tip: {
+						x: cosT,
+						y: sinT
+					},
+					color: "var(--stage-fg)",
+					weight: 2
+				}),
+				/* @__PURE__ */ jsx(MovableDot, {
+					value: {
+						x: cosT,
+						y: sinT
+					},
+					onMove: (p) => {
+						setPlaying(false);
+						let a = Math.atan2(p.y, p.x);
+						if (a < 0) a += TWO_PI;
+						setTheta(a);
+					},
+					color: "var(--stage-fg)",
+					ariaLabel: "angle on the unit circle"
+				})
+			]
+		})
+	});
+	return /* @__PURE__ */ jsx(LabFrame, {
+		title: "Trig Explorer",
+		prompt: "Drag the angle on the circle (or press play) — sin and cos are just its shadows.",
+		controls: /* @__PURE__ */ jsxs(ControlBar, { children: [
+			/* @__PURE__ */ jsx(CheckButton, {
+				onClick: () => setPlaying((p) => !p),
+				children: playing ? "Pause" : "Play"
+			}),
+			/* @__PURE__ */ jsx("button", {
+				type: "button",
+				className: "lab-chip",
+				onClick: () => {
+					setPlaying(false);
+					setTheta(toRad(startDeg));
+				},
+				children: "Reset"
+			}),
+			/* @__PURE__ */ jsxs("span", {
+				style: {
+					marginLeft: "auto",
+					display: "inline-flex",
+					gap: 16,
+					fontVariantNumeric: "tabular-nums"
+				},
+				children: [/* @__PURE__ */ jsx("span", { children: /* @__PURE__ */ jsx(Tex$1, { tex: `\\theta\\ ${deg.toFixed(0)}^\\circ` }) }), fns.map((fn) => /* @__PURE__ */ jsx("span", {
+					style: { color: FN_COLOR[fn] },
+					children: /* @__PURE__ */ jsx(Tex$1, { tex: `\\${fn}\\theta\\ ${FN_EVAL[fn](theta).toFixed(2)}` })
+				}, fn))]
+			})
+		] }),
+		children: figure
+	});
+}
+
+//#endregion
+export { TRIG_FNS, TrigExplorer };

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

@@ -0,0 +1 @@
+import { BoundaryDataset, BoundaryProps, DecisionBoundaryLab } from "./preset.mjs";

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

@@ -0,0 +1,24 @@
+import { ReactNode } from "react";
+
+//#region src/ml/boundary/preset.d.ts
+type BoundaryDataset = 'separable' | 'overlap' | 'xor';
+interface BoundaryProps {
+  dataset?: BoundaryDataset;
+  seed?: number;
+  title?: string;
+  prompt?: string;
+  objectives?: string[];
+  hints?: string[];
+  controlId?: string;
+}
+declare function DecisionBoundaryLab({
+  dataset,
+  seed,
+  title,
+  prompt,
+  objectives,
+  hints: hintList,
+  controlId
+}: BoundaryProps): ReactNode;
+//#endregion
+export { BoundaryDataset, BoundaryProps, DecisionBoundaryLab };

package/dist/ml/boundary/preset.mjs

@@ -0,0 +1,385 @@
+'use client';
+
+import { gaussian, mulberry32 } from "../../core/rng.mjs";
+import { Chip } from "../../kit/controls.mjs";
+import { Callout, ControlBar, LabFrame } from "../../kit/frame.mjs";
+import { HintLadder, useHints } from "../../kit/pedagogy.mjs";
+import { useCallback, useMemo, useRef, useState } from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+import { Axes, Circle, Dot, Grid, MovableDot, Polygon, Segment, Stage, useControlSurface, useFrameLoop, useInView } from "@classytic/stage";
+
+//#region src/ml/boundary/preset.tsx
+/**
+* DecisionBoundaryLab — a linear classifier you can SEE think. Two classes of
+* points sit in the plane; a straight boundary splits it into two predicted
+* regions. Drag the boundary's two handles to separate the classes by hand
+* (misclassified points get a red ring, accuracy updates live), then hit "train"
+* and watch a PERCEPTRON nudge the same line into place on its own. The honest
+* twist: the XOR dataset can't be split by ANY straight line — accuracy stalls
+* below 100%, the door to "why we need more than a line."
+*
+* Pure stage primitives (Stage + Polygon shading + MovableDot handles + frame-loop
+* perceptron). Seeded points → replayable. The "manipulation IS the lesson" ML lab.
+*/
+const R = 5;
+const 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) => {
+		for (let i = 0; i < k; i++) pts.push({
+			x: gaussian(rng, cx, 1),
+			y: gaussian(rng, cy, 1),
+			cls
+		});
+	};
+	if (kind === "separable") {
+		blob(-2, -1.5, 0, 14);
+		blob(2, 1.5, 1, 14);
+	} else if (kind === "overlap") {
+		blob(-1.1, -.6, 0, 16);
+		blob(1.1, .6, 1, 16);
+	} else {
+		blob(-2, 2, 0, 8);
+		blob(2, -2, 0, 8);
+		blob(2, 2, 1, 8);
+		blob(-2, -2, 1, 8);
+	}
+	return pts;
+}
+const clampR = (v) => Math.max(-5, Math.min(R, v));
+function DecisionBoundaryLab({ dataset = "separable", seed = 11, title = "Draw the decision boundary", prompt, objectives, hints: hintList, controlId }) {
+	const [kind, setKind] = useState(dataset);
+	const [pts, setPts] = useState(() => makeData(dataset, seed));
+	const [a1, setA1] = useState({
+		x: 0,
+		y: -5
+	});
+	const [a2, setA2] = useState({
+		x: 0,
+		y: R
+	});
+	const [training, setTraining] = useState(false);
+	const hints = useHints(hintList);
+	const { ref: viewRef, inView } = useInView();
+	const w = useRef([
+		0,
+		1,
+		0
+	]);
+	const iter = useRef(0);
+	const wOf = (p, q) => {
+		const dx = q.x - p.x;
+		const nx = -(q.y - p.y), ny = dx;
+		return [
+			-(nx * p.x + ny * p.y),
+			nx,
+			ny
+		];
+	};
+	const weights = useMemo(() => wOf(a1, a2), [a1, a2]);
+	const raw = (W, p) => W[0] + W[1] * p.x + W[2] * p.y;
+	const { sign, acc, wrong } = useMemo(() => {
+		const score = (s) => pts.reduce((a, p) => a + ((s * raw(weights, p) > 0 ? 1 : 0) === p.cls ? 1 : 0), 0);
+		const sp = score(1), sn = score(-1);
+		const s = sp >= sn ? 1 : -1;
+		const wr = pts.filter((p) => (s * raw(weights, p) > 0 ? 1 : 0) !== p.cls);
+		return {
+			sign: s,
+			acc: pts.length ? Math.max(sp, sn) / pts.length : 0,
+			wrong: wr
+		};
+	}, [pts, weights]);
+	const regions = useMemo(() => {
+		const corners = [
+			{
+				x: -5,
+				y: -5
+			},
+			{
+				x: R,
+				y: -5
+			},
+			{
+				x: R,
+				y: R
+			},
+			{
+				x: -5,
+				y: R
+			}
+		];
+		const f = (p) => sign * raw(weights, p);
+		const pos = [], neg = [];
+		for (let i = 0; i < 4; i++) {
+			const a = corners[i], b = corners[(i + 1) % 4], fa = f(a), fb = f(b);
+			(fa >= 0 ? pos : neg).push(a);
+			if (fa > 0 !== fb > 0) {
+				const t = fa / (fa - fb);
+				const m = {
+					x: a.x + t * (b.x - a.x),
+					y: a.y + t * (b.y - a.y)
+				};
+				pos.push(m);
+				neg.push(m);
+			}
+		}
+		return {
+			pos,
+			neg
+		};
+	}, [weights, sign]);
+	useFrameLoop(() => {
+		if (!training) return;
+		const lr = .04;
+		let changed = 0;
+		for (const p of pts) {
+			const pred = w.current[0] + w.current[1] * p.x + w.current[2] * p.y > 0 ? 1 : 0;
+			const e = p.cls - pred;
+			if (e) {
+				changed++;
+				w.current[0] += lr * e;
+				w.current[1] += lr * e * p.x;
+				w.current[2] += lr * e * p.y;
+			}
+		}
+		iter.current++;
+		const [b, wx, wy] = w.current;
+		if (Math.abs(wy) > Math.abs(wx)) {
+			setA1({
+				x: -5,
+				y: clampR(-(b + wx * -5) / (wy || 1e-6))
+			});
+			setA2({
+				x: R,
+				y: clampR(-(b + wx * R) / (wy || 1e-6))
+			});
+		} else {
+			setA1({
+				x: clampR(-(b + wy * -5) / (wx || 1e-6)),
+				y: -5
+			});
+			setA2({
+				x: clampR(-(b + wy * R) / (wx || 1e-6)),
+				y: R
+			});
+		}
+		if (changed === 0 || iter.current > 400) setTraining(false);
+	}, { running: training && inView });
+	const train = useCallback(() => {
+		w.current = [...weights];
+		iter.current = 0;
+		setTraining(true);
+	}, [weights]);
+	const loadData = useCallback((k) => {
+		setKind(k);
+		setPts(makeData(k, seed));
+		setTraining(false);
+		setA1({
+			x: 0,
+			y: -5
+		});
+		setA2({
+			x: 0,
+			y: R
+		});
+	}, [seed]);
+	const resetLine = useCallback(() => {
+		setTraining(false);
+		setA1({
+			x: 0,
+			y: -5
+		});
+		setA2({
+			x: 0,
+			y: R
+		});
+	}, []);
+	useControlSurface(controlId, {
+		dataset: {
+			type: "enum",
+			label: "dataset",
+			options: [
+				"separable",
+				"overlap",
+				"xor"
+			],
+			get: () => kind,
+			set: (v) => loadData(v)
+		},
+		train: {
+			type: "action",
+			label: "train (perceptron)",
+			invoke: train
+		},
+		reset: {
+			type: "action",
+			label: "reset boundary",
+			invoke: resetLine
+		}
+	});
+	const figure = /* @__PURE__ */ jsx("div", {
+		ref: viewRef,
+		className: "lab-playwrap",
+		children: /* @__PURE__ */ jsxs(Stage, {
+			view,
+			height: 330,
+			ariaLabel: `decision boundary, accuracy ${(acc * 100).toFixed(0)}%`,
+			children: [
+				/* @__PURE__ */ jsx(Grid, { step: 1 }),
+				/* @__PURE__ */ jsx(Axes, {}),
+				/* @__PURE__ */ jsx(Polygon, {
+					points: regions.neg,
+					fill: A0,
+					fillOpacity: .12,
+					weight: 0
+				}),
+				/* @__PURE__ */ jsx(Polygon, {
+					points: regions.pos,
+					fill: A1,
+					fillOpacity: .12,
+					weight: 0
+				}),
+				/* @__PURE__ */ jsx(Segment, {
+					from: a1,
+					to: a2,
+					color: "var(--stage-fg)",
+					weight: 2.5
+				}),
+				pts.map((p, i) => /* @__PURE__ */ jsx(Dot, {
+					x: p.x,
+					y: p.y,
+					r: 4.5,
+					color: p.cls === 0 ? A0 : A1
+				}, i)),
+				wrong.map((p, i) => /* @__PURE__ */ jsx(Circle, {
+					center: {
+						x: p.x,
+						y: p.y
+					},
+					r: .32,
+					fill: "none",
+					color: "var(--stage-danger, #e03131)",
+					weight: 2
+				}, `w${i}`)),
+				/* @__PURE__ */ jsx(MovableDot, {
+					value: a1,
+					onMove: (p) => {
+						setTraining(false);
+						setA1({
+							x: clampR(p.x),
+							y: clampR(p.y)
+						});
+					},
+					range: {
+						min: -5,
+						max: R
+					},
+					color: "var(--stage-fg)",
+					ariaLabel: "boundary handle 1"
+				}),
+				/* @__PURE__ */ jsx(MovableDot, {
+					value: a2,
+					onMove: (p) => {
+						setTraining(false);
+						setA2({
+							x: clampR(p.x),
+							y: clampR(p.y)
+						});
+					},
+					range: {
+						min: -5,
+						max: R
+					},
+					color: "var(--stage-fg)",
+					ariaLabel: "boundary handle 2"
+				})
+			]
+		})
+	});
+	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("span", {
+					className: "lab-callout-big",
+					style: { color: acc === 1 ? "var(--stage-good)" : "var(--stage-accent)" },
+					children: [
+						"accuracy ",
+						(acc * 100).toFixed(1),
+						"%"
+					]
+				}),
+				/* @__PURE__ */ jsxs("div", {
+					style: { color: "var(--stage-muted)" },
+					children: [wrong.length, " misclassified"]
+				}),
+				kind === "xor" && acc < 1 && /* @__PURE__ */ jsx("div", {
+					style: {
+						color: "var(--stage-danger, #e03131)",
+						fontWeight: 600
+					},
+					children: "a single line can't split XOR"
+				})
+			]
+		}),
+		controls: /* @__PURE__ */ jsxs(ControlBar, { children: [
+			/* @__PURE__ */ jsx(Chip, {
+				selected: training,
+				onClick: train,
+				children: training ? "⏳ training…" : "⚙ train (perceptron)"
+			}),
+			/* @__PURE__ */ jsx(Chip, {
+				selected: false,
+				onClick: resetLine,
+				children: "reset line"
+			}),
+			/* @__PURE__ */ jsx("span", {
+				style: {
+					fontSize: 12,
+					color: "var(--stage-muted)"
+				},
+				children: "data:"
+			}),
+			[
+				"separable",
+				"overlap",
+				"xor"
+			].map((k) => /* @__PURE__ */ jsx(Chip, {
+				selected: kind === k,
+				onClick: () => loadData(k),
+				children: k
+			}, k)),
+			/* @__PURE__ */ jsx("span", {
+				style: {
+					fontSize: 12,
+					color: "var(--stage-muted)"
+				},
+				children: "· drag the two handles"
+			})
+		] }),
+		footer: /* @__PURE__ */ jsx(HintLadder, { hints }),
+		children: figure
+	});
+}
+
+//#endregion
+export { DecisionBoundaryLab };

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

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

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

@@ -0,0 +1,25 @@
+import { ReactNode } from "react";
+
+//#region src/ml/classifier/preset.d.ts
+interface ClassifierProps {
+  positives?: number[];
+  negatives?: number[];
+  threshold?: number;
+  span?: number;
+  title?: string;
+  prompt?: string;
+  objectives?: string[];
+  height?: number;
+}
+declare function ClassifierThresholdLab({
+  positives,
+  negatives,
+  threshold,
+  span,
+  title,
+  prompt,
+  objectives,
+  height
+}: ClassifierProps): ReactNode;
+//#endregion
+export { ClassifierProps, ClassifierThresholdLab };