@classytic/labs 0.1.0

package/dist/kit/pedagogy.mjs

@@ -0,0 +1,331 @@
+'use client';
+
+import { useEffect, useRef, useState } from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+import { useLearner } from "@classytic/stage";
+
+//#region src/kit/pedagogy.tsx
+/**
+* Pedagogy/assessment kit — the formative-feedback layer every lab shares.
+*
+* `LabMeta` (objectives, hints, misconceptions, successCriteria) was authored
+* but never rendered. This turns it into the Brilliant-style loop:
+*   • `useCheckpoint` — the ONE assessment seam: report once on first solve,
+*     with a hint penalty folded into the score. Kills the per-lab
+*     `if (x === answer) report(...)` + done-ref boilerplate.
+*   • `useHints` + `<HintLadder>` — progressive reveal; each hint taken docks
+*     the score (pass `hints.count` to useCheckpoint).
+*   • `<Objectives>` — the learner-visible goal banner.
+*   • `<Feedback>` — unifies success / try-again / misconception note (the
+*     misconception is a boolean the lab computes from resolved state).
+*   • `<RevealSolution>` — the shared "Show answer" escape hatch every lab gets:
+*     a button → a warned solution panel, firing `onReveal` once so the lab can
+*     dock the score (peeking ≠ solving). No more dead-end "wrong/right".
+*
+* Domain glue over stage's learner seam — stays in labs so stage is a pure
+* engine; imports only `useLearner` from @classytic/stage.
+*/
+/** Report completion once, the first time `solved` becomes true. */
+function useCheckpoint({ solved, activity, score, hintsUsed = 0, hintPenalty = .1, response }) {
+	const learner = useLearner();
+	const done = useRef(false);
+	const [reported, setReported] = useState(false);
+	useEffect(() => {
+		if (solved && !done.current) {
+			done.current = true;
+			setReported(true);
+			const base = score ?? {
+				raw: 1,
+				max: 1
+			};
+			const factor = Math.max(.1, 1 - hintsUsed * hintPenalty);
+			learner?.report({
+				activity,
+				correct: true,
+				completion: true,
+				response,
+				score: {
+					raw: Math.round(base.raw * factor * 100) / 100,
+					max: base.max
+				}
+			});
+		}
+		if (!solved && done.current) {
+			done.current = false;
+			setReported(false);
+		}
+	}, [
+		solved,
+		activity,
+		hintsUsed,
+		hintPenalty,
+		score?.raw,
+		score?.max,
+		response,
+		learner
+	]);
+	return {
+		solved,
+		reported
+	};
+}
+/** Progressive hint state — reveal one at a time. */
+function useHints(hints = []) {
+	const [n, setN] = useState(0);
+	return {
+		revealed: hints.slice(0, n),
+		count: n,
+		hasMore: n < hints.length,
+		reveal: () => setN((v) => Math.min(hints.length, v + 1)),
+		reset: () => setN(0)
+	};
+}
+/** Learner-visible goal banner ("You'll be able to …"). */
+function Objectives({ items }) {
+	if (!items?.length) return null;
+	return /* @__PURE__ */ jsxs("div", {
+		className: "lab-objectives",
+		children: [/* @__PURE__ */ jsx("span", {
+			className: "lab-objectives-h",
+			children: "You'll be able to"
+		}), /* @__PURE__ */ jsx("ul", { children: items.map((o, i) => /* @__PURE__ */ jsx("li", { children: o }, i)) })]
+	});
+}
+/** The hint ladder — revealed hints + a "need a hint?" button while more remain. */
+function HintLadder({ hints }) {
+	if (hints.revealed.length === 0 && !hints.hasMore) return null;
+	return /* @__PURE__ */ jsxs("div", {
+		className: "lab-hints",
+		children: [hints.revealed.map((h, i) => /* @__PURE__ */ jsxs("p", {
+			className: "lab-hint",
+			children: [
+				/* @__PURE__ */ jsx("span", {
+					"aria-hidden": true,
+					children: "💡"
+				}),
+				" ",
+				h
+			]
+		}, i)), hints.hasMore && /* @__PURE__ */ jsx("button", {
+			type: "button",
+			className: "lab-hint-btn",
+			onClick: hints.reveal,
+			children: hints.count === 0 ? "Need a hint?" : "Another hint"
+		})]
+	});
+}
+/** State for a small set of predict/classify questions. */
+function useChallenge(questions) {
+	const [picks, setPicks] = useState({});
+	const total = questions.length;
+	const solvedCount = questions.filter((q) => picks[q.id] === q.answer).length;
+	return {
+		picks,
+		pick: (id, value) => setPicks((p) => ({
+			...p,
+			[id]: value
+		})),
+		allCorrect: total > 0 && solvedCount === total,
+		answeredAll: questions.every((q) => picks[q.id] != null),
+		solvedCount,
+		total,
+		reset: () => setPicks({})
+	};
+}
+/** Renders the challenge questions as choice chips with per-question feedback. */
+function ChallengeCard({ questions, state, title = "Predict first" }) {
+	return /* @__PURE__ */ jsxs("div", {
+		className: "lab-challenge",
+		children: [title && /* @__PURE__ */ jsxs("span", {
+			className: "lab-challenge-h",
+			children: [title, state.total > 1 && /* @__PURE__ */ jsxs("span", {
+				className: "lab-challenge-count",
+				children: [
+					" · ",
+					state.solvedCount,
+					"/",
+					state.total
+				]
+			})]
+		}), questions.map((q) => {
+			const picked = state.picks[q.id];
+			const answered = picked != null;
+			const correct = picked === q.answer;
+			return /* @__PURE__ */ jsxs("div", {
+				className: "lab-challenge-q",
+				children: [
+					/* @__PURE__ */ jsx("span", {
+						className: "lab-challenge-prompt",
+						children: q.prompt
+					}),
+					/* @__PURE__ */ jsx("div", {
+						className: "lab-choices",
+						role: "group",
+						"aria-label": typeof q.prompt === "string" ? q.prompt : "choices",
+						children: q.choices.map((c) => {
+							const isPicked = picked === c.value;
+							const tone = !answered ? void 0 : c.value === q.answer ? "correct" : isPicked ? "wrong" : void 0;
+							return /* @__PURE__ */ jsx("button", {
+								type: "button",
+								className: "lab-choice",
+								"data-picked": isPicked || void 0,
+								"data-tone": tone,
+								"aria-pressed": isPicked,
+								onClick: () => state.pick(q.id, c.value),
+								children: c.label
+							}, c.value);
+						})
+					}),
+					answered && (correct ? /* @__PURE__ */ jsxs("span", {
+						className: "lab-pill",
+						"data-state": "ok",
+						role: "status",
+						children: ["✓ ", q.explain ?? "Correct"]
+					}) : /* @__PURE__ */ jsx("span", {
+						className: "lab-pill",
+						"data-state": "no",
+						role: "status",
+						children: "Not yet — try again"
+					}))
+				]
+			}, q.id);
+		})]
+	});
+}
+function AskBox({ prompt, placeholder = "your answer", check, activity }) {
+	const [raw, setRaw] = useState("");
+	const [verdict, setVerdict] = useState(null);
+	const [solved, setSolved] = useState(false);
+	useCheckpoint({
+		solved,
+		activity
+	});
+	const run = () => {
+		const ok = check(raw);
+		setVerdict(ok);
+		if (ok) setSolved(true);
+	};
+	return /* @__PURE__ */ jsxs("div", {
+		className: "lab-challenge",
+		children: [
+			/* @__PURE__ */ jsx("span", {
+				className: "lab-challenge-prompt",
+				children: prompt
+			}),
+			/* @__PURE__ */ jsxs("div", {
+				className: "lab-ask-row",
+				children: [
+					/* @__PURE__ */ jsx("input", {
+						className: "lab-input",
+						value: raw,
+						placeholder,
+						"aria-label": "answer",
+						onChange: (e) => {
+							setRaw(e.currentTarget.value);
+							setVerdict(null);
+						},
+						onKeyDown: (e) => {
+							if (e.key === "Enter") run();
+						}
+					}),
+					/* @__PURE__ */ jsx("button", {
+						type: "button",
+						className: "lab-btn",
+						onClick: run,
+						children: "Check"
+					}),
+					verdict === true && /* @__PURE__ */ jsx("span", {
+						className: "lab-pill",
+						"data-state": "ok",
+						role: "status",
+						children: "✓ Correct"
+					}),
+					verdict === false && /* @__PURE__ */ jsx("span", {
+						className: "lab-pill",
+						"data-state": "no",
+						role: "status",
+						children: "Not yet — try again"
+					})
+				]
+			}),
+			/* @__PURE__ */ jsx("div", {
+				"aria-live": "polite",
+				style: {
+					position: "absolute",
+					width: 1,
+					height: 1,
+					overflow: "hidden",
+					clipPath: "inset(50%)"
+				},
+				children: verdict === true ? "Correct." : verdict === false ? "Not yet." : ""
+			})
+		]
+	});
+}
+/** Unified success / misconception / try-again feedback. */
+function Feedback({ ok, misconception, okText = "Correct", tryText = "Not yet — keep going" }) {
+	if (ok) return /* @__PURE__ */ jsxs("span", {
+		className: "lab-pill",
+		"data-state": "ok",
+		children: ["✓ ", okText]
+	});
+	if (misconception) return /* @__PURE__ */ jsxs("span", {
+		className: "lab-misconception",
+		role: "status",
+		children: [
+			/* @__PURE__ */ jsx("span", {
+				"aria-hidden": true,
+				children: "⚠"
+			}),
+			" ",
+			misconception
+		]
+	});
+	return /* @__PURE__ */ jsx("span", {
+		className: "lab-pill",
+		"data-state": "no",
+		children: tryText
+	});
+}
+/**
+* The shared "Show answer" escape hatch — so no lab is a dead-end "wrong/right".
+* Manages its own shown/hidden; `key` it (e.g. per step/event) to reset between
+* questions. Revealing is a deliberate peek: it warns and reports via `onReveal`.
+*/
+function RevealSolution({ solution, available = true, onReveal, buttonLabel = "Show answer", note = "Peeking — this one won’t count as solved on your own." }) {
+	const [shown, setShown] = useState(false);
+	if (shown) return /* @__PURE__ */ jsxs("div", {
+		className: "lab-solution",
+		role: "status",
+		children: [
+			/* @__PURE__ */ jsxs("span", {
+				className: "lab-solution-h",
+				children: [/* @__PURE__ */ jsx("span", {
+					"aria-hidden": true,
+					children: "🔑"
+				}), " Solution"]
+			}),
+			/* @__PURE__ */ jsx("div", {
+				className: "lab-solution-body",
+				children: solution
+			}),
+			note && /* @__PURE__ */ jsx("p", {
+				className: "lab-solution-note",
+				children: note
+			})
+		]
+	});
+	if (!available) return null;
+	return /* @__PURE__ */ jsx("button", {
+		type: "button",
+		className: "lab-reveal-btn",
+		onClick: () => {
+			setShown(true);
+			onReveal?.();
+		},
+		children: buttonLabel
+	});
+}
+
+//#endregion
+export { AskBox, ChallengeCard, Feedback, HintLadder, Objectives, RevealSolution, useChallenge, useCheckpoint, useHints };

package/dist/kit/play.d.mts

@@ -0,0 +1,21 @@
+import { ReactNode, RefObject } from "react";
+
+//#region src/kit/play.d.ts
+interface PlayGate {
+  ref: RefObject<HTMLDivElement | null>;
+  inView: boolean;
+  playing: boolean;
+  setPlaying: (p: boolean) => void;
+  /** playing && inView — pass to useFrameLoop's `running`. */
+  running: boolean;
+}
+declare function usePlayGate(autoPlay?: boolean): PlayGate;
+declare function PlayWrap({
+  gate,
+  children
+}: {
+  gate: PlayGate;
+  children: ReactNode;
+}): ReactNode;
+//#endregion
+export { PlayGate, PlayWrap, usePlayGate };

package/dist/kit/play.mjs

@@ -0,0 +1,52 @@
+'use client';
+
+import { useState } from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+import { useInView } from "@classytic/stage";
+
+//#region src/kit/play.tsx
+/**
+* Play-gate for hand-driven sim labs (those running their own useFrameLoop rather
+* than going through <Scene>, which already has this). It does two things:
+*   • off-screen pause — the loop only runs while the figure is visible, so a page
+*     of labs doesn't pin the CPU;
+*   • press-to-start — an ambient animation shouldn't auto-run; show a ▶ Play
+*     overlay until the learner starts it.
+*
+* Usage:
+*   const gate = usePlayGate();
+*   useFrameLoop(tick, { running: gate.running });   // && any other condition
+*   …  <PlayWrap gate={gate}>{figureSvg}</PlayWrap>
+*
+* For a USER-TRIGGERED lab (a Run/Drop button already decides when to animate),
+* skip the overlay — just gate the existing condition on visibility with `useInView`.
+*/
+function usePlayGate(autoPlay = false) {
+	const { ref, inView } = useInView();
+	const [playing, setPlaying] = useState(autoPlay);
+	return {
+		ref,
+		inView,
+		playing,
+		setPlaying,
+		running: playing && inView
+	};
+}
+function PlayWrap({ gate, children }) {
+	return /* @__PURE__ */ jsxs("div", {
+		ref: gate.ref,
+		className: "lab-playwrap",
+		children: [children, /* @__PURE__ */ jsx("button", {
+			type: "button",
+			className: "lab-play-toggle",
+			"data-playing": gate.playing,
+			"aria-label": gate.playing ? "Pause" : "Play",
+			"aria-pressed": gate.playing,
+			onClick: () => gate.setPlaying(!gate.playing),
+			children: gate.playing ? "⏸" : "▶ Play"
+		})]
+	});
+}
+
+//#endregion
+export { PlayWrap, usePlayGate };

package/dist/kit/probability.mjs

@@ -0,0 +1,141 @@
+'use client';
+
+import { jsx, jsxs } from "react/jsx-runtime";
+
+//#region src/kit/probability.tsx
+const FG = "var(--stage-fg)";
+const FACE = "color-mix(in oklab, var(--stage-bg) 92%, var(--stage-fg))";
+const METAL = "var(--stage-metal)";
+const GOLD = "var(--stage-warn)";
+const GOOD = "var(--stage-good)";
+const SHEEN = "color-mix(in oklab, var(--stage-sheen, white) 60%, transparent)";
+const PIPS = {
+	1: [[1, 1]],
+	2: [[0, 0], [2, 2]],
+	3: [
+		[0, 0],
+		[1, 1],
+		[2, 2]
+	],
+	4: [
+		[0, 0],
+		[2, 0],
+		[0, 2],
+		[2, 2]
+	],
+	5: [
+		[0, 0],
+		[2, 0],
+		[1, 1],
+		[0, 2],
+		[2, 2]
+	],
+	6: [
+		[0, 0],
+		[2, 0],
+		[0, 1],
+		[2, 1],
+		[0, 2],
+		[2, 2]
+	]
+};
+/** A six-sided die showing `value` (1–6) in box (x,y) of side `size`. */
+function DiceGlyph({ x, y, size: s, value, highlight = false }) {
+	const r = s * .2;
+	const pipR = s * .082;
+	const pos = PIPS[Math.max(1, Math.min(6, Math.round(value)))] ?? PIPS[1];
+	return /* @__PURE__ */ jsxs("g", { children: [
+		highlight && /* @__PURE__ */ jsx("rect", {
+			x: x - 3,
+			y: y - 3,
+			width: s + 6,
+			height: s + 6,
+			rx: r + 3,
+			fill: "none",
+			stroke: GOOD,
+			strokeWidth: 3
+		}),
+		/* @__PURE__ */ jsx("rect", {
+			x,
+			y,
+			width: s,
+			height: s,
+			rx: r,
+			fill: FACE,
+			stroke: METAL,
+			strokeWidth: Math.max(1, s * .025)
+		}),
+		/* @__PURE__ */ jsx("path", {
+			d: `M${x + r},${y + s * .06} H${x + s * .62}`,
+			stroke: SHEEN,
+			strokeWidth: s * .04,
+			strokeLinecap: "round",
+			opacity: .5
+		}),
+		pos.map(([c, rr], i) => /* @__PURE__ */ jsx("circle", {
+			cx: x + s * (.25 + .25 * c),
+			cy: y + s * (.25 + .25 * rr),
+			r: pipR,
+			fill: FG
+		}, i))
+	] });
+}
+/** A coin in box centred (cx,cy) radius `r`, showing 'H' or 'T'. */
+function CoinGlyph({ cx, cy, r, face = "H", highlight = false }) {
+	const heads = face === "H" || face === "h";
+	const base = heads ? GOLD : METAL;
+	return /* @__PURE__ */ jsxs("g", { children: [
+		highlight && /* @__PURE__ */ jsx("circle", {
+			cx,
+			cy,
+			r: r * 1.22,
+			fill: "none",
+			stroke: GOOD,
+			strokeWidth: 2.5
+		}),
+		/* @__PURE__ */ jsx("circle", {
+			cx,
+			cy: cy + r * .12,
+			r,
+			fill: `color-mix(in oklab, ${base} 55%, black)`
+		}),
+		/* @__PURE__ */ jsx("circle", {
+			cx,
+			cy,
+			r,
+			fill: base,
+			stroke: `color-mix(in oklab, ${base} 60%, black)`,
+			strokeWidth: Math.max(1, r * .08)
+		}),
+		/* @__PURE__ */ jsx("circle", {
+			cx,
+			cy,
+			r: r * .82,
+			fill: "none",
+			stroke: `color-mix(in oklab, ${base} 70%, black)`,
+			strokeWidth: Math.max(1, r * .05),
+			opacity: .6
+		}),
+		/* @__PURE__ */ jsx("path", {
+			d: `M${cx - r * .5},${cy - r * .45} A${r * .7},${r * .7} 0 0 1 ${cx + r * .3},${cy - r * .62}`,
+			fill: "none",
+			stroke: SHEEN,
+			strokeWidth: r * .14,
+			strokeLinecap: "round",
+			opacity: .7
+		}),
+		/* @__PURE__ */ jsx("text", {
+			x: cx,
+			y: cy,
+			textAnchor: "middle",
+			dominantBaseline: "central",
+			fontSize: r * 1.05,
+			fontWeight: 800,
+			fill: `color-mix(in oklab, ${base} 30%, black)`,
+			children: heads ? "H" : "T"
+		})
+	] });
+}
+
+//#endregion
+export { CoinGlyph, DiceGlyph };

package/dist/kit/proportion.mjs

@@ -0,0 +1,112 @@
+'use client';
+
+import { jsx, jsxs } from "react/jsx-runtime";
+
+//#region src/kit/proportion.tsx
+function ProportionModel({ columns, size = 234, caption, result, resultColor = "var(--stage-good)", ariaLabel = "Proportion area model" }) {
+	const OX = 12, OY = 16;
+	const total = columns.reduce((s, c) => s + c.frac, 0) || 1;
+	let acc = 0;
+	const cols = columns.map((c) => {
+		const x = OX + acc / total * size;
+		acc += c.frac;
+		return {
+			c,
+			x,
+			w: c.frac / total * size
+		};
+	});
+	return /* @__PURE__ */ jsxs("svg", {
+		viewBox: `0 0 ${size + 24} ${OY + size + (caption ? 18 : 0) + (result ? 20 : 0) + 8}`,
+		style: {
+			width: "100%",
+			maxWidth: size + 90,
+			height: "auto"
+		},
+		role: "img",
+		"aria-label": ariaLabel,
+		children: [
+			cols.map(({ c, x, w }, ci) => {
+				let ry = OY;
+				return /* @__PURE__ */ jsxs("g", { children: [c.label && /* @__PURE__ */ jsx("text", {
+					x: x + w / 2,
+					y: OY - 4,
+					textAnchor: w < size * .16 ? "start" : "middle",
+					fontSize: 10,
+					fill: "var(--stage-muted)",
+					children: c.label
+				}), c.rows.map((r, ri) => {
+					const h = r.frac * size;
+					const y = ry;
+					ry += h;
+					const big = w * h > 1400;
+					return /* @__PURE__ */ jsxs("g", { children: [
+						/* @__PURE__ */ jsx("rect", {
+							x,
+							y,
+							width: Math.max(0, w),
+							height: Math.max(0, h),
+							fill: r.color,
+							opacity: r.opacity ?? 1
+						}),
+						r.lit && /* @__PURE__ */ jsx("rect", {
+							x,
+							y,
+							width: Math.max(1.5, w),
+							height: Math.max(0, h),
+							fill: "none",
+							stroke: "var(--stage-fg)",
+							strokeWidth: 1.75
+						}),
+						r.count != null && big && /* @__PURE__ */ jsx("text", {
+							x: x + w / 2,
+							y: y + h / 2,
+							textAnchor: "middle",
+							dominantBaseline: "central",
+							fontSize: 11,
+							fontWeight: 700,
+							fill: r.lit ? "white" : "var(--stage-fg)",
+							style: { pointerEvents: "none" },
+							children: Math.round(r.count)
+						})
+					] }, ri);
+				})] }, ci);
+			}),
+			cols.slice(1).map(({ x }, i) => /* @__PURE__ */ jsx("line", {
+				x1: x,
+				y1: OY,
+				x2: x,
+				y2: OY + size,
+				stroke: "var(--stage-bg)",
+				strokeWidth: 1
+			}, i)),
+			/* @__PURE__ */ jsx("rect", {
+				x: OX,
+				y: OY,
+				width: size,
+				height: size,
+				fill: "none",
+				stroke: "var(--stage-grid)",
+				strokeWidth: 1
+			}),
+			caption && /* @__PURE__ */ jsx("text", {
+				x: OX,
+				y: OY + size + 15,
+				fontSize: 10,
+				fill: "var(--stage-muted)",
+				children: caption
+			}),
+			result && /* @__PURE__ */ jsx("text", {
+				x: OX,
+				y: OY + size + (caption ? 33 : 17),
+				fontSize: 11.5,
+				fontWeight: 700,
+				fill: resultColor,
+				children: result
+			})
+		]
+	});
+}
+
+//#endregion
+export { ProportionModel };