@classytic/labs 0.1.0 → 0.3.0

package/dist/kit/annotate.mjs

@@ -11,16 +11,37 @@ const TONE = {
 	muted: "var(--stage-muted)"
 };
 const charW = 6.4;
+/** Theme-safe SVG text with an optional background halo and edge clamping. */
+function DiagramLabel({ className, x, y, text, tone = "foreground", fontSize = 11, fontWeight = 700, anchor = "middle", bounds, maxChars, halo = true }) {
+	const shown = maxChars && text.length > maxChars ? `${text.slice(0, Math.max(1, maxChars - 1)).trimEnd()}…` : text;
+	const width = shown.length * charW * (fontSize / 11);
+	const leftExtent = anchor === "start" ? 0 : anchor === "middle" ? width / 2 : width;
+	const rightExtent = anchor === "end" ? 0 : anchor === "middle" ? width / 2 : width;
+	return /* @__PURE__ */ jsx("text", {
+		className,
+		x: bounds ? Math.max(bounds.left + leftExtent, Math.min(bounds.right - rightExtent, x)) : x,
+		y: bounds ? Math.max(bounds.top + fontSize, Math.min(bounds.bottom, y)) : y,
+		textAnchor: anchor,
+		dominantBaseline: "central",
+		fontSize,
+		fontWeight,
+		fill: tone === "foreground" ? "var(--stage-fg)" : TONE[tone],
+		paintOrder: halo ? "stroke" : void 0,
+		stroke: halo ? "var(--stage-bg)" : void 0,
+		strokeWidth: halo ? Math.max(3, fontSize * .3) : void 0,
+		strokeLinejoin: halo ? "round" : void 0,
+		children: shown
+	});
+}
 /** A labelled pointer to (x,y): a dot, a leader line, and a tinted bubble offset by
 *  (dx,dy). Keep dx/dy pointing into open space so the bubble clears the figure.
-*  (Named `Pointer`, not Callout, to avoid clashing with frame.js's prose-box Callout
-*  and cms-ui's document-level Callout block — this one anchors to FIGURE geometry.) */
+*  (Named `Pointer` to distinguish figure geometry from document-level prose blocks.) */
 function Pointer({ x, y, text, dx = 30, dy = -26, tone = "info", fontSize = 11 }) {
 	const col = TONE[tone];
 	const w = text.length * (charW * (fontSize / 11)) + 14, h = fontSize + 9;
 	const bx = dx >= 0 ? x + dx : x + dx - w, by = y + dy - h / 2;
 	return /* @__PURE__ */ jsxs("g", {
-		style: { pointerEvents: "none" },
+		pointerEvents: "none",
 		children: [
 			/* @__PURE__ */ jsx("line", {
 				x1: x,
@@ -59,11 +80,11 @@ function Pointer({ x, y, text, dx = 30, dy = -26, tone = "info", fontSize = 11 }
 		]
 	});
 }
-/** A pulsing attention ring at (cx,cy) — draws the eye to "look here". */
+/** A pulsing attention ring at (cx,cy), draws the eye to "look here". */
 function Spotlight({ cx, cy, r = 13, tone = "warn" }) {
 	const col = TONE[tone];
 	return /* @__PURE__ */ jsxs("g", {
-		style: { pointerEvents: "none" },
+		pointerEvents: "none",
 		children: [/* @__PURE__ */ jsx("circle", {
 			cx,
 			cy,
@@ -87,13 +108,13 @@ function Spotlight({ cx, cy, r = 13, tone = "warn" }) {
 		})]
 	});
 }
-/** A span bracket from x1→x2 at height y with a centred label — "this range means …".
+/** A span bracket from x1→x2 at height y with a centred label, "this range means …".
 *  `side: 'below'` drops the ticks/label under y; 'above' lifts them over it. */
 function Bracket({ x1, x2, y, text, tone = "info", side = "below", fontSize = 11 }) {
 	const col = TONE[tone];
 	const tick = 6 * (side === "below" ? 1 : -1), ly = y + (side === "below" ? 14 : -8);
 	return /* @__PURE__ */ jsxs("g", {
-		style: { pointerEvents: "none" },
+		pointerEvents: "none",
 		children: [/* @__PURE__ */ jsx("path", {
 			d: `M${x1},${y + tick} L${x1},${y} L${x2},${y} L${x2},${y + tick}`,
 			fill: "none",
@@ -113,4 +134,4 @@ function Bracket({ x1, x2, y, text, tone = "info", side = "below", fontSize = 11
 }
 
 //#endregion
-export { Bracket, Pointer, Spotlight };
+export { Bracket, DiagramLabel, Pointer, Spotlight };

package/dist/kit/answer-check.d.mts

@@ -1,10 +1,10 @@
 //#region src/kit/answer-check.d.ts
 /**
- * answer-check — the "is the student right?" layer of the interactive-problem
+ * answer-check, the "is the student right?" layer of the interactive-problem
  * engine. Pure, built on @classytic/stage's expr engine. Two real modes (the ones
  * exams need): a NUMBER (value within tolerance, parsed so `pi/2` or `2*sqrt(5)`
  * count) and an EXPRESSION (any algebraically-EQUIVALENT form accepted, checked
- * BOTH symbolically — simplify(student − answer) → 0 — AND numerically by sampling,
+ * BOTH symbolically, simplify(student − answer) → 0, AND numerically by sampling,
  * so `(x+1)(x+2)` ≡ `x^2+3x+2`). No hand-marking, no "exact-string" brittleness.
  */
 /** Evaluate a numeric answer string (`3.14`, `pi/2`, `2*sqrt(5)`) → number (NaN if invalid). */

package/dist/kit/answer-check.mjs

@@ -2,11 +2,11 @@ import { compileExpr, parseExpr, simplify } from "@classytic/stage";
 
 //#region src/kit/answer-check.ts
 /**
-* answer-check — the "is the student right?" layer of the interactive-problem
+* answer-check, the "is the student right?" layer of the interactive-problem
 * engine. Pure, built on @classytic/stage's expr engine. Two real modes (the ones
 * exams need): a NUMBER (value within tolerance, parsed so `pi/2` or `2*sqrt(5)`
 * count) and an EXPRESSION (any algebraically-EQUIVALENT form accepted, checked
-* BOTH symbolically — simplify(student − answer) → 0 — AND numerically by sampling,
+* BOTH symbolically, simplify(student − answer) → 0, AND numerically by sampling,
 * so `(x+1)(x+2)` ≡ `x^2+3x+2`). No hand-marking, no "exact-string" brittleness.
 */
 /** Compile, returning the usable form or null (never the error union). */
@@ -17,9 +17,37 @@ function tryCompile(src) {
 }
 /** Evaluate a numeric answer string (`3.14`, `pi/2`, `2*sqrt(5)`) → number (NaN if invalid). */
 function parseValue(raw) {
-	const c = tryCompile(raw);
+	const c = tryCompile(normalizeMathInput(raw));
 	return c ? c.fn({}) : NaN;
 }
+/**
+* Make exam-natural input parse: accept implicit multiplication (`2x` → `2*x`,
+* `)(` → `)*(`) and a leading `y =` (`y = 2x − 3` → `2*x - 3`). Conservative ,
+* never inserts `*` before `(` after a letter, so function calls like `sin(x)`
+* survive. Unicode minus → ascii.
+*/
+const SUPERSCRIPT = {
+	"⁰": "0",
+	"¹": "1",
+	"²": "2",
+	"³": "3",
+	"⁴": "4",
+	"⁵": "5",
+	"⁶": "6",
+	"⁷": "7",
+	"⁸": "8",
+	"⁹": "9"
+};
+function normalizeMathInput(raw) {
+	let s = raw.trim().replace(/−/g, "-").replace(/×/g, "*").replace(/÷/g, "/");
+	s = s.replace(/[⁰¹²³⁴⁵⁶⁷⁸⁹]+/g, (m) => "^" + [...m].map((ch) => SUPERSCRIPT[ch]).join(""));
+	s = s.replace(/\*\*/g, "^");
+	s = s.replace(/\s+/g, "");
+	s = s.replace(/^y=/i, "");
+	s = s.replace(/(\d)(?![eE][+-]?\d)([a-zA-Z(])/g, "$1*$2");
+	s = s.replace(/\)([a-zA-Z0-9(])/g, ")*$1");
+	return s;
+}
 /** Numeric match with a relative-ish tolerance (default ~1% of scale). */
 function checkNumber(student, value, tol = .01) {
 	if (!Number.isFinite(student) || !Number.isFinite(value)) return false;
@@ -28,11 +56,11 @@ function checkNumber(student, value, tol = .01) {
 const isZeroNode = (n, eps = 1e-9) => n.type === "num" && Math.abs(n.value) < eps;
 /** True if `student` is algebraically equivalent to `answer` (symbolic OR numeric). */
 function checkExpression(student, answer, opts = {}) {
-	const a = tryCompile(student);
-	const b = tryCompile(answer);
+	const a = tryCompile(normalizeMathInput(student));
+	const b = tryCompile(normalizeMathInput(answer));
 	if (!a || !b) return false;
 	try {
-		if (isZeroNode(simplify(parseExpr(`(${student}) - (${answer})`)), opts.tol ?? 1e-9)) return true;
+		if (isZeroNode(simplify(parseExpr(`(${normalizeMathInput(student)}) - (${normalizeMathInput(answer)})`)), opts.tol ?? 1e-9)) return true;
 	} catch {}
 	const vars = opts.vars ?? [...new Set([...a.vars, ...b.vars])];
 	const [lo, hi] = opts.domain ?? [-3.3, 3.7];
@@ -62,4 +90,4 @@ function checkAnswer(spec, raw) {
 }
 
 //#endregion
-export { checkAnswer, checkExpression, checkNumber, parseValue };
+export { checkAnswer, checkExpression, checkNumber, normalizeMathInput, parseValue };

package/dist/kit/ask.d.mts

@@ -0,0 +1,19 @@
+import { ChallengeChoice } from "./pedagogy.mjs";
+import { AnswerSpec } from "./answer-check.mjs";
+import { ReactNode } from "react";
+
+//#region src/kit/ask.d.ts
+/** A serializable question spec an author attaches to a lab. */
+interface LabAskSpec {
+  prompt: ReactNode;
+  placeholder?: string;
+  /** Typed mode: grade the typed answer (a number, or an algebraic expression). */
+  answer?: AnswerSpec;
+  /** Multiple-choice mode: the options (set `correct` to one option's value). */
+  choices?: ChallengeChoice[];
+  correct?: string;
+  /** Shown when the right choice is picked. */
+  explain?: ReactNode;
+}
+//#endregion
+export { LabAskSpec };

package/dist/kit/ask.mjs

@@ -0,0 +1,46 @@
+'use client';
+
+import { AskBox, ChallengeCard, useChallenge, useCheckpoint } from "./pedagogy.mjs";
+import { checkAnswer } from "./answer-check.mjs";
+import { jsx } from "react/jsx-runtime";
+
+//#region src/kit/ask.tsx
+function McqAsk({ prompt, choices, answer, explain, activity }) {
+	const qs = [{
+		id: "q",
+		prompt,
+		choices,
+		answer,
+		explain
+	}];
+	const state = useChallenge(qs);
+	useCheckpoint({
+		solved: state.allCorrect,
+		activity
+	});
+	return /* @__PURE__ */ jsx(ChallengeCard, {
+		questions: qs,
+		state,
+		title: ""
+	});
+}
+/** Render a lab's question, MCQ when `choices` is given, otherwise a typed box. */
+function LabAsk({ ask, activity }) {
+	if (ask.choices && ask.choices.length) return /* @__PURE__ */ jsx(McqAsk, {
+		prompt: ask.prompt,
+		choices: ask.choices,
+		answer: ask.correct ?? "",
+		explain: ask.explain,
+		activity
+	});
+	if (ask.answer) return /* @__PURE__ */ jsx(AskBox, {
+		prompt: ask.prompt,
+		placeholder: ask.placeholder,
+		check: (r) => checkAnswer(ask.answer, r),
+		activity
+	});
+	return null;
+}
+
+//#endregion
+export { LabAsk };

package/dist/kit/authored-activity-runtime.d.mts

@@ -0,0 +1,92 @@
+import { LearningSequence, LearningSequenceStep } from "./learning-sequence.mjs";
+import { AuthoredActivity, CompiledAuthoredActivity } from "./activity-authoring.mjs";
+import { AuthoredResponseResult } from "./authored-response.mjs";
+import { ControlConfig } from "./frame.mjs";
+import { ReactNode } from "react";
+
+//#region src/kit/authored-activity-runtime.d.ts
+interface AuthoredActivityContext {
+  sequence: LearningSequence;
+  complete: (conditionId: string, outcome?: string) => void;
+}
+interface AuthoredActivityRuntimeProps {
+  /** Optional domain hook for narrowly scoped scene and control composition. */
+  className?: string;
+  activity: AuthoredActivity | CompiledAuthoredActivity;
+  activityId: string;
+  eyebrow?: ReactNode;
+  title?: ReactNode;
+  description?: ReactNode;
+  status?: ReactNode | ((context: AuthoredActivityContext) => ReactNode);
+  /** Learner-facing task or prediction prompt shown before the model workspace. */
+  task?: ReactNode | ((context: AuthoredActivityContext) => ReactNode);
+  /** Domain-owned interactive model. The learning runtime never owns scientific state. */
+  children: ReactNode | ((context: AuthoredActivityContext) => ReactNode);
+  /** Authorable controls and evidence associated with the model. */
+  inspector?: ReactNode | ((context: AuthoredActivityContext) => ReactNode);
+  /** Measurements, results, or other evidence used to interpret the model. */
+  evidence?: ReactNode | ((context: AuthoredActivityContext) => ReactNode);
+  /** Named learner controls, subject to controlConfig, placed after evidence. */
+  controls?: ReactNode | ((context: AuthoredActivityContext) => ReactNode);
+  /** Optional interpretation shown after the workspace. */
+  observation?: ReactNode | ((context: AuthoredActivityContext) => ReactNode);
+  /** Accessible account of scene state and changes. */
+  transcript?: ReactNode | ((context: AuthoredActivityContext) => ReactNode);
+  /** Optional hints, worked support, or solution-reveal affordances. */
+  support?: ReactNode | ((context: AuthoredActivityContext) => ReactNode);
+  /** Creator policy for hiding or locking named Field/Control descendants. */
+  controlConfig?: ControlConfig;
+  onResponse?: (result: AuthoredResponseResult) => void;
+  onComplete?: () => void;
+  /** Optional authored checkpoint used to resume a known sequence step. */
+  initialStepId?: string;
+  /** Keeps domain scene state synchronized with Back, Continue, and authored branching. */
+  onStepChange?: (step: LearningSequenceStep, index: number) => void;
+  /** Side inspectors are opt-in; stacked keeps the learning model legible. */
+  inspectorLayout?: 'stacked' | 'side';
+  /** Controls how the activity uses a large focused viewport. */
+  focusLayout?: 'compact' | 'standard' | 'immersive';
+}
+/** Completes a domain-evaluated authored metric gate once per satisfied transition. */
+declare function AuthoredMetricGate({
+  conditionId,
+  met,
+  complete,
+  outcome
+}: {
+  conditionId: string;
+  met: boolean;
+  complete: AuthoredActivityContext['complete'];
+  outcome?: string;
+}): null;
+/**
+ * Canonical learner shell for a serializable AuthoredActivity. It owns progression,
+ * assessment wiring, feedback placement, responsive anatomy, and completion reporting;
+ * domain packages provide only their model, controls/evidence, and transcript.
+ */
+declare function AuthoredActivityRuntime({
+  className,
+  activity,
+  activityId,
+  eyebrow,
+  title,
+  description,
+  status,
+  task,
+  children,
+  inspector,
+  evidence,
+  controls,
+  observation,
+  transcript,
+  support,
+  controlConfig,
+  onResponse,
+  onComplete,
+  initialStepId,
+  onStepChange,
+  inspectorLayout,
+  focusLayout
+}: AuthoredActivityRuntimeProps): ReactNode;
+//#endregion
+export { AuthoredActivityContext, AuthoredActivityRuntime, AuthoredActivityRuntimeProps, AuthoredMetricGate };

package/dist/kit/authored-activity-runtime.mjs

@@ -0,0 +1,148 @@
+'use client';
+
+import { Activity } from "./activity.mjs";
+import { ControlPolicy } from "./frame.mjs";
+import { useCheckpoint } from "./pedagogy.mjs";
+import { compileAuthoredActivity } from "./activity-authoring.mjs";
+import { AuthoredResponse } from "./authored-response.mjs";
+import { LearningSequenceNav, useLearningSequence } from "./learning-sequence.mjs";
+import { useEffect, useMemo, useRef } from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+
+//#region src/kit/authored-activity-runtime.tsx
+const renderSlot = (slot, context) => typeof slot === "function" ? slot(context) : slot;
+/** Completes a domain-evaluated authored metric gate once per satisfied transition. */
+function AuthoredMetricGate({ conditionId, met, complete, outcome }) {
+	const fired = useRef(false);
+	useEffect(() => {
+		if (!met) {
+			fired.current = false;
+			return;
+		}
+		if (!fired.current) {
+			fired.current = true;
+			complete(conditionId, outcome);
+		}
+	}, [
+		complete,
+		conditionId,
+		met,
+		outcome
+	]);
+	return null;
+}
+/**
+* Canonical learner shell for a serializable AuthoredActivity. It owns progression,
+* assessment wiring, feedback placement, responsive anatomy, and completion reporting;
+* domain packages provide only their model, controls/evidence, and transcript.
+*/
+function AuthoredActivityRuntime({ className, activity, activityId, eyebrow = "Interactive lesson", title, description, status, task, children, inspector, evidence, controls, observation, transcript, support, controlConfig, onResponse, onComplete, initialStepId, onStepChange, inspectorLayout = "stacked", focusLayout = "standard" }) {
+	const plan = useMemo(() => compileAuthoredActivity(activity), [activity]);
+	const authored = plan.source;
+	const sequence = useLearningSequence(plan.steps, {
+		initialStepId,
+		onStepChange
+	});
+	const context = {
+		sequence,
+		complete: sequence.complete
+	};
+	const conditionPosition = sequence.current.gate ? plan.successIndex[sequence.current.gate.id] : void 0;
+	const condition = conditionPosition == null ? void 0 : authored.success?.[conditionPosition];
+	const questionPosition = condition && (condition.source === "answer" || condition.source === "reflection") ? plan.questionIndex[condition.key] : void 0;
+	const question = questionPosition == null ? void 0 : authored.questions?.[questionPosition];
+	const solved = sequence.index === sequence.total - 1 && sequence.canAdvance;
+	const observationUnlocked = sequence.current.phase !== "predict" || sequence.canAdvance;
+	useCheckpoint({
+		solved,
+		activity: activityId
+	});
+	useEffect(() => {
+		if (solved) onComplete?.();
+	}, [solved, onComplete]);
+	const respond = (result) => {
+		onResponse?.(result);
+		if (!condition) return;
+		if (result.correct === true || condition.source === "reflection" && result.correct === null) sequence.complete(condition.id, Array.isArray(result.response) ? result.response.join(",") : String(result.response));
+	};
+	const renderedTask = renderSlot(task, context);
+	const renderedModel = renderSlot(children, context);
+	const renderedEvidence = renderSlot(evidence, context);
+	const renderedInspector = renderSlot(inspector, context);
+	const renderedControls = renderSlot(controls, context);
+	const renderedObservation = renderSlot(observation, context);
+	const renderedTranscript = renderSlot(transcript, context);
+	const renderedSupport = renderSlot(support, context);
+	return /* @__PURE__ */ jsx(ControlPolicy, {
+		config: controlConfig,
+		children: /* @__PURE__ */ jsxs(Activity.Root, {
+			className: ["lab-authored-activity", className].filter(Boolean).join(" "),
+			"data-inspector-layout": inspectorLayout,
+			focusLayout,
+			children: [
+				/* @__PURE__ */ jsxs(Activity.Header, { children: [/* @__PURE__ */ jsx(Activity.Heading, {
+					eyebrow,
+					title: title ?? authored.title ?? sequence.current.title ?? "Interactive activity",
+					description
+				}), /* @__PURE__ */ jsx(Activity.FocusButton, {})] }),
+				/* @__PURE__ */ jsxs(Activity.Status, { children: [
+					(sequence.current.title ?? "").toLowerCase().includes(sequence.current.phase.toLowerCase()) ? null : /* @__PURE__ */ jsx("strong", { children: sequence.current.phase }),
+					/* @__PURE__ */ jsx("span", { children: sequence.current.title }),
+					renderSlot(status, context)
+				] }),
+				renderedTask || question || sequence.current.lead ? /* @__PURE__ */ jsxs("section", {
+					className: "lab-authored-task",
+					"aria-label": "Your task",
+					children: [
+						sequence.current.lead ? /* @__PURE__ */ jsx("p", {
+							className: "lab-authored-task-lead",
+							children: sequence.current.lead
+						}) : null,
+						renderedTask,
+						question ? /* @__PURE__ */ jsx(AuthoredResponse, {
+							question,
+							onRespond: respond
+						}, question.id) : null
+					]
+				}) : null,
+				/* @__PURE__ */ jsxs(Activity.Workspace, { children: [
+					/* @__PURE__ */ jsx(Activity.Canvas, {
+						label: `${String(title ?? authored.title ?? "Interactive activity")} model`,
+						children: renderedModel
+					}),
+					renderedControls ? /* @__PURE__ */ jsx(Activity.Dock, { children: /* @__PURE__ */ jsx("section", {
+						className: "lab-activity-fields lab-authored-controls",
+						"aria-label": "Controls",
+						children: renderedControls
+					}) }) : null,
+					renderedEvidence || renderedInspector ? /* @__PURE__ */ jsxs(Activity.Inspector, {
+						label: "Explore evidence",
+						defaultOpen: inspectorLayout === "side",
+						responsive: false,
+						children: [renderedEvidence ? /* @__PURE__ */ jsx("section", {
+							className: "lab-authored-evidence",
+							"aria-label": "Evidence",
+							children: renderedEvidence
+						}) : null, renderedInspector]
+					}) : null
+				] }),
+				renderedObservation && observationUnlocked ? /* @__PURE__ */ jsxs(Activity.Feedback, { children: [/* @__PURE__ */ jsx("span", { children: "Observe" }), /* @__PURE__ */ jsx("div", { children: renderedObservation })] }) : null,
+				renderedTranscript || renderedSupport ? /* @__PURE__ */ jsxs(Activity.Transcript, {
+					label: renderedSupport ? "Learning support" : "Event transcript",
+					children: [renderedTranscript ? /* @__PURE__ */ jsx("section", {
+						className: "lab-authored-transcript",
+						"aria-label": "Event transcript",
+						children: renderedTranscript
+					}) : null, renderedSupport ? /* @__PURE__ */ jsx("section", {
+						className: "lab-authored-support",
+						children: renderedSupport
+					}) : null]
+				}) : null,
+				/* @__PURE__ */ jsx(Activity.Transport, { children: /* @__PURE__ */ jsx(LearningSequenceNav, { sequence }) })
+			]
+		})
+	});
+}
+
+//#endregion
+export { AuthoredActivityRuntime, AuthoredMetricGate };

package/dist/kit/authored-response.d.mts

@@ -0,0 +1,21 @@
+import { AuthoredQuestion } from "./activity-authoring.mjs";
+import { ReactNode } from "react";
+
+//#region src/kit/authored-response.d.ts
+type AuthoredResponseValue = string | number | string[];
+interface AuthoredResponseResult {
+  questionId: string;
+  response: AuthoredResponseValue;
+  correct: boolean | null;
+}
+declare function evaluateAuthoredResponse(question: AuthoredQuestion, response: AuthoredResponseValue): boolean | null;
+/** Standard renderer for the portable authored response contract. */
+declare function AuthoredResponse({
+  question,
+  onRespond
+}: {
+  question: AuthoredQuestion;
+  onRespond?: (result: AuthoredResponseResult) => void;
+}): ReactNode;
+//#endregion
+export { AuthoredResponse, AuthoredResponseResult, AuthoredResponseValue, evaluateAuthoredResponse };