@classytic/labs 0.1.0 → 0.2.0

package/dist/math/trig/rules.mjs

@@ -0,0 +1,159 @@
+import { toRad } from "../../core/util.mjs";
+import { calc } from "../../kit/calc.mjs";
+import { castLetter, castPositive, evalTrig, exactTex, isSpecial, normDeg, quadrant, radTex, referenceAngleDeg, sign } from "./core.mjs";
+import { SpecialTriangles, UnitCircleMini } from "./diagrams.mjs";
+import { Fragment, createElement } from "react";
+
+//#region src/math/trig/rules.ts
+/**
+* The trig RULEBOOK: signs (CAST), exact values, the Pythagorean identity, and
+* degree↔radian — as RuleDef data for the RuleCard concept engine (formula +
+* analogy + live worked calculator + derivation + tricks). Calculators run on the
+* trig teaching kernel.
+*/
+const fmt = (n) => Number.isNaN(n) ? "\\text{undef}" : (Math.round(n * 1e3) / 1e3).toString();
+/** Which functions are positive in the quadrant of `deg`, with the signs. */
+function explainCast(deg) {
+	const q = quadrant(deg);
+	const pos = castPositive(deg);
+	const sg = (fn) => `\\${fn}: ${sign(fn, deg) > 0 ? "+" : sign(fn, deg) < 0 ? "-" : "0"}`;
+	return calc().step(`\\theta = ${normDeg(deg)}^\\circ \\Rightarrow \\text{Quadrant } ${q || "\\text{axis}"}`, "where the terminal ray lands").step(`${sg("sin")}, \\quad ${sg("cos")}, \\quad ${sg("tan")}`, q ? `Q${q}: only ${pos.join("/")} positive (${castLetter(deg)})` : "on an axis").done(q);
+}
+/** Exact sin/cos/tan at a special angle, via reference angle + sign. */
+function explainExact(deg) {
+	const ref = referenceAngleDeg(deg);
+	const special = isSpecial(deg);
+	const c = calc().step(`\\theta = ${normDeg(deg)}^\\circ, \\quad \\text{reference } = ${ref}^\\circ`, "reduce to the acute angle");
+	if (special) c.step(`\\sin = ${exactTex("sin", deg)}, \\;\\; \\cos = ${exactTex("cos", deg)}, \\;\\; \\tan = ${exactTex("tan", deg)}`, "reference value × the quadrant sign");
+	else c.step(`\\sin \\approx ${fmt(evalTrig("sin", deg))}, \\;\\; \\cos \\approx ${fmt(evalTrig("cos", deg))}`, "not a standard angle, decimal");
+	return c.done(ref);
+}
+/** Degree → exact radian. */
+function explainDegRad(deg) {
+	return calc().step(`${normDeg(deg)}^\\circ \\times \\dfrac{\\pi}{180^\\circ}`, "because 180° = π radians").step(`= ${radTex(deg)}`).done(toRad(deg));
+}
+const CAST_RULE = {
+	id: "cast",
+	name: "CAST: signs by quadrant",
+	formula: "\\text{Q1: All} \\;|\\; \\text{Q2: Sin} \\;|\\; \\text{Q3: Tan} \\;|\\; \\text{Q4: Cos}",
+	analogy: "\"All Students Take Calculus.\" Going anticlockwise from Q1: All positive, then only Sin, then only Tan, then only Cos.",
+	figure: (v) => createElement(UnitCircleMini, {
+		deg: v.deg ?? 0,
+		showLegs: true,
+		showCast: true
+	}),
+	inputs: [{
+		key: "deg",
+		label: "θ°",
+		default: 210,
+		min: 0,
+		max: 345,
+		step: 15
+	}],
+	compute: (v) => explainCast(v.deg ?? 0),
+	derivation: [
+		{
+			tex: "\\cos\\theta = x, \\quad \\sin\\theta = y",
+			note: "the point on the unit circle"
+		},
+		{ tex: "\\tan\\theta = \\tfrac{\\sin\\theta}{\\cos\\theta} = \\tfrac{y}{x}" },
+		{
+			tex: "\\text{so the signs are just the signs of } x, y",
+			note: "Q2: x<0,y>0 ⇒ only sin +"
+		}
+	],
+	tricks: [
+		"It is literally the sign of x (cos) and y (sin) in each quadrant.",
+		"tan is positive where sin and cos AGREE in sign (Q1, Q3).",
+		"Reference angle gives the size; CAST gives the sign."
+	]
+};
+const EXACT_RULE = {
+	id: "exact-values",
+	name: "Exact special-angle values",
+	formula: "\\sin 30^\\circ=\\tfrac12,\\; \\cos 30^\\circ=\\tfrac{\\sqrt3}{2},\\; \\sin 45^\\circ=\\tfrac{\\sqrt2}{2}",
+	analogy: "They all come from two triangles: the 45-45-90 (sides 1,1,√2) and the 30-60-90 (sides 1,√3,2).",
+	figure: (v) => createElement(Fragment, null, createElement("div", { style: {
+		display: "grid",
+		gap: 6,
+		justifyItems: "center"
+	} }, createElement(UnitCircleMini, {
+		deg: v.deg ?? 0,
+		showLegs: true,
+		showValue: true
+	}), createElement(SpecialTriangles, {}))),
+	inputs: [{
+		key: "deg",
+		label: "θ°",
+		default: 150,
+		min: 0,
+		max: 330,
+		step: 30
+	}],
+	compute: (v) => explainExact(v.deg ?? 0),
+	tricks: [
+		"Only the multiples of 30° and 45° are \"exact\".",
+		"Find the reference angle, look up its value, then apply the CAST sign.",
+		"sin and cos swap between 30° and 60° (½ ↔ √3⁄2)."
+	]
+};
+const PYTHAG_RULE = {
+	id: "pythagorean",
+	name: "The Pythagorean identity",
+	formula: "\\sin^2\\theta + \\cos^2\\theta = 1",
+	analogy: "It IS Pythagoras on the unit circle: the point (cosθ, sinθ) sits at distance 1 from the centre, so x² + y² = 1.",
+	figure: createElement(UnitCircleMini, {
+		deg: 52,
+		showLegs: true,
+		showHyp: true
+	}),
+	derivation: [
+		{
+			tex: "(\\cos\\theta,\\ \\sin\\theta) \\text{ is on the unit circle}",
+			note: "radius 1"
+		},
+		{
+			tex: "x^2 + y^2 = 1^2",
+			note: "distance from the origin"
+		},
+		{ tex: "\\Rightarrow \\cos^2\\theta + \\sin^2\\theta = 1" }
+	],
+	tricks: [
+		"Divide by cos²θ → 1 + tan²θ = sec²θ.",
+		"Divide by sin²θ → 1 + cot²θ = csc²θ.",
+		"Lets you get cos from sin (up to sign): cosθ = ±√(1 − sin²θ)."
+	]
+};
+const DEG_RAD_RULE = {
+	id: "deg-rad",
+	name: "Degrees ↔ radians",
+	formula: "180^\\circ = \\pi \\text{ rad}, \\qquad 1^\\circ = \\tfrac{\\pi}{180}",
+	analogy: "A radian is the angle that wraps one radius-length of arc around the circle; a full turn (360°) is 2π of them.",
+	figure: (v) => createElement(UnitCircleMini, {
+		deg: v.deg ?? 0,
+		showLegs: false
+	}),
+	inputs: [{
+		key: "deg",
+		label: "θ°",
+		default: 30,
+		min: 0,
+		max: 360,
+		step: 15
+	}],
+	compute: (v) => explainDegRad(v.deg ?? 0),
+	tricks: [
+		"× π/180 to go deg → rad; × 180/π to go back.",
+		"Memorise the anchors: 180°=π, 90°=π/2, 60°=π/3, 45°=π/4, 30°=π/6.",
+		"Calculus needs radians (so d/dx sin x = cos x works)."
+	]
+};
+const TRIG_RULES = [
+	CAST_RULE,
+	EXACT_RULE,
+	PYTHAG_RULE,
+	DEG_RAD_RULE
+];
+
+//#endregion
+export { TRIG_RULES };

package/dist/math/trig-explorer.mjs

@@ -10,14 +10,14 @@ import { Axes, Circle, Dot, Grid, MovableDot, Polyline, Segment, Stage, Vector,
 
 //#region src/math/trig-explorer.tsx
 /**
-* TrigExplorer — the unit circle ↔ sine wave connection (3Blue1Brown style),
+* 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,
+* 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
+* 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.
@@ -173,7 +173,7 @@ function TrigExplorer({ functions, startDeg = 30 } = {}) {
 	});
 	return /* @__PURE__ */ jsx(LabFrame, {
 		title: "Trig Explorer",
-		prompt: "Drag the angle on the circle (or press play) — sin and cos are just its shadows.",
+		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),

package/dist/ml/boundary/preset.mjs

@@ -3,19 +3,19 @@
 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 { HintLadder, useCheckpoint, 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
+* 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
+* 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
@@ -96,6 +96,11 @@ function DecisionBoundaryLab({ dataset = "separable", seed = 11, title = "Draw t
 			wrong: wr
 		};
 	}, [pts, weights]);
+	useCheckpoint({
+		solved: acc === 1,
+		activity: `boundary:${title}`,
+		hintsUsed: hints.count
+	});
 	const regions = useMemo(() => {
 		const corners = [
 			{

package/dist/ml/classifier/preset.mjs

@@ -3,17 +3,17 @@
 import { clamp } from "../../core/util.mjs";
 import { StatusPill } from "../../kit/controls.mjs";
 import { LabFrame, LiveRegion } from "../../kit/frame.mjs";
-import { useCheckpoint } from "../../kit/pedagogy.mjs";
+import { ChallengeCard, useChallenge, useCheckpoint } from "../../kit/pedagogy.mjs";
 import { useState } from "react";
 import { Fragment as Fragment$1, jsx, jsxs } from "react/jsx-runtime";
 import { Circle, Dot, Label, MovableDot, Polygon, Segment, Stage } from "@classytic/stage";
 
 //#region src/ml/classifier/preset.tsx
 /**
-* ClassifierThresholdLab — the precision/recall trade-off you can drag. Positive
+* ClassifierThresholdLab, the precision/recall trade-off you can drag. Positive
 * and negative examples sit along a score axis (they OVERLAP, like any real
 * classifier). Drag the threshold: everything to its right is predicted positive.
-* The 2×2 confusion matrix and precision / recall / accuracy / F1 update live —
+* The 2×2 confusion matrix and precision / recall / accuracy / F1 update live , 
 * slide right and precision climbs while recall falls; there's no setting that
 * maxes both. Misclassified points get a red ring.
 *
@@ -46,7 +46,27 @@ const DEFAULT_NEG = [
 	5,
 	6
 ];
-function ClassifierThresholdLab({ positives = DEFAULT_POS, negatives = DEFAULT_NEG, threshold = 5, span = 10, title = "The precision–recall trade-off", prompt = "Drag the threshold: everything to its right is called positive. Watch the confusion matrix — pushing precision up costs you recall.", objectives, height = 300 }) {
+const PREDICT_Q = [{
+	id: "recall-vs-threshold",
+	prompt: "As you RAISE the threshold (label fewer things positive), what happens to RECALL — the share of true positives you catch?",
+	choices: [
+		{
+			value: "down",
+			label: "recall falls"
+		},
+		{
+			value: "up",
+			label: "recall rises"
+		},
+		{
+			value: "same",
+			label: "unchanged"
+		}
+	],
+	answer: "down",
+	explain: "Raising the threshold means fewer points clear the bar, so you catch fewer of the real positives (more false negatives): recall falls. Precision usually rises in return, since the ones you do call positive are more likely correct. That is the trade-off, no single threshold maxes both."
+}];
+function ClassifierThresholdLab({ positives = DEFAULT_POS, negatives = DEFAULT_NEG, threshold = 5, span = 10, title = "The precision–recall trade-off", prompt = "Drag the threshold: everything to its right is called positive. Watch the confusion matrix, pushing precision up costs you recall.", objectives, height = 300 }) {
 	const view = {
 		xMin: 0,
 		xMax: span,
@@ -55,8 +75,9 @@ function ClassifierThresholdLab({ positives = DEFAULT_POS, negatives = DEFAULT_N
 	};
 	const [t, setT] = useState(threshold);
 	const [moved, setMoved] = useState(false);
+	const ch = useChallenge(PREDICT_Q);
 	useCheckpoint({
-		solved: moved,
+		solved: moved && ch.allCorrect,
 		activity: "classifier-threshold"
 	});
 	const TP = positives.filter((s) => s >= t).length;
@@ -306,7 +327,11 @@ function ClassifierThresholdLab({ positives = DEFAULT_POS, negatives = DEFAULT_N
 				})
 			]
 		})] }),
-		footer: /* @__PURE__ */ jsx(LiveRegion, { children: `Threshold ${t.toFixed(1)}. Precision ${(precision * 100).toFixed(0)} percent, recall ${(recall * 100).toFixed(0)} percent.` }),
+		footer: /* @__PURE__ */ jsxs(Fragment$1, { children: [/* @__PURE__ */ jsx(ChallengeCard, {
+			questions: PREDICT_Q,
+			state: ch,
+			title: "Predict first"
+		}), /* @__PURE__ */ jsx(LiveRegion, { children: `Threshold ${t.toFixed(1)}. Precision ${(precision * 100).toFixed(0)} percent, recall ${(recall * 100).toFixed(0)} percent.` })] }),
 		children: figure
 	});
 }

package/dist/ml/kmeans/preset.mjs

@@ -9,12 +9,12 @@ import { Circle, Dot, Grid, MovableDot, Segment, Stage, useFrameLoop, useInView
 
 //#region src/ml/kmeans/preset.tsx
 /**
-* KMeansLab — unsupervised clustering you can watch converge. Points sit in a few
+* 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):
 * every point recolours to its nearest centroid, and each centroid jumps to the
-* mean of its cluster. Run animates it — centroids migrate into the blobs, the
+* mean of its cluster. Run animates it, centroids migrate into the blobs, the
 * within-cluster error (inertia) drops, and it stops when nothing moves. Seed the
-* centroids badly on purpose and you land in a worse local minimum — the key
+* centroids badly on purpose and you land in a worse local minimum, the key
 * k-means intuition that initialisation matters.
 *
 * Pure stage primitives: Dot (coloured by assignment) + MovableDot (centroids) +
@@ -59,7 +59,7 @@ const DEFAULT_SEEDS = [
 	}
 ];
 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 }) {
+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 = {
 		xMin: 0,
 		xMax: span,

package/dist/ml/knn/preset.mjs

@@ -10,15 +10,15 @@ 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
+* 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
+* 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
+* 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";
@@ -182,15 +182,50 @@ function KNNBoundaryLab({ dataset = "circles", k = 5, seed = 7, title = "k-neare
 			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)}%`
+	const vw = useMemo(() => view, []);
+	const clampX = (x) => Math.max(view.xMin, Math.min(view.xMax, x));
+	const clampY = (y) => Math.max(view.yMin, Math.min(view.yMax, y));
+	const KEY_STEP = .25;
+	const onKeyDown = useCallback((e) => {
+		let dx = 0, dy = 0;
+		if (e.key === "ArrowLeft") dx = -.25;
+		else if (e.key === "ArrowRight") dx = KEY_STEP;
+		else if (e.key === "ArrowUp") dy = KEY_STEP;
+		else if (e.key === "ArrowDown") dy = -.25;
+		else return;
+		e.preventDefault();
+		setQuery((q) => ({
+			x: clampX(q.x + dx),
+			y: clampY(q.y + dy)
+		}));
+	}, []);
+	const figure = /* @__PURE__ */ jsx("div", {
+		tabIndex: 0,
+		role: "application",
+		"aria-label": `k-NN decision boundary, k ${kk}. Test point predicts class ${qCls ? "B" : "A"}. Accuracy ${(acc * 100).toFixed(0)} percent. Use arrow keys to move the test point.`,
+		onKeyDown,
+		style: {
+			outline: "none",
+			borderRadius: 6,
+			position: "relative"
+		},
+		onFocus: (e) => {
+			e.currentTarget.style.outline = "2px solid var(--stage-accent, #1c7ed6)";
+			e.currentTarget.style.outlineOffset = "2px";
+		},
+		onBlur: (e) => {
+			e.currentTarget.style.outline = "none";
+		},
+		children: /* @__PURE__ */ jsx(CanvasLayer, {
+			view: vw,
+			height,
+			draw,
+			onPointerMath: (m) => setQuery({
+				x: clampX(m[0]),
+				y: clampY(m[1])
+			}),
+			ariaLabel: `k-NN boundary, k ${kk}, accuracy ${(acc * 100).toFixed(0)}%`
+		})
 	});
 	return /* @__PURE__ */ jsx(LabFrame, {
 		title,

package/dist/ml/regression/preset.mjs

@@ -3,26 +3,26 @@
 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 { ChallengeCard, useChallenge, 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.
+* 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"
+* 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-
+* 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.
+* on-screen square, and stays SSR-deterministic.
 */
 const DEFAULT_DATA = [
 	{
@@ -62,7 +62,16 @@ const DEFAULT_DATA = [
 		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 slopeSign = (data) => {
+	const n = data.length;
+	if (n === 0) return "up";
+	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;
+	for (const p of data) num += (p.x - xb) * (p.y - yb);
+	return num >= 0 ? "up" : "down";
+};
+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,
@@ -118,6 +127,22 @@ function RegressionLab({ data = DEFAULT_DATA, showSquares = true, learnRate = .0
 		solved: closeEnough,
 		activity: "regression"
 	});
+	const predictQ = useMemo(() => {
+		return [{
+			id: "slope-sign",
+			prompt: "Before you fit the line — looking at the cloud of points, will the best-fit line slope UP or DOWN?",
+			choices: [{
+				value: "up",
+				label: "slope up (positive)"
+			}, {
+				value: "down",
+				label: "slope down (negative)"
+			}],
+			answer: slopeSign(data),
+			explain: "Least squares follows the overall trend of the cloud: as x increases the points drift the same way, so the best-fit slope picks up that direction — no dragging needed to call its sign."
+		}];
+	}, [data]);
+	const ch = useChallenge(predictQ);
 	const lineRef = useRef(line);
 	lineRef.current = line;
 	const iterRef = useRef(0);
@@ -385,7 +410,11 @@ function RegressionLab({ data = DEFAULT_DATA, showSquares = true, learnRate = .0
 				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." : ""}` }),
+		footer: /* @__PURE__ */ jsxs(Fragment$1, { children: [/* @__PURE__ */ jsx(ChallengeCard, {
+			questions: predictQ,
+			state: ch,
+			title: "Predict first"
+		}), /* @__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
 	});
 }

package/dist/physics/atwood/preset.mjs

@@ -11,7 +11,7 @@ import { Circle, Label, Polygon, Segment, Stage, useInView } from "@classytic/st
 
 //#region src/physics/atwood/preset.tsx
 /**
-* AtwoodLab — "Which way, and how fast?", two masses over a pulley.
+* AtwoodLab, "Which way, and how fast?", two masses over a pulley.
 *
 * The classic Atwood machine: link two masses over a frictionless pulley and the
 * WHOLE system shares one acceleration. Gravity pulls each side (m·g), but only
@@ -27,7 +27,7 @@ import { Circle, Label, Polygon, Segment, Stage, useInView } from "@classytic/st
 const G = 9.8;
 const Y0 = .6;
 const TRAVEL = 2.6;
-function AtwoodLab({ m1 = 3, m2 = 2, title = "Atwood machine — which way, and how fast?", prompt = "Two masses share one rope over a pulley. Only the difference in weight drives them, while the total mass resists: a = (m₁ − m₂)g / (m₁ + m₂). Predict which side falls, then release.", objectives, controlConfig }) {
+function AtwoodLab({ m1 = 3, m2 = 2, title = "Atwood machine: which way, and how fast?", prompt = "Two masses share one rope over a pulley. Only the difference in weight drives them, while the total mass resists: a = (m₁ − m₂)g / (m₁ + m₂). Predict which side falls, then release.", objectives, controlConfig }) {
 	const [ma, setMa] = useState(m1);
 	const [mb, setMb] = useState(m2);
 	const [running, setRunning] = useState(false);
@@ -244,7 +244,7 @@ function AtwoodLab({ m1 = 3, m2 = 2, title = "Atwood machine — which way, and
 				}),
 				/* @__PURE__ */ jsx(StatusPill, {
 					ok: !balanced,
-					children: balanced ? "balanced — no motion" : `${ma > mb ? "left" : "right"} side falls`
+					children: balanced ? "balanced, no motion" : `${ma > mb ? "left" : "right"} side falls`
 				}),
 				/* @__PURE__ */ jsxs("p", {
 					style: {
@@ -257,7 +257,7 @@ function AtwoodLab({ m1 = 3, m2 = 2, title = "Atwood machine — which way, and
 						/* @__PURE__ */ jsx("strong", { children: "difference" }),
 						" (m₁−m₂)g drives it; the ",
 						/* @__PURE__ */ jsx("strong", { children: "total" }),
-						" (m₁+m₂) resists. Big equal masses with a tiny difference give a slow, measurable a — how Atwood weighed gravity."
+						" (m₁+m₂) resists. Big equal masses with a tiny difference give a slow, measurable a, how Atwood weighed gravity."
 					]
 				}),
 				/* @__PURE__ */ jsx(LiveRegion, { children: balanced ? "Balanced, no motion." : `${ma > mb ? "Left" : "Right"} side falls at ${Math.abs(a).toFixed(2)} metres per second squared.` })

package/dist/physics/bullet-walls/preset.d.mts

@@ -11,7 +11,7 @@ interface BulletWallsProps {
   title?: string;
   prompt?: string;
   objectives?: string[];
-  /** Lock/hide any knob — e.g. `{ lock: ['plank toughness'] }` to fix the toughness. */
+  /** Lock/hide any knob, e.g. `{ lock: ['plank toughness'] }` to fix the toughness. */
   controlConfig?: ControlConfig;
 }
 declare function BulletWallsLab({

package/dist/physics/bullet-walls/preset.mjs

@@ -10,18 +10,18 @@ import { Label, Polygon, Segment, Stage, useInView, useLearner } from "@classyti
 
 //#region src/physics/bullet-walls/preset.tsx
 /**
-* BulletWallsLab — "How many planks?", the classic penetration problem made
+* BulletWallsLab, "How many planks?", the classic penetration problem made
 * watchable and PREDICT-FIRST.
 *
 * A bullet fires into a stack of identical planks. Each plank pushes back with a
 * constant retarding force over its thickness, so it drains a FIXED chunk of
-* kinetic energy — equivalently a fixed Δ(v²) per plank. The bullet free-flies
+* kinetic energy, equivalently a fixed Δ(v²) per plank. The bullet free-flies
 * between planks (constant v) and decelerates linearly in v² while inside one
 * (v²(x) = v²ₑ − (cost/width)·depth), the textbook v² = u² − 2as. It stops the
-* instant its kinetic energy runs out — embedding partway through a plank.
+* instant its kinetic energy runs out, embedding partway through a plank.
 *
 * The learner GUESSES how many planks it punches through, then fires and watches
-* it slow plank-by-plank while the KE bar drains — turning "N = u²/(2as)" from a
+* it slow plank-by-plank while the KE bar drains, turning "N = u²/(2as)" from a
 * formula into a bet you can win.
 *
 * Tokenized SVG; time-dependent integrator here; honours reduced-motion.
@@ -29,7 +29,7 @@ import { Label, Polygon, Segment, Stage, useInView, useLearner } from "@classyti
 const PLANK_W = .7;
 const START_X = -4;
 const STACK_X0 = 0;
-function BulletWallsLab({ speed = 30, toughness = 160, planks = 6, mass = .02, title = "How many planks? — bet, then fire", prompt = "Each plank steals the same chunk of energy. Guess how many the bullet smashes through, then fire and watch the speed (and the energy bar) drain plank by plank.", objectives, controlConfig }) {
+function BulletWallsLab({ speed = 30, toughness = 160, planks = 6, mass = .02, title = "How many planks?: bet, then fire", prompt = "Each plank steals the same chunk of energy. Guess how many the bullet smashes through, then fire and watch the speed (and the energy bar) drain plank by plank.", objectives, controlConfig }) {
 	const [v0, setV0] = useState(speed);
 	const [cost, setCost] = useState(toughness);
 	const [n, setN] = useState(planks);
@@ -253,7 +253,7 @@ function BulletWallsLab({ speed = 30, toughness = 160, planks = 6, mass = .02, t
 			]
 		})
 	});
-	const verdict = settled ? guess === fullPenetrated ? `🎯 Spot on — ${fullPenetrated} planks` : `It broke ${fullPenetrated}, you guessed ${guess}` : null;
+	const verdict = settled ? guess === fullPenetrated ? `🎯 Spot on, ${fullPenetrated} planks` : `It broke ${fullPenetrated}, you guessed ${guess}` : null;
 	return /* @__PURE__ */ jsx(LabFrame, {
 		title,
 		prompt,
@@ -303,7 +303,7 @@ function BulletWallsLab({ speed = 30, toughness = 160, planks = 6, mass = .02, t
 					children: [
 						"Predict with ",
 						/* @__PURE__ */ jsx("strong", { children: "N = u² / (Δv² per plank)" }),
-						" — then watch v² fall by the same step each plank (v² = u² − 2as). It lodges when the energy hits zero."
+						", then watch v² fall by the same step each plank (v² = u² − 2as). It lodges when the energy hits zero."
 					]
 				}),
 				/* @__PURE__ */ jsx(LiveRegion, { children: settled ? `The bullet broke ${fullPenetrated} of ${n} planks. You guessed ${guess}.` : "" })

package/dist/physics/carnot/preset.mjs

@@ -11,11 +11,11 @@ import { carnotCycle, gammaDiatomic, gammaMonatomic } from "@classytic/stage/the
 
 //#region src/physics/carnot/preset.tsx
 /**
-* CarnotCycleLab — the most efficient possible heat engine, shown two ways at once:
+* CarnotCycleLab, the most efficient possible heat engine, shown two ways at once:
 *   • P–V diagram: the four-leg loop (hot isothermal expansion → adiabatic expansion
 *     → cold isothermal compression → adiabatic compression). The ENCLOSED area is
 *     the net work the engine delivers per cycle.
-*   • T–S diagram: the very same cycle is a RECTANGLE — heat in along the top (Th),
+*   • T–S diagram: the very same cycle is a RECTANGLE, heat in along the top (Th),
 *     heat out along the bottom (Tc), entropy unchanged on the adiabatic sides. Its
 *     area (ΔS·(Th−Tc)) equals the net work too, and it makes the entropy bookkeeping
 *     obvious: ΔS = Qh/Th = Qc/Tc, so the gas returns to the same entropy (net ΔS = 0).
@@ -27,10 +27,10 @@ import { carnotCycle, gammaDiatomic, gammaMonatomic } from "@classytic/stage/the
 const W = 720, H = 380;
 const V1 = .02;
 const J = (x) => Math.round(x).toString();
-function CarnotCycleLab({ hotK = 500, coldK = 300, gas = "monatomic", expansionRatio = 2, title = "Carnot cycle — the best a heat engine can do", prompt = "A gas absorbs heat at a hot temperature, does work, and dumps the rest at a cold one. Watch the loop on the P–V diagram and the same cycle as a rectangle on the T–S diagram.", objectives = [
+function CarnotCycleLab({ hotK = 500, coldK = 300, gas = "monatomic", expansionRatio = 2, title = "Carnot cycle: the best a heat engine can do", prompt = "A gas absorbs heat at a hot temperature, does work, and dumps the rest at a cold one. Watch the loop on the P–V diagram and the same cycle as a rectangle on the T–S diagram.", objectives = [
 	"See the Carnot cycle as a P–V loop whose area is the net work",
 	"Read the same cycle as a T–S rectangle (heat in at Th, out at Tc)",
-	"Derive the efficiency η = 1 − Tc/Th — the ceiling no engine can beat"
+	"Derive the efficiency η = 1 − Tc/Th, the ceiling no engine can beat"
 ] } = {}) {
 	const [Th, setTh] = useState(hotK);
 	const [Tc, setTc] = useState(coldK);
@@ -345,7 +345,7 @@ function CarnotCycleLab({ hotK = 500, coldK = 300, gas = "monatomic", expansionR
 								" K"
 							]
 						}),
-						". The wider the temperature gap, the more efficient — but you can never reach 100% without Tc = 0."
+						". The wider the temperature gap, the more efficient, but you can never reach 100% without Tc = 0."
 					]
 				}),
 				/* @__PURE__ */ jsxs("span", {
@@ -355,7 +355,7 @@ function CarnotCycleLab({ hotK = 500, coldK = 300, gas = "monatomic", expansionR
 						/* @__PURE__ */ jsx(Tex, { tex: "\\Delta S = Q_h/T_h = Q_c/T_c" }),
 						" = ",
 						dS.toFixed(2),
-						" J/K, so the gas comes back to the same entropy — ",
+						" J/K, so the gas comes back to the same entropy, ",
 						/* @__PURE__ */ jsx("strong", {
 							style: { color: "var(--stage-fg)" },
 							children: "net ΔS = 0"