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

package/dist/_dts/{DrawCommand-DBB45NfN.d.ts → types-C-gh9Ap-.d.ts}

@@ -692,585 +692,4 @@ interface Scene<TData, TLayer extends string, TPose = RectPose> {
     getVersion(): number;
 }
 
-/**
- * Viewport state. `(view.x, view.y)` is the **world point currently
- * rendered at the canvas top-left**; `view.scale.x` / `view.scale.y` is
- * pixels per world unit on each axis (default `{ x: 1, y: 1 }`). So:
- *
- *   screenX = (worldX - view.x) * view.scale.x
- *   screenY = (worldY - view.y) * view.scale.y
- *   worldX  = screenX / view.scale.x + view.x
- *   worldY  = screenY / view.scale.y + view.y
- *
- * `scale` is always a 2-vector. Input convenience types
- * {@link ZoomFactor} and {@link ZoomBound} let callers pass a scalar
- * when they want both axes treated the same.
- */
-interface View {
-    x: number;
-    y: number;
-    scale: {
-        x: number;
-        y: number;
-    };
-}
-
-/**
- * Axis-aligned rectangle in world space. Kit-wide `Bounds` shape used by
- * selection, group, and viewport helpers. The optional `rotation` field
- * (radians, around the AABB center) lets selection chrome attach a rotated
- * orientation to an otherwise axis-aligned rect without needing a parallel
- * type.
- */
-interface Bounds {
-    x: number;
-    y: number;
-    width: number;
-    height: number;
-    rotation?: number;
-}
-/** Pixel dimensions of the canvas viewport. */
-interface ViewportDims {
-    width: number;
-    height: number;
-}
-
-/**
- * A registered texture, named by the registry that holds it.
- *
- * The handle is here rather than beside the registry because `FillStyle`'s
- * pattern variant names it, and paint is a leaf: the registry lives in the
- * renderer and imports this back.
- */
-interface TextureHandle {
-    readonly id: string;
-}
-
-/**
- * FillStyle and Stroke types — the unified shape for "what color or texture
- * paints these pixels," modeled on SVG's paint-server concept.
- *
- * - `FillStyle` is a tagged union: solid color, pattern, or gradient. Used
- *   wherever a kit option previously took `fillStyle: string`.
- * - `Stroke` pairs a `FillStyle` with structural stroke parameters (width, dash,
- *   line cap/join, alignment).
- * - These types are consumed by the GL renderer's DrawCommand path fills
- *   and strokes.
- *
- * The 2D `applyPaint` / `applyStroke` / `renderFilledRegion` helpers that
- * formerly lived alongside these types were deleted with the 2D backend in
- * Step 10. `alignedStrokeRect` survives as a pure geometry helper used by
- * path tessellation and the selection overlay.
- */
-
-/**
- * Color/texture strategy for fills (and, via `Stroke.paint`, strokes).
- *
- * `fill` is optional and defaults to `'solid'` — `{ color: '#abc' }` is
- * equivalent to `{ fill: 'solid', color: '#abc' }`. Pattern paints must set
- * `fill: 'pattern'` explicitly.
- *
- * The `'pattern'` variant's payload is either a `TilePatternSpec` — plain
- * data naming one of the built-in tiles, which survives serialization — or a
- * `TextureHandle` for a tile the consumer built itself via
- * `createTilePattern()`. A handle is a session-scoped registry key, so a
- * paint carrying one cannot be persisted or exported; prefer the spec.
- *
- * `units` on a pattern names the space the tile's origin and scale live in,
- * not the space of any geometry (a pattern has none). Under `'bounds'` the
- * tile anchors to the painted node's box, so the pattern travels with the
- * node and a resize reveals more tiles rather than stretching them;
- * `fillInPoseFrame` resolves that to a `'local'` paint with an explicit
- * `origin` before the renderer sees it.
- */
-type FillStyle = {
-    fill?: 'solid';
-    color: string;
-    opacity?: number;
-} | {
-    fill: 'pattern';
-    pattern: TextureHandle | TilePatternSpec;
-    units?: GradientUnits;
-    origin?: {
-        x: number;
-        y: number;
-    };
-    opacity?: number;
-} | {
-    fill: 'linear-gradient';
-    from: {
-        x: number;
-        y: number;
-    };
-    to: {
-        x: number;
-        y: number;
-    };
-    stops: GradStop[];
-    units?: GradientUnits;
-    opacity?: number;
-} | {
-    fill: 'radial-gradient';
-    center: {
-        x: number;
-        y: number;
-    };
-    radius: number;
-    stops: GradStop[];
-    units?: GradientUnits;
-    opacity?: number;
-} | {
-    fill: 'conic-gradient';
-    center: {
-        x: number;
-        y: number;
-    };
-    angle: number;
-    stops: GradStop[];
-    units?: GradientUnits;
-    opacity?: number;
-};
-/**
- * Which coordinate space a gradient's geometry (`from`/`to`, `center`,
- * `radius`) is expressed in. SVG's `gradientUnits`, plus an option for
- * paints that are themselves viewport furniture.
- *
- * - `'bounds'`: fractions of the painted node's bounding box, `0..1` on each
- *   axis — SVG `objectBoundingBox`. Resolved by the node painter, before the
- *   renderer sees it, so the paint follows the node through moves, resizes
- *   and rotation. What a gradient on a scene node wants.
- * - `'local'`: the coordinate space the geometry was handed to the renderer
- *   in — the enclosing group's frame. For draw commands a consumer builds
- *   itself, where "the coordinates I just wrote" is the useful frame.
- * - `'world'`: scene coordinates. The paint stays put under pan and zoom
- *   while the geometry moves through it. SVG `userSpaceOnUse`. Requires the
- *   renderer to have been handed a view matrix; falls back to `'screen'`
- *   when it has not.
- * - `'screen'`: CSS pixels of the drawing surface. For overlays and
- *   viewport-fixed washes that should not move with the content at all.
- *
- * Defaults to `'screen'`, which is the behavior every gradient had before
- * this field existed.
- */
-type GradientUnits = 'bounds' | 'local' | 'world' | 'screen';
-/**
- * A built-in tile, described as plain data. The serializable half of the
- * pattern paint: `resolvePatternSpec()` turns one into a `TextureHandle`
- * at paint time, memoized so identical specs share a texture.
- *
- * `size` is the tile's edge length, and doubles as its extent in paint
- * space — a bigger `size` rasterizes a bigger tile rather than magnifying
- * a small one, which is why there is no separate scale field.
- */
-interface TilePatternSpec {
-    tile: 'hatch' | 'crosshatch' | 'dots' | 'chunks';
-    color: string;
-    /** `chunks` only — omit for a transparent tile background. */
-    bg?: string;
-    size?: number;
-    /** `hatch` / `crosshatch`. */
-    lineWidth?: number;
-    /** `dots`. */
-    radius?: number;
-    /** `chunks`. */
-    density?: number;
-    chunkSize?: number;
-    seed?: number;
-}
-/** A single color stop within a gradient. `offset` is in 0..1. */
-interface GradStop {
-    offset: number;
-    color: string;
-}
-/**
- * Where a stroke sits relative to the geometric edge it strokes.
- *
- * - `'center'` (default): canvas-native — half the stroke width sits inside
- *   the geometry, half outside.
- * - `'inner'`: the entire stroke lies inside the geometry. The outer edge of
- *   the stroke coincides with the geometric edge.
- * - `'outer'`: the entire stroke lies outside the geometry. The inner edge
- *   of the stroke coincides with the geometric edge.
- *
- * Mirrors the (proposed) SVG `stroke-alignment` property. Honoring `inner`
- * or `outer` is the renderer's responsibility — for axis-aligned rects, the
- * kit shifts coordinates by `width / 2`. For arbitrary paths, renderers
- * typically use a stencil mask of the stroked path against the geometry.
- */
-type StrokeAlign = 'center' | 'inner' | 'outer';
-/**
- * The kit's built-in marker vocabulary, open on the string the way
- * `PaintKind` is so a consumer's registered key typechecks.
- */
-type KitMarkerKey = 'arrow' | 'arrow-open' | 'arrow-concave' | 'diamond' | 'diamond-hollow' | 'circle' | 'square' | 'bar';
-type MarkerKey = KitMarkerKey | (string & {});
-/**
- * A marker on one end (or every interior vertex) of a stroke.
- *
- * `size` reuses `Stroke.width`'s unit system: a bare number scales with the
- * resolved stroke width, `{ px }` pins screen pixels. That is SVG's
- * `markerUnits` in the idiom this codebase already resolves at draw time.
- * Omitted, the marker is one stroke width per unit.
- */
-type MarkerRef = MarkerKey | {
-    key: MarkerKey;
-    size?: number | {
-        px: number;
-    };
-};
-/** Stroke style: a FillStyle plus structural line parameters. */
-interface Stroke {
-    paint: FillStyle;
-    /** World units, or `{ px }` for screen pixels — resolved against the
-     *  accumulated transform scale at draw time, so it holds its on-screen
-     *  thickness as the view zooms. */
-    width?: number | {
-        px: number;
-    };
-    /** Per `CanvasRenderingContext2D.setLineDash` — empty/omitted = solid. */
-    dash?: number[];
-    /** Marker at the first vertex of each open subpath, rotated to point back
-     *  along the line (SVG's `auto-start-reverse`, as the only behavior). */
-    markerStart?: MarkerRef;
-    /** Marker at every interior authored vertex, on the bisector of the
-     *  incoming and outgoing directions. Never insets the stroke. */
-    markerMid?: MarkerRef;
-    /** Marker at the last vertex of each open subpath. */
-    markerEnd?: MarkerRef;
-    cap?: 'butt' | 'round' | 'square';
-    join?: 'miter' | 'round' | 'bevel';
-    /**
-     * Miter join fallback threshold. When the miter length exceeds
-     * `miterLimit * width / 2`, the join falls back to a bevel. Default 4,
-     * matching SVG — which is also what the kit's own serializer implies when
-     * it omits the attribute for an unset field. Canvas2D's 10 lets an acute
-     * corner throw a spike four times the half-width.
-     */
-    miterLimit?: number;
-    /** Where the stroke sits relative to the geometric edge. Default `'center'`. */
-    align?: StrokeAlign;
-    /**
-     * Per-anchor RGBA, flat (length = 4 × countPathAnchors(path)). Each
-     * value in 0..1. Arc-length interpolated across the tessellated ribbon
-     * between consecutive anchors. When set, `paint` is still required —
-     * its `opacity` (and color, as a placeholder) flow through the shader.
-     */
-    vertexColors?: number[];
-    /**
-     * Per-anchor stroke width (length = `countPathAnchors(path)`). When set,
-     * the tessellator interpolates half-widths along each segment to produce
-     * a tapered ribbon. `width` is used as the fallback for any anchor whose
-     * entry is missing or non-finite. Pressure-driven pencil strokes use
-     * this; pair with `pressureToWidth` to derive widths from stylus input.
-     *
-     * Joins between adjacent segments whose widths differ by more than
-     * `varyingWidthJoinThreshold` (default 1.5×) are forced to bevel
-     * regardless of the `join` setting — miter math is unstable when widths
-     * vary across the corner; smooth round joins with mismatched widths
-     * are a future enhancement.
-     */
-    vertexWidths?: number[];
-    /**
-     * Max width ratio (greater / lesser) at which a non-bevel join is
-     * preserved when `vertexWidths` causes adjacent segments to differ.
-     * Beyond this ratio the join falls back to bevel. Default 1.5. Ignored
-     * when `vertexWidths` is absent.
-     */
-    varyingWidthJoinThreshold?: number;
-}
-
-/**
- * 2D affine matrix utilities. Column-major 9-element Float32Array, matching
- * `WebGL2RenderingContext.uniformMatrix3fv` byte order so we can pass the
- * array directly without a transpose flag.
- *
- * Layout (column-major):
- *   [m00, m10, 0,
- *    m01, m11, 0,
- *    tx,  ty,  1]
- *
- * `apply(m, x, y)` returns `[m * (x, y, 1)] = [m00*x + m01*y + tx,
- *                                              m10*x + m11*y + ty]`.
- */
-type Mat3 = Float32Array;
-
-/**
- * Typography for `TextPose` and friends. Every field is optional; consumers
- * pass `{}` or override the few they care about. Defaults live in
- * `DEFAULT_TEXT_STYLE` and are applied at render/measure time, never written
- * back to the pose.
- *
- * Paint is not typography and does not live here. A text node carries its
- * fill and stroke in `data.fill` / `data.stroke`, the slots every other node
- * kind uses; `resolveTextStyle` takes them as its second argument and
- * `StyledRun.fill` / `.stroke` override them per range.
- */
-
-/**
- * Horizontal alignment. `start` / `end` resolve against the reading direction;
- * `left` / `right` are absolute. Same five values as CSS `text-align`, with
- * the same split between the relative pair and the absolute pair.
- */
-type TextAlign = 'left' | 'center' | 'right' | 'start' | 'end';
-/** Reading direction, which is what gives `start` / `end` their meaning. */
-type TextDirection = 'ltr' | 'rtl';
-/** User-facing text style. All fields optional; defaults applied at render time via `resolveTextStyle`. */
-interface TextStyle {
-    /** Font size in world units. Default 16. */
-    fontSize?: number;
-    /** Default `'sans-serif'`. */
-    fontFamily?: string;
-    /** Default 400. */
-    fontWeight?: number | string;
-    /** Default `'normal'`. */
-    fontStyle?: 'normal' | 'italic';
-    /** Default `'left'`. Pass `'start'` to align by reading order instead. */
-    align?: TextAlign;
-    /** Reading direction, resolving `align: 'start' | 'end'`. Default `'ltr'`. */
-    direction?: TextDirection;
-    /** Multiplier applied to `fontSize`. Default 1.2. */
-    lineHeight?: number;
-    /**
-     * Caret color used by the edit overlay. Defaults to the node's fill when
-     * that fill is solid; falls back to `#000` for non-solid paints.
-     */
-    caretColor?: string;
-    /**
-     * Selection background color used by the edit overlay's `::selection`
-     * pseudo-element. Defaults to a 25%-opacity tint of `caretColor` via CSS
-     * `color-mix`. Pass `'none'` to fall back to the browser-native highlight.
-     */
-    selectionBackground?: string;
-    /** Selection text color paired with `selectionBackground`. Default: inherits text color. */
-    selectionColor?: string;
-    /** Extra advance added after each glyph, in world units. Default 0. */
-    letterSpacing?: number;
-    /** Default `false`. */
-    underline?: boolean;
-    /** Default `false`. */
-    strikethrough?: boolean;
-    /** Default `false`. */
-    overline?: boolean;
-}
-
-/**
- * Apply node-level `ResolvedTextStyle` defaults to each `StyledRun`,
- * producing a fully-resolved run with every styling field set. Downstream
- * layout and draw never re-resolve defaults — `ResolvedRun` is the
- * canonical shape the renderer consumes.
- *
- * `bold`/`italic` toggles on a run are folded into `fontWeight`/`fontStyle`:
- * `bold: true` → fontWeight 700, `italic: true` → fontStyle 'italic'.
- * Explicit `fontFamily` / `fontSize` / `fill` / `letterSpacing` on the run
- * override the node-level value (`letterSpacing: 0` on a run is an override,
- * not an absence — it zeroes inherited tracking).
- *
- * `underline` / `strikethrough` / `overline` are *additive*, like
- * `bold`/`italic`: a run can turn a decoration on but never off, so they
- * resolve as `run.x || style.x` and not `run.x ?? style.x`. See the header of
- * `runs/rangeStyle.ts` for why the model collapses the tri-state.
- *
- * `script` is folded the same way the toggles are, into the two primitives it
- * is a preset over: `baselineShift` and `fontScale`. Both come out as one
- * world-unit `baselineShift` and a final `fontSize`, so layout never learns
- * that superscripts exist — it places a run against a baseline and an offset.
- */
-
-/** A run with every style resolved against the node's text style — no
- *  optional inheritance left. This is what layout and painting consume. */
-interface ResolvedRun {
-    text: string;
-    fontFamily: string;
-    fontSize: number;
-    fontWeight: number;
-    fontStyle: 'normal' | 'italic';
-    fill: FillStyle;
-    /** Outline over this run's glyphs, or absent for none. Painted only on the
-     *  outline tier — a distance field has no geometry to stroke. */
-    stroke?: Stroke;
-    /** Extra advance added after each glyph of this run, in world units. */
-    letterSpacing: number;
-    /** Draw a rule below this run's baseline. Additive over the node style. */
-    underline: boolean;
-    /** Draw a rule through this run's x-height. Additive over the node style. */
-    strikethrough: boolean;
-    /** Draw a rule above this run's ascent. Additive over the node style. */
-    overline: boolean;
-    /**
-     * How far this run sits off the line's shared baseline, in world units;
-     * positive raises. 0 for ordinary text.
-     *
-     * Already multiplied out against the inherited font size, and already
-     * carrying whatever `script` asked for — layout adds it to a baseline and
-     * asks nothing about where it came from.
-     */
-    baselineShift: number;
-}
-
-/**
- * Box vertical alignment for text draw commands. Given the command's box
- * `height` and the laid-out text block's height, returns the Y offset to
- * apply to every quad. `'top'` (or an undefined `align`, or a missing box
- * `height`) is the legacy behavior: offset 0.
- */
-type TextVerticalAlign = 'top' | 'center' | 'bottom';
-
-/**
- * registerProgram — public API for registering custom shader programs.
- *
- * Stores raw GLSL source strings in a module-level registry. GL compilation
- * happens on each WeaselRenderer via WeaselRenderer.registerProgram(), which
- * calls getProgramSource() and compiles the result. This keeps registerProgram
- * GL-context-agnostic — identical pattern to registerFont storing ImageBitmap.
- *
- * Module-level state = source strings only; compiled GL
- * programs live on each renderer's programRegistry (Map<id, ShaderProgram>).
- *
- * Lifecycle: program sources live for the module lifetime. No unregister in v1.
- */
-
-/** Opaque handle to a compiled custom shader program. */
-interface ShaderProgramHandle {
-    readonly id: string;
-}
-/**
- * Scalar and vector uniform types accepted by the custom shader uniform binder.
- *
- * | TS type                 | GL call                              |
- * |-------------------------|--------------------------------------|
- * | number                  | uniform1f                            |
- * | [n, n]                  | uniform2fv                           |
- * | [n, n, n]               | uniform3fv                           |
- * | [n, n, n, n]            | uniform4fv                           |
- * | Float32Array length 9   | uniformMatrix3fv (column-major)      |
- * | Float32Array length 16  | uniformMatrix4fv (column-major)      |
- * | TextureHandle           | bind to next tex unit + uniform1i    |
- */
-type ShaderUniform = number | [number, number] | [number, number, number] | [number, number, number, number] | Float32Array | TextureHandle;
-
-/** DrawCommand variants implemented through step 6. */
-type DrawCommand = PathDrawCommand | GroupDrawCommand | TextDrawCommand | ImageDrawCommand | ShaderDrawCommand;
-/** Draw a path, filled and/or stroked. The workhorse command: every shape the
- *  kit draws that is not text, an image, or a custom shader is one of these. */
-interface PathDrawCommand {
-    kind: 'path';
-    path: Path;
-    /** Any `FillStyle` variant: solid, pattern, or gradient (linear/radial/conic). */
-    fill?: FillStyle;
-    /** Stroke spec. Only solid `paint` supported through step 4. */
-    stroke?: Stroke;
-    /**
-     * Optional flat RGBA-per-path-anchor color array (length =
-     * `4 × countPathAnchors(path)`, floats in 0..1). The renderer
-     * arc-length-interpolates these per-anchor colors across the
-     * flattened/triangulated mesh between consecutive anchors using the
-     * mesh's `anchorA` / `anchorB` / `anchorT` parameterization.
-     *
-     * **`fill` must also be set when using `vertexColors`.** The renderer
-     * only enters the per-vertex shader path when the command has a fill
-     * (the fill provides the opacity uniform; the vertex colors override
-     * the fill's color). Pass any solid `fill` (e.g. `{ color: '#fff' }`)
-     * as the placeholder; the per-vertex colors win in the shader.
-     */
-    vertexColors?: number[];
-}
-/** Draw a list of commands under a shared transform, opacity, color matrix
- *  and clip. Groups nest, and their effects accumulate down the stack — this
- *  is how a container node's transform reaches its descendants. */
-interface GroupDrawCommand {
-    kind: 'group';
-    transform?: Mat3;
-    alpha?: number;
-    /**
-     * Optional 4×5 color matrix (row-major, 20 numbers) — `out = M₄ₓ₄ * in + bias`.
-     * Accumulated multiplicatively down the group stack. Defaults to identity.
-     */
-    colorMatrix?: number[];
-    /** Optional clip path. When set, the renderer rasterizes this path into
-     *  the stencil buffer before drawing `children`; the children paint only
-     *  where the clip covers. Nested groups with clips intersect — a child
-     *  cannot escape an ancestor's clip. Max 7 nesting levels; the renderer
-     *  throws if exceeded. */
-    clip?: Path;
-    children: DrawCommand[];
-}
-/**
- * Text draw command. Renders one or more runs at (`x`, `y`) in screen
- * space, optionally word-wrapping at `maxWidth`. The renderer resolves
- * each run's `(fontFamily, fontWeight, fontStyle)` to an MSDF atlas via
- * `resolveFontVariant` and bucket-draws by atlas + color group.
- *
- * `style` carries node-level defaults (`lineHeight`, anti-alias width)
- * that don't belong on individual runs.
- */
-interface TextDrawCommand {
-    kind: 'text';
-    x: number;
-    y: number;
-    runs: ResolvedRun[];
-    maxWidth?: number;
-    align?: 'left' | 'center' | 'right';
-    style: TextStyle;
-    /** Box height for vertical alignment. When set with `verticalAlign`,
-     *  the laid-out block shifts within `[y, y+height]`. */
-    height?: number;
-    /** Default 'top' — the legacy top-anchored behavior. */
-    verticalAlign?: TextVerticalAlign;
-}
-/**
- * Image draw command — renders `image` at screen-space rect (x, y, w, h).
- * The image is stretched to fit; no tiling. Use a pattern FillStyle on a path
- * for tiling.
- */
-interface ImageDrawCommand {
-    kind: 'image';
-    image: ImageBitmap;
-    x: number;
-    y: number;
-    w: number;
-    h: number;
-    opacity?: number;
-    /** Magnification filter. `'linear'` (default) smooths; `'nearest'` shows
-     *  device pixels as hard squares — required by anything magnifying a
-     *  framebuffer readback, where blur destroys the point of the readback. */
-    sampling?: 'linear' | 'nearest';
-    /** Sub-rectangle of `image` to draw, in bitmap pixels from the top-left.
-     *  Omitted draws the whole bitmap. Not range-checked: a rect past the edge
-     *  samples outside [0..1], which CLAMP_TO_EDGE smears. With
-     *  `sampling: 'linear'` the filter reaches half a texel beyond `source`, so
-     *  atlas frames need a gutter (see `SpriteSheet.spacing`) or `'nearest'`. */
-    source?: {
-        x: number;
-        y: number;
-        w: number;
-        h: number;
-    };
-    /** Mirror the sampled region within the destination rect. The quad does not
-     *  move — a flipped draw covers exactly the pixels an unflipped one does. */
-    flipX?: boolean;
-    flipY?: boolean;
-}
-/**
- * Custom shader draw command. The renderer generates a quad over `bounds`
- * and dispatches the consumer's fragment shader with the kit's vertex prelude.
- *
- * `uniforms` keys must match names declared in the consumer's fragment shader.
- * The kit automatically sets `u_bounds`, `u_view`, and `u_proj` — do not
- * declare those in `uniforms`.
- *
- * @experimental API may change before v2.
- */
-interface ShaderDrawCommand {
-    kind: 'shader';
-    program: ShaderProgramHandle;
-    uniforms: Record<string, ShaderUniform>;
-    /** Screen-space bounding rect in CSS pixels. */
-    bounds: {
-        x: number;
-        y: number;
-        w: number;
-        h: number;
-    };
-}
-
-export type { Bounds as B, DrawCommand as D, History as H, Node as N, Op as O, Path as P, Scene as S, View as V, ViewportDims as a, PathDrawCommand as b, NodeId as c };
+export type { History as H, Node as N, Op as O, Path as P, Scene as S, NodeId as a };

package/dist/_dts/{types-AHlQxBNN.d.ts → types-D6s4b7if.d.ts}

@@ -1,4 +1,4 @@
-import { P as PrefRenderer, T as ToolPrefLeaf, a as ToolPrefGroup } from './PrefsForm-BYa6cWnO.js';
+import { P as PrefRenderer, T as ToolPrefLeaf, a as ToolPrefGroup } from './PrefsForm-BkUJZx0A.js';
 
 /**
  * Renders the control cell for one config leaf. Identical to weasel-ui's
@@ -159,4 +159,4 @@ interface ColorField extends ConfigFieldBase {
  *  panel renders, and what `validateConfigSchema` checks. */
 type ConfigField = SliderField | CheckboxField | SelectField | NumberField | TextField | ColorField;
 
-export type { Annotations as A, ConfigNode as C, InferConfig as I, LeafPatch as L, NodeOptions as N, ResolvedConfig as R, SectionSpec as S, TextField as T, ControlRenderer as a, ConfigOption as b, ConfigSchema as c, ConfigField as d, ConfigRule as e, ConfigRuleContext as f, CheckboxField as g, ColorField as h, ConfigFieldBase as i, ConfigFieldType as j, ConfigOf as k, NodeValue as l, NumberField as m, SelectField as n, SelectOption as o, SliderField as p };
+export type { Annotations as A, ConfigField as C, InferConfig as I, LeafPatch as L, NodeOptions as N, ResolvedConfig as R, SectionSpec as S, TextField as T, ConfigSchema as a, ConfigNode as b, ControlRenderer as c, ConfigOption as d, ConfigRule as e, ConfigRuleContext as f, CheckboxField as g, ColorField as h, ConfigFieldBase as i, ConfigFieldType as j, ConfigOf as k, NodeValue as l, NumberField as m, SelectField as n, SelectOption as o, SliderField as p };

package/dist/_dts/{types-1Sdxy_Pv.d.ts → types-DYMaEvM5.d.ts}

@@ -1,3 +1,17 @@
+/** A sidebar section torn out of its trial, and where it went. */
+interface UndockedPanel {
+    trialId: string;
+    sectionId: string;
+    as: 'tile' | 'floating';
+}
+/** Undocked panels, keyed by {@link panelKey}. */
+type UndockedPanels = Record<string, UndockedPanel>;
+declare function panelKey(trialId: string, sectionId: string): string;
+declare function undockPanel(panels: UndockedPanels, trialId: string, sectionId: string, as?: UndockedPanel['as']): UndockedPanels;
+/** Dock one section back, or — with no `sectionId` — every panel the trial
+ *  owns, which is what closing a trial wants. */
+declare function dockPanel(panels: UndockedPanels, trialId: string, sectionId?: string): UndockedPanels;
+
 /** A trial's undo history, as snapshots of its state either side of the
  *  present. */
 interface UndoStack {
@@ -16,6 +30,11 @@ interface TrialRecord<TS = unknown, TC = unknown, TV = unknown> {
     view: TV;
     /** This trial's own tool slot. Undefined means it reads the lab's. */
     activeToolId?: string | null;
+    /** The marks on this trial's annotation targets, as `AnnotationsApi.toJSON`
+     *  wrote them. Opaque here, and absent for a trial whose instrument declares
+     *  no `annotations` — or declares its own `storage`. Not in `state`, which
+     *  belongs to the instrument and is typed as such. */
+    annotations?: unknown;
     undoStack: UndoStack;
 }
 /** A named, saved copy of a trial's config and state, restorable into any
@@ -42,6 +61,9 @@ interface LabStoreState {
     /** Per-trial tile extents, keyed by trial id. Opaque here — the
      *  shape belongs to whatever lays the trials out. */
     layout: Record<string, unknown>;
+    /** Sidebar sections torn out of their trial. A panel here is not rendered in
+     *  its trial's sidebar; the workspace renders it instead. */
+    undockedPanels: UndockedPanels;
 }
 /** Where a lab persists itself. Implementations are keyed string storage and
  *  nothing more, so the same store works against localStorage, the URL hash,
@@ -81,10 +103,13 @@ interface LabDocument {
     trials: SerializedTrial[];
     saves: SavedSnapshot[];
     layout: Record<string, unknown>;
+    /** Sidebar sections torn out of their trial, keyed by trial and section. */
+    undockedPanels: UndockedPanels;
     mode: LabMode;
 }
 /** Migrates a document one version forward. Index `i` in the chain takes a
  *  version-`i` document to version `i + 1`. */
 type Migration = (doc: Record<string, unknown>) => Record<string, unknown>;
 
-export type { CreateLabStoreOptions as C, InstrumentSerializers as I, LabDocument as L, Migration as M, SerializedTrial as S, TrialRecord as T, UndoStack as U, StorageAdapter as a, LabStoreState as b, SavedSnapshot as c, TrialStateHandle as d, LabMode as e };
+export { dockPanel as g, panelKey as p, undockPanel as u };
+export type { CreateLabStoreOptions as C, InstrumentSerializers as I, LabDocument as L, Migration as M, SerializedTrial as S, TrialRecord as T, UndoStack as U, StorageAdapter as a, LabStoreState as b, SavedSnapshot as c, TrialStateHandle as d, UndockedPanel as e, UndockedPanels as f, LabMode as h };

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

@@ -1,4 +1,4 @@
-import { a as StorageAdapter, b as LabStoreState, T as TrialRecord, c as SavedSnapshot, e as LabMode, I as InstrumentSerializers, C as CreateLabStoreOptions, d as TrialStateHandle } from './types-1Sdxy_Pv.js';
+import { a as StorageAdapter, b as LabStoreState, T as TrialRecord, c as SavedSnapshot, h as LabMode, e as UndockedPanel, I as InstrumentSerializers, C as CreateLabStoreOptions, d as TrialStateHandle } from './types-DYMaEvM5.js';
 import * as react from 'react';
 import { ReactNode, ReactElement } from 'react';
 import { StoreApi } from 'zustand/vanilla';
@@ -25,6 +25,7 @@ interface LabStoreActions {
     updateTrialState: <TS>(id: string, next: TS | ((prev: TS) => TS)) => void;
     updateTrialConfig: <TC>(id: string, key: keyof TC, value: TC[keyof TC]) => void;
     updateTrialView: (id: string, view: unknown) => void;
+    updateTrialAnnotations: (id: string, doc: unknown) => void;
     updateTrialUndoStack: (id: string, next: TrialRecord['undoStack'] | ((prev: TrialRecord['undoStack']) => TrialRecord['undoStack'])) => void;
     setTrialInstrument: (id: string, instrumentName: string) => void;
     saveSnapshot: (trialId: string, name: string) => void;
@@ -35,6 +36,10 @@ interface LabStoreActions {
     setLabTool: (id: string | null) => void;
     setTrialTool: (trialId: string, id: string | null) => void;
     setLayout: (layout: Record<string, unknown>) => void;
+    /** Tear a sidebar section out of its trial. Default target is a workspace tile. */
+    undockPanel: (trialId: string, sectionId: string, as?: UndockedPanel['as']) => void;
+    /** Put one section back, or — with no `sectionId` — every panel the trial owns. */
+    dockPanel: (trialId: string, sectionId?: string) => void;
 }
 /** A lab's store: its state and actions, plus the hook instruments use to
  *  register how their state is serialized. */
@@ -71,7 +76,7 @@ declare function TrialIdProvider({ trialId, children, }: {
 declare function useTrialId(): string;
 
 /** Bumped whenever the persisted shape changes; every bump needs a migration. */
-declare const CURRENT_DOCUMENT_VERSION = 2;
+declare const CURRENT_DOCUMENT_VERSION = 3;
 /** The one key a lab persists under. The `:doc` suffix keeps it out of the
  *  legacy bucket namespace, where a lab named `a:saves` would otherwise write
  *  its document over lab `a`'s saves bucket. */