@classytic/labs 0.6.0 → 0.7.0

package/dist/math/mystery-bucket/asset.mjs

@@ -1,11 +1,25 @@
 'use client';
 
-import { num, toRad } from "../../core/util.mjs";
+import { num, toRad as toRad$1 } from "../../core/util.mjs";
+import { ensureAsset } from "../../kit/ensure-asset.mjs";
 import { ScaleFrame } from "../../kit/scale.mjs";
-import { BucketGlyph, StageAssetDefs, WeightGlyph, registerAsset, useCoords, vec } from "@classytic/stage";
-import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+import { useCoords, vec } from "@classytic/stage/core";
+import { useId } from "react";
+import { Fragment as Fragment$1, jsx, jsxs } from "react/jsx-runtime";
+import { BucketGlyph, StageAssetDefs, WeightGlyph } from "@classytic/stage/assets";
 
 //#region src/math/mystery-bucket/asset.tsx
+/**
+* mystery-bucket asset, the ESSENTIALS opener for "Algebra You Can See": a
+* balance scale with a sealed BUCKET of hidden weight on the left and a row of
+* 1-unit weights on the right. The learner adds units until the beam is level ,
+* then the bucket's weight is revealed. Teaches *unknown* + *balance* with zero
+* notation, before any letter or coefficient (Hands-On-Equations lineage).
+*
+* Reuses the shared balance vocabulary (flat beam + slim pedestal + hung trays
+* from balance-algebra) + the kit BucketGlyph / WeightGlyph, theme-aware, no
+* copy-pasted glyph drawing. The resolver owns the solve (tilt + balanced).
+*/
 const TRAY_R = .95;
 const HANG = .72;
 const asVec = (v, d) => v && typeof v === "object" && "x" in v ? v : d;
@@ -22,7 +36,7 @@ function resolver({ params }) {
 	const diff = total - count;
 	const balanced = diff === 0;
 	const tiltDeg = Math.max(-13, Math.min(13, diff * 4.5));
-	const rad = toRad(tiltDeg);
+	const rad = toRad$1(tiltDeg);
 	const beamA = vec.rotateAbout({
 		x: pivot.x - arm,
 		y: pivot.y
@@ -101,7 +115,8 @@ function resolver({ params }) {
 		}
 	};
 }
-function Component({ geom }) {
+function Component$1({ geom }) {
+	const scope = useId();
 	const c = useCoords();
 	const p = geom.parts;
 	const m = geom.meta ?? {};
@@ -121,9 +136,10 @@ function Component({ geom }) {
 			label: b.label
 		};
 	};
-	return /* @__PURE__ */ jsxs(Fragment, { children: [
-		/* @__PURE__ */ jsx(StageAssetDefs, {}),
+	return /* @__PURE__ */ jsxs(Fragment$1, { children: [
+		/* @__PURE__ */ jsx(StageAssetDefs, { scope }),
 		/* @__PURE__ */ jsx(ScaleFrame, {
+			scope,
 			pivot,
 			beamA: p.beamA,
 			beamB: p.beamB,
@@ -133,15 +149,24 @@ function Component({ geom }) {
 			panR: TRAY_R,
 			balanced: m.balanced
 		}),
-		(m.buckets ?? []).map((b, i) => /* @__PURE__ */ jsx(BucketGlyph, { ...toGlyph(b) }, `b${i}`)),
-		(m.coins ?? []).map((coin, i) => /* @__PURE__ */ jsx(WeightGlyph, { ...toGlyph(coin) }, `c${i}`))
+		(m.buckets ?? []).map((b, i) => /* @__PURE__ */ jsx(BucketGlyph, {
+			scope,
+			...toGlyph(b)
+		}, `b${i}`)),
+		(m.coins ?? []).map((coin, i) => /* @__PURE__ */ jsx(WeightGlyph, {
+			scope,
+			...toGlyph(coin)
+		}, `c${i}`))
 	] });
 }
 const MYSTERY_BUCKET_ASSET = {
 	resolver,
-	Component
+	Component: Component$1
 };
-registerAsset("mystery-bucket", MYSTERY_BUCKET_ASSET);
+/** Register the `mystery-bucket` asset (idempotent). `mysteryBucketDoc` calls it. */
+function registerMysteryBucketAsset() {
+	ensureAsset("mystery-bucket", MYSTERY_BUCKET_ASSET);
+}
 
 //#endregion
-export { MYSTERY_BUCKET_ASSET };
+export { MYSTERY_BUCKET_ASSET, registerMysteryBucketAsset };

package/dist/math/mystery-bucket/preset.d.mts

@@ -1,7 +1,7 @@
-import { MYSTERY_BUCKET_ASSET } from "./asset.mjs";
-import { SceneDoc } from "@classytic/stage";
+import { MYSTERY_BUCKET_ASSET, registerMysteryBucketAsset } from "./asset.mjs";
+import { SceneDoc } from "@classytic/stage/scene";
 //#region src/math/mystery-bucket/preset.d.ts
-/** Params → a portable SceneDoc (the asset self-registers on import). */
+/** Params → a portable SceneDoc. Registers the asset it names, so the doc always renders. */
 export declare function mysteryBucketDoc(params: {
   bucketWeight: number;
   count: number;
@@ -9,4 +9,4 @@ export declare function mysteryBucketDoc(params: {
   maxWeights?: number;
 }): SceneDoc;
 //#endregion
-export { MYSTERY_BUCKET_ASSET };
+export { MYSTERY_BUCKET_ASSET, registerMysteryBucketAsset };

package/dist/math/mystery-bucket/preset.mjs

@@ -1,12 +1,11 @@
 'use client';
 
-import { MYSTERY_BUCKET_ASSET } from "./asset.mjs";
-import { ensureAsset } from "../../kit/ensure-asset.mjs";
+import { MYSTERY_BUCKET_ASSET, registerMysteryBucketAsset } from "./asset.mjs";
 
 //#region src/math/mystery-bucket/preset.tsx
-ensureAsset("mystery-bucket", MYSTERY_BUCKET_ASSET);
-/** Params → a portable SceneDoc (the asset self-registers on import). */
+/** Params → a portable SceneDoc. Registers the asset it names, so the doc always renders. */
 function mysteryBucketDoc(params) {
+	registerMysteryBucketAsset();
 	return {
 		schemaVersion: 2,
 		type: "stage-scene",
@@ -35,4 +34,4 @@ function mysteryBucketDoc(params) {
 }
 
 //#endregion
-export { MYSTERY_BUCKET_ASSET, mysteryBucketDoc };
+export { MYSTERY_BUCKET_ASSET, mysteryBucketDoc, registerMysteryBucketAsset };

package/dist/ml/worlds/synthetic.mjs

@@ -4,7 +4,7 @@ import { data } from "@classytic/stage/ml";
 /**
 * The named synthetic two-class datasets the k-NN and linear-boundary labs load by id.
 *
-* Curated data, so it stays in labs (ML-ENGINE-PLAN 5): which blobs a lesson shows is how it
+* Curated data, so it stays in labs: which blobs a lesson shows is how it
 * teaches. The seeded generator (`data.makeSynthetic`) and the point type are stage's; its draw
 * order is part of its contract, so a seed produces the numbers it always did and a lesson that
 * pinned a seed still shows the same picture.

package/dist/model/controls.d.mts

@@ -51,6 +51,10 @@ export interface NumberControl<S, St> extends ControlBase<S, St> {
   symbol?: string;
   /** One key press; a function follows the lesson's precision. */
   step: Dynamic<S, St, number>;
+  /** Numeric writes snap to the step by default. Continuous precision preserves finite
+   * requested values within range; step and bigStep then specify keyboard increments only.
+   */
+  precision?: 'step' | 'continuous';
   /** Shift + key; defaults to ten steps. */
   bigStep?: Dynamic<S, St, number>;
   /** The allowed range now. Reads the state too, for a limit set by another control (sold ≤ produced). */

package/dist/model/define.d.mts

@@ -1,7 +1,14 @@
 import { ControlBuilder, LabControl } from "./controls.mjs";
+import { ModelCard } from "@classytic/stage/core";
 import { Refusal } from "@classytic/stage/result";
 import { z } from "zod";
 //#region src/model/define.d.ts
+/**
+ * The Stage model card(s) behind a lab's readings: the card its kernel exports, never a copy. A
+ * lab whose model changes with the learner's choice (a spring or a pendulum) passes a function of
+ * the scenario and state; `undefined` means no card applies to this state.
+ */
+export type LabModelCards<S = unknown, St = unknown> = ModelCard | readonly ModelCard[] | ((scenario: S, state: St) => ModelCard | readonly ModelCard[] | undefined);
 /** A model's clock, for labs whose state advances with time. */
 export type ReducedMotionPolicy = 'finish' | 'pause' | 'run';
 export interface LabClock<S = unknown> {
@@ -61,6 +68,11 @@ export interface LabModelSpec<P extends z.ZodObject, S, St, R, C extends Record<
   witness?: (scenario: S) => St;
   /** The live screen-reader account of the state, in the lesson's words. */
   describe: (scenario: S, state: St, reading: R) => string;
+  /**
+   * The scientific model, as Stage's own model card(s) (`ORBIT_FLIGHT_CARD`). The shell shows it as
+   * one quiet "Model:" line under Readings, with its assumptions behind a disclosure.
+   */
+  model?: LabModelCards<S, St>;
 }
 /** A defined model: the spec with its controls built and its ids listed. */
 export interface LabModel<P extends z.ZodObject = z.ZodObject, S = unknown, St = unknown, R = unknown, C extends Record<string, LabControl<S, St>> = Record<string, LabControl<S, St>>, G extends string = string, A extends string = string> {
@@ -84,6 +96,8 @@ export interface LabModel<P extends z.ZodObject = z.ZodObject, S = unknown, St =
   readonly goalIds: readonly G[];
   readonly witness: ((scenario: S) => St) | undefined;
   readonly describe: (scenario: S, state: St, reading: R) => string;
+  /** The model cards that apply to this state, each once; empty when the lab declares none. */
+  readonly modelCards: (scenario: S, state: St) => readonly ModelCard[];
 }
 export type AnyLabModel = LabModel<any, any, any, any, any, any, any>;
 export type ParamsOf<M> = M extends LabModel<infer P, any, any, any, any, any, any> ? z.output<P> : never;

package/dist/model/define.mjs

@@ -8,6 +8,21 @@ const DEFAULT_CLOCK = {
 	publishHz: 0
 };
 const ACTION_ID = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
+const NO_CARDS = Object.freeze([]);
+/** One card or several, as a frozen list with each card id once. Rejects what is not a card. */
+function cardList(id, value) {
+	if (value === undefined) return NO_CARDS;
+	const list = Array.isArray(value) ? value : [value];
+	const seen = new Set();
+	const out = [];
+	for (const card of list) {
+		if (typeof card?.id !== "string" || !Array.isArray(card.assumptions)) throw new TypeError(`${id}: model must be a Stage model card (with an id and assumptions)`);
+		if (seen.has(card.id)) continue;
+		seen.add(card.id);
+		out.push(card);
+	}
+	return out.length ? Object.freeze(out) : NO_CARDS;
+}
 /**
 * Define a lab's model. Validates the declaration (ids, kinds) and returns a frozen model. It does not
 * run the model: `resolveScenario` and `createLabSession` do, and conformance runs them over every lab.
@@ -47,6 +62,9 @@ function defineLabModel(spec) {
 	if (spec.clock?.reducedMotion === "finish" && !spec.settled) {
 		throw new TypeError(`${spec.id}: reducedMotion 'finish' needs settled(), so the run knows where it ends`);
 	}
+	const declared = spec.model;
+	const fixedCards = typeof declared === "function" ? undefined : cardList(spec.id, declared);
+	const modelCards = typeof declared === "function" ? (scenario, state) => cardList(spec.id, declared(scenario, state)) : () => fixedCards;
 	return Object.freeze({
 		kind: "classytic.lab-model",
 		id: spec.id,
@@ -69,7 +87,8 @@ function defineLabModel(spec) {
 		goals: Object.freeze(goals),
 		goalIds: Object.freeze(goalIds),
 		witness: spec.witness,
-		describe: spec.describe
+		describe: spec.describe,
+		modelCards
 	});
 }
 function isLabModel(value) {

package/dist/model/format.d.mts

@@ -0,0 +1,33 @@
+//#region src/model/format.d.ts
+/** Pure display formatters: no React, controls or scientific calculation dependencies. */
+/**
+ * A number for a learner to read: rounded to `digits` places with trailing zeros dropped (`2.50` ->
+ * `2.5`), and an em dash instead of `NaN`/`Infinity`, which mean "no value" to a reader. This is the
+ * one display formatter; labs had ~20 private copies of it written four different ways.
+ */
+export declare const fmt: (n: number, digits?: number) => string;
+/**
+ * A number in the notation chemistry actually uses: `1.8 × 10⁻¹⁰`, not `1.8e-10`.
+ *
+ * `toExponential` prints for a machine. It was going straight onto figure labels, so a solubility
+ * product read `1.1e-12`, a concentration read `1e-6 mol/dm³`, and a mixture two hundred times
+ * under its limit announced itself as `2e+2 times under it`. None of those are how the quantity is
+ * written in any book the learner will ever open, and the last one is worse than ugly: it dresses
+ * the plain number 200 up as something that needs decoding.
+ *
+ * So the exponent is only reached for when it earns its place. Between a hundredth and ten thousand
+ * the ordinary decimal is shorter AND clearer, and that band covers most of what a learner
+ * measures; outside it the mantissa and a real superscripted power of ten are used.
+ *
+ * The band's lower edge is 0.01 rather than 0.001 because of what a render showed: a figure listed
+ * two concentrations one above the other and got `0.001` over `10⁻⁴`. Both were right and the pair
+ * was unreadable, because comparing two numbers means comparing their notation first. Dropping the
+ * edge puts every concentration a learner mixes on the same side of it.
+ */
+export declare function sci(value: number, digits?: number): string;
+/** Significant figures, with the same readable decimal/scientific notation as `sci`.
+ * Unlike `sci`'s decimal-place argument, precision stays consistent across powers of ten. */
+export declare function sciSignificant(value: number, digits?: number): string;
+/** Shorten floating representation noise within four relative epsilons, preserving integer digits. */
+export declare function fmtPrecise(value: number): string;
+//#endregion

package/dist/model/format.mjs

@@ -0,0 +1,76 @@
+//#region src/model/format.ts
+/** Pure display formatters: no React, controls or scientific calculation dependencies. */
+/**
+* A number for a learner to read: rounded to `digits` places with trailing zeros dropped (`2.50` ->
+* `2.5`), and an em dash instead of `NaN`/`Infinity`, which mean "no value" to a reader. This is the
+* one display formatter; labs had ~20 private copies of it written four different ways.
+*/
+const fmt = (n, digits = 1) => Number.isFinite(n) ? Number(n.toFixed(digits)).toString() : "—";
+const SUPERSCRIPT = [
+	"⁰",
+	"¹",
+	"²",
+	"³",
+	"⁴",
+	"⁵",
+	"⁶",
+	"⁷",
+	"⁸",
+	"⁹"
+];
+function scientific(lead, exponent) {
+	const power = `${exponent < 0 ? "⁻" : ""}${String(Math.abs(exponent)).split("").map((d) => SUPERSCRIPT[Number(d)]).join("")}`;
+	return lead === "1" ? `10${power}` : `${lead} × 10${power}`;
+}
+/**
+* A number in the notation chemistry actually uses: `1.8 × 10⁻¹⁰`, not `1.8e-10`.
+*
+* `toExponential` prints for a machine. It was going straight onto figure labels, so a solubility
+* product read `1.1e-12`, a concentration read `1e-6 mol/dm³`, and a mixture two hundred times
+* under its limit announced itself as `2e+2 times under it`. None of those are how the quantity is
+* written in any book the learner will ever open, and the last one is worse than ugly: it dresses
+* the plain number 200 up as something that needs decoding.
+*
+* So the exponent is only reached for when it earns its place. Between a hundredth and ten thousand
+* the ordinary decimal is shorter AND clearer, and that band covers most of what a learner
+* measures; outside it the mantissa and a real superscripted power of ten are used.
+*
+* The band's lower edge is 0.01 rather than 0.001 because of what a render showed: a figure listed
+* two concentrations one above the other and got `0.001` over `10⁻⁴`. Both were right and the pair
+* was unreadable, because comparing two numbers means comparing their notation first. Dropping the
+* edge puts every concentration a learner mixes on the same side of it.
+*/
+function sci(value, digits = 1) {
+	if (!Number.isFinite(value)) return "—";
+	if (value === 0) return "0";
+	const magnitude = Math.abs(value);
+	if (magnitude >= .01 && magnitude < 1e4) return fmt(value, magnitude < 1 ? digits + 2 : digits);
+	const exponent = Math.floor(Math.log10(magnitude));
+	const mantissa = value / 10 ** exponent;
+	const lead = fmt(mantissa, digits);
+	return scientific(lead, exponent);
+}
+/** Significant figures, with the same readable decimal/scientific notation as `sci`.
+* Unlike `sci`'s decimal-place argument, precision stays consistent across powers of ten. */
+function sciSignificant(value, digits = 3) {
+	if (!Number.isFinite(value)) return "—";
+	if (value === 0) return "0";
+	const rounded = Number(value.toPrecision(digits));
+	if (Math.abs(rounded) >= .01 && Math.abs(rounded) < 1e4) return String(rounded);
+	const [lead, exponent] = value.toExponential(digits - 1).split("e");
+	return scientific(String(Number(lead)), Number(exponent));
+}
+/** Shorten floating representation noise within four relative epsilons, preserving integer digits. */
+function fmtPrecise(value) {
+	if (Number.isInteger(value) || !Number.isFinite(value)) return String(value);
+	const exponent = Math.floor(Math.log10(Math.abs(value)));
+	const sameValue = (candidate) => Math.abs(candidate - value) <= Math.abs(value) * Number.EPSILON * 4;
+	const decimal = fmt(value, Math.min(100, Math.max(0, 14 - exponent)));
+	if (sameValue(Number(decimal))) return decimal;
+	const power = 10 ** exponent;
+	if (exponent < -100 && power > 0 && sameValue(Number(fmt(value / power, 14)) * power)) return sci(value, 14);
+	return String(value);
+}
+
+//#endregion
+export { fmt, fmtPrecise, sci, sciSignificant };

package/dist/model/index.d.mts

@@ -1,6 +1,8 @@
 import { ActionControl, CONTROL_ID, ChoiceControl, ControlBuilder, ControlKind, ControlOption, ControlPoint, LabControl, NumberControl, PointControl, TextControl, ToggleControl, stepDecimals } from "./controls.mjs";
-import { ActionIdOf, AnyLabModel, ControlIdOf, GoalCheck, GoalIdOf, LabClock, LabModel, LabModelSpec, ParamsOf, PropsOf, ReadingOf, ScenarioOf, StateOf, defineLabModel, isLabModel } from "./define.mjs";
+import { ActionIdOf, AnyLabModel, ControlIdOf, GoalCheck, GoalIdOf, LabClock, LabModel, LabModelCards, LabModelSpec, ParamsOf, PropsOf, ReadingOf, ScenarioOf, StateOf, defineLabModel, isLabModel } from "./define.mjs";
+import { Grouping, MoneyFormat, NumberFormat, formatMoney, formatNumber, groupingFor } from "./money.mjs";
 import { ControlValue, ControlView, LabRefusalError, LabSession, ResolvedScenario, SessionEvent, createLabSession, resolveScenario, startSession } from "./session.mjs";
+import { ModelNote, modelNoteOf } from "./model-note.mjs";
 import { storyParams } from "./story.mjs";
 import { Refusal, isRefusal, refuse } from "@classytic/stage/result";
-export { type ActionControl, type ActionIdOf, type AnyLabModel, CONTROL_ID, type ChoiceControl, type ControlBuilder, type ControlIdOf, type ControlKind, type ControlOption, type ControlPoint, type ControlValue, type ControlView, type GoalCheck, type GoalIdOf, type LabClock, type LabControl, type LabModel, type LabModelSpec, LabRefusalError, type LabSession, type NumberControl, type ParamsOf, type PointControl, type PropsOf, type ReadingOf, type Refusal, type ResolvedScenario, type ScenarioOf, type SessionEvent, type StateOf, type TextControl, type ToggleControl, createLabSession, defineLabModel, isLabModel, isRefusal, refuse, resolveScenario, startSession, stepDecimals, storyParams };
+export { type ActionControl, type ActionIdOf, type AnyLabModel, CONTROL_ID, type ChoiceControl, type ControlBuilder, type ControlIdOf, type ControlKind, type ControlOption, type ControlPoint, type ControlValue, type ControlView, type GoalCheck, type GoalIdOf, type Grouping, type LabClock, type LabControl, type LabModel, type LabModelCards, type LabModelSpec, LabRefusalError, type LabSession, type ModelNote, type MoneyFormat, type NumberControl, type NumberFormat, type ParamsOf, type PointControl, type PropsOf, type ReadingOf, type Refusal, type ResolvedScenario, type ScenarioOf, type SessionEvent, type StateOf, type TextControl, type ToggleControl, createLabSession, defineLabModel, formatMoney, formatNumber, groupingFor, isLabModel, isRefusal, modelNoteOf, refuse, resolveScenario, startSession, stepDecimals, storyParams };

package/dist/model/index.mjs

@@ -1,7 +1,9 @@
 import { CONTROL_ID, stepDecimals } from "./controls.mjs";
 import { defineLabModel, isLabModel } from "./define.mjs";
+import { modelNoteOf } from "./model-note.mjs";
 import { LabRefusalError, createLabSession, resolveScenario, startSession } from "./session.mjs";
 import { storyParams } from "./story.mjs";
+import { formatMoney, formatNumber, groupingFor } from "./money.mjs";
 import { isRefusal, refuse } from "@classytic/stage/result";
 
-export { CONTROL_ID, LabRefusalError, createLabSession, defineLabModel, isLabModel, isRefusal, refuse, resolveScenario, startSession, stepDecimals, storyParams };
+export { CONTROL_ID, LabRefusalError, createLabSession, defineLabModel, formatMoney, formatNumber, groupingFor, isLabModel, isRefusal, modelNoteOf, refuse, resolveScenario, startSession, stepDecimals, storyParams };

package/dist/model/model-note.d.mts

@@ -0,0 +1,16 @@
+import { ModelCard } from "@classytic/stage/core";
+//#region src/model/model-note.d.ts
+export interface ModelNote {
+  /** The text after "Model:": each card's summary, in order. */
+  readonly summary: string;
+  /** Where each model holds, one plain sentence per card, each once. */
+  readonly limits: readonly string[];
+  /** The cards it was built from, for a data attribute or a teacher view. */
+  readonly ids: readonly string[];
+}
+/**
+ * The note for these cards, or undefined when there is nothing a learner should read: a card with
+ * no `summary` contributes nothing, so developer wording never reaches the page.
+ */
+export declare function modelNoteOf(cards: readonly ModelCard[]): ModelNote | undefined;
+//#endregion

package/dist/model/model-note.mjs

@@ -0,0 +1,34 @@
+//#region src/model/model-note.ts
+/** 'holds for swings up to 177 degrees' becomes 'Holds for swings up to 177 degrees.' */
+function sentence(text) {
+	const trimmed = text?.trim();
+	if (!trimmed) return undefined;
+	const capital = trimmed[0].toUpperCase() + trimmed.slice(1);
+	return /[.!?]$/.test(capital) ? capital : `${capital}.`;
+}
+/**
+* The note for these cards, or undefined when there is nothing a learner should read: a card with
+* no `summary` contributes nothing, so developer wording never reaches the page.
+*/
+function modelNoteOf(cards) {
+	const summaries = [];
+	const limits = [];
+	const shown = [];
+	for (const card of cards) {
+		const summary = sentence(card.summary);
+		if (!summary) continue;
+		shown.push(card.id);
+		if (!summaries.includes(summary)) summaries.push(summary);
+		const limit = sentence(card.limits);
+		if (limit && !limits.includes(limit)) limits.push(limit);
+	}
+	if (summaries.length === 0) return undefined;
+	return {
+		summary: summaries.join(" "),
+		limits,
+		ids: shown
+	};
+}
+
+//#endregion
+export { modelNoteOf };

package/dist/model/money.d.mts

@@ -0,0 +1,36 @@
+//#region src/model/money.d.ts
+/**
+ * Money and number formatting for every commerce lab, in one place.
+ *
+ * Deterministic on purpose: no browser locale. `toLocaleString()` without a locale printed 100,000 for one viewer
+ * and ১,০০,০০০ for another, and the server render disagreed with the client. Grouping is explicit:
+ *
+ *   western  1,234,567   (thousands)
+ *   lakh     12,34,567   (South Asian: the last three digits, then pairs), the form a Bangladeshi book prints
+ *
+ * The grouping follows the currency unless a lab passes one: taka and rupee amounts group in lakhs, everything
+ * else in thousands. Digits are always Latin here; a lesson writes Bangla digits in its own prose.
+ */
+export type Grouping = 'western' | 'lakh';
+export interface NumberFormat {
+  /** Digit grouping; defaults from the currency for money, western for plain numbers. */
+  grouping?: Grouping;
+  /**
+   * Decimal places. A number fixes them (2 shows 12.50); 'auto' (the default) shows up to two and drops
+   * trailing zeros (12.5, 12), which is how a ledger amount reads.
+   */
+  decimals?: number | 'auto';
+}
+export interface MoneyFormat extends NumberFormat {
+  /** What is printed before the amount, exactly as given: '$', 'Tk ', '৳', '£'. */
+  currency?: string;
+  /** How a negative amount reads: '-Tk 500' (minus) or '(Tk 500)' (brackets, as statements print it). */
+  negative?: 'minus' | 'brackets';
+}
+/** The grouping a currency is written with: lakh for taka and rupee, western otherwise. */
+export declare function groupingFor(currency: string | undefined): Grouping;
+/** A number with grouping and decimals, Latin digits, a leading minus when negative. */
+export declare function formatNumber(value: number, format?: NumberFormat): string;
+/** An amount with its currency: 'Tk 1,25,000', '$125,000', '(Tk 500)'. */
+export declare function formatMoney(value: number, format?: MoneyFormat): string;
+//#endregion

package/dist/model/money.mjs

@@ -0,0 +1,45 @@
+//#region src/model/money.ts
+const LAKH_CURRENCY = /^\s*(tk|bdt|৳|rs\.?|inr|₹)/i;
+/** The grouping a currency is written with: lakh for taka and rupee, western otherwise. */
+function groupingFor(currency) {
+	return currency !== undefined && LAKH_CURRENCY.test(currency) ? "lakh" : "western";
+}
+function groupDigits(digits, grouping) {
+	if (digits.length <= 3) return digits;
+	const last3 = digits.slice(-3);
+	const rest = digits.slice(0, -3);
+	const size = grouping === "lakh" ? 2 : 3;
+	const parts = [];
+	for (let end = rest.length; end > 0; end -= size) parts.unshift(rest.slice(Math.max(0, end - size), end));
+	return `${parts.join(",")},${last3}`;
+}
+/** A number with grouping and decimals, Latin digits, a leading minus when negative. */
+function formatNumber(value, format = {}) {
+	if (!Number.isFinite(value)) return String(value);
+	const { grouping = "western", decimals = "auto" } = format;
+	const places = decimals === "auto" ? 2 : Math.max(0, Math.min(10, Math.trunc(decimals)));
+	let fixed = Math.abs(value).toFixed(places);
+	if (decimals === "auto" && fixed.includes(".")) fixed = fixed.replace(/\.?0+$/, "");
+	const [whole = "0", fraction] = fixed.split(".");
+	const body = groupDigits(whole, grouping) + (fraction ? `.${fraction}` : "");
+	const negative = value < 0 && Number(fixed) !== 0;
+	return negative ? `-${body}` : body;
+}
+/** An amount with its currency: 'Tk 1,25,000', '$125,000', '(Tk 500)'. */
+function formatMoney(value, format = {}) {
+	const { currency = "$", negative = "minus" } = format;
+	const grouping = format.grouping ?? groupingFor(currency);
+	const amount = formatNumber(Math.abs(value), {
+		grouping,
+		decimals: format.decimals
+	});
+	const isNegative = value < 0 && formatNumber(value, {
+		grouping,
+		decimals: format.decimals
+	}).startsWith("-");
+	if (!isNegative) return `${currency}${amount}`;
+	return negative === "brackets" ? `(${currency}${amount})` : `-${currency}${amount}`;
+}
+
+//#endregion
+export { formatMoney, formatNumber, groupingFor };

package/dist/model/resolved-value.mjs

@@ -0,0 +1,16 @@
+//#region src/model/resolved-value.ts
+/**
+* Read a kernel value only after scenario validation and bounded model writes
+* have established its input invariants. Authored invalid values belong in
+* resolve/schema refusals; an unexpected refusal here is a broken model contract.
+* Internal model glue, not a public alternate Result API or UI error fallback.
+*/
+function resolvedValue(result, context) {
+	if (!result.ok) {
+		throw new TypeError(`${context}: unexpected refusal ${result.code}: ${result.message}`);
+	}
+	return result.value;
+}
+
+//#endregion
+export { resolvedValue };

package/dist/model/session.d.mts

@@ -27,6 +27,7 @@ type ControlViewBody = {
   max: number;
   step: number;
   bigStep: number;
+  precision?: 'step' | 'continuous';
   unit?: string;
   symbol?: string;
   valueText: string;
@@ -91,6 +92,8 @@ export interface LabSession<M extends AnyLabModel> {
   readonly playing: boolean;
   /** Bumps on every discrete change; React keys its snapshot on it. */
   readonly version: number;
+  /** Opaque lifecycle identity, renewed only by reset and unique to each session. */
+  readonly resetKey: object;
   /** The learner has changed something since the start or the last reset (Start over shows). */
   readonly dirty: boolean;
   /** Whether a goal is met; `args` as a step passes them (a round's index). */

package/dist/model/session.mjs

@@ -118,7 +118,7 @@ function viewControlBody(model, scenario, state, id) {
 			const value = control.get(state, scenario);
 			const step = dynamic(control.step, scenario, state);
 			const bigStep = control.bigStep === undefined ? step * 10 : dynamic(control.bigStep, scenario, state);
-			const text = control.format ? control.format(value, scenario) : `${value.toFixed(shownDecimals(step))}${control.unit ? ` ${control.unit}` : ""}`;
+			const text = control.format ? control.format(value, scenario) : `${control.precision === "continuous" ? String(value) : value.toFixed(shownDecimals(step))}${control.unit ? ` ${control.unit}` : ""}`;
 			return {
 				id,
 				kind: "number",
@@ -128,6 +128,7 @@ function viewControlBody(model, scenario, state, id) {
 				max,
 				step,
 				bigStep,
+				...control.precision ? { precision: control.precision } : {},
 				...control.unit ? { unit: control.unit } : {},
 				...control.symbol ? { symbol: control.symbol } : {},
 				valueText: text
@@ -233,6 +234,7 @@ function startSession(model, resolved) {
 	let reading = model.read(scenario, state);
 	let time = 0;
 	let version = 0;
+	let resetKey = {};
 	let dirty = false;
 	/** The learner's (or autoplay's) wish for the clock: set by play, pause and reset. */
 	let playing = Boolean(model.step && model.clock.autoplay);
@@ -311,6 +313,9 @@ function startSession(model, resolved) {
 		get version() {
 			return version;
 		},
+		get resetKey() {
+			return resetKey;
+		},
 		get dirty() {
 			return dirty;
 		},
@@ -420,6 +425,7 @@ function startSession(model, resolved) {
 			emit("change");
 		},
 		reset() {
+			resetKey = {};
 			clock.reset();
 			time = 0;
 			lastPublish = 0;

package/dist/networking/CellularScene.mjs

@@ -1,5 +1,6 @@
 'use client';
 
+import { textWidth } from "../kit/figure/text-metrics.mjs";
 import { FigText } from "../kit/figure/text.mjs";
 import { Figure, HUE, STROKE, alpha, figUrl, tint, useFigureId } from "../kit/figure/figure.mjs";
 import "../kit/figure/index.mjs";
@@ -297,9 +298,9 @@ const rectEdges = (x, y, w, h) => [
 		y + h
 	]
 ];
-/** Note-size text: about 6 units a character, cap to descender about 12. */
+/** Note-size text: its measured width, cap to descender about 12. */
 const noteBox = (x, baseline, text, anchor) => {
-	const w = text.length * 6.1;
+	const w = textWidth(text, { role: "note" });
 	const l = anchor === "start" ? x : anchor === "end" ? x - w : x - w / 2;
 	return {
 		l,
@@ -312,7 +313,7 @@ const noteBox = (x, baseline, text, anchor) => {
 const NOTE_LEADING = 12;
 /** The box of a name set as `lines`, the first baseline at `baseline`. */
 const linesBox = (x, baseline, lines, anchor) => {
-	const widest = lines.reduce((m, line) => line.length > m.length ? line : m, "");
+	const widest = lines.reduce((m, line) => textWidth(line, { role: "note" }) > textWidth(m, { role: "note" }) ? line : m, "");
 	const box = noteBox(x, baseline, widest, anchor);
 	return {
 		...box,