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

package/dist/_dts/frac-Cp3NivlC.d.ts

@@ -0,0 +1,728 @@
+import { ComponentType, ReactNode, RefObject } from 'react';
+import { R as ResolvedConfig, C as ConfigField, a as ConfigSchema } from './types-D6s4b7if.js';
+import { c as SavedSnapshot } from './types-DYMaEvM5.js';
+import { J as JobHandle, a as JobCapability } from './types-DJ79Tg5J.js';
+import { S as Scene } from './types-C-gh9Ap-.js';
+
+/** 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;
+
+/** 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;
+    /** 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;
+    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;
+    /** 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 {
+    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;
+    /** 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;
+    setConfig: (key: string, value: unknown) => 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;
+    /** 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;
+}
+
+/** 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 colour 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;
+    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;
+        /** 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;
+}
+/** 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>[];
+    /** 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;
+}
+/** 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;
+    /** 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 colour its
+     *  status gives it. */
+    meaning?: AnnotationMeaning;
+    /** 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. */
+type AnnotationKind = 'stroke' | 'line' | 'arrow' | 'rect' | 'ellipse' | 'text';
+/** 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 colour — 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;
+}
+/** Filters, ANDed. A mark matches `tags` when it carries every tag listed. */
+interface AnnotationQuery {
+    target?: string;
+    kind?: AnnotationKind;
+    status?: string;
+    tags?: readonly string[];
+    where?: (a: Annotation) => boolean;
+}
+/** What a mark's meaning can be patched to. Geometry moves through `frac` /
+ *  `points`; everything else is the meaning tier. */
+type AnnotationPatch = Partial<Pick<Annotation, 'frac' | 'points' | 'title' | 'status' | 'tags' | 'meta'>>;
+/** A target's own picture, handed over for an export to draw marks on top of.
+ *  labkit cannot rasterize it: it is the consumer's DOM. `svg` is the one that
+ *  keeps the export vector all the way through. */
+type CaptureSource = {
+    kind: 'svg';
+    markup: string;
+} | {
+    kind: 'image';
+    src: string;
+} | {
+    kind: 'canvas';
+    canvas: HTMLCanvasElement;
+};
+/** What an export produces, and at what resolution. */
+interface CaptureOptions {
+    /** `png` rasterizes; `svg` stays vector, which needs the base to be one too
+     *  — a raster base embeds as an `<image>`. Default `png`. */
+    format?: 'png' | 'svg';
+    /** Output pixels per unit of the target's content box. Default 2. */
+    scale?: number;
+}
+/** A finished export. `width`/`height` are the output's, not the content
+ *  box's — `content × scale`. */
+interface CaptureResult {
+    target: string;
+    blob: Blob;
+    format: 'png' | 'svg';
+    width: number;
+    height: number;
+}
+/** What the store needs to know about a target: enough to convert a position
+ *  and to date a mark. `AnnotationTarget` adds what only the overlay reads. */
+interface AnnotationTargetInfo {
+    id: string;
+    /** Intrinsic content size in CSS pixels at zoom 1 — the box fractions are
+     *  fractions *of*, and the target's world. */
+    content: {
+        w: number;
+        h: number;
+    };
+    /** Config keys whose change means a stored position no longer refers to the
+     *  same picture. labkit snapshots and compares them without knowing what any
+     *  of them mean. */
+    positionDependsOn?: readonly string[];
+    /** The target's own picture, for an export to draw marks over. A target
+     *  declaring none exports its marks on transparency, which fails visibly
+     *  rather than producing a blank brick.
+     *
+     *  Here rather than on `AnnotationTarget` because the store is what calls
+     *  it: `ref` and `view` are the React-shaped half only the overlay reads. */
+    base?: () => CaptureSource | Promise<CaptureSource>;
+}
+/** One region of an instrument that accepts marks. */
+interface AnnotationTarget extends AnnotationTargetInfo {
+    /** The element the overlay tracks and takes input from. */
+    ref: RefObject<HTMLElement | null>;
+    /** The pane's camera, mirrored so marks pan and zoom with what they mark. */
+    view?: ViewTransform;
+}
+/** Where an instrument keeps its own marks. Declaring this means labkit never
+ *  writes its trial slot — for an instrument whose marks belong in a format it
+ *  already owns. Both halves are called outside React; `save` is already
+ *  debounced by the time it arrives. */
+interface AnnotationStorage {
+    load: () => SerializedAnnotations | null | undefined;
+    save: (doc: SerializedAnnotations) => void;
+}
+/** Declares that an instrument accepts marks: which regions take them,
+ *  optionally what a mark is allowed to mean, and optionally where they live. */
+interface AnnotationsCapability<TS = unknown, TC = unknown> {
+    targets: (state: TS, config: TC) => readonly AnnotationTarget[];
+    meaning?: AnnotationMeaning;
+    storage?: AnnotationStorage;
+    /** Fires after every finished export, labkit's own chrome included. A
+     *  notification, not an interception: a host wanting its own flow calls
+     *  `capture()` from its own UI, which is the surface the chrome uses. */
+    onCapture?: (result: CaptureResult) => void;
+}
+/** A persisted mark set. Versioned by this arc rather than by labkit's
+ *  document migrations, which only ever reach top-level document sections and
+ *  never into a trial's state. */
+interface SerializedAnnotations {
+    version: 1;
+    /** One serialized scene per target that has ever held a mark. */
+    scenes: Record<string, unknown>;
+}
+/** 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
+     *  because a pane's hit-test, marquee and paint walk the whole scene they
+     *  are given: a shared one would put a neighbour's marks under the pointer. */
+    sceneFor(target: string): MarkScene;
+    /** The targets the instrument declares, in declaration order. Chrome needs
+     *  the list and cannot get it from the capability, which wants instrument
+     *  state the chrome context does not carry. */
+    targets(): readonly AnnotationTargetInfo[];
+    get(id: string): Annotation | undefined;
+    /** Every mark matching the filters, in scene order. Omit `q` for all. */
+    query(q?: AnnotationQuery): Annotation[];
+    /** Marks whose bounds contain `pt`, topmost first. `tol` widens the hit in
+     *  fractions, so a hairline mark stays reachable. */
+    hitTest(target: string, pt: FracPoint, tol?: number): Annotation[];
+    /** Marks wholly inside `box` — a marquee, not a brush. */
+    within(target: string, box: FracRect): Annotation[];
+    /** Whether `a`'s position still describes the picture `config` produces. */
+    isStale(a: Annotation, config: unknown): boolean;
+    /** Fires after every mutation. No delta: the scene does not diff, so
+     *  re-query rather than expecting a change payload. */
+    subscribe(fn: () => void): () => void;
+    /** Whether the last mark change on any target can be taken back. Weasel
+     *  history is the authority; this only decides *which* target's. */
+    canUndo(): boolean;
+    canRedo(): boolean;
+    /** Take back the most recent mark change, wherever it was made. */
+    undo(): boolean;
+    redo(): boolean;
+    /** 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>;
+    add(init: AnnotationInit, config?: unknown): string;
+    update(id: string, patch: AnnotationPatch): void;
+    setMeta(id: string, meta: unknown): void;
+    remove(id: string): void;
+    /** A JSON-safe snapshot for `record.state`. */
+    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;
+    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 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. */
+declare function fracIntersects(outer: FracRect, inner: FracRect): boolean;
+
+export { LOUPE_DEFAULTS as L, annotationsFromJSON as a3, applyCamera as a4, createAnnotationScene as a5, createAnnotationStore as a6, fracContains as a7, fracIntersects as a8, fracToWorld as a9, resolveFrame as aa, resolveLoupe as ab, roundFrac as ac, worldToFrac as ad, DEFAULT_FRAME as x };
+export type { TrialRegion as $, AnnotationData as A, LayerCapability as B, CaptureSource as C, DragFeedback as D, LayerDescriptor as E, FracPoint as F, LoupeCapability as G, HitResult as H, Instrument as I, LoupeDeclaration as J, LoupeRenderArgs as K, MarkScene as M, ResolvedLoupe as N, SidebarSection as O, PaletteItem as P, StatusReadout as Q, RenderContext as R, SerializedAnnotations as S, TrialTool as T, SystemEvent as U, ViewTransform as V, WorldFrame as W, ToolCapability as X, ToolItem as Y, ToolbarItem as Z, TrialChromeContext as _, Point as a, UndoCapability as a0, ViewportControl as a1, ViewportSize as a2, LoupeMode as ae, DragDropCapability as b, WorldSpec as c, WorldRect as d, AnnotationMeaning as e, CaptureOptions as f, CaptureResult as g, AnnotationTarget as h, AnnotationsApi as i, AnnotationsCapability as j, AnnotationKind as k, InstrumentList as l, TrialContribution as m, Annotation as n, AnnotationInit as o, AnnotationPatch as p, AnnotationQuery as q, AnnotationStatus as r, AnnotationStoreOptions as s, AnnotationTargetInfo as t, CanvasCapability as u, CanvasLayer as v, CaptureDeps as w, FracRect as y, IconComponent as z };