@weasel-js/labkit 1.4.1 → 1.4.3

package/dist/dragdrop/index.d.ts

@@ -1,10 +1,11 @@
-import { P as PaletteItem, a as Point, D as DragFeedback, b as DragDropCapability, V as ViewTransform, c as WorldSpec } from '../_dts/frac-X7mWgd7y.js';
+import { P as PaletteItem, a as Point, D as DragFeedback, b as DragDropCapability, V as ViewTransform, c as WorldSpec } from '../_dts/frac-B5mB8LsJ.js';
 import * as react_jsx_runtime from 'react/jsx-runtime';
-import { RefObject, ReactPortal } from 'react';
-import '../_dts/types-lg4TSCb2.js';
-import '../_dts/weasel-canvas-FJTFi3ZZ.js';
-import '../_dts/PrefsForm.d-CgxUequc.js';
-import '../_dts/types-ChVJJHvk.js';
+import { RefObject, PointerEvent, ReactPortal } from 'react';
+import '../_dts/types-B9_zrHmb.js';
+import '@weasel-js/core';
+import '../_dts/PrefsForm.d-DDHFANkc.js';
+import '../_dts/types-x92Kfeme.js';
+import '../_dts/types-BP2OCcpg.js';
 import '../_dts/types-DJ79Tg5J.js';
 
 interface DragState {
@@ -26,7 +27,7 @@ interface UseDragDropArgs<TS, TC> {
 }
 interface UseDragDropResult {
     drag: DragState | null;
-    startDrag: (item: PaletteItem, originScreenPos: Point) => void;
+    startDrag: (item: PaletteItem, e: PointerEvent) => void;
 }
 declare function useDragDrop<TS, TC>({ capability, canvasContainerRef, view, state, config, setState, emit, worldSpec, }: UseDragDropArgs<TS, TC>): UseDragDropResult;
 interface DragOverlayProps {
@@ -42,7 +43,7 @@ declare function DragGhost({ item, screenPos }: DragGhostProps): ReactPortal | n
 
 interface PaletteProps {
     items: PaletteItem[];
-    onDragStart: (item: PaletteItem, originScreenPos: Point) => void;
+    onDragStart: (item: PaletteItem, e: PointerEvent) => void;
     className?: string;
 }
 declare function Palette({ items, onDragStart, className }: PaletteProps): react_jsx_runtime.JSX.Element;

package/dist/dragdrop/index.js

@@ -1,5 +1,4 @@
-export { DragGhost, DragOverlay, Palette, useDragDrop } from '../chunk-D7QIPGEB.js';
+export { DragGhost, DragOverlay, Palette, useDragDrop } from '../chunk-RS3HRQWU.js';
 import '../chunk-2AYGEN57.js';
-import '../chunk-DG2IFMLA.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/index.d.ts

@@ -2,27 +2,30 @@ 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 } from 'react';
-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-FEa1MudK.js';
-import { D as DrawCommand, N as Node, V as View, P as Path, F as FillStyle, b as StyledRun, c as TextStyle, d as Stroke, B as BuiltinToolId, T as ToolPrefLeaf } from './_dts/weasel-canvas-FJTFi3ZZ.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-X7mWgd7y.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-X7mWgd7y.js';
+import { P as PropertyMetricProps, a as PropertyListPack } from './_dts/index-DelFfeV0.js';
+export { C as CheckboxRow, b as CheckboxRowProps, c as ColorRow, d as ColorRowProps, e as ControlPanel, N as NumberRow, f as NumberRowProps, g as PropertyList, h as PropertyListProps, i as PropertyOption, j as PropertyPanel, k as PropertyPanelProps, l as PropertyRow, m as PropertyRowLayout, n as PropertyRowProps, o as PropertyRowVariant, p as PropertySpan, q as PropertySpanProps, S as SelectRow, r as SelectRowProps, s as SliderRow, t as SliderRowProps, T as TextRow, u as TextRowProps, v as ToggleRow, w as ToggleRowProps } from './_dts/index-DelFfeV0.js';
+import { DrawCommand, SceneNode, View, Path, FillStyle, StyledRun, TextStyle, Stroke, BuiltinToolId, ToolPrefLeaf, ToolPrefGroup } from '@weasel-js/core';
+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-B5mB8LsJ.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-B5mB8LsJ.js';
+import { i as TrialInfo, a as StorageAdapter, h as LabMode, T as TrialRecord, c as SavedSnapshot } from './_dts/types-BP2OCcpg.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-BP2OCcpg.js';
 export { CanvasStack, CanvasStackProps, OrbitHandlers, OrbitView, PITCH_LIMIT, PanZoomHandlers, UseOrbitOptions, UsePanZoomOptions, Vec3, ZoomAtOptions, centerOn, clampPitch, orbitAfterDrag, orbitAfterWheel, screenToWorld, useOrbit, usePanZoom, worldToScreen, wrapYaw, zoomAt } from './canvas/index.js';
-export { C as CanvasLayerDescriptor, a as CanvasStackContext, b as CanvasStackContextValue, c as CanvasStackSurface } from './_dts/CanvasStackContext-BIRUVVGH.js';
-export { PaletteRegion, PaletteRegionProps, SidebarRegion, SidebarRegionProps, StatusRegion, StatusRegionProps, TitleBarRegion, TitleBarRegionProps, ToolbarRegion, ToolbarRegionProps, ViewportRegion, ViewportRegionProps, builtinContributions, mergeContributions, suppressContributions } from './chrome/index.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-lg4TSCb2.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-lg4TSCb2.js';
+export { C as CanvasLayerDescriptor, a as CanvasStackContext, b as CanvasStackContextValue, c as CanvasStackSurface } from './_dts/CanvasStackContext-Dde8_1my.js';
+export { PaletteRegion, PaletteRegionProps, SidebarRegion, SidebarRegionProps, StatusRegion, StatusRegionProps, TitleBarPlacement, TitleBarRegion, TitleBarRegionProps, ToolbarRegion, ToolbarRegionProps, ViewportRegion, ViewportRegionProps, builtinContributions, mergeContributions, suppressContributions } from './chrome/index.js';
+import { b as ConfigNode, A as Annotations, N as NodeOptions, c as ControlRenderer, d as ConfigOption, e as ConfigShape, f as ConfigBranch, B as BranchAnnotations, g as BranchOptions, a as ConfigSchema, I as InferConfig, h as ConfigEntry, R as ResolvedConfig, i as ConfigRule, L as LeafPatch, j as ConfigRuleContext } from './_dts/types-B9_zrHmb.js';
+export { k as ConfigOf, C as ConfigPath, E as EntryValue, l as NodeValue, S as SectionSpec, V as ValueAtPath } from './_dts/types-B9_zrHmb.js';
+import { C as ConfigField } from './_dts/types-x92Kfeme.js';
+export { a as CheckboxField, b as ColorField, c as ConfigFieldBase, d as ConfigFieldType, N as NumberField, S as SelectField, e as SelectOption, f as SliderField, T as TextField } from './_dts/types-x92Kfeme.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, h as LabMode, T as TrialRecord, c as SavedSnapshot } from './_dts/types-ChVJJHvk.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-ChVJJHvk.js';
-export { LayerList, LayerListProps } from './layers/index.js';
+export { LayerList, LayerListProps, LayerTreeNode } 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-Cdm13fvl.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-D6Vb3T-g.js';
 export { Box, Rect, SurfaceCanvasContext, SurfaceContext, SurfaceFrame, SurfaceHandle, TilePainter, UseTiledSurfaceOptions, composeRects, rectsEqual, toDeviceRect, useSurface, useSurfaceCanvas, useSurfaceOptional, useSurfaceTile, useTileId, useTiledSurface } from './surface/index.js';
 export { EventBus, EventListener, clearUndo, createEventBus, emptyStack, pushSnapshot, redo, undo } from './undo/index.js';
-import './_dts/PrefsForm.d-CgxUequc.js';
+import './_dts/PrefsForm.d-DDHFANkc.js';
 import 'windease';
 import 'zustand/vanilla';
 
@@ -64,14 +67,14 @@ interface CurveFieldProps {
 declare function CurveField({ values, min, max, step, width, height, defaults, onChange, marks, }: CurveFieldProps): react_jsx_runtime.JSX.Element;
 
 /** Props for `<Subpanel>`. */
-interface SubpanelProps {
+interface SubpanelProps extends PropertyMetricProps {
     title: ReactNode;
     children: ReactNode;
     className?: string;
 }
 /** A typographic divider inside a property list: a small title flanked by a
  *  rule. Purely a heading — use `<PropertyGroup>` for a bordered section. */
-declare function Subpanel({ title, children, className }: SubpanelProps): react_jsx_runtime.JSX.Element;
+declare function Subpanel({ title, children, className, density, align }: SubpanelProps): react_jsx_runtime.JSX.Element;
 /** Props for `<EffectCard>`. */
 interface EffectCardProps {
     /** Card title rendered in the title bar (e.g. effect kind label or a select). */
@@ -131,27 +134,40 @@ interface EffectCardListProps<T extends EffectCardListItem> {
 declare function EffectCardList<T extends EffectCardListItem>({ items, renderItem, onReorder, empty, defaultExpandedIds, }: EffectCardListProps<T>): react_jsx_runtime.JSX.Element;
 
 /** Props for `<PropertyGroup>`. */
-interface PropertyGroupProps {
+interface PropertyGroupProps extends PropertyMetricProps {
     /** Title rendered between two rules at the top of the group. */
     title: ReactNode;
     /** When true the group renders nothing — useful for conditional sections. */
     hidden?: boolean;
-    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.
-     *   - `'pairs'`: every row auto-places into the 2-column grid two-per-row.
+     * Give the title a twisty that folds the rows away. Implied by any of the
+     * three props below, so it is only needed for a group that starts open and
+     * keeps its own state.
+     */
+    collapsible?: boolean;
+    /** Start folded. Read once; the group owns the state from then on. */
+    defaultCollapsed?: boolean;
+    /**
+     * Folded or not, as the consumer holds it. Given, the group keeps no state
+     * of its own and every toggle arrives at `onCollapsedChange` instead — which
+     * is what a panel that remembers its sections past a reload needs.
      */
-    pack?: 'auto-color' | 'pairs';
+    collapsed?: boolean;
+    onCollapsedChange?: (next: boolean) => void;
+    children: ReactNode;
+    className?: string;
+    /** How rows pack into the 2-column grid — see `<PropertyList pack>`. */
+    pack?: PropertyListPack;
 }
 /**
  * Visually-bordered group inside a PropertyList. Use to scope a set of
  * related rows under a heading (e.g. "Aqua", "Bevel", "Dome" sections
  * inside a fill effect's controls).
+ *
+ * A collapsible group keeps its rows mounted and hides them, so a control's
+ * local state survives being folded away.
  */
-declare function PropertyGroup({ title, hidden, children, className, pack, }: PropertyGroupProps): react_jsx_runtime.JSX.Element | null;
+declare function PropertyGroup({ title, hidden, collapsible, defaultCollapsed, collapsed, onCollapsedChange, children, className, pack, density, align, }: PropertyGroupProps): react_jsx_runtime.JSX.Element | null;
 
 /** The subset of a mark's scene node this needs: where it is, and what it is. */
 interface PaintableMark {
@@ -201,7 +217,7 @@ interface MarkDrawOptions {
  * 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[];
+declare function createMarkDrawOne(opts: MarkDrawOptions): (node: SceneNode<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. */
@@ -445,8 +461,11 @@ interface SvgTextNode {
      * 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.
+     *
+     * `null` is SVG's `fill="none"`: outline-only text, painted by its stroke
+     * alone. Absent takes the default black.
      */
-    fill?: FillStyle;
+    fill?: FillStyle | null;
     stroke?: Stroke;
     /** Element-level opacity (`opacity="..."`), 0..1. */
     opacity?: number;
@@ -536,11 +555,14 @@ interface AnnotationTargetsProps {
     capability: AnnotationsCapability;
     state: unknown;
     config: unknown;
+    /** The trial these targets belong to. `capability.targets` is told it, so a
+     *  consumer holding per-trial refs can hand back this trial's. */
+    trial: TrialInfo;
     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;
+declare function AnnotationTargets({ capability, state, config, trial, 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. */
@@ -583,6 +605,8 @@ declare function fromWeaselView(v: View): ViewTransform;
  */
 declare function fitView(content: ContentSize, pane: PaneSize): ViewTransform;
 
+/** Whether a schema entry is a branch rather than a leaf. */
+declare function isConfigBranch(entry: ConfigEntry): entry is ConfigBranch;
 /** Shared chaining surface. Every method clones, so a node can be reused as a
  *  base for several leaves without one bleeding into the next. */
 declare abstract class BaseNode<T> implements ConfigNode<T> {
@@ -604,8 +628,11 @@ declare abstract class BaseNode<T> implements ConfigNode<T> {
     hidden(): this;
     /** Pair with a sibling sharing this id, side-by-side on one row. */
     pair(pair: string): this;
-    /** Render under a named section heading. */
-    section(section: string): this;
+    /** Render under a named section heading. `collapsed` opens the section
+     *  folded — say it on any one of the section's leaves. */
+    section(label: string, opts?: {
+        collapsed?: boolean;
+    }): this;
     /** Show this row only while the predicate holds. Presentational — the value
      *  stays in config and the instrument still reads it. */
     showIf(predicate: (config: Record<string, unknown>) => boolean): this;
@@ -659,6 +686,31 @@ declare class CustomNode<T> extends BaseNode<T> {
     constructor(kind: string, defaultValue: T, annotations?: Readonly<Annotations>, options?: Readonly<NodeOptions>);
     protected with(annotations: Annotations, options: NodeOptions): this;
 }
+/**
+ * A branch of the schema: its children nest under its key, so a leaf inside
+ * one is read and written at a dotted path. Distinct from `.section()`, which
+ * puts a heading over sibling leaves and leaves their paths alone.
+ */
+declare class GroupNode<S extends ConfigShape> implements ConfigBranch<S> {
+    readonly children: S;
+    readonly annotations: Readonly<BranchAnnotations>;
+    readonly options: Readonly<BranchOptions>;
+    constructor(children: S, annotations?: Readonly<BranchAnnotations>, options?: Readonly<BranchOptions>);
+    private with;
+    /** Heading for the group's rows. Defaults to the key, title-cased. */
+    label(name: string): GroupNode<S>;
+    /** Longer help text. Carried on the resolved `PrefGroup`, where weasel-ui's
+     *  `PrefsForm` draws it under the heading; `ControlPanel` has no place for
+     *  it yet and shows the heading alone. */
+    describe(description: string): GroupNode<S>;
+    /** Render this whole group under a named section heading. */
+    section(label: string, opts?: {
+        collapsed?: boolean;
+    }): GroupNode<S>;
+    /** Show this group only while the predicate holds. Presentational — every
+     *  value beneath it stays in config and the instrument still reads it. */
+    showIf(predicate: (config: Record<string, unknown>) => boolean): GroupNode<S>;
+}
 /**
  * Builds an instrument's config: the values, their types, and how each is
  * edited, in one declaration.
@@ -667,6 +719,8 @@ declare class CustomNode<T> extends BaseNode<T> {
  * const config = f.schema({
  *   showGrid: f.boolean(true),
  *   cellSize: f.number(20).range(5, 80).step(5).label('Grid spacing'),
+ *   // Nested: read and written at `grid.color`.
+ *   grid: f.group({ color: f.color('#ffffff') }),
  * })
  * ```
  */
@@ -682,10 +736,14 @@ declare const f: {
     /** A leaf with no declared kind: the rule chain decides, which is how a lab
      *  states a convention like "every `*Color` key is a color picker". */
     value: <T>(def: T) => ValueNode<T>;
+    /** A branch: its children nest under this key, so `grid: f.group({ size })`
+     *  puts the value at `config.grid.size` and addresses it as `'grid.size'`.
+     *  Groups nest as deeply as the schema wants. */
+    group: <const S extends ConfigShape>(children: S) => GroupNode<S>;
     /** A leaf of a kind a lab supplies the control for, through `controls`. */
     custom: <T>(kind: string, def: T, validate?: (leaf: ToolPrefLeaf) => string[]) => CustomNode<T>;
-    /** Collect leaves into an instrument's config. */
-    schema<S extends Record<string, ConfigNode>>(nodes: S): ConfigSchema<InferConfig<S>>;
+    /** Collect leaves and groups into an instrument's config. */
+    schema<S extends ConfigShape>(nodes: S): ConfigSchema<InferConfig<S>>;
 };
 
 /**
@@ -697,12 +755,37 @@ declare const f: {
  */
 declare function fromConfigFields(fields: readonly ConfigField[]): ResolvedConfig;
 
+/** The value at a dotted path. `undefined` when a segment is missing or the
+ *  walk hits something that is not a record. */
+declare function valueAtPath(config: unknown, path: string): unknown;
+/** Whether a dotted path is actually present, which a `undefined` value is
+ *  not enough to tell you. */
+declare function hasConfigPath(config: unknown, path: string): boolean;
+/** A copy of `config` with `value` written at a dotted path. Every record on
+ *  the way down is copied and the input is left alone; a missing — or
+ *  non-record — intermediate is replaced with the branch the path implies. */
+declare function withValueAtPath<T>(config: T, path: string, value: unknown): T;
+/**
+ * `stored` with every gap filled from `defaults`, down the whole tree.
+ *
+ * This is how a config written before its schema grew a branch still loads:
+ * the branch arrives at its defaults instead of `undefined`, and a key the
+ * defaults no longer mention is kept rather than dropped, so nothing is lost
+ * to a schema change the author has not finished making.
+ */
+declare function fillConfigDefaults<T>(stored: unknown, defaults: T): T;
+/** A node in a resolved schema tree, by dotted path. Structural rather than
+ *  `isPrefLeaf` so this stays free of a runtime import. */
+declare function schemaNodeAtPath(group: ToolPrefGroup, path: string): ToolPrefLeaf | ToolPrefGroup | undefined;
+
 /**
  * Resolve a schema into the vocabulary weasel-ui renders, running each leaf
  * through the consumer's rules and then labkit's own.
  *
- * The group is flat — every leaf is a direct child — so a leaf's path is its
- * config key and both `ControlPanel` and `PrefsForm` address it identically.
+ * The group mirrors the schema's own nesting: an `f.group` becomes a nested
+ * `PrefGroup`, so a leaf's dotted path within the tree is the path its value
+ * is written at, and both `ControlPanel` and `PrefsForm` address it
+ * identically.
  */
 declare function resolveConfigSchema<TC>(schema: ConfigSchema<TC>, rules?: readonly ConfigRule[]): ResolvedConfig;
 
@@ -733,9 +816,10 @@ declare function applyRules(seed: LeafPatch, ctx: Omit<ConfigRuleContext, 'leaf'
 declare function useConfigSchema(instrument: Instrument<any, any, any>): ResolvedConfig;
 
 /**
- * Whether a leaf's row should be drawn right now.
+ * Whether the row at a dotted path should be drawn right now. A group answers
+ * for its whole subtree — hiding one hides everything under it.
  *
- * `hidden` is the leaf's own static flag; `showIf` is the schema's predicate
+ * `hidden` is the node's own static flag; `showIf` is the schema's predicate
  * over the live config. Both are presentational — a hidden leaf keeps its
  * value and the instrument still reads it.
  */
@@ -816,13 +900,43 @@ interface LabProps {
  *  per record in a grid. Each trial runs one of `instruments`. */
 declare function Lab({ instruments, defaultInstrument, storage, storageKey, mode, nebula, title, footer, chrome, suppress, tools, configRules, controls, children, }: LabProps): react_jsx_runtime.JSX.Element;
 
+/** What a trial opens on beyond its instrument's own defaults. */
+interface AddTrialOptions<TC = Record<string, unknown>> {
+    /** Overlaid on `defaultConfig()` before `initialState` reads it, so a trial
+     *  opened on a subject is running that subject from its first frame. Keys
+     *  whose value is `undefined` are left to the default. */
+    config?: Partial<TC>;
+}
+/** Append a new trial running `instrumentName`, at that instrument's default
+ *  config — with `options.config` written over it — and the initial state
+ *  that config produces. */
+declare function addTrial(trials: TrialRecord[], instruments: InstrumentList, instrumentName: string, options?: AddTrialOptions): TrialRecord[];
+/** Insert a deep copy of a trial directly after it. The copy starts with
+ *  an empty undo history — the original's is not shared. */
+declare function cloneTrial(trials: TrialRecord[], id: string): TrialRecord[];
+/** Remove a trial, unless it is the last one — a lab always has at least
+ *  one. */
+declare function closeTrial(trials: TrialRecord[], id: string): TrialRecord[];
+/** Return a trial to what it opened on — its instrument's defaults under the
+ *  seed `addTrial` was given — keeping its id and its place in the list. */
+declare function resetTrial(trials: TrialRecord[], id: string, instruments: InstrumentList): TrialRecord[];
+/**
+ * Reorder to match `ids`. Ids the list doesn't mention keep their relative
+ * order at the end, and ids it names that no longer exist are dropped — a
+ * reorder that raced a close should not resurrect the closed trial.
+ */
+declare function reorderTrials(trials: TrialRecord[], ids: readonly string[]): TrialRecord[];
+
 /** Lab-wide state and commands: the available instruments, the open
  *  trials and the operations over them, saved snapshots, and the color
  *  mode. */
 interface LabContextValue {
     instruments: InstrumentList;
     trials: TrialRecord[];
-    addTrial: (instrumentName: string) => void;
+    /** Open a trial running `instrumentName`. `options.config` is written over
+     *  that instrument's defaults, which is where a trial opened on a subject
+     *  says which subject. */
+    addTrial: (instrumentName: string, options?: AddTrialOptions) => void;
     cloneTrial: (id: string) => void;
     closeTrial: (id: string) => void;
     resetTrial: (id: string) => void;
@@ -1069,24 +1183,5 @@ interface TrialChromeProps {
  *  each region its slice. */
 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. */
-declare function addTrial(trials: TrialRecord[], instruments: InstrumentList, instrumentName: string): TrialRecord[];
-/** Insert a deep copy of a trial directly after it. The copy starts with
- *  an empty undo history — the original's is not shared. */
-declare function cloneTrial(trials: TrialRecord[], id: string): TrialRecord[];
-/** Remove a trial, unless it is the last one — a lab always has at least
- *  one. */
-declare function closeTrial(trials: TrialRecord[], id: string): TrialRecord[];
-/** Return a trial to its instrument's defaults, keeping its id and its
- *  place in the list. */
-declare function resetTrial(trials: TrialRecord[], id: string, instruments: InstrumentList): TrialRecord[];
-/**
- * Reorder to match `ids`. Ids the list doesn't mention keep their relative
- * order at the end, and ids it names that no longer exist are dropped — a
- * reorder that raced a close should not resurrect the closed trial.
- */
-declare function reorderTrials(trials: TrialRecord[], ids: readonly string[]): TrialRecord[];
-
-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, PropertyGroup, ResolvedConfig, SavedSnapshot, StorageAdapter, Subpanel, Trial, TrialBody, TrialChrome, TrialContribution, TrialRecord, TrialTool, ViewTransform, Workspace, WorldRect, addTrial, annotationToolInfo, applyRules, as2DView, builtinRules, capturePlan, captureTarget, cloneTrial, closeTrial, composeCaptureSvg, createMarkDrawOne, defineInstrument, f, fitView, fromConfigFields, fromWeaselView, interstellarTheme, isLeafVisible, isStale, markCommands, markSvgNodes, reorderTrials, resetTrial, resolveConfigSchema, resolveMarkStyle, seenFrom, titleCase, toWeaselView, useAnnotations, useAnnotationsOptional, useConfigSchema, useLabContext, validateConfigSchema };
-export type { AnnotationOverlayProps, AnnotationTargetsProps, AnnotationToolInfo, CaptureArgs, CapturePlan, ComposeSvgArgs, ContentSize, CurveFieldProps, CurveMark, EffectCardListItem, EffectCardListProps, EffectCardProps, InstrumentSpec, LabContextValue, LabPaletteProps, LabProps, LabShellProps, MarkDrawOptions, MarkListProps, MarkStyle, PaintableMark, PaneSize, PanelDescriptor, PropertyGroupProps, SubpanelProps, TrialBodyProps, TrialChromeProps, TrialLayout, TrialProps, UndoBindings, ValidationResult, ViewTransform2D, WorkspaceProps };
+export { ANNOTATION_TOOLS, ANNOTATION_WEASEL_TOOLS, AnnotationData, AnnotationKind, AnnotationMeaning, AnnotationOverlay, AnnotationTarget, AnnotationTargets, Annotations, AnnotationsApi, AnnotationsCapability, AnnotationsContext, BranchAnnotations, BranchOptions, CaptureOptions, CaptureResult, CaptureSource, ConfigBranch, ConfigEntry, ConfigField, ConfigNode, ConfigOption, ConfigRule, ConfigRuleContext, ConfigSchema, ConfigShape, ControlRenderer, CurveField, DEFAULT_VIEW, EffectCard, EffectCardList, ExportMenu, InferConfig, Instrument, InstrumentList, JobHandle, Lab, LabContext, LabMode, LabPalette, LabShell, LeafPatch, MarkList, MarkScene, NodeOptions, PropertyGroup, PropertyListPack, ResolvedConfig, SavedSnapshot, StorageAdapter, Subpanel, Trial, TrialBody, TrialChrome, TrialContribution, TrialInfo, TrialRecord, TrialTool, ViewTransform, Workspace, WorldRect, addTrial, annotationToolInfo, applyRules, as2DView, builtinRules, capturePlan, captureTarget, cloneTrial, closeTrial, composeCaptureSvg, createMarkDrawOne, defineInstrument, f, fillConfigDefaults, fitView, fromConfigFields, fromWeaselView, hasConfigPath, interstellarTheme, isConfigBranch, isLeafVisible, isStale, markCommands, markSvgNodes, reorderTrials, resetTrial, resolveConfigSchema, resolveMarkStyle, schemaNodeAtPath, seenFrom, titleCase, toWeaselView, useAnnotations, useAnnotationsOptional, useConfigSchema, useLabContext, validateConfigSchema, valueAtPath, withValueAtPath };
+export type { AddTrialOptions, AnnotationOverlayProps, AnnotationTargetsProps, AnnotationToolInfo, CaptureArgs, CapturePlan, ComposeSvgArgs, ContentSize, CurveFieldProps, CurveMark, EffectCardListItem, EffectCardListProps, EffectCardProps, InstrumentSpec, LabContextValue, LabPaletteProps, LabProps, LabShellProps, MarkDrawOptions, MarkListProps, MarkStyle, PaintableMark, PaneSize, PanelDescriptor, PropertyGroupProps, SubpanelProps, TrialBodyProps, TrialChromeProps, TrialLayout, TrialProps, UndoBindings, ValidationResult, ViewTransform2D, WorkspaceProps };