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

package/dist/index.d.ts

@@ -2,27 +2,92 @@ export { LayerStack, LayerStackItem, LayerStackProps } from './ui/layers/index.j
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import * as react from 'react';
 import { ReactNode, WheelEvent, PointerEvent } from 'react';
-export { CanvasLayerDescriptor, CanvasStack, CanvasStackContext, CanvasStackContextValue, CanvasStackProps, screenToWorld, worldToScreen } from './canvas/index.js';
+export { C as CheckboxRow, a as CheckboxRowProps, b as ColorRow, c as ColorRowProps, d as ControlPanel, N as NumberRow, e as NumberRowProps, P as PropertyList, f as PropertyListPack, g as PropertyListProps, h as PropertyOption, i as PropertyPanel, j as PropertyPanelProps, k as PropertyRow, l as PropertyRowLayout, m as PropertyRowProps, n as PropertyRowVariant, o as PropertySpan, p as PropertySpanProps, S as SelectRow, q as SelectRowProps, r as SliderRow, s as SliderRowProps, T as TextRow, t as TextRowProps, u as ToggleRow, v as ToggleRowProps } from './_dts/index-BDVzvRzQ.js';
+import { N as Node, P as Path } from './_dts/types-C-gh9Ap-.js';
+import { F as FillStyle, S as Stroke, D as DrawCommand, V as View, T as TextStyle } from './_dts/DrawCommand-B3bskUsC.js';
+import { d as WorldRect, A as AnnotationData, e as AnnotationMeaning, M as MarkScene, C as CaptureSource, f as CaptureOptions, g as CaptureResult, h as AnnotationTarget, i as AnnotationsApi, j as AnnotationsCapability, T as TrialTool, k as AnnotationKind, V as ViewTransform, I as Instrument, l as InstrumentList, m as TrialContribution } from './_dts/frac-Cp3NivlC.js';
+export { n as Annotation, o as AnnotationInit, p as AnnotationPatch, q as AnnotationQuery, r as AnnotationStatus, s as AnnotationStoreOptions, t as AnnotationTargetInfo, u as CanvasCapability, v as CanvasLayer, w as CaptureDeps, x as DEFAULT_FRAME, b as DragDropCapability, D as DragFeedback, F as FracPoint, y as FracRect, H as HitResult, z as IconComponent, L as LOUPE_DEFAULTS, B as LayerCapability, E as LayerDescriptor, G as LoupeCapability, J as LoupeDeclaration, K as LoupeRenderArgs, P as PaletteItem, a as Point, R as RenderContext, N as ResolvedLoupe, S as SerializedAnnotations, O as SidebarSection, Q as StatusReadout, U as SystemEvent, X as ToolCapability, Y as ToolItem, Z as ToolbarItem, _ as TrialChromeContext, $ as TrialRegion, a0 as UndoCapability, a1 as ViewportControl, a2 as ViewportSize, W as WorldFrame, c as WorldSpec, a3 as annotationsFromJSON, a4 as applyCamera, a5 as createAnnotationScene, a6 as createAnnotationStore, a7 as fracContains, a8 as fracIntersects, a9 as fracToWorld, aa as resolveFrame, ab as resolveLoupe, ac as roundFrac, ad as worldToFrac } from './_dts/frac-Cp3NivlC.js';
+import { B as BuiltinShapeToolId } from './_dts/shapeKinds-Cx_rxwsa.js';
+export { CanvasStack, CanvasStackProps, ZoomAtOptions, centerOn, screenToWorld, worldToScreen, zoomAt } from './canvas/index.js';
+export { C as CanvasLayerDescriptor, a as CanvasStackContext, b as CanvasStackContextValue, c as CanvasStackSurface } from './_dts/CanvasStackContext-DtAn_3O-.js';
 export { PaletteRegion, PaletteRegionProps, SidebarRegion, SidebarRegionProps, StatusRegion, StatusRegionProps, TitleBarRegion, TitleBarRegionProps, ToolbarRegion, ToolbarRegionProps, ViewportRegion, ViewportRegionProps, builtinContributions, mergeContributions, suppressContributions } from './chrome/index.js';
-import { I as Instrument, c as InstrumentList, T as TrialContribution, d as TrialTool, V as ViewTransform } from './_dts/types-BttTIent.js';
-export { C as CanvasCapability, e as CanvasLayer, b as DragDropCapability, D as DragFeedback, H as HitResult, f as IconComponent, L as LayerCapability, g as LayerDescriptor, P as PaletteItem, a as Point, R as RenderContext, S as SidebarSection, h as StatusReadout, i as SystemEvent, j as ToolCapability, k as ToolItem, l as ToolbarItem, m as TrialChromeContext, n as TrialRegion, U as UndoCapability, o as ViewportControl } from './_dts/types-BttTIent.js';
-import { T as ToolPrefLeaf } from './_dts/PrefsForm-BYa6cWnO.js';
-import { b as ConfigNode, A as Annotations, N as NodeOptions, c as ControlRenderer, d as ConfigOption, a as ConfigSchema, I as InferConfig, C as ConfigField, R as ResolvedConfig, e as ConfigRule, L as LeafPatch, f as ConfigRuleContext } from './_dts/types-DCGEcMO_.js';
-export { g as CheckboxField, h as ColorField, i as ConfigFieldBase, j as ConfigFieldType, k as ConfigOf, l as NodeValue, m as NumberField, S as SectionSpec, n as SelectField, o as SelectOption, p as SliderField, T as TextField } from './_dts/types-DCGEcMO_.js';
-export { ControlPanel } from './controls/index.js';
+import { T as ToolPrefLeaf } from './_dts/PrefsForm-BkUJZx0A.js';
+import { b as ConfigNode, A as Annotations, N as NodeOptions, c as ControlRenderer, d as ConfigOption, a as ConfigSchema, I as InferConfig, C as ConfigField, R as ResolvedConfig, e as ConfigRule, L as LeafPatch, f as ConfigRuleContext } from './_dts/types-D6s4b7if.js';
+export { g as CheckboxField, h as ColorField, i as ConfigFieldBase, j as ConfigFieldType, k as ConfigOf, l as NodeValue, m as NumberField, S as SectionSpec, n as SelectField, o as SelectOption, p as SliderField, T as TextField } from './_dts/types-D6s4b7if.js';
 import { J as JobHandle } from './_dts/types-DJ79Tg5J.js';
 export { a as JobCapability, b as JobEvent, c as JobFailure, d as JobStatus } from './_dts/types-DJ79Tg5J.js';
 export { UseJobOptions, useJob } from './job/index.js';
-import { a as StorageAdapter, e as LabMode, T as TrialRecord, c as SavedSnapshot } from './_dts/types-1Sdxy_Pv.js';
-export { C as CreateLabStoreOptions, L as LabDocument, b as LabStoreState, S as SerializedTrial, d as TrialStateHandle, U as UndoStack } from './_dts/types-1Sdxy_Pv.js';
+import { a as StorageAdapter, h as LabMode, T as TrialRecord, c as SavedSnapshot } from './_dts/types-DYMaEvM5.js';
+export { C as CreateLabStoreOptions, L as LabDocument, b as LabStoreState, S as SerializedTrial, d as TrialStateHandle, U as UndoStack, e as UndockedPanel, f as UndockedPanels, g as dockPanel, p as panelKey, u as undockPanel } from './_dts/types-DYMaEvM5.js';
 export { LayerList, LayerListProps } from './layers/index.js';
+export { CanvasLoupe, CanvasLoupeProps, DomLoupe, DomLoupeProps, LensCamera, LoupeBubble, LoupeBubbleProps, LoupeState, SourceRect, TrialLoupe, TrialLoupeProps, UseLoupeOptions, drawCanvasLens, lensCamera, lensSourceRect, sampleStack, useLoupe } from './loupe/index.js';
 export { FloatingPanel, FloatingPanelProps, FpsMeter, JobProgress, JobProgressProps, Legend, LegendEntry, LegendMark, LegendProps, ScaleIndicator, ScaleIndicatorProps, Sidebar, SidebarProps, StatusBar, StatusBarProps, StatusBarSectionProps, Toolbar, ToolbarButtonProps, ToolbarGroupProps, ToolbarProps, ZoomControl, ZoomControlProps } from './primitives/index.js';
-export { C as CURRENT_DOCUMENT_VERSION, b as LabStoreContext, c as LabStoreProvider, T as TrialIdContext, d as TrialIdProvider, f as createMemoryAdapter, l as labDocumentKey, g as localStorageAdapter, n as noneAdapter, q as quarantineKey, s as sessionStorageAdapter, u as urlHashAdapter, h as useLabStore, i as useTrialId, j as useTrialState } from './_dts/useTrialState-CsGMjhu9.js';
-export { Box, Rect, SurfaceContext, SurfaceFrame, SurfaceHandle, UseTiledSurfaceOptions, composeRects, rectsEqual, toDeviceRect, useSurface, useSurfaceOptional, useSurfaceTile, useTiledSurface } from './surface/index.js';
+export { C as CURRENT_DOCUMENT_VERSION, b as LabStoreContext, c as LabStoreProvider, T as TrialIdContext, d as TrialIdProvider, f as createMemoryAdapter, l as labDocumentKey, g as localStorageAdapter, n as noneAdapter, q as quarantineKey, s as sessionStorageAdapter, u as urlHashAdapter, h as useLabStore, i as useTrialId, j as useTrialState } from './_dts/useTrialState-gmMvZqPc.js';
+export { Box, Rect, SurfaceCanvasContext, SurfaceContext, SurfaceFrame, SurfaceHandle, TilePainter, UseTiledSurfaceOptions, composeRects, rectsEqual, toDeviceRect, useSurface, useSurfaceCanvas, useSurfaceOptional, useSurfaceTile, useTiledSurface } from './surface/index.js';
 export { EventBus, EventListener, clearUndo, createEventBus, emptyStack, pushSnapshot, redo, undo } from './undo/index.js';
 import 'windease';
 import 'zustand/vanilla';
 
+/**
+ * Canonical inline-styling primitive for text nodes. A node's text is
+ * either a plain `string` (treated as a single-run, default-styled fragment)
+ * or `StyledRun[]` for rich content. `toRuns` is the funnel that normalizes
+ * either form into the array shape used by the renderer.
+ *
+ * Every field except `text` is optional; missing fields fall back to the
+ * node-level `TextStyle`. `bold`/`italic` are toggles; richer weight axes
+ * (300/500/900) are out of scope for slice 1.
+ */
+
+/** A span of text with its own styling, as authored. Fields left absent
+ *  inherit from the node's text style — this is the difference between a run
+ *  and a fully resolved one. */
+interface StyledRun {
+    text: string;
+    bold?: boolean;
+    italic?: boolean;
+    fontFamily?: string;
+    fontSize?: number;
+    fill?: FillStyle;
+    /** Outline over this run's glyphs. Overrides the node's own `data.stroke`;
+     *  absent inherits it. Only painted on the outline tier. */
+    stroke?: Stroke;
+    letterSpacing?: number;
+    underline?: boolean;
+    strikethrough?: boolean;
+    /** Draw a rule above this run's ascent. Additive over the node style. */
+    overline?: boolean;
+    /**
+     * Set this run as a superscript or subscript — a raised or lowered baseline
+     * and a smaller size together, which is the pair `<sup>` and `<sub>` imply.
+     *
+     * A preset over the two primitives below, not a third mechanism: it supplies
+     * a `baselineShift` and a `fontScale`, and naming either of those directly
+     * overrides that half while leaving the other alone. The numbers are in
+     * {@link SCRIPT_METRICS}.
+     */
+    script?: 'super' | 'sub';
+    /**
+     * Raise (positive) or lower (negative) this run off the line's shared
+     * baseline, in ems of the *inherited* font size — so a run's rise does not
+     * shrink along with the run when `fontScale` also applies.
+     */
+    baselineShift?: number;
+    /**
+     * Multiplier on the inherited font size. The relative counterpart to
+     * `fontSize`, which pins an absolute size and wins over this when both are
+     * present.
+     */
+    fontScale?: number;
+}
+
+/** Built-in tool ids that aren't shape tools — the ones with no entry in
+ *  the `core/shapeKinds` table. */
+declare const NON_SHAPE_BUILTIN_TOOLS: readonly ["select", "rotate", "hand"];
+/** Built-in tool ids SceneCanvas knows how to mount when no `tools` prop
+ *  is supplied. Pass a subset via `defaultTools` to slim the registered set. */
+type BuiltinToolId = (typeof NON_SHAPE_BUILTIN_TOOLS)[number] | BuiltinShapeToolId;
+
 /** An annotation drawn over a curve plot: a shaded band across a range of x,
  *  or a vertical line at one x. */
 type CurveMark = {
@@ -150,185 +215,435 @@ interface PropertyGroupProps {
  */
 declare function PropertyGroup({ title, hidden, children, className, pack, }: PropertyGroupProps): react_jsx_runtime.JSX.Element | null;
 
-/** Props for `<PropertyPanel>`. */
-interface PropertyPanelProps {
-    title?: ReactNode;
-    children: ReactNode;
-    className?: string;
+/** The subset of a mark's scene node this needs: where it is, and what it is. */
+interface PaintableMark {
+    pose: WorldRect;
+    data: AnnotationData;
 }
-/** A titled panel holding property rows — the sidebar container the rest of
- *  this module's components fill. */
-declare function PropertyPanel({ title, children, className }: PropertyPanelProps): react_jsx_runtime.JSX.Element;
-/** How a property list packs its rows into two columns. */
-type PropertyListPack = 'auto-color' | 'pairs';
-/** Props for `<PropertyList>`. */
-interface PropertyListProps {
-    children: ReactNode;
-    className?: string;
-    /**
-     * How rows pack into the 2-column grid.
-     *   - `'auto-color'` (default): only color rows pair side-by-side; everything
-     *     else spans the full width. Right for sparse top-level panels.
-     *   - `'pairs'`: every row auto-places into the 2-column grid two-per-row.
-     *     Headers and subpanels still span the full width; wrap any other
-     *     full-width child in `<PropertySpan>`. Right for dense effect bodies.
-     */
-    pack?: PropertyListPack;
+/** 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 colour, 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;
 }
 /**
- * Grid container for PropertyRows. Use standalone for chrome-less layouts, or
- * nest inside <PropertyPanel/> for the standard glass card.
+ * 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.
  */
-declare function PropertyList({ children, className, pack }: PropertyListProps): react_jsx_runtime.JSX.Element;
-/** Props for `<PropertySpan>`. */
-interface PropertySpanProps {
-    children: ReactNode;
-    className?: string;
+declare function markCommands(m: PaintableMark, content: {
+    w: number;
+    h: number;
+}, style?: MarkStyle): DrawCommand[];
+
+/** What resolving a mark's appearance needs beyond the mark itself. */
+interface MarkDrawOptions {
+    /** The target's content box — the world a mark's geometry is in. */
+    content: {
+        w: number;
+        h: number;
+    };
+    /** The target's `positionDependsOn`, for staleness. */
+    positionDependsOn?: readonly string[];
+    /** The trial's config at the time of the draw. */
+    config: unknown;
+    /** The instrument's vocabulary, for a status's colour. */
+    meaning?: AnnotationMeaning;
 }
 /**
- * Wrapper that makes an arbitrary child span both columns of a
- * `<PropertyList pack="pairs">`, a `<PropertyGroup pack="pairs">` body, or a
- * `<Subpanel>`. `<PropertyRow span>` covers the row case; this covers
- * everything else a consumer puts in the grid.
- */
-declare function PropertySpan({ children, className }: PropertySpanProps): react_jsx_runtime.JSX.Element;
-/** Which control shape a row holds, which decides its intrinsic layout. */
-type PropertyRowVariant = 'default' | 'color' | 'checkbox';
-/** Whether a row's label sits above its control or beside it. */
-type PropertyRowLayout = 'block' | 'inline';
-/** Props for `<PropertyRow>`. */
-interface PropertyRowProps {
-    label: ReactNode;
-    /** Right-aligned readout shown next to the label (e.g. current value). */
-    readout?: ReactNode;
-    /**
-     * Help text for the row, shown in a tooltip off an ⓘ affordance beside the
-     * label. Empty or absent renders no affordance.
-     */
-    description?: string;
-    variant?: PropertyRowVariant;
-    /**
-     * Label position relative to the control. "block" (default) stacks
-     * label above control; "inline" places the label to the left.
-     * Color and checkbox variants are always inline by their own nature.
-     */
-    layout?: PropertyRowLayout;
-    /**
-     * Take the full width of the enclosing grid. Only has an effect inside a
-     * `<PropertyList pack="pairs">` or a `<Subpanel>`; elsewhere rows are already
-     * full width.
-     */
-    span?: boolean;
-    children: ReactNode;
-    htmlFor?: string;
-    className?: string;
+ * How one mark is drawn — shared by the pane on screen and by an export.
+ *
+ * One function rather than two call sites building their own, because an
+ * export that resolves a status colour or a stale dash differently from the
+ * screen produces a picture nobody was looking at.
+ */
+declare function createMarkDrawOne(opts: MarkDrawOptions): (node: Node<AnnotationData, 'marks', WorldRect>, pose: WorldRect, view: View) => DrawCommand[];
+/** How a mark looks, as opposed to where it is. Separate from the callback
+ *  above because an SVG export resolves the same appearance without ever
+ *  building a draw command. */
+declare function resolveMarkStyle(data: AnnotationData, opts: MarkDrawOptions): MarkStyle;
+
+/** Which of the two composition routes an export takes. */
+type CapturePlan = 'svg-document' | 'raster-stack';
+/**
+ * Vector all the way through, or both sides rasterized and stacked.
+ *
+ * An SVG base is the only one that nests: the marks serialize beside the
+ * artifact's own markup and the whole document rasterizes once at the end. A
+ * raster base, or none at all, takes the renderer's own path instead — which
+ * is also what draws marks onto transparency for a target that declares no
+ * base.
+ */
+declare function capturePlan(base: CaptureSource | undefined, format: 'png' | 'svg'): CapturePlan;
+interface ComposeSvgArgs {
+    base?: CaptureSource;
+    scene: MarkScene;
+    draw: MarkDrawOptions;
+    scale: number;
+    onWarn?: (message: string) => void;
 }
-/** The label-plus-control frame every typed row below is built from. Use it
- *  directly for a control this module does not cover. */
-declare function PropertyRow({ label, readout, description, variant, layout, span, children, htmlFor, className, }: PropertyRowProps): react_jsx_runtime.JSX.Element;
-/** Props for `<SliderRow>`. */
-interface SliderRowProps {
-    label: ReactNode;
-    value: number;
-    min: number;
-    max: number;
-    step?: number;
-    onChange: (next: number) => void;
-    /** Override how the value is rendered next to the label. Defaults to `value.toString()`. */
-    format?: (value: number) => ReactNode;
+/**
+ * The base and the marks in one SVG document.
+ *
+ * The outer `viewBox` is the content box, so marks — which are already in it —
+ * need no transform, and `width`/`height` carry the export scale. Both halves
+ * nest as child `<svg>` elements, which each establish their own viewport and
+ * so keep their own `viewBox` maths out of this function.
+ */
+declare function composeCaptureSvg(args: ComposeSvgArgs): string;
+/** What a capture needs about the target it is exporting. */
+interface CaptureArgs {
+    target: string;
+    scene: MarkScene;
+    draw: MarkDrawOptions;
+    base?: () => CaptureSource | Promise<CaptureSource>;
+    onWarn?: (message: string) => void;
+}
+/** Export one target's picture with its marks on it. */
+declare function captureTarget(args: CaptureArgs, opts?: CaptureOptions): Promise<CaptureResult>;
+
+/**
+ * Export a target's picture with its marks on it.
+ *
+ * A panel rather than a button because a mark belongs to a target: with more
+ * than one pane, "export" on its own does not say what.
+ *
+ * Reads the store through the hook the way `<MarkList>` does — the chrome
+ * context carries no instrument state and is not the route to it.
+ */
+declare function ExportMenu(): react_jsx_runtime.JSX.Element | null;
+
+/** Props for `<MarkList>`. */
+interface MarkListProps {
+    /** The instrument's vocabulary. Omitted, rows carry no status control —
+     *  a host that declared none owns what a mark means. */
+    meaning?: AnnotationMeaning;
+    /** The live config, for answering staleness. */
+    config: unknown;
+}
+/** Every mark on this trial's targets: what it says, and whether it still
+ *  describes the picture under it.
+ *
+ *  Reads the store through the hook, which re-renders on every mutation — so a
+ *  mark drawn on a pane appears here without anything wiring the two. */
+declare function MarkList({ meaning, config }: MarkListProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Whether a stored mark still describes the picture the current config
+ * produces. A target names the config keys its positions depend on; labkit
+ * snapshots and compares them without knowing what any of them mean.
+ */
+/** The values of `keys` in `config`, for storing beside a new mark. Keys the
+ *  config does not carry are omitted rather than stored as undefined, so the
+ *  snapshot says what was known rather than what was asked. */
+declare function seenFrom(config: unknown, keys: readonly string[]): Record<string, unknown>;
+/**
+ * Whether the picture moved under the mark.
+ *
+ * Only keys present in `seen` are compared. A mark filed before its target
+ * declared a new dependency must not go stale retroactively: nothing can know
+ * what that key was at the time, and guessing would grey out every old mark
+ * the first time a target grows a key.
+ */
+declare function isStale(seen: Readonly<Record<string, unknown>> | undefined, config: unknown, keys: readonly string[]): boolean;
+
+/**
+ * Public types for `@weasel-js/svg`. The package exposes a flat,
+ * discriminated-union node model (`SvgNode`) that mirrors the SVG element
+ * tree but uses weasel-native leaf data (`Path`, `FillStyle`) for geometry and
+ * paint.
+ *
+ * Parsing collapses every `transform="..."` onto its descendants' geometry,
+ * so the `SvgNode` tree returned from `parseSvg` never has a non-identity
+ * group transform. Consumers may still construct groups with explicit
+ * transforms before serializing, in which case the serializer emits a
+ * single `matrix(a b c d e f)` on the `<g>`.
+ */
+
+/**
+ * Opaque pass-through bag for namespaced XML content.
+ *
+ * weasel-svg does not interpret the contents — it only ensures that any
+ * attributes or child elements in a *declared* XML namespace round-trip
+ * losslessly through parse → serialize. Consumers (e.g. an app-specific
+ * bridge layer) hang their domain semantics off this structure.
+ *
+ * Keyed by namespace prefix (the prefix is a write-time choice; the URI
+ * is the canonical identifier and is supplied via `ParseOptions.namespaces`
+ * / `SerializeOptions.namespaces`).
+ */
+interface NamespaceMeta {
+    [prefix: string]: {
+        /** Local-name → string-value map for attributes in this namespace. */
+        attrs?: Record<string, string>;
+        /**
+         * Child elements in this namespace, keyed by local name. Each entry
+         * is an array because a namespace can host multiple sibling elements
+         * with the same tag (e.g. `<wd:layer/><wd:layer/>`).
+         */
+        elements?: Record<string, NamespacedElement[]>;
+    };
+}
+/** Opaque structured representation of a namespaced element. */
+interface NamespacedElement {
+    /** Attribute local-name → string-value. */
+    attrs: Record<string, string>;
+    /** Text content, when the element contains only text (no child elements). */
+    text?: string;
+    /** Nested namespaced children, keyed by local name (recursive). */
+    children?: Record<string, NamespacedElement[]>;
+}
+/**
+ * 2x3 affine matrix in column-major form (SVG's `matrix(a b c d e f)`
+ * order). Maps `[x', y'] = [a*x + c*y + e, b*x + d*y + f]`.
+ */
+type Matrix = readonly [number, number, number, number, number, number];
+/**
+ * FillStyle description in the SVG sense — either explicit `none`, a solid
+ * color, or a reference to a weasel-native gradient `FillStyle`. Solid colors
+ * are normalized to `#rrggbb` strings; opacity is carried separately so
+ * `fill-opacity` and `stroke-opacity` round-trip cleanly.
+ */
+type SvgPaint = {
+    kind: 'none';
+} | {
+    kind: 'solid';
+    color: string;
+    opacity?: number;
+} | {
+    kind: 'gradient';
+    paint: FillStyle;
+};
+/** Stroke description: a paint plus structural line parameters. */
+interface SvgStroke {
+    paint: SvgPaint;
+    width: number;
+    opacity?: number;
+    /** `stroke-linecap`. Default per SVG spec is `'butt'`. */
+    cap?: 'butt' | 'round' | 'square';
+    /** `stroke-linejoin`. Default per SVG spec is `'miter'`. SVG's `arcs` / `miter-clip` map to `'miter'` with a warning. */
+    join?: 'miter' | 'round' | 'bevel';
+    /** `stroke-dasharray` as a flat number array. Odd-length inputs are doubled per SVG spec. */
+    dash?: number[];
     /**
-     * Optional suffix rendered next to the readout. A string becomes a
-     * baseline-aligned dim "word" unit (e.g. "px"); pass JSX like `<sup>°</sup>`
-     * to get the browser's native super positioning for symbol units.
+     * `stroke-miterlimit`. SVG's default is 4. Weasel's renderer defaults to
+     * 10 (Canvas2D) when unset, so parsed strokes without an explicit
+     * attribute may render with longer miters than the source SVG intended.
      */
-    unit?: ReactNode;
-    layout?: PropertyRowLayout;
-    description?: string;
-}
-/** A bounded number edited by dragging, with a live readout whose precision
- *  follows `step`. */
-declare function SliderRow({ label, value, min, max, step, onChange, format, unit, layout, description, }: SliderRowProps): react_jsx_runtime.JSX.Element;
-/** Props for `<ColorRow>`. */
-interface ColorRowProps {
-    label: ReactNode;
-    value: string;
-    onChange: (next: string) => void;
-    /** 0..1 alpha. When provided, a translucent slider renders beneath the swatch. */
-    alpha?: number;
-    onAlphaChange?: (next: number) => void;
+    miterLimit?: number;
+    /** `marker-start` / `marker-mid` / `marker-end`, as the bare `url(#id)` key. */
+    markerStart?: string;
+    markerMid?: string;
+    markerEnd?: string;
+}
+/**
+ * Leaf node: a path geometry plus fill/stroke. All other v1 shapes
+ * (`<rect>`, `<ellipse>`, etc.) are lowered to this representation on
+ * parse — `<rect>` uses weasel's `RectPath` fast-path subtype when
+ * possible, everything else becomes a `PolygonPath`.
+ */
+interface SvgPathNode {
+    kind: 'path';
+    path: Path;
+    fill: SvgPaint;
+    stroke?: SvgStroke;
+    /** Element-level opacity (`opacity="..."`), 0..1. */
+    opacity?: number;
+    /** Element-level rotation in **radians**, pivoting around the AABB
+     *  center of the underlying `path` geometry. Emitted as SVG
+     *  `transform="rotate(angleDegrees cx cy)"`. */
+    rotation?: number;
+    /** Opaque per-element bag for declared namespaces. See `NamespaceMeta`. */
+    meta?: NamespaceMeta;
+}
+/**
+ * Group node: an SVG `<g>`. On parse, `transform` is always omitted (any
+ * `transform` attribute is collapsed onto descendants' geometry). On
+ * serialize, a non-identity `transform` is emitted as
+ * `matrix(a b c d e f)`.
+ */
+interface SvgGroupNode {
+    kind: 'group';
+    children: SvgNode[];
+    transform?: Matrix;
+    opacity?: number;
+    /** Opaque per-element bag for declared namespaces. See `NamespaceMeta`. */
+    meta?: NamespaceMeta;
+}
+/**
+ * Text leaf node. Mirrors the kit's `TextPose` shape — a bounding box plus
+ * text content, optional rich-text `runs` (per-range styling), and an
+ * optional `TextStyle` for the node-wide defaults.
+ *
+ * Note on SVG text geometry: native `<text>` flows from a baseline; it
+ * doesn't have width/height attributes. The serializer emits
+ * `dominant-baseline="text-before-edge"` so `y` is the top of the text
+ * box, plus `data-weasel-width` / `data-weasel-height` so weasel's
+ * explicit box dimensions round-trip losslessly. External SVG text
+ * (lacking the data-* attrs) imports with estimated dimensions —
+ * {@link UNBOUNDED_TEXT_WIDTH} and
+ * `height = fontSize * lineHeight * (lineCount || 1)`.
+ */
+interface SvgTextNode {
+    kind: 'text';
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    /** Plain text. When `runs` is set, `runsToPlainText(runs)` must equal `text`. */
+    text: string;
+    /** Optional per-range styling — same shape as `TextPose.runs`. */
+    runs?: StyledRun[];
+    /** Node-wide typography. Defaults applied at render time via `resolveTextStyle`. */
+    style?: TextStyle;
     /**
-     * Render the alpha track as inert (dimmed, no thumb, not-allowed cursor).
-     * Use when the color's consumer drops alpha so the affordance reads dead.
+     * Node-wide glyph paint, the `FillStyle` / `Stroke` a kit text node holds
+     * in `data.fill` / `data.stroke`. Not `SvgPaint`, which is the path
+     * nodes' shape — a text paint reaches the renderer through the runs, and
+     * `StyledRun.fill` / `.stroke` override these per range.
      */
-    alphaDisabled?: boolean;
-    description?: string;
-}
-/** A color swatch, optionally with an alpha slider beneath it. */
-declare function ColorRow({ label, value, onChange, alpha, onAlphaChange, alphaDisabled, description, }: ColorRowProps): react_jsx_runtime.JSX.Element;
-/** Props for `<CheckboxRow>`. */
-interface CheckboxRowProps {
-    label: ReactNode;
-    value: boolean;
-    onChange: (next: boolean) => void;
-    description?: string;
-}
-/** A boolean checkbox. */
-declare function CheckboxRow({ label, value, onChange, description }: CheckboxRowProps): react_jsx_runtime.JSX.Element;
-/** Props for `<TextRow>`. */
-interface TextRowProps {
-    label: ReactNode;
-    value: string;
-    onChange: (next: string) => void;
-    placeholder?: string;
-    maxLength?: number;
-    layout?: PropertyRowLayout;
-    description?: string;
-}
-/** A single-line text input. */
-declare function TextRow({ label, value, onChange, placeholder, maxLength, layout, description, }: TextRowProps): react_jsx_runtime.JSX.Element;
-/** Props for `<NumberRow>`. */
-interface NumberRowProps {
-    label: ReactNode;
-    value: number;
-    onChange: (next: number) => void;
-    min?: number;
-    max?: number;
-    step?: number;
-    placeholder?: string;
-    layout?: PropertyRowLayout;
-    description?: string;
-}
-/** A number typed directly. Reach for `<SliderRow>` when the range matters
- *  more than the exact value. */
-declare function NumberRow({ label, value, onChange, min, max, step, placeholder, layout, description, }: NumberRowProps): react_jsx_runtime.JSX.Element;
-interface PropertyOption<T extends string> {
-    value: T;
-    label: ReactNode;
-}
-/** Props for `<SelectRow>`. */
-interface SelectRowProps<T extends string> {
-    label: ReactNode;
-    value: T;
-    options: ReadonlyArray<PropertyOption<T>>;
-    onChange: (next: T) => void;
-    layout?: PropertyRowLayout;
-    description?: string;
-}
-/** A dropdown over a fixed set of choices. Prefer `<ToggleRow>` when there
- *  are only two or three and they should all stay visible. */
-declare function SelectRow<T extends string>({ label, value, options, onChange, layout, description, }: SelectRowProps<T>): react_jsx_runtime.JSX.Element;
-/** Props for `<ToggleRow>`. */
-interface ToggleRowProps<T extends string> {
-    label: ReactNode;
-    value: T;
-    options: ReadonlyArray<PropertyOption<T>>;
-    onChange: (next: T) => void;
-    layout?: PropertyRowLayout;
-    description?: string;
-}
-/** A segmented control: the same choice as a select, with every option
- *  visible at once. */
-declare function ToggleRow<T extends string>({ label, value, options, onChange, layout, description, }: ToggleRowProps<T>): react_jsx_runtime.JSX.Element;
+    fill?: FillStyle;
+    stroke?: Stroke;
+    /** Element-level opacity (`opacity="..."`), 0..1. */
+    opacity?: number;
+    /** Element-level rotation in **radians**, pivoting around the unrotated
+     *  AABB center `(x + width/2, y + height/2)`. Emitted as SVG
+     *  `transform="rotate(angleDegrees cx cy)"`. */
+    rotation?: number;
+    /** Opaque per-element bag for declared namespaces. See `NamespaceMeta`. */
+    meta?: NamespaceMeta;
+}
+/**
+ * Raster-image leaf — an SVG `<image>`. `href` is the element's `href` (or
+ * legacy `xlink:href`) verbatim: an external URL or a `data:` URI. The
+ * package neither fetches nor decodes it, so an external URL round-trips as
+ * a reference and only resolves when something downstream loads it.
+ *
+ * SVG's `preserveAspectRatio` is not modeled; the box is taken literally.
+ */
+interface SvgImageNode {
+    kind: 'image';
+    href: string;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    /** Element-level opacity (`opacity="..."`), 0..1. */
+    opacity?: number;
+    /** Element-level rotation in **radians**, pivoting around the unrotated
+     *  AABB center `(x + width/2, y + height/2)`. Emitted as SVG
+     *  `transform="rotate(angleDegrees cx cy)"`. */
+    rotation?: number;
+    /** Opaque per-element bag for declared namespaces. See `NamespaceMeta`. */
+    meta?: NamespaceMeta;
+}
+/** Discriminated-union node — the leaf of the public tree. */
+type SvgNode = SvgPathNode | SvgGroupNode | SvgTextNode | SvgImageNode;
+
+/**
+ * One mark as SVG nodes, converted from the very commands the pane paints.
+ *
+ * Deliberately not a second switch over `data.kind`: geometry has one source,
+ * and this is a translation of it. `serializeSvg` turns the result into a
+ * document.
+ */
+declare function markSvgNodes(m: PaintableMark, content: {
+    w: number;
+    h: number;
+}, style?: MarkStyle): SvgNode[];
+
+/** Props for `<AnnotationOverlay>`. */
+interface AnnotationOverlayProps {
+    target: AnnotationTarget;
+    /** The trial's mark scene — shared by every target; a mark's own `target`
+     *  field is what separates them. */
+    scene: MarkScene;
+    /** Snapshotted onto each new mark, so staleness can be answered later. */
+    config: unknown;
+    /** The trial's resolved tool slot. */
+    activeToolId: string | null;
+    /** The instrument's vocabulary, for a status's colour. */
+    meaning?: AnnotationMeaning;
+}
+/**
+ * One target's drawing surface: a transparent box over the target's element
+ * taking the input, and a `<SceneCanvas>` painting into the lab's shared
+ * buffer at that box's rect.
+ *
+ * The box is portalled into the surface container because that is what tile
+ * rects are measured against; positioning it among the instrument's own DOM
+ * would put it in whatever positioning context happened to be there.
+ */
+declare function AnnotationOverlay({ target, scene, config, activeToolId, meaning, }: AnnotationOverlayProps): react.ReactPortal | null;
+
+/** Null in a trial whose instrument declares no `annotations`. */
+declare const AnnotationsContext: react.Context<AnnotationsApi | null>;
+/** The marks on this trial's targets. Reached through a hook rather than the
+ *  chrome context, which carries no instrument state — a sidebar panel listing
+ *  marks pulls it the way `useTrialState()` does. Throws outside a trial whose
+ *  instrument declares the capability. */
+declare function useAnnotations(): AnnotationsApi;
+/** The marks on this trial's targets, or null. For chrome that renders in
+ *  every trial and does something else where there are none. */
+declare function useAnnotationsOptional(): AnnotationsApi | null;
+
+/** Props for `<AnnotationTargets>`. */
+interface AnnotationTargetsProps {
+    capability: AnnotationsCapability;
+    state: unknown;
+    config: unknown;
+    annotations: AnnotationsApi;
+    activeToolId: string | null;
+}
+/** One overlay per region the instrument said accepts marks. */
+declare function AnnotationTargets({ capability, state, config, annotations, activeToolId, }: AnnotationTargetsProps): react_jsx_runtime.JSX.Element;
+
+/** Which weasel tool an annotation tool drives, and what kind of mark that
+ *  makes. `select` makes none. */
+interface AnnotationToolInfo {
+    weaselTool: BuiltinToolId;
+    kind?: AnnotationKind;
+}
+/** The palette an instrument gets for declaring `annotations`. Ids share the
+ *  trial's contribution namespace with `instrument.tools`, and one tool slot
+ *  holds whichever is active. */
+declare const ANNOTATION_TOOLS: readonly TrialTool[];
+/** What `id` drives, or undefined for a tool that is not one of these. */
+declare function annotationToolInfo(id: string | null): AnnotationToolInfo | undefined;
+/** Every weasel tool the overlay has to mount for this palette to work. */
+declare const ANNOTATION_WEASEL_TOOLS: readonly BuiltinToolId[];
+
+/** A target's world in CSS pixels: the box its fractions are fractions of. */
+interface ContentSize {
+    w: number;
+    h: number;
+}
+/** A target's drawn box on the surface, in CSS pixels. */
+interface PaneSize {
+    w: number;
+    h: number;
+}
+/** labkit's camera in weasel's shape. Zoom is uniform, so it lands on both
+ *  scale axes; pan is weasel's translation unchanged. */
+declare function toWeaselView(v: ViewTransform): View;
+/** The inverse. A weasel view with unequal axis scales collapses to its x —
+ *  labkit's camera has one zoom and cannot hold the other. */
+declare function fromWeaselView(v: View): ViewTransform;
+/**
+ * The camera a target with none of its own draws through: its content box
+ * scaled to fit the box it is drawn in, anchored at the origin.
+ *
+ * The spec calls the camera "a plain scale" at zoom 1; zoom 1 is only right
+ * when the pane happens to be the content's size, and a mark drawn on a
+ * scaled-down pane otherwise lands outside it.
+ */
+declare function fitView(content: ContentSize, pane: PaneSize): ViewTransform;
 
 /** A point in the space the instrument works in. */
 interface Vec3 {
@@ -695,6 +1010,11 @@ interface WorkspaceProps {
     onLayoutChange?: (layout: TrialLayout) => void;
     gap?: number;
     padding?: number;
+    /** Undocked sidebar panels to render alongside the trials. A `'tile'` panel
+     *  joins the grid as a peer of the trials; a `'floating'` one goes into the
+     *  floating zone above it. The body is portalled in by the trial that owns
+     *  it, so all this renders is the frame and the host. */
+    panels?: readonly PanelDescriptor[];
     /**
      * Fixed tiling extent. Omit in an app — the grid measures its own box. Supply
      * it where nothing measures, notably jsdom: at a zero measurement the grid
@@ -705,14 +1025,14 @@ interface WorkspaceProps {
         h: number;
     };
 }
-/**
- * Auto-balanced tiling of trials, `ceil(sqrt(n))` columns wide.
- *
- * Tiles are absolutely positioned at the rects `gridStrategy` computes, not
- * laid out by CSS — `windease/styles.css` (folded into
- * `@weasel-js/labkit/styles.css`) carries the rules that positioning depends on.
- */
-declare function Workspace({ children, ids, resizable, reorderable, onReorder, layout, onLayoutChange, gap, padding, viewport, }: WorkspaceProps): react_jsx_runtime.JSX.Element;
+/** One undocked panel, as the workspace needs to know it. */
+interface PanelDescriptor {
+    /** Stable key; also the portal host key the owning trial writes into. */
+    key: string;
+    title: string;
+    as: 'tile' | 'floating';
+}
+declare function Workspace({ children, ids, panels, resizable, reorderable, onReorder, layout, onLayoutChange, gap, padding, viewport, }: WorkspaceProps): react_jsx_runtime.JSX.Element;
 
 /** The 2D view labkit has always shipped, and what a trial gets when it names no
  *  other. Re-exported under its own name so a consumer can say which it means. */
@@ -773,6 +1093,11 @@ interface TrialProps {
  *  instrument, and mounts the instrument inside the trial chrome. */
 declare function Trial({ id, chrome, suppress }: TrialProps): react_jsx_runtime.JSX.Element;
 
+/** The trial's loupe as its chrome sees it: a switch and its position. */
+interface LoupeBindings {
+    on: boolean;
+    toggle: () => void;
+}
 interface UndoBindings {
     canUndo: boolean;
     canRedo: boolean;
@@ -788,6 +1113,9 @@ interface TrialChromeProps {
     undoBindings?: UndoBindings;
     /** Supplied when the instrument declares a `job`. */
     job?: JobHandle;
+    /** Supplied when the instrument declares a `loupe`. The lens itself is the
+     *  trial's to mount; the chrome only offers the switch. */
+    loupe?: LoupeBindings;
     /** Contributions the trial runtime itself adds — the drag palette and the
      *  layer list, which depend on runtime state the instrument cannot reach. */
     trialChrome?: readonly TrialContribution[];
@@ -804,7 +1132,7 @@ interface TrialChromeProps {
 /** The frame around a running instrument. Builds one chrome context, assembles
  *  the contributions the instrument, the runtime and the lab declare, and hands
  *  each region its slice. */
-declare function TrialChrome({ trialId, record, instrument, isLastTrial, undoBindings, job, trialChrome, chrome, suppress, activeToolId, setActiveTool, children, }: TrialChromeProps): react_jsx_runtime.JSX.Element;
+declare function TrialChrome({ trialId, record, instrument, isLastTrial, undoBindings, job, loupe, trialChrome, chrome, suppress, activeToolId, setActiveTool, children, }: TrialChromeProps): react_jsx_runtime.JSX.Element;
 
 /** Append a new trial running `instrumentName`, at that instrument's
  *  default config and initial state. */
@@ -825,5 +1153,5 @@ declare function resetTrial(trials: TrialRecord[], id: string, instruments: Inst
  */
 declare function reorderTrials(trials: TrialRecord[], ids: readonly string[]): TrialRecord[];
 
-export { Annotations, CheckboxRow, ColorRow, ConfigField, ConfigNode, ConfigOption, ConfigRule, ConfigRuleContext, ConfigSchema, ControlRenderer, CurveField, DEFAULT_VIEW, EffectCard, EffectCardList, InferConfig, Instrument, InstrumentList, JobHandle, Lab, LabContext, LabMode, LabPalette, LabShell, LeafPatch, NodeOptions, NumberRow, PITCH_LIMIT, PropertyGroup, PropertyList, PropertyPanel, PropertyRow, PropertySpan, ResolvedConfig, SavedSnapshot, SelectRow, SliderRow, StorageAdapter, Subpanel, TextRow, ToggleRow, Trial, TrialChrome, TrialContribution, TrialRecord, TrialTool, ViewTransform, Workspace, addTrial, applyRules, as2DView, builtinRules, clampPitch, cloneTrial, closeTrial, defineInstrument, f, fromConfigFields, interstellarTheme, isLeafVisible, orbitAfterDrag, orbitAfterWheel, reorderTrials, resetTrial, resolveConfigSchema, titleCase, useConfigSchema, useLabContext, useOrbit, validateConfigSchema, wrapYaw };
-export type { CheckboxRowProps, ColorRowProps, CurveFieldProps, CurveMark, EffectCardListItem, EffectCardListProps, EffectCardProps, InstrumentSpec, LabContextValue, LabPaletteProps, LabProps, LabShellProps, NumberRowProps, OrbitHandlers, OrbitView, PropertyGroupProps, PropertyListPack, PropertyListProps, PropertyOption, PropertyPanelProps, PropertyRowLayout, PropertyRowProps, PropertyRowVariant, PropertySpanProps, SelectRowProps, SliderRowProps, SubpanelProps, TextRowProps, ToggleRowProps, TrialChromeProps, TrialLayout, TrialProps, UndoBindings, UseOrbitOptions, ValidationResult, Vec3, ViewTransform2D, WorkspaceProps };
+export { ANNOTATION_TOOLS, ANNOTATION_WEASEL_TOOLS, AnnotationData, AnnotationKind, AnnotationMeaning, AnnotationOverlay, AnnotationTarget, AnnotationTargets, Annotations, AnnotationsApi, AnnotationsCapability, AnnotationsContext, CaptureOptions, CaptureResult, CaptureSource, ConfigField, ConfigNode, ConfigOption, ConfigRule, ConfigRuleContext, ConfigSchema, ControlRenderer, CurveField, DEFAULT_VIEW, EffectCard, EffectCardList, ExportMenu, InferConfig, Instrument, InstrumentList, JobHandle, Lab, LabContext, LabMode, LabPalette, LabShell, LeafPatch, MarkList, MarkScene, NodeOptions, PITCH_LIMIT, PropertyGroup, ResolvedConfig, SavedSnapshot, StorageAdapter, Subpanel, Trial, TrialChrome, TrialContribution, TrialRecord, TrialTool, ViewTransform, Workspace, WorldRect, addTrial, annotationToolInfo, applyRules, as2DView, builtinRules, capturePlan, captureTarget, clampPitch, cloneTrial, closeTrial, composeCaptureSvg, createMarkDrawOne, defineInstrument, f, fitView, fromConfigFields, fromWeaselView, interstellarTheme, isLeafVisible, isStale, markCommands, markSvgNodes, orbitAfterDrag, orbitAfterWheel, reorderTrials, resetTrial, resolveConfigSchema, resolveMarkStyle, seenFrom, titleCase, toWeaselView, useAnnotations, useAnnotationsOptional, useConfigSchema, useLabContext, useOrbit, validateConfigSchema, wrapYaw };
+export type { AnnotationOverlayProps, AnnotationTargetsProps, AnnotationToolInfo, CaptureArgs, CapturePlan, ComposeSvgArgs, ContentSize, CurveFieldProps, CurveMark, EffectCardListItem, EffectCardListProps, EffectCardProps, InstrumentSpec, LabContextValue, LabPaletteProps, LabProps, LabShellProps, MarkDrawOptions, MarkListProps, MarkStyle, OrbitHandlers, OrbitView, PaintableMark, PaneSize, PanelDescriptor, PropertyGroupProps, SubpanelProps, TrialChromeProps, TrialLayout, TrialProps, UndoBindings, UseOrbitOptions, ValidationResult, Vec3, ViewTransform2D, WorkspaceProps };