@weasel-js/labkit 1.6.0 → 1.7.0

package/dist/_dts/{frac-DTRq7Xpb.d.ts → types-CSm9jgol.d.ts}

@@ -1,37 +1,9 @@
-import { ComponentType, ReactNode, RefObject } from 'react';
-import { S as StanceProps } from './PrefsRow.d-DFpPIeIC.js';
-import { R as ResolvedConfig, a as ConfigPath, V as ValueAtPath, b as ConfigField, c as ConfigSchema } from './types-B7y8hX1D.js';
+import { DrawCommand, Scene, PointerContextValue } from '@weasel-js/core';
+import { RefObject, ComponentType, ReactNode } from 'react';
+import { S as StanceProps } from './PrefsRow.d-TOZ7BgD9.js';
+import { R as ResolvedConfig, C as ConfigPath, V as ValueAtPath, a as ConfigField, b as ConfigSchema } from './types-CRPSGFAp.js';
 import { ColorModePreference } from '@weasel-js/theme';
 import { J as JobHandle, a as JobCapability } from './types-DJ79Tg5J.js';
-import { Scene } from '@weasel-js/core';
-
-/** How an instrument's world sits on the canvas, independent of the camera.
- *  The defaults reproduce the convention labkit shipped before this existed:
- *  world (0,0) at the element's top-left, y growing downward. */
-interface WorldSpec {
-    /** Where world (0,0) sits at `pan` zero, as a fraction of the viewport.
-     *  `{x:0,y:0}` top-left (default); `{x:0.5,y:0.5}` centre. */
-    origin?: Point;
-    /** Which way the world y axis runs on screen. Default `'down'`. */
-    yAxis?: 'down' | 'up';
-}
-/** A viewport's CSS-pixel size. */
-interface ViewportSize {
-    width: number;
-    height: number;
-}
-/** A `WorldSpec` resolved against a viewport: what the coordinate helpers,
- *  the camera and the wheel all read. */
-interface WorldFrame {
-    /** Screen position of world (0,0) at `pan` zero. */
-    originPx: Point;
-    yDir: 1 | -1;
-}
-declare const DEFAULT_FRAME: WorldFrame;
-declare function resolveFrame(spec: WorldSpec | undefined, size: ViewportSize): WorldFrame;
-/** Put a 2D context into the instrument's world coordinates, so a layer's
- *  `draw` works in them. Must stay the exact inverse of `screenToWorld`. */
-declare function applyCamera(ctx: CanvasRenderingContext2D, view: ViewTransform, frame?: WorldFrame): void;
 
 /**
  * Written at a config path to mean "do not pin this — let the instrument
@@ -244,614 +216,178 @@ interface LabDocument {
  *  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 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 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. */
-    shortcut?: string;
-    disabled?: boolean;
-    /** Reddens on hover. For actions that discard work. */
-    danger?: boolean;
-    /** A toggle rather than a command: renders `aria-pressed` and reads as held
-     *  down while true. */
-    pressed?: boolean;
-    /** Render the label beside the glyph rather than only in the tooltip. */
-    showLabel?: boolean;
-    /** 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 tool in the palette region: a mode by default, a command when it carries
- *  an `onActivate`. `TCtx` is the chrome context that handler is handed — a
- *  trial's, or the lab's for a lab-level rail. */
-interface ToolItem<TCtx = TrialChromeContext> {
-    icon: IconComponent;
-    label: string;
-    /** Shown in the tooltip. Not bound here — the trial owns its keymap. */
-    shortcut?: string;
-    disabled?: boolean;
-    /** Runs on press instead of selecting. An item with one is a command: it
-     *  never writes the tool slot, and never reads as the current tool. */
-    onActivate?: (ctx: TCtx) => void;
-}
-/** A titled block in the sidebar. `stance` and `tone` work as on a
- *  `<PropertyPanel>`: what kind of content the section holds, and which of its
- *  peers it is. */
-interface SidebarSection extends StanceProps {
-    title: string;
-    /** Starts collapsed, until the trial remembers a fold of its own. */
-    defaultCollapsed?: boolean;
-    /** Offer the tear-out control. On by default; a section that only makes
-     *  sense beside its trial sets this false. */
-    undockable?: boolean;
-    /** Where the tear-out control sends it. Default `'tile'`. */
-    undockAs?: 'tile' | 'floating';
-    body: ReactNode;
-}
-/** A control acting on the view of the trial, not on the trial. */
-interface ViewportControl<TCtx = TrialChromeContext> {
-    icon: IconComponent;
-    label: string;
-    disabled?: boolean;
-    /** Handed the trial's chrome context, as `ToolbarItem.onActivate` is. */
-    onActivate: (ctx: TCtx) => void;
+/** A mark's box in its target's world: CSS pixels at zoom 1. Matches weasel's
+ *  default `RectPose`, which is what the scene stores. */
+interface WorldRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
 }
-/** A readout in the status bar. */
-interface StatusReadout {
-    /** Short enough for a status bar. Rendered as text. */
-    text: string;
-    /** Tooltip. */
-    title?: string;
+/** Where a fraction lands on a content box of this size. */
+declare function fracToWorld(f: FracRect, content: {
+    w: number;
+    h: number;
+}): WorldRect;
+/** What fraction of the content box a world rect covers.
+ *
+ *  A pane measured before layout is 0×0, and dividing by that would seed every
+ *  stored position with `NaN` — which compares false against everything and so
+ *  fails silently rather than loudly. Zero sides give zeros. */
+declare function worldToFrac(r: WorldRect, content: {
+    w: number;
+    h: number;
+}): FracRect;
+/** Snap to 4dp. Positions are diffed by humans in stored documents, so the
+ *  last digits of a float are noise that hides the change that matters. */
+declare function roundFrac(f: FracRect): FracRect;
+/** Whether `pt` falls in `box`, widened by `tol` on every side so a hairline
+ *  mark stays reachable. */
+declare function fracContains(box: FracRect, pt: FracPoint, tol?: number): boolean;
+/** Whether `outer` wholly encloses `inner`. A marquee takes what it encloses,
+ *  not what it grazes — brushing selection is a different gesture, and this
+ *  answers false for two rects that merely overlap. */
+declare function fracEncloses(outer: FracRect, inner: FracRect): boolean;
+
+/** The subset of a mark's scene node this needs: where it is, and what it is. */
+interface PaintableMark {
+    pose: WorldRect;
+    data: AnnotationData;
 }
-/** 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
-     *  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;
+/** How a mark is drawn, as opposed to where. Resolved by the overlay from the
+ *  instrument's vocabulary and the mark's own staleness. */
+interface MarkStyle {
+    /** The status's color, or the default. */
+    color?: string;
+    /** A mark whose stored position no longer describes the picture. Drawn
+     *  dashed rather than hidden: it still describes *something*, and dropping
+     *  it would lose it. */
+    stale?: 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;
-});
-/**
- * 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.
+ * What one mark draws, in its target's world.
+ *
+ * Pure: a node and the target's content box in, draw commands out. Geometry
+ * that a bounding box cannot describe — a line's ends, a stroke's path — comes
+ * from `data.points`, which is in fractions like the bounds.
  */
-interface ToolSlotContext {
-    activeToolId: string | null;
-    setActiveTool: (id: string) => void;
+declare function markCommands(m: PaintableMark, content: {
+    w: number;
+    h: number;
+}, style?: MarkStyle): DrawCommand[];
+
+/** A mark's box in its target's world. Matches weasel's default `RectPose`. */
+type MarkPose = WorldRect;
+/** The scene one target's marks live in. */
+type MarkScene = Scene<AnnotationData, 'marks', MarkPose>;
+/** A mark scene: one layer, because marks do not stack in tiers. */
+declare function createAnnotationScene(): MarkScene;
+interface AnnotationStoreOptions {
+    /** Re-read on every call, so a target resizing or gaining a dependency takes
+     *  effect without rebuilding the store. */
+    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 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;
+    /** Notified after every finished export. */
+    onCapture?: (result: CaptureResult) => 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;
+/** Everything a capture needs that is not the store's own state. Split out so
+ *  `capture.ts` takes data rather than reaching back into the store. */
+interface CaptureDeps {
+    scene: MarkScene;
+    target: AnnotationTargetInfo;
+    meaning?: AnnotationMeaning;
+    config: unknown;
 }
 /**
- * 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.
+ * A facade over one weasel scene per target: the scenes are the truth, this
+ * answers questions about them. Everything crossing this boundary is in
+ * fractions of a target's content box; the scenes hold world units.
+ *
+ * A scene per target rather than one scene with a `target` field, because a
+ * pane's hit-test, marquee and paint all walk the whole scene it is given and
+ * take no filter — one shared scene puts every other pane's marks under the
+ * pointer.
  */
-interface RegionContribution<TCtx> extends ContributionBase {
-    region: string;
-    item?: unknown;
-    render?: (ctx: TCtx) => ReactNode;
+declare function createAnnotationStore(opts: AnnotationStoreOptions): AnnotationsApi;
+/** Rebuild a store from what `toJSON` wrote. Unknown or future versions give
+ *  an empty store rather than throwing: a lab that cannot read its marks
+ *  should still open. */
+declare function annotationsFromJSON(raw: unknown, targets: () => readonly AnnotationTargetInfo[], rest?: Omit<AnnotationStoreOptions, 'targets' | 'restore'>): AnnotationsApi;
+
+/** A point in fractions of a target's content box. */
+interface FracPoint {
+    x: number;
+    y: number;
 }
-/**
- * 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 extends ToolSlotContext, SidebarSlotContext {
-    trialId: string;
-    instrumentName: string;
-    /** 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's title. Persisted with
-     *  the trial, so a title survives a reload. */
-    setTitle: (title: string | null) => void;
-    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;
-    /** Whether the trial's loupe is turned on. False for an instrument that
-     *  declares none, whose chrome offers no way to turn one on. */
-    loupeOn: boolean;
-    toggleLoupe: () => 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;
-    /** The trial's unpinned paths. `config` stays raw, so a control drawn from
-     *  it sits at the value un-pinning writes back. */
-    auto: ReadonlySet<string>;
-    setConfig: (key: string, value: unknown) => void;
-    /** Which of this trial's collapsible sections are folded. A sidebar
-     *  section's key is its contribution id; a section *inside* a contribution —
-     *  a control panel's property group — is keyed `<contribution id>/<label>`.
-     *  A section absent here is at its own default. Persisted with the trial. */
-    collapsedSections: Readonly<Record<string, boolean>>;
-    /** Fold or unfold one section, keyed as `collapsedSections` is. */
-    setSectionCollapsed: (key: string, collapsed: boolean) => void;
-    /** Section ids this trial currently has torn out of its sidebar. */
-    undockedPanels: readonly string[];
-    /** Tear a sidebar section out into the workspace. */
-    undockPanel: (sectionId: string, as?: 'tile' | 'floating') => void;
-    /** Put a torn-out section back in the sidebar. */
-    dockPanel: (sectionId: string) => void;
-    savedSnapshots: SavedSnapshot[];
-    saveSnapshot: (name?: string) => void;
-    loadSnapshot: (snapshotId: string) => void;
-    clone: () => void;
-    reset: () => void;
-    close: () => void;
-}
-
-/** A point on the magnified surface, in its own CSS pixels. */
-interface LoupePoint {
+/** A rectangle in fractions of a target's content box.
+ *
+ *  Fractions rather than pixels because a mark must survive a change of render
+ *  resolution: the picture gets bigger, the mark stays on the same feature. */
+interface FracRect {
     x: number;
     y: number;
+    w: number;
+    h: number;
 }
-
-/** How a loupe magnifies. `'vector'` re-renders the source through a zoomed-in
- *  view, so content stays sharp at any factor; `'pixel'` blows up the actual
- *  pixels the surface presented. */
-type LoupeMode = 'vector' | 'pixel';
-
-/** What a DOM instrument's loupe `render` is handed: the same data its own
- *  `render` gets, and the camera to draw it through. */
-interface LoupeRenderArgs<TS = unknown, TC = unknown> {
-    state: TS;
-    config: TC;
-    /** The trial's own camera composed with the magnification, about the aimed
-     *  point — so drawing the same content through it magnifies in place. */
-    view: ViewTransform;
-    /** The magnification on its own, for whatever must not scale with the
-     *  camera. */
-    factor: number;
-    mode: LoupeMode;
-    /** The size of the viewport `view` is written for: the trial's content well,
-     *  not the lens. The lens shows a circle cut out of it. */
-    size: ViewportSize;
-}
-/**
- * Declares that an instrument can be magnified.
- *
- * With no `render`, the loupe re-draws the instrument's canvas layers through a
- * zoomed camera, so it stays sharp at any factor. An instrument whose content is
- * DOM supplies `render` instead: given a camera, draw me again.
- */
-interface LoupeCapability<TS = unknown, TC = unknown> {
-    render?: (args: LoupeRenderArgs<TS, TC>) => ReactNode;
-    /** Opening magnification, clamped to the bounds below. Default 6. */
-    factor?: number;
-    /** What the wheel clamps to. Defaults 2 and 32. */
-    minFactor?: number;
-    maxFactor?: number;
-    /** `'vector'` (default) re-renders the content magnified; `'pixel'` blows up
-     *  the pixels the instrument presented. A `render` loupe is always vector —
-     *  DOM has no framebuffer to enlarge. */
-    mode?: LoupeMode;
-    /** Lens diameter in CSS px. Default 200. */
-    diameter?: number;
-    /** 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 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;
-}
-/** An instrument's loupe declaration. `true` takes every default. */
-type LoupeDeclaration<TS = unknown, TC = unknown> = true | LoupeCapability<TS, TC>;
-/** A {@link LoupeCapability} with every default filled in. */
-interface ResolvedLoupe<TS = unknown, TC = unknown> {
-    render?: (args: LoupeRenderArgs<TS, TC>) => ReactNode;
-    onColorChange?: (hex: string) => void;
-    factor: number;
-    minFactor: number;
-    maxFactor: number;
-    mode: LoupeMode;
-    diameter: number;
-    peekKey: string | null;
-}
-declare const LOUPE_DEFAULTS: {
-    readonly factor: 6;
-    readonly minFactor: 2;
-    readonly maxFactor: 32;
-    readonly mode: "vector";
-    readonly diameter: 200;
-    readonly peekKey: "Alt";
-};
-declare function resolveLoupe<TS, TC>(declared: LoupeDeclaration<TS, TC>): ResolvedLoupe<TS, TC>;
-
-/**
- * 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 {
+/** What shape a mark is. The kinds map onto weasel's own tools; an arrow is a
+ *  line carrying an end marker, not a separate geometry. A point holds one
+ *  entry in `points` and zero-size bounds at that position. */
+type AnnotationKind = 'stroke' | 'line' | 'arrow' | 'rect' | 'ellipse' | 'text' | 'point';
+/** One selectable status in an instrument's meaning tier. */
+interface AnnotationStatus {
     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 a mark in this status is drawn in. Omitted, it takes the default
+     *  mark color — a status is allowed to be a label and nothing more. */
+    color?: 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;
+/** The optional meaning tier: what a mark means, as opposed to where it is.
+ *  An instrument declaring it gets labkit's own chrome for the vocabulary;
+ *  one that omits it keeps `meta` and owns meaning entirely. */
+interface AnnotationMeaning {
+    statuses?: readonly AnnotationStatus[];
 }
-
-/** 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;
-    /** Write one config value, by dotted path — `'grid.size'` for a leaf under
-     *  an `f.group`, `'cellSize'` for one at the root. */
-    setConfig: (path: ConfigPath<TC>, value: unknown) => void;
-    /** labkit persists `view` and restores it on Reset without ever reading
-     *  into it. */
-    trial: TrialInfo & {
-        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;
-        /** The canvas layers currently shown, in declaration order. labkit skips a
-         *  hidden layer's `draw`, so this is the only way to know what was
-         *  painted — a legend listing rows the view did not draw needs it. */
-        visibleLayers: readonly string[];
-    };
-    emit: (event: string) => void;
-    /** Present only when the instrument declares a `job`. */
-    job?: JobHandle;
+/** What labkit keeps in a mark's scene-node data. */
+interface AnnotationData {
+    target: string;
+    kind: AnnotationKind;
+    /** Vertices for the kinds a bounding box cannot describe — a line's two
+     *  ends, a stroke's path. In fractions, like the bounds. */
+    points?: readonly FracPoint[];
+    title?: string;
+    status?: string;
+    tags?: readonly string[];
+    meta?: unknown;
+    /** The target's `positionDependsOn` values when the mark was made. Compared
+     *  against the live config to answer whether the mark still describes the
+     *  same picture. */
+    seen?: Readonly<Record<string, unknown>>;
 }
-/** 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> {
+/** A mark, as the store reports it. `id` is `<target>/<node>`: one scene per
+ *  target means a node id is only unique within one. */
+interface Annotation extends AnnotationData {
     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>[];
-    /** The coordinate system this instrument's world is in. Omitted, world (0,0)
-     *  sits at the canvas top-left with y running down — what labkit assumed
-     *  before an instrument could say otherwise. */
-    worldSpec?: WorldSpec;
-    /** Where the view starts. A function is called once the canvas knows its
-     *  size, so an instrument can frame content it can only place in terms of
-     *  the viewport; until then the trial's view is `null`. */
-    initialView?: ViewTransform | ((size: ViewportSize) => ViewTransform);
-    /** Widens `usePanZoom`'s default clamp; the opening zoom stays reachable
-     *  regardless of these. */
-    minZoom?: number;
-    maxZoom?: number;
+    /** Bounds in fractions of the target's content box. */
+    frac: FracRect;
 }
-/** 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<TS = unknown, TC = unknown> {
-    /** 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;
-    /** Drawn over the content in viewport pixels, outside the camera — a legend,
-     *  a floating panel, anything that must not zoom with the picture. */
-    overlay?: (ctx: RenderContext<TS, TC>) => ReactNode;
-}
-/** 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. `zoom` is always positive and finite once labkit holds
- *  it — see `normalize2DView`. */
-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> {
-    /** 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.
-     *  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;
-    /** 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<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;
-    /** Regions of this instrument that accept marks, and optionally what a mark
-     *  is allowed to mean. Declaring it is what makes the trial provide the
-     *  annotation overlay and its chrome. */
-    annotations?: AnnotationsCapability<TS, TC>;
-    /** Magnification. `true` takes every default and re-draws the instrument's
-     *  canvas layers through a zoomed camera; an instrument whose content is DOM
-     *  gives a `render` that draws it again at a camera it is handed. A function
-     *  is re-read as the config changes, so a setting can drive the lens. */
-    loupe?: LoupeDeclaration<TS, TC> | ((config: TC) => LoupeDeclaration<TS, TC>);
-    /** 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>[];
-
-/** A mark's box in its target's world. Matches weasel's default `RectPose`. */
-type MarkPose = WorldRect;
-/** The scene one target's marks live in. */
-type MarkScene = Scene<AnnotationData, 'marks', MarkPose>;
-/** A mark scene: one layer, because marks do not stack in tiers. */
-declare function createAnnotationScene(): MarkScene;
-interface AnnotationStoreOptions {
-    /** Re-read on every call, so a target resizing or gaining a dependency takes
-     *  effect without rebuilding the store. */
-    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 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;
-    /** Notified after every finished export. */
-    onCapture?: (result: CaptureResult) => void;
-}
-/** Everything a capture needs that is not the store's own state. Split out so
- *  `capture.ts` takes data rather than reaching back into the store. */
-interface CaptureDeps {
-    scene: MarkScene;
-    target: AnnotationTargetInfo;
-    meaning?: AnnotationMeaning;
-    config: unknown;
-}
-/**
- * A facade over one weasel scene per target: the scenes are the truth, this
- * answers questions about them. Everything crossing this boundary is in
- * fractions of a target's content box; the scenes hold world units.
- *
- * A scene per target rather than one scene with a `target` field, because a
- * pane's hit-test, marquee and paint all walk the whole scene it is given and
- * take no filter — one shared scene puts every other pane's marks under the
- * pointer.
- */
-declare function createAnnotationStore(opts: AnnotationStoreOptions): AnnotationsApi;
-/** Rebuild a store from what `toJSON` wrote. Unknown or future versions give
- *  an empty store rather than throwing: a lab that cannot read its marks
- *  should still open. */
-declare function annotationsFromJSON(raw: unknown, targets: () => readonly AnnotationTargetInfo[], rest?: Omit<AnnotationStoreOptions, 'targets' | 'restore'>): AnnotationsApi;
-
-/** A point in fractions of a target's content box. */
-interface FracPoint {
-    x: number;
-    y: number;
-}
-/** A rectangle in fractions of a target's content box.
- *
- *  Fractions rather than pixels because a mark must survive a change of render
- *  resolution: the picture gets bigger, the mark stays on the same feature. */
-interface FracRect {
-    x: number;
-    y: number;
-    w: number;
-    h: number;
-}
-/** What shape a mark is. The kinds map onto weasel's own tools; an arrow is a
- *  line carrying an end marker, not a separate geometry. A point holds one
- *  entry in `points` and zero-size bounds at that position. */
-type AnnotationKind = 'stroke' | 'line' | 'arrow' | 'rect' | 'ellipse' | 'text' | 'point';
-/** One selectable status in an instrument's meaning tier. */
-interface AnnotationStatus {
-    id: string;
-    label: string;
-    /** What a mark in this status is drawn in. Omitted, it takes the default
-     *  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.
- *  An instrument declaring it gets labkit's own chrome for the vocabulary;
- *  one that omits it keeps `meta` and owns meaning entirely. */
-interface AnnotationMeaning {
-    statuses?: readonly AnnotationStatus[];
-}
-/** What labkit keeps in a mark's scene-node data. */
-interface AnnotationData {
-    target: string;
-    kind: AnnotationKind;
-    /** Vertices for the kinds a bounding box cannot describe — a line's two
-     *  ends, a stroke's path. In fractions, like the bounds. */
-    points?: readonly FracPoint[];
-    title?: string;
-    status?: string;
-    tags?: readonly string[];
-    meta?: unknown;
-    /** The target's `positionDependsOn` values when the mark was made. Compared
-     *  against the live config to answer whether the mark still describes the
-     *  same picture. */
-    seen?: Readonly<Record<string, unknown>>;
-}
-/** A mark, as the store reports it. `id` is `<target>/<node>`: one scene per
- *  target means a node id is only unique within one. */
-interface Annotation extends AnnotationData {
-    id: string;
-    /** Bounds in fractions of the target's content box. */
-    frac: FracRect;
-}
-/** A new mark, before the store gives it an id and dates it. */
-interface AnnotationInit {
-    target: string;
-    kind: AnnotationKind;
-    frac: FracRect;
-    points?: readonly FracPoint[];
-    title?: string;
-    status?: string;
-    tags?: readonly string[];
-    meta?: unknown;
+/** A new mark, before the store gives it an id and dates it. */
+interface AnnotationInit {
+    target: string;
+    kind: AnnotationKind;
+    frac: FracRect;
+    points?: readonly FracPoint[];
+    title?: string;
+    status?: string;
+    tags?: readonly string[];
+    meta?: unknown;
 }
 /** Filters, ANDed. A mark matches `tags` when it carries every tag listed. */
 interface AnnotationQuery {
@@ -934,10 +470,16 @@ interface AnnotationStorage {
 }
 /** Declares that an instrument accepts marks: which regions take them,
  *  optionally what a mark is allowed to mean, and optionally where they live. */
+/** The annotation tools a lab's rail can carry. */
+type AnnotationToolId = 'pointer' | 'select' | 'stroke' | 'line' | 'arrow' | 'rect' | 'ellipse' | 'text';
 interface AnnotationsCapability<TS = unknown, TC = unknown> {
     /** `trial` is which trial is asking: a declaration made once per instrument
      *  is called once per trial, and its targets are that trial's own. */
     targets: (state: TS, config: TC, trial: TrialInfo) => readonly AnnotationTarget[];
+    /** Which annotation tools the lab's rail offers. The rail is shared, so it
+     *  carries every tool any annotating instrument asks for, in the kit's own
+     *  order; an instrument that leaves this unset asks for all of them. */
+    tools?: readonly AnnotationToolId[];
     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. */
@@ -955,6 +497,11 @@ interface SerializedAnnotations {
     /** One serialized scene per target that has ever held a mark. */
     scenes: Record<string, unknown>;
 }
+/** One mark, as `AnnotationsApi.paintedMarks` hands it over. */
+interface PaintedMark {
+    mark: PaintableMark;
+    style: MarkStyle;
+}
 /** Everything a host can ask or tell labkit about the marks on its targets. */
 interface AnnotationsApi {
     /** The scene a target's marks live in, created on first ask. One per target
@@ -992,6 +539,10 @@ interface AnnotationsApi {
     /** Take back the most recent mark change, wherever it was made. */
     undo(): boolean;
     redo(): boolean;
+    /** A target's marks as its pane paints them, in scene order: geometry in
+     *  the target's content box, each with the style its status and staleness
+     *  resolve to. For a painter outside the pane — an overview. */
+    paintedMarks(target: string): PaintedMark[];
     /** Export a target's picture with its marks on it. Rejects on an id the
      *  instrument does not declare. */
     capture(target: string, opts?: CaptureOptions): Promise<CaptureResult>;
@@ -1003,38 +554,537 @@ interface AnnotationsApi {
     toJSON(): SerializedAnnotations;
 }
 
-/** A mark's box in its target's world: CSS pixels at zoom 1. Matches weasel's
- *  default `RectPose`, which is what the scene stores. */
-interface WorldRect {
-    x: number;
-    y: number;
+/** How an instrument's world sits on the canvas, independent of the camera.
+ *  The defaults reproduce the convention labkit shipped before this existed:
+ *  world (0,0) at the element's top-left, y growing downward. */
+interface WorldSpec {
+    /** Where world (0,0) sits at `pan` zero, as a fraction of the viewport.
+     *  `{x:0,y:0}` top-left (default); `{x:0.5,y:0.5}` centre. */
+    origin?: Point;
+    /** Which way the world y axis runs on screen. Default `'down'`. */
+    yAxis?: 'down' | 'up';
+}
+/** A viewport's CSS-pixel size. */
+interface ViewportSize {
     width: number;
     height: number;
 }
-/** Where a fraction lands on a content box of this size. */
-declare function fracToWorld(f: FracRect, content: {
-    w: number;
-    h: number;
-}): WorldRect;
-/** What fraction of the content box a world rect covers.
+/** A `WorldSpec` resolved against a viewport: what the coordinate helpers,
+ *  the camera and the wheel all read. */
+interface WorldFrame {
+    /** Screen position of world (0,0) at `pan` zero. */
+    originPx: Point;
+    yDir: 1 | -1;
+}
+declare const DEFAULT_FRAME: WorldFrame;
+declare function resolveFrame(spec: WorldSpec | undefined, size: ViewportSize): WorldFrame;
+/** Put a 2D context into the instrument's world coordinates, so a layer's
+ *  `draw` works in them. Must stay the exact inverse of `screenToWorld`. */
+declare function applyCamera(ctx: CanvasRenderingContext2D, view: ViewTransform, frame?: WorldFrame): void;
+
+/** A named position in a trial's chrome. Content is not a region — that is
+ *  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 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. */
+    shortcut?: string;
+    disabled?: boolean;
+    /** Reddens on hover. For actions that discard work. */
+    danger?: boolean;
+    /** A toggle rather than a command: renders `aria-pressed` and reads as held
+     *  down while true. */
+    pressed?: boolean;
+    /** Render the label beside the glyph rather than only in the tooltip. */
+    showLabel?: boolean;
+    /** 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 tool in the palette region: a mode by default, a command when it carries
+ *  an `onActivate`. `TCtx` is the chrome context that handler is handed — a
+ *  trial's, or the lab's for a lab-level rail. */
+interface ToolItem<TCtx = TrialChromeContext> {
+    icon: IconComponent;
+    label: string;
+    /** Shown in the tooltip. Not bound here — the trial owns its keymap. */
+    shortcut?: string;
+    disabled?: boolean;
+    /** Runs on press instead of selecting. An item with one is a command: it
+     *  never writes the tool slot, and never reads as the current tool. */
+    onActivate?: (ctx: TCtx) => void;
+}
+/** A titled block in the sidebar. `stance` and `tone` work as on a
+ *  `<PropertyPanel>`: what kind of content the section holds, and which of its
+ *  peers it is. */
+interface SidebarSection extends StanceProps {
+    title: string;
+    /** Starts collapsed, until the trial remembers a fold of its own. */
+    defaultCollapsed?: boolean;
+    /** Offer the tear-out control. On by default; a section that only makes
+     *  sense beside its trial sets this false. */
+    undockable?: boolean;
+    /** Where the tear-out control sends it. Default `'tile'`. */
+    undockAs?: 'tile' | 'floating';
+    body: ReactNode;
+}
+/** A control acting on the view of the trial, not on the trial. */
+interface ViewportControl<TCtx = TrialChromeContext> {
+    icon: IconComponent;
+    label: string;
+    disabled?: boolean;
+    /** Handed the trial's chrome context, as `ToolbarItem.onActivate` is. */
+    onActivate: (ctx: TCtx) => 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, whichever chrome it is declared against. */
+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;
+});
+/**
+ * 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 extends ToolSlotContext, SidebarSlotContext {
+    trialId: string;
+    instrumentName: string;
+    /** 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's title. Persisted with
+     *  the trial, so a title survives a reload. */
+    setTitle: (title: string | null) => void;
+    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;
+    /** Whether the trial's loupe is turned on. False for an instrument that
+     *  declares none, whose chrome offers no way to turn one on. */
+    loupeOn: boolean;
+    toggleLoupe: () => 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;
+    /** The trial's unpinned paths. `config` stays raw, so a control drawn from
+     *  it sits at the value un-pinning writes back. */
+    auto: ReadonlySet<string>;
+    setConfig: (key: string, value: unknown) => void;
+    /** Which of this trial's collapsible sections are folded. A sidebar
+     *  section's key is its contribution id; a section *inside* a contribution —
+     *  a control panel's property group — is keyed `<contribution id>/<label>`.
+     *  A section absent here is at its own default. Persisted with the trial. */
+    collapsedSections: Readonly<Record<string, boolean>>;
+    /** Fold or unfold one section, keyed as `collapsedSections` is. */
+    setSectionCollapsed: (key: string, collapsed: boolean) => void;
+    /** Section ids this trial currently has torn out of its sidebar. */
+    undockedPanels: readonly string[];
+    /** Tear a sidebar section out into the workspace. */
+    undockPanel: (sectionId: string, as?: 'tile' | 'floating') => void;
+    /** Put a torn-out section back in the sidebar. */
+    dockPanel: (sectionId: string) => void;
+    savedSnapshots: SavedSnapshot[];
+    saveSnapshot: (name?: string) => void;
+    loadSnapshot: (snapshotId: string) => void;
+    clone: () => void;
+    reset: () => void;
+    close: () => void;
+}
+
+/** A point on the magnified surface, in its own CSS pixels. */
+interface LoupePoint {
+    x: number;
+    y: number;
+}
+
+/** How a loupe magnifies. `'vector'` re-renders the source through a zoomed-in
+ *  view, so content stays sharp at any factor; `'pixel'` blows up the actual
+ *  pixels the surface presented. */
+type LoupeMode = 'vector' | 'pixel';
+
+/** What a DOM instrument's loupe `render` is handed: the same data its own
+ *  `render` gets, and the camera to draw it through. */
+interface LoupeRenderArgs<TS = unknown, TC = unknown> {
+    state: TS;
+    config: TC;
+    /** The trial's own camera composed with the magnification, about the aimed
+     *  point — so drawing the same content through it magnifies in place. */
+    view: ViewTransform;
+    /** The magnification on its own, for whatever must not scale with the
+     *  camera. */
+    factor: number;
+    mode: LoupeMode;
+    /** The size of the viewport `view` is written for: the trial's content well,
+     *  not the lens. The lens shows a circle cut out of it. */
+    size: ViewportSize;
+}
+/**
+ * Declares that an instrument can be magnified.
+ *
+ * With no `render`, the loupe re-draws the instrument's canvas layers through a
+ * zoomed camera, so it stays sharp at any factor. An instrument whose content is
+ * DOM supplies `render` instead: given a camera, draw me again.
+ */
+interface LoupeCapability<TS = unknown, TC = unknown> {
+    render?: (args: LoupeRenderArgs<TS, TC>) => ReactNode;
+    /** Opening magnification, clamped to the bounds below. Default 6. */
+    factor?: number;
+    /** What the wheel clamps to. Defaults 2 and 32. */
+    minFactor?: number;
+    maxFactor?: number;
+    /** `'vector'` (default) re-renders the content magnified; `'pixel'` blows up
+     *  the pixels the instrument presented. A `render` loupe is always vector —
+     *  DOM has no framebuffer to enlarge. */
+    mode?: LoupeMode;
+    /** Lens diameter in CSS px. Default 200. */
+    diameter?: number;
+    /** 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 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;
+}
+/** An instrument's loupe declaration. `true` takes every default. */
+type LoupeDeclaration<TS = unknown, TC = unknown> = true | LoupeCapability<TS, TC>;
+/** A {@link LoupeCapability} with every default filled in. */
+interface ResolvedLoupe<TS = unknown, TC = unknown> {
+    render?: (args: LoupeRenderArgs<TS, TC>) => ReactNode;
+    onColorChange?: (hex: string) => void;
+    factor: number;
+    minFactor: number;
+    maxFactor: number;
+    mode: LoupeMode;
+    diameter: number;
+    peekKey: string | null;
+}
+declare const LOUPE_DEFAULTS: {
+    readonly factor: 6;
+    readonly minFactor: 2;
+    readonly maxFactor: 32;
+    readonly mode: "vector";
+    readonly diameter: 200;
+    readonly peekKey: "Alt";
+};
+declare function resolveLoupe<TS, TC>(declared: LoupeDeclaration<TS, TC>): ResolvedLoupe<TS, TC>;
+
+/**
+ * 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;
+    /** Write one config value, by dotted path — `'grid.size'` for a leaf under
+     *  an `f.group`, `'cellSize'` for one at the root. */
+    setConfig: (path: ConfigPath<TC>, value: unknown) => void;
+    /** labkit persists `view` and restores it on Reset without ever reading
+     *  into it. */
+    trial: TrialInfo & {
+        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;
+        /** The canvas layers currently shown, in declaration order. labkit skips a
+         *  hidden layer's `draw`, so this is the only way to know what was
+         *  painted — a legend listing rows the view did not draw needs it. */
+        visibleLayers: readonly string[];
+        /**
+         * Where the pointer is over this trial, in the instrument's world:
+         * `get()` answers `{ worldX, worldY, viewId }`, where `viewId` is
+         * `'stage'` over the trial's own camera and `'overview'` over its
+         * `<TrialOverview>`, or `null` when it is over neither. A key handler
+         * reading it works over either view.
+         */
+        pointer: PointerContextValue;
+    };
+    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.
  *
- *  A pane measured before layout is 0×0, and dividing by that would seed every
- *  stored position with `NaN` — which compares false against everything and so
- *  fails silently rather than loudly. Zero sides give zeros. */
-declare function worldToFrac(r: WorldRect, content: {
-    w: number;
-    h: number;
-}): FracRect;
-/** Snap to 4dp. Positions are diffed by humans in stored documents, so the
- *  last digits of a float are noise that hides the change that matters. */
-declare function roundFrac(f: FracRect): FracRect;
-/** Whether `pt` falls in `box`, widened by `tol` on every side so a hairline
- *  mark stays reachable. */
-declare function fracContains(box: FracRect, pt: FracPoint, tol?: number): boolean;
-/** Whether `outer` wholly encloses `inner`. A marquee takes what it encloses,
- *  not what it grazes — brushing selection is a different gesture, and this
- *  answers false for two rects that merely overlap. */
-declare function fracEncloses(outer: FracRect, inner: FracRect): boolean;
+ *  `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>[];
+    /** The coordinate system this instrument's world is in. Omitted, world (0,0)
+     *  sits at the canvas top-left with y running down — what labkit assumed
+     *  before an instrument could say otherwise. */
+    worldSpec?: WorldSpec;
+    /** Where the view starts. A function is called once the canvas knows its
+     *  size, so an instrument can frame content it can only place in terms of
+     *  the viewport; until then the trial's view is `null`. */
+    initialView?: ViewTransform | ((size: ViewportSize) => ViewTransform);
+    /** Widens the camera's default zoom clamp; the opening zoom stays reachable
+     *  regardless of these. */
+    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<TS = unknown, TC = unknown> {
+    /** 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;
+    /** Drawn over the content in viewport pixels, outside the camera — a legend,
+     *  a floating panel, anything that must not zoom with the picture. */
+    overlay?: (ctx: RenderContext<TS, TC>) => ReactNode;
+}
+/** 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. `zoom` is always positive and finite once labkit holds
+ *  it — see `normalize2DView`. */
+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> {
+    /** 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.
+     *  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;
+    /** 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<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;
+    /** Regions of this instrument that accept marks, and optionally what a mark
+     *  is allowed to mean. Declaring it is what makes the trial provide the
+     *  annotation overlay and its chrome. */
+    annotations?: AnnotationsCapability<TS, TC>;
+    /** Magnification. `true` takes every default and re-draws the instrument's
+     *  canvas layers through a zoomed camera; an instrument whose content is DOM
+     *  gives a `render` that draws it again at a camera it is handed. A function
+     *  is re-read as the config changes, so a setting can drive the lens. */
+    loupe?: LoupeDeclaration<TS, TC> | ((config: TC) => LoupeDeclaration<TS, TC>);
+    /** 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 { DEFAULT_FRAME as D, fracContains as aA, fracEncloses as aB, fracToWorld as aC, isAuto as aD, resolveLoupe as aE, roundFrac as aF, worldToFrac as aG, LOUPE_DEFAULTS as ab, annotationsFromJSON as aw, auto as ax, createAnnotationScene as ay, createAnnotationStore as az, applyCamera as c, dockPanel as l, panelKey as p, resolveFrame as r, undockPanel as u };
-export type { AnnotationStatus as $, AnnotationData as A, CaptureOptions as B, CreateLabStoreOptions as C, CaptureResult as E, AnnotationTarget as F, AnnotationsApi as G, AnnotationsCapability as H, InstrumentSerializers as I, TrialInfo as J, TrialTool as K, LayerCapability as L, Migration as M, AnnotationKind as N, Instrument as O, PaletteItem as P, LabDensity as Q, TrialContribution as R, SerializedTrial as S, TrialRecord as T, UndoStack as U, ViewportSize as V, WorldFrame as W, Annotation as X, AnnotationInit as Y, AnnotationPatch as Z, AnnotationQuery as _, LayerDescriptor as a, AnnotationStoreOptions as a0, AnnotationTargetInfo as a1, Auto as a2, CanvasCapability as a3, CanvasLayer as a4, CaptureDeps as a5, ContributionBase as a6, FracPoint as a7, FracRect as a8, HitResult as a9, LoupePoint as aH, LoupeMode as aI, IconComponent as aa, LoupeCapability as ac, LoupeDeclaration as ad, LoupeRenderArgs as ae, RegionContribution as af, RenderContext as ag, ResolvedLoupe as ah, SerializedAnnotations as ai, SidebarSection as aj, SidebarSlotContext as ak, StageCapability as al, StatusReadout as am, SystemEvent as an, ToolCapability as ao, ToolItem as ap, ToolSlotContext as aq, ToolbarItem as ar, TrialChromeContext as as, TrialRegion as at, UndoCapability as au, ViewportControl as av, WorldSpec as b, StorageAdapter as d, LabDocument as e, LabStoreState as f, SavedSnapshot as g, StorageChange as h, TrialStateHandle as i, UndockedPanel as j, UndockedPanels as k, ViewTransform as m, Point as n, DragFeedback as o, DragDropCapability as q, LabMode as s, InstrumentList as t, InstrumentHooks as v, WorldRect as w, AnnotationMeaning as x, MarkScene as y, CaptureSource as z };
+export { DEFAULT_FRAME as D, annotationsFromJSON as aB, auto as aC, createAnnotationScene as aD, createAnnotationStore as aE, fracContains as aF, fracEncloses as aG, fracToWorld as aH, isAuto as aI, markCommands as aJ, resolveLoupe as aK, roundFrac as aL, worldToFrac as aM, LOUPE_DEFAULTS as ae, dockPanel as k, applyCamera as m, panelKey as p, resolveFrame as r, undockPanel as u };
+export type { AnnotationPatch as $, AnnotationMeaning as A, CaptureSource as B, CreateLabStoreOptions as C, CaptureOptions as E, CaptureResult as F, PaintableMark as G, AnnotationTarget as H, InstrumentSerializers as I, AnnotationsApi as J, AnnotationsCapability as K, LayerCapability as L, Migration as M, TrialInfo as N, TrialTool as O, Point as P, AnnotationKind as Q, Instrument as R, SerializedTrial as S, TrialRecord as T, UndoStack as U, ViewportSize as V, WorldFrame as W, LabDensity as X, TrialContribution as Y, Annotation as Z, AnnotationInit as _, LayerDescriptor as a, AnnotationQuery as a0, AnnotationStatus as a1, AnnotationStoreOptions as a2, AnnotationTargetInfo as a3, AnnotationToolId as a4, Auto as a5, CanvasCapability as a6, CanvasLayer as a7, CaptureDeps as a8, ContributionBase as a9, ViewportControl as aA, FracPoint as aa, FracRect as ab, HitResult as ac, IconComponent as ad, LoupeCapability as af, LoupeDeclaration as ag, LoupeMode as ah, LoupePoint as ai, LoupeRenderArgs as aj, RegionContribution as ak, RenderContext as al, ResolvedLoupe as am, SerializedAnnotations as an, SidebarSection as ao, SidebarSlotContext as ap, StageCapability as aq, StatusReadout as ar, SystemEvent as as, ToolCapability as at, ToolItem as au, ToolSlotContext as av, ToolbarItem as aw, TrialChromeContext as ax, TrialRegion as ay, UndoCapability as az, ViewTransform as b, StorageAdapter as c, LabDocument as d, LabStoreState as e, SavedSnapshot as f, StorageChange as g, TrialStateHandle as h, UndockedPanel as i, UndockedPanels as j, WorldSpec as l, PaletteItem as n, DragFeedback as o, DragDropCapability as q, LabMode as s, InstrumentList as t, InstrumentHooks as v, AnnotationData as w, WorldRect as x, MarkStyle as y, MarkScene as z };