@weasel-js/labkit 1.1.0 → 1.3.0-pre.0

package/dist/_dts/PrefsForm-BYa6cWnO.d.ts

@@ -0,0 +1,201 @@
+import { ReactNode } from 'react';
+
+/** The value types a built-in pref leaf can hold. */
+type ToolPrefKind = 'number' | 'boolean' | 'string' | 'enum' | 'color' | 'paint' | 'object';
+interface ToolPrefBase<K extends string, Value> {
+    kind: K;
+    /** Human-readable label. */
+    name: string;
+    /** Longer help text — shown in tooltips / a settings pane. */
+    description: string;
+    /** Fallback when nothing is persisted. */
+    default: Value;
+    /** Hide from a host app's settings UI by default. */
+    hidden?: boolean;
+    /** Render full-width with no label row in schema-driven settings UIs
+     *  (weasel-ui `PrefsForm` honors this for leaves whose control brings
+     *  its own chrome). */
+    block?: boolean;
+    /** Glyph naming this leaf in a host UI's icon set (weasel-ui resolves it
+     *  against `ICON_PATHS`). A plain string because core ships no icon set and
+     *  cannot depend on one. Read where a leaf's `name` has nowhere to go — a
+     *  `pair`ed row is labeled by the pair, so its fields have only the glyph
+     *  to tell them apart. */
+    icon?: string;
+    /** Row-pairing hint for compact property UIs (weasel-ui
+     *  `SelectionPanel`): leaves sharing a `pair` id render side-by-side
+     *  on one row labeled with the `pair` string (e.g. `'Position'` for
+     *  `pose.x` / `pose.y`). Purely presentational. */
+    pair?: string;
+}
+/** How a schema-driven UI should present a number pref. */
+type ToolPrefNumberControl = 'input' | 'slider';
+/** How a schema-driven UI should present a boolean pref. */
+type ToolPrefBooleanControl = 'checkbox' | 'switch';
+/** How a schema-driven UI should present a string pref. */
+type ToolPrefStringControl = 'input' | 'textarea';
+/** How a schema-driven UI should present an enum pref. */
+type ToolPrefEnumControl = 'select' | 'radio' | 'toggle';
+/** Display-unit conversion for number leaves whose stored value uses a
+ *  canonical unit the user shouldn't see (e.g. radians stored, degrees
+ *  shown). The stored value stays canonical; UIs convert at the edge. */
+interface ToolPrefNumberUnit {
+    toDisplay: (stored: number) => number;
+    fromDisplay: (display: number) => number;
+    /** Shown after the input, e.g. `'°'`. */
+    suffix?: string;
+}
+/** A numeric pref, optionally bounded and stepped, and optionally stored in a
+ *  different unit from the one shown. */
+interface ToolPrefNumber extends ToolPrefBase<'number', number> {
+    min?: number;
+    max?: number;
+    step?: number;
+    control?: ToolPrefNumberControl;
+    unit?: ToolPrefNumberUnit;
+}
+/** An on/off pref. */
+interface ToolPrefBoolean extends ToolPrefBase<'boolean', boolean> {
+    control?: ToolPrefBooleanControl;
+}
+/** A free-text pref. */
+interface ToolPrefString extends ToolPrefBase<'string', string> {
+    control?: ToolPrefStringControl;
+}
+/**
+ * Stored-value bridge for an enum leaf whose value is not the option string —
+ * the counterpart of {@link ToolPrefNumberUnit}, which does the same for a
+ * number stored in a canonical unit.
+ *
+ * A dash array is the case that needs it: `Stroke.dash` stores lengths, and
+ * the thing a person chooses is a style. The presets scale by the stroke's
+ * width, so both directions are given the object's other fields — a style is
+ * meaningless without the width it is a multiple of.
+ */
+interface ToolPrefEnumEncoding<T extends string = string> {
+    /**
+     * The option `stored` reads as, or `undefined` for none — which a UI shows
+     * the way it shows a mixed selection, by selecting nothing.
+     *
+     * `siblings` is the object the leaf is a field of, or `undefined` when the
+     * node does not hold that object (and for a top-level leaf, which has none).
+     */
+    read: (stored: unknown, siblings: Record<string, unknown> | undefined) => T | undefined;
+    /** What to store for `option`. `undefined` removes the field. */
+    write: (option: T, siblings: Record<string, unknown> | undefined) => unknown;
+}
+/** A pref with a fixed set of labeled choices. */
+interface ToolPrefEnum<T extends string = string> extends ToolPrefBase<'enum', T> {
+    /** `short` is the label a segmented control uses when a full one would not
+     *  fit — a capital or two. `icon` names a glyph in the host UI's set
+     *  (weasel-ui resolves it against `ICON_PATHS`) and outranks `short` where
+     *  it resolves. It is a plain string because core ships no icon set and
+     *  cannot depend on one. The full `label` stays the accessible name, so
+     *  neither the abbreviation nor the glyph becomes the only thing naming
+     *  the option.
+     *
+     *  `disabled` marks an option a control reports but cannot author — the
+     *  value a stored form reads as when it matches nothing offered. Dropping it
+     *  from the list instead would leave the control selecting nothing and
+     *  claiming the field is unset. */
+    options: readonly {
+        value: T;
+        label: string;
+        short?: string;
+        icon?: string;
+        disabled?: boolean;
+    }[];
+    control?: ToolPrefEnumControl;
+    encoding?: ToolPrefEnumEncoding<T>;
+}
+/** A single color, stored as a hex string. For a value that may also be a
+ *  gradient or a pattern, use {@link ToolPrefPaint} instead. */
+interface ToolPrefColor extends ToolPrefBase<'color', string> {
+    /** Value is `#rrggbb`, or `#rrggbbaa` when `alpha` is set (UIs then
+     *  offer an opacity control). */
+    alpha?: boolean;
+}
+/**
+ * Open leaf: any node with a `kind` outside the built-ins. Schema-driven
+ * UIs (weasel-ui `PrefsForm` / `SelectionPanel`) dispatch it to an
+ * app-supplied renderer. Deliberately NOT index-signatured so concrete
+ * app interfaces stay assignable. Mirrors weasel-ui's `PrefCustom`.
+ */
+type ToolPrefCustom = ToolPrefBase<string, unknown>;
+/**
+ * A whole `FillStyle`, not a color inside one. Use it wherever the value is
+ * the tagged paint union — a solid color, a pattern, a gradient — rather
+ * than a hex string.
+ *
+ * Addressing `…fill.color` instead reads `undefined` off a gradient (so the
+ * control shows its default and claims the text is black) and writes a
+ * hybrid `{ fill: 'gradient', stops, color }` that the renderer's structural
+ * `'color' in paint` checks then paint flat solid. The union has to be
+ * edited as a union.
+ */
+interface ToolPrefPaint extends ToolPrefBase<'paint', unknown> {
+    /** Offer an opacity control alongside the color. */
+    alpha?: boolean;
+}
+/**
+ * A leaf whose value is one object, with its own fields hanging off it.
+ *
+ * A compound value — a stroke, a shadow, a pattern spec — could be described
+ * as several sibling leaves addressing into it (`data.stroke.width`,
+ * `data.stroke.cap`). It shouldn't be: each control would then write one field
+ * of a value it can only half see, and writing into something that is not an
+ * object yet corrupts it. Here the fields are `children` of one leaf, and
+ * every edit commits the parent object whole.
+ *
+ * `children` paths are relative to the object. They are ordinary leaves, so a
+ * field that is itself a union (a stroke's `paint`) declares the kind that
+ * edits that union. A child may also be a {@link ToolPrefGroup}, which
+ * organises the fields under a heading without contributing to the path —
+ * the same rule group keys follow at the top level. A `TextStyle` needs it:
+ * its character and paragraph fields belong to one value but read as two
+ * lists.
+ */
+interface ToolPrefObject extends ToolPrefBase<'object', unknown> {
+    children: Record<string, ToolPrefLeaf | ToolPrefGroup>;
+    /**
+     * Lift a non-object value into the object form, for a consumer field that
+     * may also be held as a scalar. Called before a child edit is applied;
+     * without it a scalar-valued leaf shows its children empty and refuses the
+     * edit.
+     */
+    fromScalar?: (value: unknown) => Record<string, unknown>;
+}
+/** One built-in pref leaf. `ToolPrefLeaf` widens this to include
+ *  app-defined kinds. */
+type ToolPref = ToolPrefNumber | ToolPrefBoolean | ToolPrefString | ToolPrefEnum | ToolPrefColor | ToolPrefPaint | ToolPrefObject;
+/** Built-in or app-defined leaf. */
+type ToolPrefLeaf = ToolPref | ToolPrefCustom;
+/** Nestable group: branch nodes a tool can use to organize its prefs. */
+interface ToolPrefGroup {
+    /** Heading for the group's rows. **Empty means no heading** — for a group
+     *  that exists to organise, not to name: one whose children are themselves
+     *  groups carrying the labels a reader needs. Give it a name whenever the
+     *  name is the referent (a `Border` group over `Top` / `Right` / `Bottom`
+     *  reads as nothing without it). */
+    name: string;
+    description?: string;
+    children: Record<string, ToolPrefLeaf | ToolPrefGroup>;
+}
+
+/** What a {@link PrefRenderer} is given for the leaf it is rendering. */
+interface PrefRenderContext {
+    /** Dotted path of the leaf within the schema root. */
+    path: string;
+    /** The schema node. App renderers narrow this to their own kind shape. */
+    pref: ToolPrefLeaf;
+    /** Current value — `values` at `path`, falling back to `pref.default`. */
+    value: unknown;
+    setValue: (value: unknown) => void;
+}
+/**
+ * Renders the control cell for one preference leaf. Returning `null`
+ * collapses the row.
+ */
+type PrefRenderer = (ctx: PrefRenderContext) => ReactNode;
+
+export type { PrefRenderer as P, ToolPrefLeaf as T, ToolPrefGroup as a, ToolPref as b, ToolPrefBoolean as c, ToolPrefBooleanControl as d, ToolPrefColor as e, ToolPrefCustom as f, ToolPrefEnum as g, ToolPrefEnumControl as h, ToolPrefEnumEncoding as i, ToolPrefKind as j, ToolPrefNumber as k, ToolPrefNumberControl as l, ToolPrefNumberUnit as m, ToolPrefObject as n, ToolPrefPaint as o, PrefRenderContext as p, ToolPrefString as q, ToolPrefStringControl as r };

package/dist/_dts/index-DgcNdEdh.d.ts

@@ -0,0 +1,314 @@
+import { ComponentType, ReactNode } from 'react';
+import { R as ResolvedConfig, d as ConfigField, c as ConfigSchema } from './types-AHlQxBNN.js';
+import { c as SavedSnapshot } from './types-1Sdxy_Pv.js';
+import { J as JobHandle, a as JobCapability } from './types-DJ79Tg5J.js';
+
+/** A named position in a trial's chrome. Content is not a region — that is
+ *  the instrument. */
+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 {
+    icon: IconComponent;
+    label: string;
+    /** Shown in the tooltip. Not bound here — the trial owns its keymap. */
+    shortcut?: string;
+    disabled?: boolean;
+    /** Reddens on hover. For actions that discard work. */
+    danger?: boolean;
+    /** Render the label beside the glyph rather than only in the tooltip. */
+    showLabel?: boolean;
+    onActivate: () => void;
+}
+/** A selectable tool in the palette region. */
+interface ToolItem {
+    icon: IconComponent;
+    label: string;
+    shortcut?: string;
+    disabled?: boolean;
+}
+/** A titled block in the sidebar. */
+interface SidebarSection {
+    title: string;
+    /** Starts collapsed. The open/closed state itself is the region's. */
+    defaultCollapsed?: boolean;
+    body: ReactNode;
+}
+/** A control acting on the view of the trial, not on the trial. */
+interface ViewportControl {
+    icon: IconComponent;
+    label: string;
+    disabled?: boolean;
+    onActivate: () => void;
+}
+/** A readout in the status bar. */
+interface StatusReadout {
+    /** Short enough for a status bar. Rendered as text. */
+    text: string;
+    /** Tooltip. */
+    title?: string;
+}
+/** What every contribution shares. */
+interface ContributionBase {
+    id: string;
+    /** Groups sort by first appearance; items sort within a group by
+     *  declaration order. Contributions with no group sort after grouped ones. */
+    group?: string;
+    /** Pushes this contribution, and its group, to the far end of the region. */
+    end?: boolean;
+}
+/**
+ * A contribution is data the chrome renders, keyed to a region. Supplying
+ * `render` instead of `item` opts out of the chrome's layout — deliberate,
+ * and visible in the declaration.
+ */
+type TrialContribution = (ContributionBase & {
+    region: 'titlebar';
+    item: ToolbarItem;
+    render?: never;
+}) | (ContributionBase & {
+    region: 'toolbar';
+    item: ToolbarItem;
+    render?: never;
+}) | (ContributionBase & {
+    region: 'palette';
+    item: ToolItem;
+    render?: never;
+}) | (ContributionBase & {
+    region: 'sidebar';
+    item: SidebarSection;
+    render?: never;
+}) | (ContributionBase & {
+    region: 'viewport';
+    item: ViewportControl;
+    render?: never;
+}) | (ContributionBase & {
+    region: 'status';
+    item: StatusReadout;
+    render?: never;
+}) | (ContributionBase & {
+    region: TrialRegion;
+    item?: never;
+    render: (ctx: TrialChromeContext) => 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 {
+    trialId: string;
+    instrumentName: string;
+    isLastTrial: boolean;
+    /** Null when the trial holds a view that is not the 2D one. */
+    zoom: number | null;
+    setZoom: (z: number) => void;
+    canUndo: boolean;
+    canRedo: boolean;
+    undo: () => void;
+    redo: () => void;
+    /** The instrument's controls, resolved against the lab's rules. Always
+     *  populated: a legacy `configSchema()` is adapted into the same shape. */
+    configSchema: ResolvedConfig;
+    /** @deprecated Read `configSchema`. Empty for an instrument declaring
+     *  `config`, since a builder schema has no `ConfigField[]` form. */
+    configFields: ConfigField[];
+    config: unknown;
+    setConfig: (key: string, value: unknown) => void;
+    savedSnapshots: SavedSnapshot[];
+    saveSnapshot: (name?: string) => void;
+    loadSnapshot: (snapshotId: string) => void;
+    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 tool a trial can be in. labkit's own — core's `ToolsApi` carries hotkey
+ * slots, ambient tools, eligibility tiers and canvas overlay layers, all bound
+ * to the gesture dispatcher, and a labkit instrument is an arbitrary canvas or
+ * DOM tree rather than a weasel scene.
+ */
+interface TrialTool {
+    id: string;
+    label: string;
+    icon: IconComponent;
+    /** Shown in the tooltip. Not bound here — the instrument owns its keymap. */
+    shortcut?: string;
+    /** Presentation grouping in the palette. Ungrouped tools sort after grouped. */
+    group?: string;
+}
+/** What an instrument declares to get a palette region. */
+interface ToolCapability {
+    tools: TrialTool[];
+    /** Which tool a fresh trial starts in. Defaults to the first. */
+    initial?: string;
+}
+
+/** What an instrument's `render` is handed: its state and config, the setters
+ *  for both, the trial it is mounted in, and a way to emit named events. */
+interface RenderContext<TS = unknown, TC = unknown> {
+    state: TS;
+    config: TC;
+    setState: (next: TS | ((prev: TS) => TS)) => void;
+    setConfig: (key: keyof TC, value: unknown) => void;
+    trial: {
+        id: string;
+        /** The trial's view, in whatever shape this instrument chose. labkit persists
+         *  it and restores it on Reset without ever reading into it. */
+        view: unknown;
+        setView: (next: unknown) => void;
+        /** 2D convenience over `view`. Reads 1 and writes nothing when the trial holds
+         *  a view that is not the 2D one. */
+        zoom: number;
+        setZoom: (z: number) => void;
+        /** Resolved active tool: this trial's slot, or the lab's. Null when neither
+         *  holds one. */
+        activeToolId: string | null;
+    };
+    emit: (event: string) => void;
+    /** Present only when the instrument declares a `job`. */
+    job?: JobHandle;
+}
+/** One 2D canvas layer of an instrument, drawn in declaration order.
+ *
+ *  `draw` is called with the camera already applied, so it works in world
+ *  coordinates. `zoom` is passed for the things that must not scale with it —
+ *  set `ctx.lineWidth = 1 / zoom` to keep a hairline hairline. */
+interface CanvasLayer<TS = unknown, TC = unknown> {
+    id: string;
+    draw: (ctx: CanvasRenderingContext2D, args: {
+        state: TS;
+        config: TC;
+        zoom: number;
+    }) => void;
+}
+/** Declares that an instrument draws to a canvas: its layers, and where the
+ *  view starts. */
+interface CanvasCapability<TS = unknown, TC = unknown> {
+    layers: CanvasLayer<TS, TC>[];
+    initialView?: {
+        zoom: number;
+        pan: {
+            x: number;
+            y: number;
+        };
+    };
+    /** Widens `usePanZoom`'s default clamp; the opening zoom stays reachable
+     *  regardless of these. */
+    minZoom?: number;
+    maxZoom?: number;
+}
+/** Declares which of an instrument's layers the trial should offer
+ *  show/hide controls for. */
+interface LayerCapability {
+    /** In list order. A bare string is a layer id that doubles as its own label;
+     *  give a descriptor instead to label a layer or mark it `alwaysOn`. */
+    ids: readonly (string | LayerDescriptor)[];
+}
+/** Declares that an instrument accepts items dragged from a palette: what the
+ *  palette offers, what a drop does to the state, and — optionally — live
+ *  feedback during the drag and the ability to drag existing items back out. */
+interface DragDropCapability<TS = unknown, TC = unknown> {
+    palette: PaletteItem[] | ((state: TS, config: TC) => PaletteItem[]);
+    onDrop: (worldPos: Point, item: PaletteItem, state: TS, config: TC) => TS;
+    onDragOver?: (worldPos: Point, item: PaletteItem, state: TS, config: TC) => DragFeedback | null;
+    pickUp?: (hit: HitResult, state: TS, config: TC) => {
+        item: PaletteItem;
+        state: TS;
+    } | null;
+}
+/** Declares that an instrument's state is undoable: which emitted events
+ *  snapshot it, and how many snapshots to keep. */
+interface UndoCapability {
+    snapshotOn?: string[];
+    maxDepth?: number;
+}
+/** The name of an event an instrument emits through `RenderContext.emit`. */
+type SystemEvent = string;
+/** A point in world coordinates. */
+type Point = {
+    x: number;
+    y: number;
+};
+/** What a hit-test found, and where. */
+type HitResult = {
+    hit: boolean;
+    layerId?: string;
+    pointId?: string;
+};
+/** A trial's camera. */
+type ViewTransform = {
+    zoom: number;
+    pan: Point;
+};
+/** A layer as the layer list shows it. `alwaysOn` layers cannot be hidden. */
+type LayerDescriptor = {
+    id: string;
+    label: string;
+    alwaysOn?: boolean;
+};
+/** One draggable entry in an instrument's palette. */
+type PaletteItem = {
+    id: string;
+    label: string;
+    data?: unknown;
+};
+/** Whether a drop would be accepted at the current position, and why not if
+ *  it would not. */
+type DragFeedback = {
+    ok: boolean;
+    reason?: string;
+};
+/**
+ * An instrument: one self-contained interactive experiment a lab can host.
+ *
+ * It owns two pieces of data — `config`, the settings the control panel edits,
+ * and `state`, what the experiment is currently doing — and renders from both.
+ * The optional capability fields declare what else it wants from the runtime:
+ * a canvas, a layer list, palette drag-and-drop, undo. Declaring a capability
+ * is what makes the trial provide the corresponding chrome.
+ */
+interface Instrument<TS = unknown, TC = unknown, TItem = unknown> {
+    name: string;
+    defaultConfig: () => TC;
+    initialState: (config: TC) => TS;
+    /** The instrument's config, declared once: values, types and controls.
+     *  Supplying this makes `defaultConfig` optional — `defineInstrument`
+     *  synthesizes it. Prefer it over `defaultConfig` + `configSchema`. */
+    config?: ConfigSchema<TC>;
+    /** @deprecated Declare `config` instead; this repeats what `TC` already
+     *  says and nothing holds the two to one answer. */
+    configSchema?: () => ConfigField[];
+    /** The instrument's DOM. With `canvas`, this renders as an overlay above the
+     *  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;
+    serialize?: (state: TS) => unknown;
+    deserialize?: (data: unknown, config: TC) => TS;
+    canvas?: CanvasCapability<TS, TC>;
+    layers?: LayerCapability;
+    dragDrop?: DragDropCapability<TS, TC>;
+    undo?: UndoCapability;
+    /** Tools this instrument offers. Declaring them gives the trial a palette
+     *  region and its own tool slot. */
+    tools?: ToolCapability;
+    /** Chrome this instrument contributes beyond what its capabilities imply. */
+    chrome?: TrialContribution[];
+    /** Work too slow to do during a render. The runtime starts it, aborts it on
+     *  unmount and on a `key` change, and renders progress into the trial. */
+    job?: JobCapability<TS, TC, TItem>;
+}
+/** Instruments as a lab receives them. `any` rather than `unknown` because
+ *  parameter contravariance keeps a `defineInstrument<TS, TC>` result out of
+ *  an `Instrument<unknown, unknown>[]`; it is contained to this alias. */
+type InstrumentList = readonly Instrument<any, any, any>[];
+
+export type { CanvasCapability as C, DragDropCapability as D, HitResult as H, Instrument as I, LayerCapability as L, PaletteItem as P, RenderContext as R, SidebarSection as S, TrialContribution as T, UndoCapability as U, ViewTransform as V, InstrumentList as a, TrialTool as b, CanvasLayer as c, DragFeedback as d, IconComponent as e, LayerDescriptor as f, Point as g, StatusReadout as h, SystemEvent as i, ToolCapability as j, ToolItem as k, ToolbarItem as l, TrialChromeContext as m, TrialRegion as n, ViewportControl as o };

package/dist/_dts/types-1Sdxy_Pv.d.ts

@@ -0,0 +1,90 @@
+/** A trial's undo history, as snapshots of its state either side of the
+ *  present. */
+interface UndoStack {
+    past: unknown[];
+    future: unknown[];
+}
+/** 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;
+    /** This trial's own tool slot. Undefined means it reads the lab's. */
+    activeToolId?: string | null;
+    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>;
+}
+/** Where a lab persists itself. Implementations are keyed string storage and
+ *  nothing more, so the same store works against localStorage, the URL hash,
+ *  or memory. */
+interface StorageAdapter {
+    read(key: string): string | null;
+    write(key: string, value: string): void;
+    delete?(key: string): 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;
+    setConfig: (key: keyof TC, value: TC[keyof TC]) => void;
+}
+/** Options for `createLabStore`. `storageKey` namespaces the keys written, so
+ *  two labs on one origin do not collide. */
+interface CreateLabStoreOptions {
+    storageKey: string;
+    storage: StorageAdapter;
+    initialMode?: LabMode;
+}
+/** Per-instrument serialize/deserialize hooks, keyed by instrument name. An
+ *  instrument whose state is already JSON-safe needs no entry. */
+type InstrumentSerializers = Record<string, {
+    serialize?: (state: unknown) => unknown;
+    deserialize?: (data: 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>;
+    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>;
+
+export type { CreateLabStoreOptions as C, InstrumentSerializers as I, LabDocument as L, Migration as M, SerializedTrial as S, TrialRecord as T, UndoStack as U, StorageAdapter as a, LabStoreState as b, SavedSnapshot as c, TrialStateHandle as d, LabMode as e };