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

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 };

package/dist/_dts/types-AHlQxBNN.d.ts

@@ -0,0 +1,162 @@
+import { P as PrefRenderer, T as ToolPrefLeaf, a as ToolPrefGroup } from './PrefsForm-BYa6cWnO.js';
+
+/**
+ * Renders the control cell for one config leaf. Identical to weasel-ui's
+ * `PrefRenderer` on purpose — aliased rather than redeclared so the two
+ * cannot drift.
+ */
+type ControlRenderer = PrefRenderer;
+/** One labeled choice in an `enum` leaf. */
+interface ConfigOption {
+    value: string;
+    label: string;
+}
+/** Everything a leaf can carry beyond its kind and default. A flat union of
+ *  every `Pref*` leaf's extras, plus labkit's own `debounceMs`. */
+interface Annotations {
+    name?: string;
+    description?: string;
+    hidden?: boolean;
+    block?: boolean;
+    pair?: string;
+    min?: number;
+    max?: number;
+    step?: number;
+    control?: string;
+    options?: readonly ConfigOption[];
+    placeholder?: string;
+    maxLength?: number;
+    /** Milliseconds to debounce a string leaf's live writes. Default 150. */
+    debounceMs?: number;
+}
+/** What a rule contributes. `kind` is honored only while it is still unset,
+ *  which is what makes `f.value` claimable and a kinded factory final. */
+type LeafPatch = Annotations & {
+    kind?: string;
+};
+/** What a rule is given for the leaf it is deciding about. */
+interface ConfigRuleContext {
+    /** The config key this leaf writes. */
+    key: string;
+    /** Dotted path within the schema. Equal to `key` while schemas are flat. */
+    path: string;
+    /** The leaf's default value. A rule may read it but never change it. */
+    default: unknown;
+    /** What earlier rules and the author's own annotations have settled. */
+    leaf: Readonly<LeafPatch>;
+}
+/**
+ * Decides part of how a leaf is presented. Returns a patch, or null to
+ * abstain. Merging is gap-filling: a property already settled is never
+ * overwritten, so the author's annotations beat every rule and a consumer's
+ * rules beat labkit's built-ins.
+ */
+type ConfigRule = (ctx: ConfigRuleContext) => LeafPatch | null;
+/** A presentational bucket of leaves, rendered under one heading. */
+interface SectionSpec {
+    label: string;
+    paths: readonly string[];
+}
+/** A schema resolved against a set of rules: the vocabulary weasel-ui renders,
+ *  plus the three things labkit keeps on the side because `PrefLeaf` has no
+ *  field for them. */
+interface ResolvedConfig {
+    /** Flat: every leaf is a direct child, so a leaf's path is its config key. */
+    group: ToolPrefGroup;
+    sections: readonly SectionSpec[];
+    showIf: ReadonlyMap<string, (config: Record<string, unknown>) => boolean>;
+    /** Node-level `.render` overrides, keyed by path. */
+    renderers: Readonly<Record<string, ControlRenderer>>;
+}
+/** Per-node extras that do not belong on a `PrefLeaf`. */
+interface NodeOptions {
+    section?: string;
+    showIf?: (config: Record<string, unknown>) => boolean;
+    render?: ControlRenderer;
+    validate?: (leaf: ToolPrefLeaf) => string[];
+}
+/** The builder's leaf: a kind (or null, to be decided by rules), a default,
+ *  an annotation bag, and the extras above. */
+interface ConfigNode<T = unknown> {
+    readonly kind: string | null;
+    readonly default: T;
+    readonly annotations: Readonly<Annotations>;
+    readonly options: Readonly<NodeOptions>;
+}
+/** The value type a node produces. */
+type NodeValue<N> = N extends ConfigNode<infer T> ? T : never;
+/** The config type a builder shape produces. */
+type InferConfig<S> = {
+    [K in keyof S]: NodeValue<S[K]>;
+};
+/** An instrument's config, declared once. */
+interface ConfigSchema<TC> {
+    readonly nodes: Readonly<Record<string, ConfigNode>>;
+    /** The starting config — what `defaultConfig()` would have returned. */
+    defaults(): TC;
+}
+/** The config type behind a schema: `ConfigOf<typeof sceneConfig>`. */
+type ConfigOf<S> = S extends ConfigSchema<infer TC> ? TC : never;
+
+/** Which control a config field is edited with. */
+type ConfigFieldType = 'slider' | 'checkbox' | 'select' | 'number' | 'text' | 'color';
+/** What every config field carries: the config key it writes, the label shown
+ *  beside it, and which control renders it. */
+interface ConfigFieldBase {
+    key: string;
+    label: string;
+    type: ConfigFieldType;
+}
+/** A bounded number edited by dragging. */
+interface SliderField extends ConfigFieldBase {
+    type: 'slider';
+    default: number;
+    min: number;
+    max: number;
+    step?: number;
+}
+/** A boolean. */
+interface CheckboxField extends ConfigFieldBase {
+    type: 'checkbox';
+    default: boolean;
+}
+/** One choice in a select field. */
+interface SelectOption {
+    value: string;
+    label: string;
+}
+/** A fixed set of labeled choices. */
+interface SelectField extends ConfigFieldBase {
+    type: 'select';
+    default: string;
+    options: SelectOption[];
+}
+/** A number typed directly, optionally bounded. Use a slider field instead
+ *  when the range matters more than the exact value. */
+interface NumberField extends ConfigFieldBase {
+    type: 'number';
+    default: number;
+    min?: number;
+    max?: number;
+    step?: number;
+}
+/** A free-text string. Writes are debounced so typing does not re-run the
+ *  instrument on every keystroke. */
+interface TextField extends ConfigFieldBase {
+    type: 'text';
+    default: string;
+    placeholder?: string;
+    maxLength?: number;
+    /** Milliseconds to debounce live setConfig calls. Default 150 ms. Set to 0 to disable. */
+    debounceMs?: number;
+}
+/** A color, as a CSS color string. */
+interface ColorField extends ConfigFieldBase {
+    type: 'color';
+    default: string;
+}
+/** One field of an instrument's config schema. The schema is what the control
+ *  panel renders, and what `validateConfigSchema` checks. */
+type ConfigField = SliderField | CheckboxField | SelectField | NumberField | TextField | ColorField;
+
+export type { Annotations as A, ConfigNode as C, InferConfig as I, LeafPatch as L, NodeOptions as N, ResolvedConfig as R, SectionSpec as S, TextField as T, ControlRenderer as a, ConfigOption as b, ConfigSchema as c, ConfigField as d, ConfigRule as e, ConfigRuleContext as f, CheckboxField as g, ColorField as h, ConfigFieldBase as i, ConfigFieldType as j, ConfigOf as k, NodeValue as l, NumberField as m, SelectField as n, SelectOption as o, SliderField as p };

package/dist/_dts/{useTrialState-BMNIx3Cy.d.ts → useTrialState-CsGMjhu9.d.ts}

@@ -1,92 +1,8 @@
+import { a as StorageAdapter, b as LabStoreState, T as TrialRecord, c as SavedSnapshot, e as LabMode, I as InstrumentSerializers, C as CreateLabStoreOptions, d as TrialStateHandle } from './types-1Sdxy_Pv.js';
 import * as react from 'react';
 import { ReactNode, ReactElement } from 'react';
 import { StoreApi } from 'zustand/vanilla';
 
-/** 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;
-    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;
-    /** 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>;
-
 /** Persist to `localStorage` — state survives a reload and a new tab. Falls
  *  back to no-ops when storage is unavailable. */
 declare const localStorageAdapter: StorageAdapter;
@@ -116,6 +32,8 @@ interface LabStoreActions {
     deleteSnapshot: (snapshotId: string) => void;
     listSnapshots: (trialId?: string) => SavedSnapshot[];
     setMode: (mode: LabMode) => void;
+    setLabTool: (id: string | null) => void;
+    setTrialTool: (trialId: string, id: string | null) => void;
     setLayout: (layout: Record<string, unknown>) => void;
 }
 /** A lab's store: its state and actions, plus the hook instruments use to
@@ -167,5 +85,5 @@ declare function quarantineKey(storageKey: string): string;
  *  running in. Throws outside a lab store and trial. */
 declare function useTrialState<TS = unknown, TC = unknown>(): TrialStateHandle<TS, TC>;
 
-export { CURRENT_DOCUMENT_VERSION as C, LabStoreContext as e, LabStoreProvider as f, TrialIdContext as i, TrialIdProvider as j, createLabStore as l, createMemoryAdapter as m, labDocumentKey as n, localStorageAdapter as o, noneAdapter as p, quarantineKey as q, useLabStore as r, sessionStorageAdapter as s, useTrialId as t, urlHashAdapter as u, useTrialState as v };
-export type { InstrumentSerializers as I, LabDocument as L, Migration as M, SerializedTrial as S, TrialRecord as T, UndoStack as U, StorageAdapter as a, CreateLabStoreOptions as b, LabStore as c, LabStoreActions as d, LabStoreState as g, SavedSnapshot as h, TrialStateHandle as k, LabMode as w };
+export { CURRENT_DOCUMENT_VERSION as C, TrialIdContext as T, LabStoreContext as b, LabStoreProvider as c, TrialIdProvider as d, createLabStore as e, createMemoryAdapter as f, localStorageAdapter as g, useLabStore as h, useTrialId as i, useTrialState as j, labDocumentKey as l, noneAdapter as n, quarantineKey as q, sessionStorageAdapter as s, urlHashAdapter as u };
+export type { LabStore as L, LabStoreActions as a };