@weasel-js/labkit 1.4.4 → 1.5.0

package/README.md

@@ -36,7 +36,7 @@ Annotations are on the `pre` tag until the next stable release:
 ## A lab
 
 ```tsx
-import { type ConfigOf, defineInstrument, f, Lab, localStorageAdapter } from '@weasel-js/labkit';
+import { type ConfigOf, defineInstrument, f, Lab } from '@weasel-js/labkit';
 import '@weasel-js/labkit/styles.css';
 
 const config = f.schema({
@@ -64,13 +64,24 @@ export function App() {
       instruments={[Histogram]}
       defaultInstrument="Histogram"
       title="Histogram"
-      storage={localStorageAdapter}
       storageKey="histogram-lab"
     />
   );
 }
 ```
 
+`storageKey` makes the lab persist: its trials, snapshots, layout and mode
+survive a reload and stay in step across tabs. It persists to IndexedDB — or
+localStorage, with a warning, where IndexedDB will not open — and `storage`
+names another substrate: `localStorageAdapter`, `sessionStorageAdapter`,
+`urlHashAdapter`, or your own `StorageAdapter` over a server. The lab renders
+`fallback` while it loads. Leave `storageKey` off and nothing persists.
+
+A widget's own state persists the same way through `usePersistedState(name,
+initial)`, which is `useState` whose value survives a reload — kept per trial
+inside one, and plain `useState` wherever no `<Lab>` or `<Persistence>` is
+above it.
+
 `f.schema` states the config once — values, types and controls — and the trial
 renders the settings panel from it. `render` returns the instrument's own DOM;
 returning `null` alongside `canvas` means the canvas layers are the whole

package/dist/_dts/{CanvasStackContext-kTEZvEgE.d.ts → CanvasStackContext-CqkxkFJW.d.ts}

@@ -1,6 +1,6 @@
 import * as react from 'react';
 import { RefObject } from 'react';
-import { V as ViewTransform, W as WorldFrame } from './frac-z7ker2Vx.js';
+import { k as ViewTransform, W as WorldFrame } from './frac-8R6UmlvN.js';
 
 /** One layer of a canvas stack: its id, whether it is currently shown, and how
  *  it paints itself. */

package/dist/_dts/ToggleBar.d-DbHoWKIA.d.ts

@@ -0,0 +1,116 @@
+import * as react from 'react';
+import { ReactNode, ButtonHTMLAttributes, ReactElement } from 'react';
+
+/** Visual weight of a button. Defaults to `secondary`. */
+type ButtonVariant = 'primary' | 'secondary' | 'ghost';
+/** Button height and type scale. */
+type ButtonSize = 'sm' | 'md';
+type ButtonBase = {
+    variant?: ButtonVariant;
+    size?: ButtonSize;
+    /** A button that stays down: renders `aria-pressed` and holds the active
+     *  treatment while it is on. For a control that reports a state rather than
+     *  firing an action -- a panel toggle, a mode switch. Left off, the button
+     *  announces no pressed state at all, which is what an action button wants. */
+    pressed?: boolean;
+    disabled?: boolean;
+    loading?: boolean;
+    leadingIcon?: ReactNode;
+    trailingIcon?: ReactNode;
+    fullWidth?: boolean;
+    type?: 'button' | 'submit' | 'reset';
+    className?: string;
+    style?: ButtonHTMLAttributes<HTMLButtonElement>['style'];
+    children?: ReactNode;
+    onClick?: ButtonHTMLAttributes<HTMLButtonElement>['onClick'];
+};
+type ButtonRegular = ButtonBase & {
+    iconOnly?: false;
+    ariaLabel?: string;
+};
+type ButtonIconOnly = ButtonBase & {
+    iconOnly: true;
+    ariaLabel: string;
+};
+/**
+ * Props for {@link Button}. Setting `iconOnly` makes `ariaLabel` required,
+ * since an icon-only button has no text for a screen reader to announce.
+ */
+type ButtonProps = ButtonRegular | ButtonIconOnly;
+/**
+ * Standard button. `loading` swaps the leading icon for a spinner, marks the
+ * button `aria-busy`, and leaves the label in place; it does not disable the
+ * button, so pass `disabled` too if the click should be blocked.
+ *
+ * `ref` forwards to the underlying `<button>`.
+ */
+declare const Button: react.ForwardRefExoticComponent<ButtonProps & react.RefAttributes<HTMLButtonElement>>;
+
+/** One segment of a {@link ToggleBar}, identified by its `value`. */
+type ToggleBarItem<V extends string | number = string> = {
+    value: V;
+    label?: ReactNode;
+    ariaLabel?: string;
+    disabled?: boolean;
+};
+/** Segment height and type scale for a {@link ToggleBar}. */
+type ToggleBarSize = 'sm' | 'md';
+/** Visual treatment of a {@link ToggleBar}. */
+type ToggleBarVariant = 'default' | 'minimal' | 'flat';
+type CommonProps = {
+    ariaLabel?: string;
+    className?: string;
+    height?: number;
+    /** Size variant. `sm` is ~60% of the default height with reduced padding
+     *  and font size — sized for dense surfaces like lab control panels. */
+    size?: ToggleBarSize;
+    /** Visual variant. `minimal` strips the pill track and glass treatment;
+     *  selection becomes a flat accent. For dense diagnostic surfaces. */
+    variant?: ToggleBarVariant;
+};
+/**
+ * Props for {@link ToggleBar}, discriminated on `mode`. Single mode is
+ * controlled by one value or `null`; multiple mode by an array, and only it
+ * accepts `mixedValues`.
+ */
+type ToggleBarProps<V extends string | number = string> = (CommonProps & {
+    mode?: 'single';
+    items: readonly ToggleBarItem<V>[];
+    value: V | null;
+    onChange: (next: V | null) => void;
+    allowDeselect?: boolean;
+}) | (CommonProps & {
+    mode: 'multiple';
+    items: readonly ToggleBarItem<V>[];
+    value: readonly V[];
+    /**
+     * Values that are neither on nor off — the sources this bar
+     * aggregates disagree (a text range that is bold in part of it, a
+     * multi-selection whose nodes differ). Rendered `aria-pressed="mixed"`,
+     * the ARIA tri-state a toggle button actually has, rather than
+     * `SelectionPanel`'s reduced-opacity-plus-`title` workaround for
+     * `Switch`, which has no indeterminate state to render.
+     *
+     * `value` wins where the two lists overlap, so a caller that can't
+     * cheaply keep them disjoint doesn't get an ambiguous segment.
+     *
+     * Clicking a mixed segment turns it fully **on**, matching the
+     * everywhere-else convention (and `toggleFlagInRange`'s rule for a
+     * partially-styled text range) that a mixed toggle resolves toward
+     * the affirmative rather than clearing.
+     */
+    mixedValues?: readonly V[];
+    onChange: (next: V[]) => void;
+});
+/**
+ * Segmented control for choosing among a fixed set of values — one of them
+ * (`mode: 'single'`, the default) or any number (`mode: 'multiple'`).
+ *
+ * Single mode ignores a click on the already-selected segment unless
+ * `allowDeselect` is set. Arrow keys move focus without changing the value;
+ * Space and Enter commit.
+ */
+declare function ToggleBar<V extends string | number = string>(props: ToggleBarProps<V>): ReactElement;
+
+export { Button as B, ToggleBar as T };
+export type { ButtonProps as a, ButtonSize as b, ButtonVariant as c, ToggleBarItem as d, ToggleBarProps as e, ToggleBarSize as f, ToggleBarVariant as g };

package/dist/_dts/{frac-z7ker2Vx.d.ts → frac-8R6UmlvN.d.ts}

@@ -1,7 +1,5 @@
 import { ComponentType, ReactNode, RefObject } from 'react';
-import { R as ResolvedConfig, a as ConfigSchema, C as ConfigPath } from './types-B9_zrHmb.js';
-import { C as ConfigField } from './types-x92Kfeme.js';
-import { c as SavedSnapshot, i as TrialInfo } from './types-BP2OCcpg.js';
+import { C as ConfigPath, V as ValueAtPath, R as ResolvedConfig, a as ConfigField, b as ConfigSchema } from './types-Ca2LCnPq.js';
 import { J as JobHandle, a as JobCapability } from './types-DJ79Tg5J.js';
 import { Scene } from '@weasel-js/core';
 
@@ -33,15 +31,188 @@ declare function resolveFrame(spec: WorldSpec | undefined, size: ViewportSize):
  *  `draw` works in them. Must stay the exact inverse of `screenToWorld`. */
 declare function applyCamera(ctx: CanvasRenderingContext2D, view: ViewTransform, frame?: WorldFrame): void;
 
+/** A sidebar section torn out of its trial, and where it went. */
+interface UndockedPanel {
+    trialId: string;
+    sectionId: string;
+    as: 'tile' | 'floating';
+}
+/** Undocked panels, keyed by {@link panelKey}. */
+type UndockedPanels = Record<string, UndockedPanel>;
+declare function panelKey(trialId: string, sectionId: string): string;
+declare function undockPanel(panels: UndockedPanels, trialId: string, sectionId: string, as?: UndockedPanel['as']): UndockedPanels;
+/** Dock one section back, or — with no `sectionId` — every panel the trial
+ *  owns, which is what closing a trial wants. */
+declare function dockPanel(panels: UndockedPanels, trialId: string, sectionId?: string): UndockedPanels;
+
+/** A trial's undo history, as snapshots of its state either side of the
+ *  present. */
+interface UndoStack {
+    past: unknown[];
+    future: unknown[];
+}
+/** The trial a per-trial call is coming from. `id` is the id `useTileId`
+ *  scopes a surface tile under, so a consumer keying its own per-trial
+ *  registry and labkit's tiles agree on the key. */
+interface TrialInfo<TV = unknown> {
+    id: string;
+    /** The trial's view, in whatever shape the instrument keeps it. */
+    view: TV;
+}
+/** One trial as the store holds it: which instrument it runs, that
+ *  instrument's config and state, the camera, and the undo history. */
+interface TrialRecord<TS = unknown, TC = unknown, TV = unknown> {
+    id: string;
+    instrumentName: string;
+    config: TC;
+    state: TS;
+    /** Opaque to labkit: persisted, restored on Reset and handed to the instrument,
+     *  but never read into. A 3D lab puts an orbit here and keeps all three. */
+    view: TV;
+    /** The config `addTrial` opened this trial on, overlaid on the instrument's
+     *  defaults. Kept so Reset restores the trial's own subject rather than the
+     *  bare defaults. */
+    configSeed?: Partial<TC>;
+    /** This trial's own tool slot. Undefined means it reads the lab's. */
+    activeToolId?: string | null;
+    /** The extent the trial's sidebar was last dragged to, in pixels. Undefined
+     *  until someone moves the seam. */
+    sidebarWidth?: number;
+    /** What the title bar reads. Undefined — the state a trial opens in, and the
+     *  one `setTitle(null)` returns it to — means the instrument's name. */
+    title?: string | null;
+    /** Which of the trial's collapsible sections are folded, keyed as
+     *  `TrialChromeContext.collapsedSections` describes. A key that is absent
+     *  takes the section's own default. */
+    collapsedSections?: Record<string, boolean>;
+    /** The marks on this trial's annotation targets, as `AnnotationsApi.toJSON`
+     *  wrote them. Opaque here, and absent for a trial whose instrument declares
+     *  no `annotations` — or declares its own `storage`. Not in `state`, which
+     *  belongs to the instrument and is typed as such. */
+    annotations?: unknown;
+    undoStack: UndoStack;
+}
+/** A named, saved copy of a trial's config and state, restorable into any
+ *  trial running the same instrument. */
+interface SavedSnapshot {
+    id: string;
+    name: string;
+    trialId: string;
+    instrumentName: string;
+    config: unknown;
+    state: unknown;
+    savedAt: number;
+}
+/** `auto` follows the OS; the other two are an explicit choice. */
+type LabMode = 'auto' | 'light' | 'dark';
+/** Everything a lab persists: its trials, its saved snapshots, and the
+ *  chosen color mode. */
+interface LabStoreState {
+    trials: TrialRecord[];
+    savedSnapshots: SavedSnapshot[];
+    mode: LabMode;
+    /** The lab's tool slot — what a trial with no slot of its own resolves to. */
+    activeToolId: string | null;
+    /** Per-trial tile extents, keyed by trial id. Opaque here — the
+     *  shape belongs to whatever lays the trials out. */
+    layout: Record<string, unknown>;
+    /** Sidebar sections torn out of their trial. A panel here is not rendered in
+     *  its trial's sidebar; the workspace renders it instead. */
+    undockedPanels: UndockedPanels;
+    /** The instruments this store serializes, migrates and fills configs for.
+     *  Null for a store built without them, whose trials look their instrument
+     *  up on the lab instead. Not persisted. */
+    instruments: InstrumentList | null;
+}
+/** A change someone else made to one record: its new value, or `undefined`
+ *  when it was deleted. */
+type StorageChange = [key: string, value: unknown];
+/** Where a lab persists itself: asynchronous keyed storage of
+ *  structured-clone values, so IndexedDB, the URL, memory or a server can all
+ *  back one. */
+interface StorageAdapter {
+    /** `undefined` when the key is absent. */
+    get(key: string): Promise<unknown>;
+    list(prefix: string): Promise<[string, unknown][]>;
+    /** Rejects when the value did not land. */
+    set(key: string, value: unknown): Promise<void>;
+    delete(key: string): Promise<void>;
+    /** Reports writes under `prefix` made by anyone but this adapter — another
+     *  tab, another instance, a server. Omit when the substrate cannot tell. */
+    subscribe?(prefix: string, on: (changes: StorageChange[]) => void): () => void;
+}
+/** What `useTrialState` hands an instrument: its state and config, with
+ *  a setter for each. */
+interface TrialStateHandle<TS, TC> {
+    state: TS;
+    setState: (next: TS | ((prev: TS) => TS)) => void;
+    config: TC;
+    /** Write one config value, by dotted path — `'grid.size'` for a leaf under
+     *  an `f.group`, `'cellSize'` for one at the root. */
+    setConfig: <P extends ConfigPath<TC> & string>(path: P, value: ValueAtPath<TC, P>) => void;
+}
+/** Options for `createLabStore`, which knows nothing about storage. */
+interface CreateLabStoreOptions {
+    /** A document already read and migrated — what `openLabStore` hands over. */
+    initial?: LabDocument;
+    initialMode?: LabMode;
+    /** Each instrument's default config, keyed by instrument name, used to fill
+     *  the gaps in a stored one. A config saved before its schema grew a branch
+     *  arrives holding that branch's defaults rather than `undefined`, and keeps
+     *  whatever keys the schema has since stopped naming. */
+    configDefaults?: Record<string, () => unknown>;
+    /** Each instrument's `migrateConfig`, keyed by instrument name, run on a
+     *  stored config before its defaults fill it. */
+    configMigrations?: Record<string, (stored: unknown) => unknown>;
+    /** How each instrument's state survives a reload. Hydration is the first
+     *  thing `createLabStore` does, so these have to arrive with the store. */
+    serializers?: InstrumentSerializers;
+    /** The instruments to serialize, migrate and fill configs for. Given, it
+     *  supplies all three and the three fields above are ignored. */
+    instruments?: InstrumentList;
+}
+/** What a store does per instrument on the way in and out. */
+interface InstrumentHooks {
+    serializers: InstrumentSerializers;
+    configDefaults: Record<string, () => unknown>;
+    configMigrations: Record<string, (stored: unknown) => unknown>;
+}
+/** Per-instrument serialize/deserialize hooks, keyed by instrument name. An
+ *  instrument whose state is already JSON-safe needs no entry. `deserialize`
+ *  is handed the config the state was saved against — a trial's own for a
+ *  reload, the snapshot's for a load — since a state rebuilt without it can
+ *  disagree with the settings sitting next to it. */
+type InstrumentSerializers = Record<string, {
+    serialize?: (state: unknown) => unknown;
+    deserialize?: (data: unknown, config: unknown) => unknown;
+} | undefined>;
+/** A trial as it is persisted: everything but the undo history, which is
+ *  session-only. */
+type SerializedTrial = Omit<TrialRecord, 'undoStack'>;
+/** Everything a lab persists, under one key, at a known version. */
+interface LabDocument {
+    version: number;
+    trials: SerializedTrial[];
+    saves: SavedSnapshot[];
+    layout: Record<string, unknown>;
+    /** Sidebar sections torn out of their trial, keyed by trial and section. */
+    undockedPanels: UndockedPanels;
+    mode: LabMode;
+}
+/** Migrates a document one version forward. Index `i` in the chain takes a
+ *  version-`i` document to version `i + 1`. */
+type Migration = (doc: Record<string, unknown>) => Record<string, unknown>;
+
 /** A named position in a trial's chrome. Content is not a region — that is
- *  the instrument. */
+ *  the instrument. The lab's own boxes are named in `LabRegion`. */
 type TrialRegion = 'titlebar' | 'toolbar' | 'palette' | 'sidebar' | 'viewport' | 'status';
 /** An icon component taking a pixel size, as `@weasel-js/ui` glyphs do. */
 type IconComponent = ComponentType<{
     size?: number;
 }>;
-/** A button in the trial toolbar. */
-interface ToolbarItem {
+/** A button in a toolbar. `TCtx` is the chrome context its `onActivate` is
+ *  handed — a trial's, or the lab's for a lab-level bar. */
+interface ToolbarItem<TCtx = TrialChromeContext> {
     icon: IconComponent;
     label: string;
     /** Shown in the tooltip. Not bound here — the trial owns its keymap. */
@@ -54,10 +225,10 @@ interface ToolbarItem {
     pressed?: boolean;
     /** Render the label beside the glyph rather than only in the tooltip. */
     showLabel?: boolean;
-    /** Handed the trial's chrome context, so a contribution declared from the
-     *  lab can reach `ctx.saveSnapshot()` and the rest without the `render`
-     *  escape. A zero-argument handler stays valid. */
-    onActivate: (ctx: TrialChromeContext) => void;
+    /** Handed the chrome context it was declared against, so a contribution can
+     *  reach `ctx.saveSnapshot()` and the rest without the `render` escape. A
+     *  zero-argument handler stays valid. */
+    onActivate: (ctx: TCtx) => void;
 }
 /** A selectable tool in the palette region. */
 interface ToolItem {
@@ -79,12 +250,12 @@ interface SidebarSection {
     body: ReactNode;
 }
 /** A control acting on the view of the trial, not on the trial. */
-interface ViewportControl {
+interface ViewportControl<TCtx = TrialChromeContext> {
     icon: IconComponent;
     label: string;
     disabled?: boolean;
     /** Handed the trial's chrome context, as `ToolbarItem.onActivate` is. */
-    onActivate: (ctx: TrialChromeContext) => void;
+    onActivate: (ctx: TCtx) => void;
 }
 /** A readout in the status bar. */
 interface StatusReadout {
@@ -93,7 +264,7 @@ interface StatusReadout {
     /** Tooltip. */
     title?: string;
 }
-/** What every contribution shares. */
+/** What every contribution shares, whichever chrome it is declared against. */
 interface ContributionBase {
     id: string;
     /** Groups sort by first appearance; items sort within a group by
@@ -136,18 +307,46 @@ type TrialContribution = (ContributionBase & {
     item?: never;
     render: (ctx: TrialChromeContext) => ReactNode;
 });
+/**
+ * A tool slot a region can reflect and write. Both chrome contexts carry one:
+ * a trial's resolves to the lab's when its instrument declares no tools.
+ */
+interface ToolSlotContext {
+    activeToolId: string | null;
+    setActiveTool: (id: string) => void;
+}
+/** What a sidebar region reflects and writes: which sections are folded, and —
+ *  where the chrome can tear a section out — where it goes. A trial supplies
+ *  all four; a lab supplies the fold state only. */
+interface SidebarSlotContext {
+    collapsedSections: Readonly<Record<string, boolean>>;
+    setSectionCollapsed: (key: string, collapsed: boolean) => void;
+    undockedPanels?: readonly string[];
+    undockPanel?: (sectionId: string, as?: 'tile' | 'floating') => void;
+}
+/**
+ * A contribution as a region renderer sees it. A renderer checks the region
+ * name against its own and narrows `item` itself, which is what lets one
+ * renderer serve both chromes — the trial's and the lab's — without knowing
+ * which context it was handed.
+ */
+interface RegionContribution<TCtx> extends ContributionBase {
+    region: string;
+    item?: unknown;
+    render?: (ctx: TCtx) => ReactNode;
+}
 /**
  * Everything a contribution can read about the trial it is being rendered
  * into. Replaces the three separate slot contexts, which each carried a
  * hand-picked subset.
  */
-interface TrialChromeContext {
+interface TrialChromeContext extends ToolSlotContext, SidebarSlotContext {
     trialId: string;
     instrumentName: string;
-    /** What the title bar reads, which is the instrument's name until something
-     *  calls `setTitle`. */
+    /** What the title bar reads, which is the instrument's title (or, lacking
+     *  one, its name) until something calls `setTitle`. */
     title: string;
-    /** Retitle this trial; `null` restores the instrument name. Persisted with
+    /** Retitle this trial; `null` restores the instrument's title. Persisted with
      *  the trial, so a title survives a reload. */
     setTitle: (title: string | null) => void;
     isLastTrial: boolean;
@@ -189,10 +388,6 @@ interface TrialChromeContext {
     clone: () => void;
     reset: () => void;
     close: () => void;
-    /** Resolved active tool: the trial's slot, or the lab's when the trial has
-     *  none. Null when neither holds one. */
-    activeToolId: string | null;
-    setActiveTool: (id: string) => void;
 }
 
 /** A point on the magnified surface, in its own CSS pixels. */
@@ -245,7 +440,7 @@ interface LoupeCapability<TS = unknown, TC = unknown> {
     /** Held for a momentary peek while the loupe is off. Default `'Alt'`; `null`
      *  turns hold-to-peek off. Matched against `KeyboardEvent.key`. */
     peekKey?: string | null;
-    /** Called with the colour under the aim, wherever the surface can say. The
+    /** Called with the color under the aim, wherever the surface can say. The
      *  canvas painter reads it back; a DOM loupe has no pixels to sample. */
     onColorChange?: (hex: string) => void;
 }
@@ -353,6 +548,18 @@ interface CanvasCapability<TS = unknown, TC = unknown> {
     minZoom?: number;
     maxZoom?: number;
 }
+/** Declares that an instrument's DOM is content of a fixed size, which the
+ *  trial pans and zooms the way it does a canvas's layers. Not combined with
+ *  `canvas`: there the DOM is an unzoomed overlay, and `canvas` wins. */
+interface StageCapability {
+    /** The content's own size in CSS pixels, at zoom 1. */
+    size: ViewportSize;
+    /** Where the view starts. Omitted, the content opens centered and shrunk to
+     *  fit (`fitStage`). A function is called once the stage knows its size. */
+    initialView?: ViewTransform | ((viewport: ViewportSize) => ViewTransform);
+    minZoom?: number;
+    maxZoom?: number;
+}
 /** Declares which of an instrument's layers the trial should offer
  *  show/hide controls for. */
 interface LayerCapability {
@@ -391,7 +598,8 @@ type HitResult = {
     layerId?: string;
     pointId?: string;
 };
-/** A trial's camera. */
+/** A trial's camera. `zoom` is always positive and finite once labkit holds
+ *  it — see `normalize2DView`. */
 type ViewTransform = {
     zoom: number;
     pan: Point;
@@ -424,7 +632,10 @@ type DragFeedback = {
  * is what makes the trial provide the corresponding chrome.
  */
 interface Instrument<TS = unknown, TC = unknown, TItem = unknown> {
+    /** The id a trial record names its instrument by. */
     name: string;
+    /** What a trial of this instrument and the add-trial menu read. Default: `name`. */
+    title?: string;
     defaultConfig: () => TC;
     initialState: (config: TC) => TS;
     /** The instrument's config, declared once: values, types and controls.
@@ -438,9 +649,16 @@ interface Instrument<TS = unknown, TC = unknown, TItem = unknown> {
      *  layers rather than instead of them; return `null` for canvas only. */
     render: (ctx: RenderContext<TS, TC>) => ReactNode;
     onConfigChange?: (config: TC, prev: TC, state: TS) => TS;
+    /** Moves a stored config's values to where the current schema keeps them —
+     *  `gridSize` to `grid.size` — before the defaults fill its gaps, so it
+     *  returns only what it moved and leaves the rest to them. It runs on every
+     *  read of a stored config, including one already moved, so it must hand
+     *  back a current config unchanged. */
+    migrateConfig?: (stored: unknown) => unknown;
     serialize?: (state: TS) => unknown;
     deserialize?: (data: unknown, config: TC) => TS;
     canvas?: CanvasCapability<TS, TC>;
+    stage?: StageCapability;
     layers?: LayerCapability;
     dragDrop?: DragDropCapability<TS, TC>;
     undo?: UndoCapability;
@@ -479,9 +697,10 @@ interface AnnotationStoreOptions {
     targets: () => readonly AnnotationTargetInfo[];
     /** Serialized scenes from a previous `toJSON`, keyed by target. */
     restore?: Readonly<Record<string, unknown>>;
-    /** The instrument's vocabulary, so an export draws a mark in the colour its
-     *  status gives it. */
-    meaning?: AnnotationMeaning;
+    /** The instrument's vocabulary, so an export draws a mark in the color its
+     *  status gives it. A thunk is read at each capture, for a vocabulary that
+     *  changes under a store built once. */
+    meaning?: AnnotationMeaning | (() => AnnotationMeaning | undefined);
     /** The trial's live config. A getter for the same reason `targets` is: the
      *  store is built once and the config changes under it. */
     config?: () => unknown;
@@ -535,7 +754,7 @@ interface AnnotationStatus {
     id: string;
     label: string;
     /** What a mark in this status is drawn in. Omitted, it takes the default
-     *  mark colour — a status is allowed to be a label and nothing more. */
+     *  mark color — a status is allowed to be a label and nothing more. */
     color?: string;
 }
 /** The optional meaning tier: what a mark means, as opposed to where it is.
@@ -651,9 +870,10 @@ interface AnnotationTarget extends AnnotationTargetInfo {
 /** Where an instrument keeps its own marks. Declaring this means labkit never
  *  writes its trial slot — for an instrument whose marks belong in a format it
  *  already owns. Both halves are called outside React; `save` is already
- *  debounced by the time it arrives. */
+ *  debounced by the time it arrives. A trial shows an empty body until `load`
+ *  settles. */
 interface AnnotationStorage {
-    load: () => SerializedAnnotations | null | undefined;
+    load: () => Promise<SerializedAnnotations | null | undefined>;
     save: (doc: SerializedAnnotations) => void;
 }
 /** Declares that an instrument accepts marks: which regions take them,
@@ -663,6 +883,8 @@ interface AnnotationsCapability<TS = unknown, TC = unknown> {
      *  is called once per trial, and its targets are that trial's own. */
     targets: (state: TS, config: TC, trial: TrialInfo) => readonly AnnotationTarget[];
     meaning?: AnnotationMeaning;
+    /** An instrument replacing this one under a live trial must pass the same
+     *  object: the trial keeps the marks it loaded from the first. */
     storage?: AnnotationStorage;
     /** Fires after every finished export, labkit's own chrome included. A
      *  notification, not an interception: a host wanting its own flow calls
@@ -758,5 +980,5 @@ declare function fracContains(box: FracRect, pt: FracPoint, tol?: number): boole
  *  answers false for two rects that merely overlap. */
 declare function fracEncloses(outer: FracRect, inner: FracRect): boolean;
 
-export { LOUPE_DEFAULTS as L, annotationsFromJSON as a3, applyCamera as a4, createAnnotationScene as a5, createAnnotationStore as a6, fracContains as a7, fracEncloses as a8, fracToWorld as a9, resolveFrame as aa, resolveLoupe as ab, roundFrac as ac, worldToFrac as ad, DEFAULT_FRAME as x };
-export type { TrialRegion as $, AnnotationData as A, LayerCapability as B, CaptureSource as C, DragFeedback as D, LayerDescriptor as E, FracPoint as F, LoupeCapability as G, HitResult as H, Instrument as I, LoupeDeclaration as J, LoupeRenderArgs as K, MarkScene as M, ResolvedLoupe as N, SidebarSection as O, PaletteItem as P, StatusReadout as Q, RenderContext as R, SerializedAnnotations as S, TrialTool as T, SystemEvent as U, ViewTransform as V, WorldFrame as W, ToolCapability as X, ToolItem as Y, ToolbarItem as Z, TrialChromeContext as _, Point as a, UndoCapability as a0, ViewportControl as a1, ViewportSize as a2, LoupePoint as ae, LoupeMode as af, DragDropCapability as b, WorldSpec as c, WorldRect as d, AnnotationMeaning as e, CaptureOptions as f, CaptureResult as g, AnnotationTarget as h, AnnotationsApi as i, AnnotationsCapability as j, AnnotationKind as k, InstrumentList as l, TrialContribution as m, Annotation as n, AnnotationInit as o, AnnotationPatch as p, AnnotationQuery as q, AnnotationStatus as r, AnnotationStoreOptions as s, AnnotationTargetInfo as t, CanvasCapability as u, CanvasLayer as v, CaptureDeps as w, FracRect as y, IconComponent as z };
+export { DEFAULT_FRAME as D, LOUPE_DEFAULTS as a7, resolveLoupe as aA, roundFrac as aB, worldToFrac as aC, annotationsFromJSON as au, createAnnotationScene as av, createAnnotationStore as aw, fracContains as ax, fracEncloses as ay, fracToWorld as az, applyCamera as b, dockPanel as j, panelKey as p, resolveFrame as r, undockPanel as u };
+export type { CanvasCapability as $, AnnotationData as A, AnnotationTarget as B, CreateLabStoreOptions as C, AnnotationsApi as E, AnnotationsCapability as F, TrialInfo as G, TrialTool as H, InstrumentSerializers as I, AnnotationKind as J, Instrument as K, LabDocument as L, Migration as M, TrialContribution as N, Annotation as O, PaletteItem as P, AnnotationInit as Q, AnnotationPatch as R, SerializedTrial as S, TrialRecord as T, UndoStack as U, ViewportSize as V, WorldFrame as W, AnnotationQuery as X, AnnotationStatus as Y, AnnotationStoreOptions as Z, AnnotationTargetInfo as _, WorldSpec as a, CanvasLayer as a0, CaptureDeps as a1, ContributionBase as a2, FracPoint as a3, FracRect as a4, HitResult as a5, IconComponent as a6, LayerCapability as a8, LayerDescriptor as a9, LoupePoint as aD, LoupeMode as aE, LoupeCapability as aa, LoupeDeclaration as ab, LoupeRenderArgs as ac, RegionContribution as ad, RenderContext as ae, ResolvedLoupe as af, SerializedAnnotations as ag, SidebarSection as ah, SidebarSlotContext as ai, StageCapability as aj, StatusReadout as ak, SystemEvent as al, ToolCapability as am, ToolItem as an, ToolSlotContext as ao, ToolbarItem as ap, TrialChromeContext as aq, TrialRegion as ar, UndoCapability as as, ViewportControl as at, StorageAdapter as c, LabStoreState as d, SavedSnapshot as e, StorageChange as f, TrialStateHandle as g, UndockedPanel as h, UndockedPanels as i, ViewTransform as k, Point as l, DragFeedback as m, DragDropCapability as n, LabMode as o, InstrumentList as q, InstrumentHooks as s, WorldRect as t, AnnotationMeaning as v, MarkScene as w, CaptureSource as x, CaptureOptions as y, CaptureResult as z };