@classytic/labs 0.6.0 → 0.7.0

package/dist/kit/scene/tokens.d.mts

@@ -1,11 +1,22 @@
 //#region src/kit/scene/tokens.d.ts
 /**
- * The scene materials and motion, typed (docs/SCENES.md, §5; values in styles/scene.css).
+ * The scene materials, light and motion, typed (docs/SCENES.md, §5; values in styles/scene.css).
  *
  * A scene never writes a colour: it names a material here. Each value is a CSS variable, so the
  * theme resolves it (light stone bench, charcoal in dark mode) and a typo fails to compile instead of
- * painting black. Records, not ternaries: a new accent must be given all three tones or it will not
+ * painting black. Records, not ternaries: a new accent must be given all its tones or it will not
  * type-check.
+ *
+ * One ramp. Every material is one base colour; its lit face mixes 20% toward the warm key light,
+ * its deep face is the base 0.1 darker in OKLCH lightness at the same chroma, then 8% toward the
+ * cool shade, and a far part recedes 40% into the bench. The token
+ * ramps (`SCENE.steel`, `ACCENT.*`) are derived that way in scene.css, and `rampOf` derives the same
+ * ramp from any other colour, so there is no second shading rule anywhere in the kit.
+ *
+ * Light is not paint. The highlight (`SCENE.spec`) and the shadow ink (`SCENE.shadow`) are pinned:
+ * a highlight is where the light hits, white on a dark knob and on a pale one alike, and a shadow is
+ * the absence of light, dark under both. Mixing either toward the page paper or the text ink makes
+ * a highlight a dark streak, or a shadow a pale halo, in one theme.
  */
 export interface Ramp {
   /** The face turned to the light. */
@@ -13,23 +24,43 @@ export interface Ramp {
   base: string;
   /** The side face and the edge. */
   deep: string;
+  /** A rear part of the same object (a far leg, a back wall), receding into the bench. Every token
+   * ramp and every `rampOf` ramp has it; a hand-built ramp may leave it out. */
+  far?: string;
 }
+/** Every slot present: what the token ramps and `rampOf` return. */
+export type FullRamp = Required<Ramp>;
+declare const rampOf: (base: string) => FullRamp;
 export declare const SCENE: {
   readonly bench: {
     readonly top: string;
     readonly edge: string;
   };
+  /** Contact-shadow ink: physical, dark in both themes (drawn by `Grounding`). */
   readonly shadow: string;
-  readonly steel: {
-    lit: string;
-    base: string;
-    deep: string;
+  /** The key light (warm) and the shade (cool) every ramp mixes toward. Pinned. */
+  readonly light: {
+    readonly warm: string;
+    readonly cool: string;
+  };
+  /** The highlight: a fixed warm white in both themes, never page paper (drawn by `Glint`). */
+  readonly spec: {
+    readonly hard: string;
+    readonly soft: string;
   };
+  readonly steel: Required<Ramp>;
   readonly glass: {
     readonly fill: string;
     readonly edge: string;
     readonly shine: string;
   };
+  /** Amber glass (`Solid finish="amber-glass"`): body, the lighter thin middle, the dark thick
+   * walls. Pinned: a brown reagent bottle is brown in both themes. */
+  readonly amberGlass: {
+    readonly body: string;
+    readonly core: string;
+    readonly wall: string;
+  };
   readonly plastic: {
     readonly base: string;
     readonly edge: string;
@@ -57,11 +88,37 @@ export declare const SCENE: {
   readonly label: {
     readonly paper: string;
     readonly ink: string;
+    readonly accent: string;
+  };
+  /** A cut through solid material (`Cutaway`): the face, its hatch, the cavity behind. Pinned. */
+  readonly section: {
+    readonly face: string;
+    readonly hatch: string;
+    readonly cavity: string;
   };
 };
+/** The section hatch: 45 degree lines `gap` apart, the blueprint convention for a cut face. */
+declare const HATCH: {
+  readonly angle: 45;
+  readonly gap: 6;
+};
 export type AccentName = 'cobalt' | 'coral' | 'violet' | 'amber' | 'mint';
 /** The five object accents. What makes an object an object: a cylinder, a knob, a thumb pad. */
-export declare const ACCENT: Readonly<Record<AccentName, Ramp>>;
+export declare const ACCENT: Readonly<Record<AccentName, FullRamp>>;
+/**
+ * Science colours: what heat, cold and emitted light look like. Pinned in both themes and never the
+ * host's warning or danger UI colours, so re-branding `--destructive` cannot re-colour temperature.
+ * `incandescent(t)` runs from a dull ember (t = 0) to white heat (t = 1).
+ */
+declare const SCI: {
+  readonly hot: "var(--sci-hot)";
+  readonly cold: "var(--sci-cold)";
+  readonly ember: "var(--sci-ember)";
+  readonly whiteHot: "var(--sci-white-hot)";
+  /** The warm light of a lamp or flame, the colour an incandescent glow spreads. */
+  readonly glow: "var(--sci-glow)";
+  readonly incandescent: (t: number) => string;
+};
 export type MotionName = 'settle' | 'release' | 'reward' | 'reject';
 /**
  * Springs by duration and bounce (Apple WWDC23): the CSS shorthand `<duration> <easing>` for a
@@ -69,4 +126,5 @@ export type MotionName = 'settle' | 'release' | 'reward' | 'reject';
  * `reward` a goal reached, once; `reject` a wrong bin or an invalid build.
  */
 export declare const MOTION: Readonly<Record<MotionName, string>>;
-//#endregion
+//#endregion
+export {};

package/dist/kit/scene/tokens.mjs

@@ -1,29 +1,74 @@
 //#region src/kit/scene/tokens.ts
 /**
-* The scene materials and motion, typed (docs/SCENES.md, §5; values in styles/scene.css).
+* The scene materials, light and motion, typed (docs/SCENES.md, §5; values in styles/scene.css).
 *
 * A scene never writes a colour: it names a material here. Each value is a CSS variable, so the
 * theme resolves it (light stone bench, charcoal in dark mode) and a typo fails to compile instead of
-* painting black. Records, not ternaries: a new accent must be given all three tones or it will not
+* painting black. Records, not ternaries: a new accent must be given all its tones or it will not
 * type-check.
+*
+* One ramp. Every material is one base colour; its lit face mixes 20% toward the warm key light,
+* its deep face is the base 0.1 darker in OKLCH lightness at the same chroma, then 8% toward the
+* cool shade, and a far part recedes 40% into the bench. The token
+* ramps (`SCENE.steel`, `ACCENT.*`) are derived that way in scene.css, and `rampOf` derives the same
+* ramp from any other colour, so there is no second shading rule anywhere in the kit.
+*
+* Light is not paint. The highlight (`SCENE.spec`) and the shadow ink (`SCENE.shadow`) are pinned:
+* a highlight is where the light hits, white on a dark knob and on a pale one alike, and a shadow is
+* the absence of light, dark under both. Mixing either toward the page paper or the text ink makes
+* a highlight a dark streak, or a shadow a pale halo, in one theme.
 */
 const v = (name) => `var(--scene-${name})`;
+const tokenRamp = (name) => ({
+	lit: v(`${name}-lit`),
+	base: v(name),
+	deep: v(`${name}-deep`),
+	far: v(`${name}-far`)
+});
+/**
+* The ramp of any colour, by the same rule the token ramps follow: lit 20% toward the warm key,
+* deep 0.1 darker at the same chroma and 8% toward the cool shade, far 40% toward the bench.
+* Opaque in both themes. The deep face keeps its chroma: a plain mix toward the near-neutral
+* shade greys a saturated accent (amber turns tan) as fast as it darkens it.
+*/
+/** The deep face of any colour (see `rampOf`); scene.css writes the same rule for the token ramps. */
+const deepOf = (base) => `color-mix(in oklab, oklch(from ${base} calc(l - 0.1) c h), ${v("shade-cool")} 8%)`;
+const rampOf = (base) => ({
+	lit: `color-mix(in oklab, ${base}, ${v("light-warm")} 20%)`,
+	base,
+	deep: deepOf(base),
+	far: `color-mix(in oklab, ${base}, ${v("bench-top")} 40%)`
+});
 const SCENE = {
 	bench: {
 		top: v("bench-top"),
 		edge: v("bench-edge")
 	},
+	/** Contact-shadow ink: physical, dark in both themes (drawn by `Grounding`). */
 	shadow: v("shadow"),
-	steel: {
-		lit: v("steel-lit"),
-		base: v("steel"),
-		deep: v("steel-deep")
+	/** The key light (warm) and the shade (cool) every ramp mixes toward. Pinned. */
+	light: {
+		warm: v("light-warm"),
+		cool: v("shade-cool")
 	},
+	/** The highlight: a fixed warm white in both themes, never page paper (drawn by `Glint`). */
+	spec: {
+		hard: v("spec"),
+		soft: v("spec-soft")
+	},
+	steel: tokenRamp("steel"),
 	glass: {
 		fill: v("glass"),
 		edge: v("glass-edge"),
 		shine: v("shine")
 	},
+	/** Amber glass (`Solid finish="amber-glass"`): body, the lighter thin middle, the dark thick
+	* walls. Pinned: a brown reagent bottle is brown in both themes. */
+	amberGlass: {
+		body: v("amber-glass"),
+		core: v("amber-glass-core"),
+		wall: v("amber-glass-wall")
+	},
 	plastic: {
 		base: v("plastic"),
 		edge: v("plastic-edge")
@@ -50,36 +95,42 @@ const SCENE = {
 	/** Every piece of text on an object: ink on paper, readable on anything, in both themes. */
 	label: {
 		paper: v("label"),
-		ink: v("label-ink")
+		ink: v("label-ink"),
+		accent: v("label-accent")
+	},
+	/** A cut through solid material (`Cutaway`): the face, its hatch, the cavity behind. Pinned. */
+	section: {
+		face: v("section"),
+		hatch: v("section-hatch"),
+		cavity: v("section-cavity")
 	}
 };
+/** The section hatch: 45 degree lines `gap` apart, the blueprint convention for a cut face. */
+const HATCH = {
+	angle: 45,
+	gap: 6
+};
 /** The five object accents. What makes an object an object: a cylinder, a knob, a thumb pad. */
 const ACCENT = {
-	cobalt: {
-		lit: v("cobalt-lit"),
-		base: v("cobalt"),
-		deep: v("cobalt-deep")
-	},
-	coral: {
-		lit: v("coral-lit"),
-		base: v("coral"),
-		deep: v("coral-deep")
-	},
-	violet: {
-		lit: v("violet-lit"),
-		base: v("violet"),
-		deep: v("violet-deep")
-	},
-	amber: {
-		lit: v("amber-lit"),
-		base: v("amber"),
-		deep: v("amber-deep")
-	},
-	mint: {
-		lit: v("mint-lit"),
-		base: v("mint"),
-		deep: v("mint-deep")
-	}
+	cobalt: tokenRamp("cobalt"),
+	coral: tokenRamp("coral"),
+	violet: tokenRamp("violet"),
+	amber: tokenRamp("amber"),
+	mint: tokenRamp("mint")
+};
+/**
+* Science colours: what heat, cold and emitted light look like. Pinned in both themes and never the
+* host's warning or danger UI colours, so re-branding `--destructive` cannot re-colour temperature.
+* `incandescent(t)` runs from a dull ember (t = 0) to white heat (t = 1).
+*/
+const SCI = {
+	hot: "var(--sci-hot)",
+	cold: "var(--sci-cold)",
+	ember: "var(--sci-ember)",
+	whiteHot: "var(--sci-white-hot)",
+	/** The warm light of a lamp or flame, the colour an incandescent glow spreads. */
+	glow: "var(--sci-glow)",
+	incandescent: (t) => `color-mix(in oklab, var(--sci-white-hot) ${Math.round(Math.max(0, Math.min(1, t)) * 100)}%, var(--sci-ember))`
 };
 /**
 * Springs by duration and bounce (Apple WWDC23): the CSS shorthand `<duration> <easing>` for a
@@ -94,4 +145,4 @@ const MOTION = {
 };
 
 //#endregion
-export { ACCENT, MOTION, SCENE };
+export { ACCENT, HATCH, MOTION, SCENE, SCI, rampOf };

package/dist/kit/scene/vectors.mjs

@@ -3,7 +3,6 @@
 import { FigText } from "../figure/text.mjs";
 import { HUE, STROKE, alpha } from "../figure/figure.mjs";
 import { Arrow } from "../figure/beam.mjs";
-import "../figure/index.mjs";
 import { jsx, jsxs } from "react/jsx-runtime";
 
 //#region src/kit/scene/vectors.tsx

package/dist/kit/scene/workbench.d.mts

@@ -8,8 +8,8 @@ export declare function Bench({ x1, x2, y, depth }: {
   depth?: number;
 }): ReactNode;
 /**
- * Text on an object: a paper pill with ink, centred on (x, y). Width follows the text (an estimate
- * from its length), so a short "Na⁺" and a longer "AgNO₃" both sit comfortably.
+ * Text on an object: a paper pill with ink, centred on (x, y). Width follows the text (measured from
+ * the advance table, `textWidth`), so a short "Na⁺" and a longer "AgNO₃" both sit comfortably.
  */
 export declare function LabelChip({ x, y, children, width }: {
   x: number;

package/dist/kit/scene/workbench.mjs

@@ -1,9 +1,9 @@
 'use client';
 
+import { textWidth } from "../figure/text-metrics.mjs";
 import { FigText } from "../figure/text.mjs";
-import { STROKE } from "../figure/figure.mjs";
 import { SCENE } from "./tokens.mjs";
-import "../figure/index.mjs";
+import { STROKE } from "../figure/figure.mjs";
 import { jsx, jsxs } from "react/jsx-runtime";
 
 //#region src/kit/scene/workbench.tsx
@@ -30,11 +30,11 @@ function Bench({ x1, x2, y, depth = 20 }) {
 	});
 }
 /**
-* Text on an object: a paper pill with ink, centred on (x, y). Width follows the text (an estimate
-* from its length), so a short "Na⁺" and a longer "AgNO₃" both sit comfortably.
+* Text on an object: a paper pill with ink, centred on (x, y). Width follows the text (measured from
+* the advance table, `textWidth`), so a short "Na⁺" and a longer "AgNO₃" both sit comfortably.
 */
 function LabelChip({ x, y, children, width }) {
-	const w = width ?? Math.max(26, children.length * 7.4 + 14);
+	const w = width ?? Math.max(26, Math.round(textWidth(children, { role: "note" }) + 16));
 	return /* @__PURE__ */ jsxs("g", {
 		"data-part": "label",
 		children: [/* @__PURE__ */ jsx("rect", {

package/dist/kit/scene-settings.d.mts

@@ -6,7 +6,9 @@ export interface SceneSettingsProps {
   controls: readonly (BoundChoiceControl | GripNumberControl)[];
   /** Names the group; individual field names always come from their bound control. */
   label?: string;
+  /** Show concise state choices directly; select keeps dense settings compact by default. */
+  presentation?: 'auto' | 'select';
 }
 /** Quiet abstract settings, distinct from the raised keys that operate the apparatus. */
-export declare function SceneSettings({ controls, label }: SceneSettingsProps): ReactNode;
+export declare function SceneSettings({ controls, label, presentation }: SceneSettingsProps): ReactNode;
 //#endregion

package/dist/kit/scene-settings.mjs

@@ -2,34 +2,42 @@
 
 import { ActivitySelect, Slider } from "./controls.mjs";
 import { Field } from "./frame.mjs";
+import { Cluster } from "./layout.mjs";
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
 
 //#region src/kit/scene-settings.tsx
 /** Quiet abstract settings, distinct from the raised keys that operate the apparatus. */
-function SceneSettings({ controls, label }) {
+function SceneSettings({ controls, label, presentation = "select" }) {
 	const visible = controls.filter((control) => !control.hidden && !control.waiting && !("relevant" in control && control.relevant === false));
 	if (!visible.length) return null;
+	const fields = visible.map((control) => /* @__PURE__ */ jsx("div", {
+		className: "lab-scene-setting",
+		children: control.kind === "number" ? /* @__PURE__ */ jsx(Field, {
+			label: control.label,
+			value: control.valueText,
+			children: /* @__PURE__ */ jsx(Slider, { control })
+		}) : /* @__PURE__ */ jsxs(Fragment, { children: [/* @__PURE__ */ jsx("span", {
+			className: "lab-scene-setting-label",
+			children: control.label
+		}), /* @__PURE__ */ jsx(ActivitySelect, {
+			control,
+			presentation,
+			disabled: control.enabled === false
+		})] })
+	}, control.id ?? control.label));
+	if (presentation === "auto") return /* @__PURE__ */ jsx(Cluster, {
+		gap: 16,
+		role: "group",
+		"aria-label": label,
+		children: fields
+	});
 	return /* @__PURE__ */ jsx("div", {
 		className: "lab-scene-settings",
 		role: "group",
 		"aria-label": label,
 		children: /* @__PURE__ */ jsx("div", {
 			className: "lab-scene-settings-fields",
-			children: visible.map((control) => /* @__PURE__ */ jsx("div", {
-				className: "lab-scene-setting",
-				children: control.kind === "number" ? /* @__PURE__ */ jsx(Field, {
-					label: control.label,
-					value: control.valueText,
-					children: /* @__PURE__ */ jsx(Slider, { control })
-				}) : /* @__PURE__ */ jsxs(Fragment, { children: [/* @__PURE__ */ jsx("span", {
-					className: "lab-scene-setting-label",
-					children: control.label
-				}), /* @__PURE__ */ jsx(ActivitySelect, {
-					control,
-					presentation: "select",
-					disabled: control.enabled === false
-				})] })
-			}, control.id ?? control.label))
+			children: fields
 		})
 	});
 }

package/dist/kit/scenes.d.mts

@@ -23,7 +23,13 @@ export interface SceneMeta {
   label: string;
   render: QuantityScene;
 }
+/**
+ * Add the built-in scenes (declared below) once. Nothing registers at import (Labs declares only
+ * CSS as side-effectful), so every lookup and `registerScene` call runs this first.
+ */
+declare function registerBuiltinScenes(): void;
 export declare function registerScene(meta: SceneMeta): void;
 export declare function getScene(name: string): SceneMeta | undefined;
 export declare function listScenes(kind?: 'level' | 'count'): SceneMeta[];
-//#endregion
+//#endregion
+export {};

package/dist/kit/scenes.mjs

@@ -3,20 +3,32 @@
 import { FigText } from "./figure/text.mjs";
 import { Figure, HUE, STROKE, alpha, shade } from "./figure/figure.mjs";
 import { Thermometer } from "./scene/objects/thermometer.mjs";
-import "./figure/index.mjs";
 import { Vessel } from "./vessel.mjs";
 import { DotCluster } from "./cluster.mjs";
 import { jsx, jsxs } from "react/jsx-runtime";
 
 //#region src/kit/scenes.tsx
 const REGISTRY = new Map();
+let builtinScenes = false;
+/**
+* Add the built-in scenes (declared below) once. Nothing registers at import (Labs declares only
+* CSS as side-effectful), so every lookup and `registerScene` call runs this first.
+*/
+function registerBuiltinScenes() {
+	if (builtinScenes) return;
+	builtinScenes = true;
+	for (const meta of BUILTIN_SCENES) REGISTRY.set(meta.name, meta);
+}
 function registerScene(meta) {
+	registerBuiltinScenes();
 	REGISTRY.set(meta.name, meta);
 }
 function getScene(name) {
+	registerBuiltinScenes();
 	return REGISTRY.get(name);
 }
 function listScenes(kind) {
+	registerBuiltinScenes();
 	return [...REGISTRY.values()].filter((m) => !kind || m.kind === kind);
 }
 const TONE = {
@@ -117,7 +129,7 @@ function VolumeFillV({ x, y, w, h, rx, color, animate = true }) {
 		})
 	] });
 }
-registerScene({
+const vesselScene = {
 	name: "vessel",
 	kind: "level",
 	label: "Beaker",
@@ -130,8 +142,8 @@ registerScene({
 		liquidColor: q.color ?? "var(--stage-accent)",
 		label: q.label
 	})
-});
-registerScene({
+};
+const tankScene = {
 	name: "tank",
 	kind: "level",
 	label: "Tank",
@@ -211,8 +223,8 @@ registerScene({
 			]
 		});
 	}
-});
-registerScene({
+};
+const barScene = {
 	name: "bar",
 	kind: "level",
 	label: "Bar",
@@ -258,8 +270,8 @@ registerScene({
 			]
 		});
 	}
-});
-registerScene({
+};
+const batteryScene = {
 	name: "battery",
 	kind: "level",
 	label: "Battery",
@@ -314,8 +326,8 @@ registerScene({
 			]
 		});
 	}
-});
-registerScene({
+};
+const jarScene = {
 	name: "jar",
 	kind: "level",
 	label: "Money jar",
@@ -383,8 +395,8 @@ registerScene({
 			]
 		});
 	}
-});
-registerScene({
+};
+const pieScene = {
 	name: "pie",
 	kind: "level",
 	label: "Pie",
@@ -445,8 +457,8 @@ registerScene({
 			]
 		});
 	}
-});
-registerScene({
+};
+const balloonScene = {
 	name: "balloon",
 	kind: "level",
 	label: "Balloon",
@@ -503,8 +515,8 @@ registerScene({
 			]
 		});
 	}
-});
-registerScene({
+};
+const thermometerScene = {
 	name: "thermometer",
 	kind: "level",
 	label: "Thermometer",
@@ -524,8 +536,8 @@ registerScene({
 			})
 		});
 	}
-});
-registerScene({
+};
+const clusterScene = {
 	name: "cluster",
 	kind: "count",
 	label: "Crowd",
@@ -536,8 +548,8 @@ registerScene({
 		label: q.label,
 		highlightColor: q.color ?? "var(--stage-accent)"
 	})
-});
-registerScene({
+};
+const gridScene = {
 	name: "grid",
 	kind: "count",
 	label: "Grid",
@@ -585,8 +597,8 @@ registerScene({
 			children: cells
 		});
 	}
-});
-registerScene({
+};
+const coinsScene = {
 	name: "coins",
 	kind: "count",
 	label: "Coin stack",
@@ -684,8 +696,8 @@ registerScene({
 			})
 		});
 	}
-});
-registerScene({
+};
+const blocksScene = {
 	name: "blocks",
 	kind: "count",
 	label: "Blocks",
@@ -743,7 +755,22 @@ registerScene({
 			children: blocks
 		});
 	}
-});
+};
+/** Built-in scenes, in picker order. */
+const BUILTIN_SCENES = [
+	vesselScene,
+	tankScene,
+	barScene,
+	batteryScene,
+	jarScene,
+	pieScene,
+	balloonScene,
+	thermometerScene,
+	clusterScene,
+	gridScene,
+	coinsScene,
+	blocksScene
+];
 
 //#endregion
-export { getScene, listScenes, registerScene };
+export { getScene, listScenes, registerBuiltinScenes, registerScene };

package/dist/kit/shell/context.d.mts

@@ -106,7 +106,21 @@ export interface ShellContextValue {
   actions: ShellActions;
   meta: ShellMeta;
 }
-declare const ShellContext: import("react").Context<ShellContextValue | null>;
+declare const ShellMetaContext: import("react").Context<ShellMeta | null>;
+declare const ShellActionsContext: import("react").Context<ShellActions | null>;
+declare const ShellStateContext: import("react").Context<ShellState | null>;
+declare const ShellVerdictContext: import("react").Context<ShellVerdict | undefined>;
+declare const ShellSpotlightContext: import("react").Context<string | undefined>;
+export declare function useShellMeta(): ShellMeta;
+export declare function useShellActions(): ShellActions;
+export declare function useShellState(): ShellState;
+/** The checked verdict of the current answer; undefined before Check, on a fresh try, outside a lab. */
+export declare function useShellVerdict(): ShellVerdict | undefined;
+/**
+ * All three lanes, for a shell part that needs the answer draft, the actions and the step together
+ * (the choice cards, the Check button). It re-renders on every keystroke: anything that does not
+ * read the draft uses a narrower hook. tests/policy/shell-context-lanes.test.ts keeps it in the shell.
+ */
 export declare function useShell(): ShellContextValue;
 /** For a lab's scene: is the note pointing at this piece of evidence right now? */
 export declare function useSpotlight(id: string): boolean;