@classytic/labs 0.2.0 → 0.3.0

package/dist/kit/frame.mjs

@@ -1,31 +1,35 @@
 'use client';
 
-import { createContext, useContext } from "react";
+import { Activity } from "./activity.mjs";
+import { createContext, useContext, useRef } from "react";
 import { Fragment as Fragment$1, jsx, jsxs } from "react/jsx-runtime";
 
 //#region src/kit/frame.tsx
+/** Shared field, readout, progress, and author-control primitives for Activity. */
 /**
-* LabFrame, the shared layout shell every lab composes into, so labs stop being
-* hand-rolled inline-styled one-offs and read as ONE product. Structure:
-*
-*   title + one-line prompt           (header, no walls of text)
-*   [▸ goals]                         (collapsed disclosure, reveal-on-action)
-*   ┌─ figure (dominant) ─┬─ aside ─┐ (one grid; aside optional + narrow)
-*   └─────────────────────┴─────────┘
-*   [ one controls bar ]             (ALL knobs in one place, never scattered)
-*   feedback / hints / reveal        (quiet footer)
-*
-* Everything styles off `.lab-*` in @classytic/labs/styles.css, no inline layout.
-* Pair with the existing pedagogy kit (HintLadder, RevealSolution, Feedback).
-*
-* CREATOR CONTROL, `controlConfig` lets the author decide, per knob, what a learner
-* may touch: `{ hide: ['mass'], lock: ['angle'] }`. Hidden knobs vanish; locked knobs
-* stay visible but read-only (their value is whatever the creator set as the initial
-* prop). LabFrame provides this as context; `Field` (keyed by its `name ?? label`) and
-* the `Control` wrapper consume it, so a lab opts in with ~2 lines and every knob,
-* existing or new, honours it. The mechanism is uniform: no per-knob boolean props.
+* Cause→effect glue: bump a sequence number whenever a primitive (string/number)
+* value changes, so the value element can replay a short CSS flash (via `key`
+* remount). The number GLOWS while the learner drags and settles when they stop,
+* visually linking "I moved this" to "that changed". Non-primitive values never
+* flash (no cheap equality). 0 on mount = no flash on first paint.
 */
+function useFlashSeq(v) {
+	const prev = useRef(v);
+	const seq = useRef(0);
+	if ((typeof v === "string" || typeof v === "number") && !Object.is(prev.current, v)) {
+		prev.current = v;
+		seq.current++;
+	}
+	return seq.current;
+}
 const ControlCtx = createContext(void 0);
+/** Apply creator hide/lock policy to composed shells such as Activity. */
+function ControlPolicy({ config, children }) {
+	return /* @__PURE__ */ jsx(ControlCtx.Provider, {
+		value: config,
+		children
+	});
+}
 /** Resolve a single control's state from the surrounding `controlConfig`. */
 function useControlOverride(name) {
 	const cfg = useContext(ControlCtx);
@@ -35,70 +39,54 @@ function useControlOverride(name) {
 	};
 }
 const INERT = { inert: true };
-function LabFrame({ title, prompt, objectives, children, aside, controls, footer, rootRef, controlConfig }) {
-	return /* @__PURE__ */ jsx(ControlCtx.Provider, {
-		value: controlConfig,
-		children: /* @__PURE__ */ jsxs("div", {
-			ref: rootRef,
-			className: "not-prose lab-frame",
-			children: [
-				(title || prompt) && /* @__PURE__ */ jsxs("div", {
-					className: "lab-frame-head",
-					children: [title && /* @__PURE__ */ jsx("p", {
-						className: "lab-title",
-						children: title
-					}), prompt && /* @__PURE__ */ jsx("p", {
-						className: "lab-prompt",
-						children: prompt
-					})]
-				}),
-				objectives && objectives.length > 0 && /* @__PURE__ */ jsxs("details", {
-					className: "lab-goals",
-					children: [/* @__PURE__ */ jsx("summary", { children: "What you'll learn" }), /* @__PURE__ */ jsx("ul", { children: objectives.map((o, i) => /* @__PURE__ */ jsx("li", { children: o }, i)) })]
-				}),
-				/* @__PURE__ */ jsxs("div", {
-					className: "lab-body",
-					"data-aside": aside ? "true" : "false",
-					children: [/* @__PURE__ */ jsx("div", {
-						className: "lab-figure",
-						children
-					}), aside && /* @__PURE__ */ jsx("div", {
-						className: "lab-aside",
-						children: aside
-					})]
-				}),
-				controls && /* @__PURE__ */ jsx("div", {
-					className: "lab-controls",
-					children: controls
-				}),
-				footer && /* @__PURE__ */ jsx("div", {
-					className: "lab-foot",
-					children: footer
-				})
-			]
-		})
+/**
+* Keep a primary visualization and its live concrete representations in one
+* perceptual workspace. Unlike inspector evidence, these views are not supporting
+* metadata: they are equal representations of the same value and therefore stay
+* adjacent until the narrow mobile breakpoint.
+*/
+function LinkedViews({ primary, representations, readout }) {
+	return /* @__PURE__ */ jsxs("div", {
+		className: "lab-linked-stack",
+		children: [representations ? /* @__PURE__ */ jsxs("div", {
+			className: "lab-reps",
+			children: [/* @__PURE__ */ jsx("div", {
+				className: "lab-reps-plot",
+				children: primary
+			}), /* @__PURE__ */ jsx("div", {
+				className: "lab-reps-views",
+				children: representations
+			})]
+		}) : primary, readout]
 	});
 }
-/** The single controls bar. Put `Field`s (or any control) inside. */
-function ControlBar({ children }) {
-	return /* @__PURE__ */ jsx(Fragment$1, { children });
+/**
+* A stable responsive frame for interchangeable SVG, Canvas, or WebGL scenes.
+*
+* Authors may swap renderers without changing the activity's geometry. This is
+* intentionally a layout primitive—not a drawing surface—so domain renderers
+* retain their own semantics, camera, and interaction model.
+*/
+function SceneViewport({ children, size = "standard", label, overflow = "fit", className }) {
+	return /* @__PURE__ */ jsx("div", {
+		className: ["lab-scene-viewport", className].filter(Boolean).join(" "),
+		"data-size": size,
+		"data-overflow": overflow,
+		"aria-label": label,
+		role: label ? "region" : void 0,
+		tabIndex: overflow === "scroll" ? 0 : void 0,
+		children
+	});
 }
 /**
 * Group an inline expression (parens, steppers, "→ result", …) so it reads as ONE
-* unit. `.lab-controls` is a grid that gives EACH ControlBar child its own ~185px
+* unit. Activity field grids give each child its own responsive cell;
 * cell, which scatters a multi-piece expression across columns. Wrap those pieces
 * in `<ControlExpr>` and they stay together (one cell, tight gaps, baseline-aligned).
 */
 function ControlExpr({ children }) {
 	return /* @__PURE__ */ jsx("span", {
-		style: {
-			gridColumn: "1 / -1",
-			display: "flex",
-			alignItems: "center",
-			flexWrap: "wrap",
-			gap: 8,
-			fontWeight: 600
-		},
+		className: "lab-control-expr",
 		children
 	});
 }
@@ -161,64 +149,94 @@ function Control({ name, children }) {
 		children
 	});
 }
-/** A highlighted readout box. `tone="result"` for the headline answer. */
-function Callout({ tone, children }) {
+/**
+* The standard aside stat-block: an optional eyebrow `label`, a bold headline
+* `value`, and a muted `sub` line on a standard evidence surface.
+*/
+function Readout({ label, value, sub, tone = "result", accent }) {
+	const flash = useFlashSeq(value);
 	return /* @__PURE__ */ jsx("div", {
-		className: "lab-callout",
-		"data-tone": tone ?? "info",
-		children
+		className: "lab-evidence-surface",
+		"data-tone": tone,
+		children: /* @__PURE__ */ jsxs("span", {
+			className: "lab-readout",
+			children: [
+				label != null && /* @__PURE__ */ jsx("span", {
+					className: "lab-readout-label",
+					children: label
+				}),
+				/* @__PURE__ */ jsx("span", {
+					className: flash ? "lab-readout-val lab-val-flash" : "lab-readout-val",
+					style: accent ? { color: accent } : void 0,
+					children: value
+				}, flash),
+				sub != null && /* @__PURE__ */ jsx("span", {
+					className: "lab-readout-sub",
+					children: sub
+				})
+			]
+		})
 	});
 }
-const SR_ONLY = {
-	position: "absolute",
-	width: 1,
-	height: 1,
-	overflow: "hidden",
-	clipPath: "inset(50%)"
-};
-/** Visually-hidden polite live region for screen-reader narration of a changing value. */
-function LiveRegion({ children }) {
+/**
+* One "label … value" row in a readout. `tone` colours the value (good/warn/danger).
+* The label sits left (muted), the value right (bold, tabular) — aligned columns, so
+* a stack of stats reads like a clean instrument panel instead of ragged sentences.
+*/
+function Stat({ label, value, tone }) {
+	const flash = useFlashSeq(value);
+	return /* @__PURE__ */ jsxs("span", {
+		className: "lab-stat",
+		children: [/* @__PURE__ */ jsx("span", {
+			className: "lab-stat-label",
+			children: label
+		}), /* @__PURE__ */ jsx("strong", {
+			className: flash ? "lab-stat-val lab-val-flash" : "lab-stat-val",
+			"data-tone": tone,
+			children: value
+		}, flash)]
+	});
+}
+/**
+* A readout of several `Stat` rows on one standard evidence surface.
+*/
+function StatList({ children, tone = "result" }) {
 	return /* @__PURE__ */ jsx("div", {
-		"aria-live": "polite",
-		style: SR_ONLY,
-		children
+		className: "lab-evidence-surface",
+		"data-tone": tone,
+		children: /* @__PURE__ */ jsx("span", {
+			className: "lab-statlist",
+			children
+		})
 	});
 }
+/** Visually-hidden polite live region for screen-reader narration of a changing value. */
+function LiveRegion({ children }) {
+	return /* @__PURE__ */ jsx(Activity.LiveRegion, { children });
+}
 /**
 * A labelled progress/energy bar: `frac` (0–1) fills it, `value` is the right-hand
-* readout. Replaces the hand-rolled bars in collision/energy/impulse/etc.
+* readout. Styling lives in `.lab-meter*`; the fill colour is passed as a CSS var.
 */
 function MeterBar({ label, frac, color, value }) {
 	const pct = Math.max(0, Math.min(1, frac)) * 100;
-	return /* @__PURE__ */ jsxs("div", { children: [/* @__PURE__ */ jsxs("div", {
-		style: {
-			display: "flex",
-			justifyContent: "space-between",
-			fontSize: 11,
-			fontWeight: 700,
-			color: "var(--stage-muted)"
-		},
-		children: [/* @__PURE__ */ jsx("span", { children: label }), value != null && /* @__PURE__ */ jsx("span", {
-			style: { fontVariantNumeric: "tabular-nums" },
-			children: value
+	return /* @__PURE__ */ jsxs("div", {
+		className: "lab-meter",
+		children: [/* @__PURE__ */ jsxs("div", {
+			className: "lab-meter-head",
+			children: [/* @__PURE__ */ jsx("span", { children: label }), value != null && /* @__PURE__ */ jsx("b", { children: value })]
+		}), /* @__PURE__ */ jsx("div", {
+			className: "lab-meter-track",
+			children: /* @__PURE__ */ jsx("div", {
+				className: "lab-meter-fill",
+				style: {
+					width: `${pct}%`,
+					["--lab-meter-color"]: color
+				}
+			})
 		})]
-	}), /* @__PURE__ */ jsx("div", {
-		style: {
-			height: 12,
-			borderRadius: 6,
-			background: "color-mix(in oklab, var(--stage-muted) 18%, transparent)",
-			overflow: "hidden",
-			marginTop: 3
-		},
-		children: /* @__PURE__ */ jsx("div", { style: {
-			width: `${pct}%`,
-			height: "100%",
-			background: color,
-			borderRadius: 6,
-			transition: "width 0.1s"
-		} })
-	})] });
+	});
 }
 
 //#endregion
-export { Callout, Control, ControlBar, ControlExpr, Field, LabFrame, LiveRegion, MeterBar };
+export { Control, ControlExpr, ControlPolicy, Field, LinkedViews, LiveRegion, MeterBar, Readout, SceneViewport, Stat, StatList };

package/dist/kit/guide.d.mts

@@ -0,0 +1,44 @@
+import { Steps } from "./steps.mjs";
+import { ReactNode } from "react";
+
+//#region src/kit/guide.d.ts
+/** @deprecated Use serializable `LearningSequenceStep` data. */
+interface GuideStep {
+  /** narrator one-liner shown above the Back/Continue nav. */
+  lead?: string;
+  /** layer names revealed from this step onward (cumulative). */
+  reveal?: string[];
+  /** id of the predict question to show at this step; blocks Continue until answered. */
+  ask?: string;
+  /** reveal the control bar at this step (cumulative). */
+  controls?: boolean;
+}
+/** @deprecated Use `LearningSequence`. */
+interface Guide {
+  enabled: boolean;
+  step: number;
+  total: number;
+  lead?: string;
+  /** the question id to render at the current step, if any. */
+  activeAsk?: string;
+  /** current step asks a question that isn't answered yet. */
+  gated: boolean;
+  /** is a named reveal layer visible now. */
+  shows: (layer: string) => boolean;
+  showControls: boolean;
+  nav: Steps;
+}
+/** @deprecated Use `useLearningSequence`; retained for third-party compatibility. */
+declare function useGuide(steps: GuideStep[], opts?: {
+  enabled?: boolean;
+  isAnswered?: (id: string) => boolean;
+}): Guide;
+/** The narrator line + Back/Continue (or a "pick an answer" gate when the step asks a question). */
+/** @deprecated Use `LearningSequenceNav` inside `Activity.Transport`. */
+declare function GuideNav({
+  guide
+}: {
+  guide: Guide;
+}): ReactNode;
+//#endregion
+export { Guide, GuideNav, GuideStep, useGuide };

package/dist/kit/guide.mjs

@@ -0,0 +1,53 @@
+'use client';
+
+import { StatusPill } from "./controls.mjs";
+import { StepNav, useSteps } from "./steps.mjs";
+import { jsx, jsxs } from "react/jsx-runtime";
+
+//#region src/kit/guide.tsx
+/** @deprecated Use `useLearningSequence`; retained for third-party compatibility. */
+function useGuide(steps, opts = {}) {
+	const enabled = opts.enabled !== false && steps.length > 0;
+	const total = Math.max(1, steps.length);
+	const nav = useSteps(total);
+	const step = enabled ? nav.step : total - 1;
+	const visible = /* @__PURE__ */ new Set();
+	let showControls = !enabled;
+	for (let i = 0; i <= step; i++) {
+		(steps[i]?.reveal ?? []).forEach((l) => visible.add(l));
+		if (steps[i]?.controls) showControls = true;
+	}
+	const cur = steps[step];
+	const activeAsk = enabled ? cur?.ask : void 0;
+	const gated = enabled && activeAsk != null && !(opts.isAnswered?.(activeAsk) ?? false);
+	return {
+		enabled,
+		step,
+		total,
+		lead: enabled ? cur?.lead : void 0,
+		activeAsk,
+		gated,
+		shows: (l) => !enabled || visible.has(l),
+		showControls,
+		nav
+	};
+}
+/** The narrator line + Back/Continue (or a "pick an answer" gate when the step asks a question). */
+/** @deprecated Use `LearningSequenceNav` inside `Activity.Transport`. */
+function GuideNav({ guide }) {
+	if (!guide.enabled) return null;
+	return /* @__PURE__ */ jsxs("nav", {
+		className: "lab-guide-nav",
+		"aria-label": "Guided lesson steps",
+		children: [guide.lead && /* @__PURE__ */ jsx("p", { children: guide.lead }), guide.gated ? /* @__PURE__ */ jsx(StatusPill, {
+			ok: false,
+			children: "pick an answer to continue"
+		}) : /* @__PURE__ */ jsx(StepNav, {
+			steps: guide.nav,
+			doneLabel: "✓ Done"
+		})]
+	});
+}
+
+//#endregion
+export { GuideNav, useGuide };

package/dist/kit/index.d.mts

@@ -1,17 +1,37 @@
+import { LearningBranch, LearningGate, LearningPhase, LearningSequence, LearningSequenceNav, LearningSequenceStep, useLearningSequence } from "./learning-sequence.mjs";
+import { ActivityPattern, AuthoredActivity, AuthoredActivityStep, AuthoredChoice, AuthoredChoiceQuestion, AuthoredDataset, AuthoredNumericQuestion, AuthoredOrderingQuestion, AuthoredQuestion, AuthoredReflectionQuestion, AuthoredSuccessCondition, AuthoredTextQuestion, AuthoredTransferCase, CompiledAuthoredActivity, SuccessOperator, activitySteps, compileAuthoredActivity, defineAuthoredActivity, isCompiledAuthoredActivity, withAuthoredObjectives } from "./activity-authoring.mjs";
 import { ChallengeCard, ChallengeChoice, ChallengeQuestion, ChallengeState, CheckpointArgs, Feedback, HintLadder, Hints, Objectives, RevealSolution, RevealSolutionProps, useChallenge, useCheckpoint, useHints } from "./pedagogy.mjs";
 import { Calc, CalcStep, Worked, calc, texNum } from "./calc.mjs";
-import { RuleCard, RuleDef, RuleInput, RuleLab, WorkedSteps } from "./rule.mjs";
-import { ReceiptItem, ReceiptScene, ReceiptSceneProps } from "./receipt.mjs";
-import { Clue, ClueBalance, ClueBar, ClueCoins, ClueReceipt, ClueScene, ClueSceneKind, ClueSceneMeta, ClueTiles, Unknown, UnknownChip, clueTotal, getClueScene, listClueScenes, registerClueScene } from "./clue-scene.mjs";
-import { Callout, ControlBar, ControlConfig, Field, LabFrame } from "./frame.mjs";
+import { RuleCard, RuleDef, RuleFigure, RuleInput, RuleLab, WorkedSteps } from "./rule.mjs";
+import { Celebrate, SolvedPill } from "./celebrate.mjs";
+import { PredictGate, PredictGateProps } from "./predict-gate.mjs";
 import { StepNav, Steps, useSteps } from "./steps.mjs";
+import { Guide, GuideNav, GuideStep, useGuide } from "./guide.mjs";
+import { AuthoredResponse, AuthoredResponseResult, AuthoredResponseValue, evaluateAuthoredResponse } from "./authored-response.mjs";
+import { ControlConfig, Field, Readout, Stat, StatList } from "./frame.mjs";
+import { AuthoredActivityContext, AuthoredActivityRuntime, AuthoredActivityRuntimeProps, AuthoredMetricGate } from "./authored-activity-runtime.mjs";
+import { Activity, ActivityRootProps } from "./activity.mjs";
 import { PlayGate, PlayWrap, usePlayGate } from "./play.mjs";
+import { FigDomain, Figure, FigureProps, HUE, STROKE, StrokeRole, alpha, figUrl, fmt, shade, tint, useFigureId } from "./figure/figure.mjs";
+import { FigTag, FigText, FigTextProps, FigTextSize, FigTextTone } from "./figure/text.mjs";
+import { Ball, BallProps, Block, BlockProps, Particle } from "./figure/body.mjs";
+import { Bubbles, Glass, GlassProps, GlassShape, Region, glassInner } from "./figure/container.mjs";
+import { Arrow, ArrowProps, Ground, Ray, Track } from "./figure/beam.mjs";
+import { Area, Curve, Marker, PlotBox, PlotFrame, PlotFrameProps, SegmentBar, scale } from "./figure/plot.mjs";
+import { Illustration, IllustrationProps } from "./figure/illustration.mjs";
 import { GuessTone, Vessel, VesselGlyph, VesselGlyphProps, VesselProps } from "./vessel.mjs";
 import { PredictPlot, PredictPlotProps } from "./predict.mjs";
 import { DotCluster, DotClusterProps } from "./cluster.mjs";
+import { CoinGlyph, DiceGlyph, ProbabilityBoardOutcome, ProbabilityContributionBoard } from "./probability.mjs";
 import { Blank, FillSlot, SlotFill, SlotFillProps, SlotFillState, SlotTray, useSlotFill } from "./slot-fill.mjs";
+import { ReceiptItem, ReceiptScene, ReceiptSceneProps } from "./receipt.mjs";
+import { PlotChart, PlotChartProps, PlotGeom, PlotGuide, PlotLegendItem } from "./finance-viz/plot-chart.mjs";
+import { ApportionBar, ApportionBarProps, ApportionSegment } from "./finance-viz/apportion-bar.mjs";
+import { StockGuide, StockTimeline, StockTimelineProps } from "./finance-viz/stock-timeline.mjs";
+import { TradeoffCurve, TradeoffCurveProps } from "./finance-viz/tradeoff-curve.mjs";
+import { Clue, ClueBalance, ClueBar, ClueCoins, ClueReceipt, ClueScene, ClueSceneKind, ClueSceneMeta, ClueTiles, Unknown, UnknownChip, clueTotal, getClueScene, listClueScenes, registerClueScene } from "./clue-scene.mjs";
 import { QuantityInput, QuantityScene, SceneMeta, getScene, listScenes, registerScene } from "./scenes.mjs";
 import { DataSceneSpec, dataScene, registerDataScene } from "./data-scene.mjs";
 import { SceneStudio, SceneStudioProps } from "./scene-studio.mjs";
 import { SceneLibrary, SceneLibraryManager, loadSceneLibrary, registerScenes, saveSceneLibrary, useSceneLibrary } from "./scene-library.mjs";
-export { Blank, Calc, type CalcStep, Callout, ChallengeCard, type ChallengeChoice, type ChallengeQuestion, type ChallengeState, type CheckpointArgs, type Clue, ClueBalance, ClueBar, ClueCoins, ClueReceipt, ClueScene, type ClueSceneKind, type ClueSceneMeta, ClueTiles, ControlBar, type ControlConfig, type DataSceneSpec, DotCluster, type DotClusterProps, Feedback, Field, type FillSlot, type GuessTone, HintLadder, type Hints, LabFrame, Objectives, type PlayGate, PlayWrap, PredictPlot, type PredictPlotProps, type QuantityInput, type QuantityScene, type ReceiptItem, ReceiptScene, type ReceiptSceneProps, RevealSolution, type RevealSolutionProps, RuleCard, type RuleDef, type RuleInput, RuleLab, type SceneLibrary, SceneLibraryManager, type SceneMeta, SceneStudio, type SceneStudioProps, SlotFill, type SlotFillProps, type SlotFillState, SlotTray, StepNav, type Steps, type Unknown, UnknownChip, Vessel, VesselGlyph, type VesselGlyphProps, type VesselProps, type Worked, WorkedSteps, calc, clueTotal, dataScene, getClueScene, getScene, listClueScenes, listScenes, loadSceneLibrary, registerClueScene, registerDataScene, registerScene, registerScenes, saveSceneLibrary, texNum, useChallenge, useCheckpoint, useHints, usePlayGate, useSceneLibrary, useSlotFill, useSteps };
+export { Activity, type ActivityPattern, type ActivityRootProps, ApportionBar, type ApportionBarProps, type ApportionSegment, Area, Arrow, type ArrowProps, type AuthoredActivity, type AuthoredActivityContext, AuthoredActivityRuntime, type AuthoredActivityRuntimeProps, type AuthoredActivityStep, type AuthoredChoice, type AuthoredChoiceQuestion, type AuthoredDataset, AuthoredMetricGate, type AuthoredNumericQuestion, type AuthoredOrderingQuestion, type AuthoredQuestion, type AuthoredReflectionQuestion, AuthoredResponse, type AuthoredResponseResult, type AuthoredResponseValue, type AuthoredSuccessCondition, type AuthoredTextQuestion, type AuthoredTransferCase, Ball, type BallProps, Blank, Block, type BlockProps, Bubbles, Calc, type CalcStep, Celebrate, ChallengeCard, type ChallengeChoice, type ChallengeQuestion, type ChallengeState, type CheckpointArgs, type Clue, ClueBalance, ClueBar, ClueCoins, ClueReceipt, ClueScene, type ClueSceneKind, type ClueSceneMeta, ClueTiles, CoinGlyph, type CompiledAuthoredActivity, type ControlConfig, Curve, type DataSceneSpec, DiceGlyph, DotCluster, type DotClusterProps, Feedback, Field, type FigDomain, FigTag, FigText, type FigTextProps, type FigTextSize, type FigTextTone, Figure, type FigureProps, type FillSlot, Glass, type GlassProps, type GlassShape, Ground, type GuessTone, Guide, GuideNav, type GuideStep, HUE, HintLadder, type Hints, Illustration, type IllustrationProps, type LearningBranch, type LearningGate, type LearningPhase, type LearningSequence, LearningSequenceNav, type LearningSequenceStep, Marker, Objectives, Particle, type PlayGate, PlayWrap, type PlotBox, PlotChart, type PlotChartProps, PlotFrame, type PlotFrameProps, type PlotGeom, type PlotGuide, type PlotLegendItem, PredictGate, type PredictGateProps, PredictPlot, type PredictPlotProps, type ProbabilityBoardOutcome, ProbabilityContributionBoard, type QuantityInput, type QuantityScene, Ray, Readout, type ReceiptItem, ReceiptScene, type ReceiptSceneProps, Region, RevealSolution, type RevealSolutionProps, RuleCard, type RuleDef, RuleFigure, type RuleInput, RuleLab, STROKE, type SceneLibrary, SceneLibraryManager, type SceneMeta, SceneStudio, type SceneStudioProps, SegmentBar, SlotFill, type SlotFillProps, type SlotFillState, SlotTray, SolvedPill, Stat, StatList, StepNav, type Steps, type StockGuide, StockTimeline, type StockTimelineProps, type StrokeRole, type SuccessOperator, Track, TradeoffCurve, type TradeoffCurveProps, type Unknown, UnknownChip, Vessel, VesselGlyph, type VesselGlyphProps, type VesselProps, type Worked, WorkedSteps, activitySteps, alpha, calc, clueTotal, compileAuthoredActivity, dataScene, defineAuthoredActivity, evaluateAuthoredResponse, figUrl, fmt, getClueScene, getScene, glassInner, isCompiledAuthoredActivity, listClueScenes, listScenes, loadSceneLibrary, registerClueScene, registerDataScene, registerScene, registerScenes, saveSceneLibrary, scale, shade, texNum, tint, useChallenge, useCheckpoint, useFigureId, useGuide, useHints, useLearningSequence, usePlayGate, useSceneLibrary, useSlotFill, useSteps, withAuthoredObjectives };

package/dist/kit/index.mjs

@@ -1,5 +1,18 @@
-import { Callout, ControlBar, Field, LabFrame } from "./frame.mjs";
+import { Activity } from "./activity.mjs";
+import { Field, Readout, Stat, StatList } from "./frame.mjs";
+import { Celebrate, SolvedPill } from "./celebrate.mjs";
 import { ChallengeCard, Feedback, HintLadder, Objectives, RevealSolution, useChallenge, useCheckpoint, useHints } from "./pedagogy.mjs";
+import { activitySteps, compileAuthoredActivity, defineAuthoredActivity, isCompiledAuthoredActivity, withAuthoredObjectives } from "./activity-authoring.mjs";
+import { AuthoredResponse, evaluateAuthoredResponse } from "./authored-response.mjs";
+import { LearningSequenceNav, useLearningSequence } from "./learning-sequence.mjs";
+import { AuthoredActivityRuntime, AuthoredMetricGate } from "./authored-activity-runtime.mjs";
+import { Figure, HUE, STROKE, alpha, figUrl, fmt, shade, tint, useFigureId } from "./figure/figure.mjs";
+import { FigTag, FigText } from "./figure/text.mjs";
+import { Ball, Block, Particle } from "./figure/body.mjs";
+import { Bubbles, Glass, Region, glassInner } from "./figure/container.mjs";
+import { Arrow, Ground, Ray, Track } from "./figure/beam.mjs";
+import { Area, Curve, Guide, Marker, PlotFrame, SegmentBar, scale } from "./figure/plot.mjs";
+import { Illustration } from "./figure/illustration.mjs";
 import { PlayWrap, usePlayGate } from "./play.mjs";
 import { PredictPlot } from "./predict.mjs";
 import { Vessel, VesselGlyph } from "./vessel.mjs";
@@ -7,12 +20,19 @@ import { DotCluster } from "./cluster.mjs";
 import { getScene, listScenes, registerScene } from "./scenes.mjs";
 import { Blank, SlotFill, SlotTray, useSlotFill } from "./slot-fill.mjs";
 import { Calc, calc, texNum } from "./calc.mjs";
+import { PredictGate } from "./predict-gate.mjs";
+import { RuleCard, RuleFigure, RuleLab, WorkedSteps } from "./rule.mjs";
 import { ReceiptScene } from "./receipt.mjs";
 import { ClueBalance, ClueBar, ClueCoins, ClueReceipt, ClueScene, ClueTiles, UnknownChip, clueTotal, getClueScene, listClueScenes, registerClueScene } from "./clue-scene.mjs";
-import { RuleCard, RuleLab, WorkedSteps } from "./rule.mjs";
+import { PlotChart } from "./finance-viz/plot-chart.mjs";
+import { ApportionBar } from "./finance-viz/apportion-bar.mjs";
+import { StockTimeline } from "./finance-viz/stock-timeline.mjs";
+import { TradeoffCurve } from "./finance-viz/tradeoff-curve.mjs";
+import { CoinGlyph, DiceGlyph, ProbabilityContributionBoard } from "./probability.mjs";
 import { StepNav, useSteps } from "./steps.mjs";
+import { GuideNav, useGuide } from "./guide.mjs";
 import { dataScene, registerDataScene } from "./data-scene.mjs";
 import { SceneStudio } from "./scene-studio.mjs";
 import { SceneLibraryManager, loadSceneLibrary, registerScenes, saveSceneLibrary, useSceneLibrary } from "./scene-library.mjs";
 
-export { Blank, Calc, Callout, ChallengeCard, ClueBalance, ClueBar, ClueCoins, ClueReceipt, ClueScene, ClueTiles, ControlBar, DotCluster, Feedback, Field, HintLadder, LabFrame, Objectives, PlayWrap, PredictPlot, ReceiptScene, RevealSolution, RuleCard, RuleLab, SceneLibraryManager, SceneStudio, SlotFill, SlotTray, StepNav, UnknownChip, Vessel, VesselGlyph, WorkedSteps, calc, clueTotal, dataScene, getClueScene, getScene, listClueScenes, listScenes, loadSceneLibrary, registerClueScene, registerDataScene, registerScene, registerScenes, saveSceneLibrary, texNum, useChallenge, useCheckpoint, useHints, usePlayGate, useSceneLibrary, useSlotFill, useSteps };
+export { Activity, ApportionBar, Area, Arrow, AuthoredActivityRuntime, AuthoredMetricGate, AuthoredResponse, Ball, Blank, Block, Bubbles, Calc, Celebrate, ChallengeCard, ClueBalance, ClueBar, ClueCoins, ClueReceipt, ClueScene, ClueTiles, CoinGlyph, Curve, DiceGlyph, DotCluster, Feedback, Field, FigTag, FigText, Figure, Glass, Ground, Guide, GuideNav, HUE, HintLadder, Illustration, LearningSequenceNav, Marker, Objectives, Particle, PlayWrap, PlotChart, PlotFrame, PredictGate, PredictPlot, ProbabilityContributionBoard, Ray, Readout, ReceiptScene, Region, RevealSolution, RuleCard, RuleFigure, RuleLab, STROKE, SceneLibraryManager, SceneStudio, SegmentBar, SlotFill, SlotTray, SolvedPill, Stat, StatList, StepNav, StockTimeline, Track, TradeoffCurve, UnknownChip, Vessel, VesselGlyph, WorkedSteps, activitySteps, alpha, calc, clueTotal, compileAuthoredActivity, dataScene, defineAuthoredActivity, evaluateAuthoredResponse, figUrl, fmt, getClueScene, getScene, glassInner, isCompiledAuthoredActivity, listClueScenes, listScenes, loadSceneLibrary, registerClueScene, registerDataScene, registerScene, registerScenes, saveSceneLibrary, scale, shade, texNum, tint, useChallenge, useCheckpoint, useFigureId, useGuide, useHints, useLearningSequence, usePlayGate, useSceneLibrary, useSlotFill, useSteps, withAuthoredObjectives };

package/dist/kit/learning-sequence.d.mts

@@ -0,0 +1,51 @@
+import { ReactNode } from "react";
+
+//#region src/kit/learning-sequence.d.ts
+type LearningPhase = 'predict' | 'act' | 'observe' | 'explain' | 'transfer';
+interface LearningGate {
+  /** The host decides what completes the gate and reports it through complete(). */
+  kind: 'answer' | 'action' | 'state' | 'reflection';
+  id: string;
+  pendingLabel?: string;
+}
+interface LearningBranch {
+  /** Map an authored outcome to the next step id. */
+  byOutcome: Record<string, string>;
+  fallback?: string;
+}
+interface LearningSequenceStep {
+  id: string;
+  phase: LearningPhase;
+  title?: string;
+  lead?: string;
+  reveal?: string[];
+  controls?: boolean;
+  gate?: LearningGate;
+  /** Omit for the next authored step; use a string or outcome branch when needed. */
+  next?: string | LearningBranch;
+}
+interface LearningSequence {
+  current: LearningSequenceStep;
+  index: number;
+  total: number;
+  history: string[];
+  canAdvance: boolean;
+  complete: (gateId: string, outcome?: string) => void;
+  next: () => void;
+  back: () => void;
+  reset: () => void;
+  shows: (layer: string) => boolean;
+  showControls: boolean;
+}
+interface LearningSequenceOptions {
+  initialStepId?: string;
+  onStepChange?: (step: LearningSequenceStep, index: number) => void;
+}
+declare function useLearningSequence(steps: readonly LearningSequenceStep[], options?: LearningSequenceOptions): LearningSequence;
+declare function LearningSequenceNav({
+  sequence
+}: {
+  sequence: LearningSequence;
+}): ReactNode;
+//#endregion
+export { LearningBranch, LearningGate, LearningPhase, LearningSequence, LearningSequenceNav, LearningSequenceStep, useLearningSequence };

package/dist/kit/learning-sequence.mjs

@@ -0,0 +1,101 @@
+'use client';
+
+import { ActionButton } from "./controls.mjs";
+import { useEffect, useMemo, useState } from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+
+//#region src/kit/learning-sequence.tsx
+/** A small, serializable learning arc for authored labs. The scene stays
+* domain-specific; this contract standardizes the learner loop and its gates. */
+function useLearningSequence(steps, options = {}) {
+	if (steps.length === 0) throw new Error("useLearningSequence requires at least one step");
+	const byId = useMemo(() => new Map(steps.map((step) => [step.id, step])), [steps]);
+	const firstId = options.initialStepId && byId.has(options.initialStepId) ? options.initialStepId : steps[0].id;
+	const [history, setHistory] = useState([firstId]);
+	const [completed, setCompleted] = useState({});
+	const currentId = history[history.length - 1] ?? steps[0].id;
+	const current = byId.get(currentId) ?? steps[0];
+	const index = Math.max(0, steps.findIndex((step) => step.id === current.id));
+	const canAdvance = current.gate == null || completed[current.gate.id] != null;
+	useEffect(() => {
+		options.onStepChange?.(current, index);
+	}, [
+		current,
+		index,
+		options.onStepChange
+	]);
+	const nextId = () => {
+		if (typeof current.next === "string") return current.next;
+		if (current.next) {
+			const outcome = current.gate ? completed[current.gate.id] : void 0;
+			return typeof outcome === "string" ? current.next.byOutcome[outcome] ?? current.next.fallback : current.next.fallback;
+		}
+		return steps[index + 1]?.id;
+	};
+	const visited = history.map((id) => byId.get(id)).filter((step) => step != null);
+	const layers = new Set(visited.flatMap((step) => step.reveal ?? []));
+	return {
+		current,
+		index,
+		total: steps.length,
+		history,
+		canAdvance,
+		complete: (gateId, outcome) => setCompleted((state) => ({
+			...state,
+			[gateId]: outcome ?? true
+		})),
+		next: () => {
+			if (!canAdvance) return;
+			const target = nextId();
+			if (target && byId.has(target)) setHistory((items) => [...items, target]);
+		},
+		back: () => setHistory((items) => items.length > 1 ? items.slice(0, -1) : items),
+		reset: () => {
+			setHistory([firstId]);
+			setCompleted({});
+		},
+		shows: (layer) => layers.has(layer),
+		showControls: visited.some((step) => step.controls)
+	};
+}
+function LearningSequenceNav({ sequence }) {
+	const { current } = sequence;
+	const pending = current.gate?.pendingLabel ?? `Complete the ${current.gate?.kind ?? "step"} to continue`;
+	return /* @__PURE__ */ jsxs("nav", {
+		className: "lab-sequence",
+		"aria-label": "Learning activity steps",
+		children: [/* @__PURE__ */ jsxs("div", {
+			className: "lab-sequence-actions",
+			children: [
+				/* @__PURE__ */ jsx(ActionButton, {
+					className: "lab-btn-ghost",
+					onClick: sequence.back,
+					disabled: sequence.history.length <= 1,
+					"aria-label": "Back",
+					children: "← Back"
+				}),
+				/* @__PURE__ */ jsxs("span", {
+					className: "lab-sequence-count",
+					"aria-live": "polite",
+					children: [
+						sequence.index + 1,
+						" / ",
+						sequence.total
+					]
+				}),
+				/* @__PURE__ */ jsx(ActionButton, {
+					onClick: sequence.next,
+					disabled: !sequence.canAdvance || sequence.index >= sequence.total - 1,
+					children: sequence.index >= sequence.total - 1 ? "Complete" : "Continue"
+				})
+			]
+		}), !sequence.canAdvance && /* @__PURE__ */ jsx("p", {
+			className: "lab-sequence-gate",
+			role: "status",
+			children: pending
+		})]
+	});
+}
+
+//#endregion
+export { LearningSequenceNav, useLearningSequence };