@weasel-js/labkit 1.4.1 → 1.4.3

package/README.md

@@ -13,10 +13,16 @@ algorithm and would rather not build the page around it.
 ## Install
 
 ```bash
-npm i @weasel-js/labkit
+npm i @weasel-js/labkit @weasel-js/core
 ```
 
-React 19 is a peer dependency (`react` and `react-dom`, `^19.0.0`). One
+`@weasel-js/core` is a peer dependency, pinned to the matching version. labkit
+does not ship its own copy: core keeps its content handlers, paint kinds, shape
+painters and markers in module-global registries, and two copies means anything
+registered through one is invisible to the other — a blank canvas with no error.
+Installing it alongside is what guarantees there is exactly one.
+
+React 19 is a peer dependency too (`react` and `react-dom`, `^19.0.0`). One
 stylesheet import covers everything labkit draws, including the theme tokens and
 the `@weasel-js/ui` components it passes through:
 
@@ -70,6 +76,18 @@ renders the settings panel from it. `render` returns the instrument's own DOM;
 returning `null` alongside `canvas` means the canvas layers are the whole
 picture. `storage` keeps open trials and their state across reloads.
 
+A value is addressed by its path: `bins` above sits at `config.bins` and is
+written as `setConfig('bins', 40)`. `f.group` nests one —
+`paper: f.group({ width: f.number(210) })` puts the value at
+`config.paper.width` and addresses it as `'paper.width'`, in `setConfig`, in a
+control override, and anywhere else a path is taken. `.section('Advanced')` is
+the other thing and only looks like it: it puts a heading over sibling rows and
+leaves their paths alone.
+
+A stored config missing something its schema has since gained — a whole nested
+group included — is filled from the instrument's defaults as it loads, so
+growing a schema never strands a saved trial or a snapshot.
+
 ## Capabilities
 
 A capability is a field on the instrument. Declaring it is what makes the trial
@@ -120,6 +138,14 @@ changed draws dashed and reports `isStale`. `meaning.statuses` is the optional
 vocabulary a mark can be labelled with — a status carries its own color, which
 the mark on the canvas follows.
 
+`targets` is declared once per instrument and called once per trial, with the
+asking trial as its third argument: `targets(state, config, trial)`. `trial.id`
+is the id `useTileId` scopes a surface tile under, so a consumer holding its own
+per-trial refs keys them by it and hands back the ones this trial owns; a
+module-level ref like the one above is one ref shared by every trial of the
+instrument, which only shows once a second trial is open. `trial.view` is that
+trial's camera.
+
 Marks live in the trial's record and survive a reload. An instrument that would
 rather keep them in a format it already owns declares `annotations.storage` with
 a `load`/`save` pair, and labkit never writes its own slot.

package/dist/_dts/{CanvasStackContext-BIRUVVGH.d.ts → CanvasStackContext-Dde8_1my.d.ts}

@@ -1,6 +1,6 @@
 import * as react from 'react';
 import { RefObject } from 'react';
-import { V as ViewTransform, W as WorldFrame } from './frac-X7mWgd7y.js';
+import { V as ViewTransform, W as WorldFrame } from './frac-B5mB8LsJ.js';
 
 /** One layer of a canvas stack: its id, whether it is currently shown, and how
  *  it paints itself. */

package/dist/_dts/{PrefsForm.d-CgxUequc.d.ts → PrefsForm.d-DDHFANkc.d.ts}

@@ -1,5 +1,5 @@
 import { ReactNode } from 'react';
-import { T as ToolPrefLeaf } from './weasel-canvas-FJTFi3ZZ.js';
+import { ToolPrefLeaf } from '@weasel-js/core';
 
 /** What a {@link PrefRenderer} is given for the leaf it is rendering. */
 interface PrefRenderContext {

package/dist/_dts/{frac-X7mWgd7y.d.ts → frac-B5mB8LsJ.d.ts}

@@ -1,8 +1,9 @@
 import { ComponentType, ReactNode, RefObject } from 'react';
-import { R as ResolvedConfig, C as ConfigField, a as ConfigSchema } from './types-lg4TSCb2.js';
-import { c as SavedSnapshot } from './types-ChVJJHvk.js';
+import { R as ResolvedConfig, a as ConfigSchema, C as ConfigPath } from './types-B9_zrHmb.js';
+import { C as ConfigField } from './types-x92Kfeme.js';
+import { c as SavedSnapshot, i as TrialInfo } from './types-BP2OCcpg.js';
 import { J as JobHandle, a as JobCapability } from './types-DJ79Tg5J.js';
-import { S as Scene } from './weasel-canvas-FJTFi3ZZ.js';
+import { Scene } from '@weasel-js/core';
 
 /** How an instrument's world sits on the canvas, independent of the camera.
  *  The defaults reproduce the convention labkit shipped before this existed:
@@ -53,7 +54,10 @@ interface ToolbarItem {
     pressed?: boolean;
     /** Render the label beside the glyph rather than only in the tooltip. */
     showLabel?: boolean;
-    onActivate: () => void;
+    /** Handed the trial's chrome context, so a contribution declared from the
+     *  lab can reach `ctx.saveSnapshot()` and the rest without the `render`
+     *  escape. A zero-argument handler stays valid. */
+    onActivate: (ctx: TrialChromeContext) => void;
 }
 /** A selectable tool in the palette region. */
 interface ToolItem {
@@ -65,7 +69,7 @@ interface ToolItem {
 /** A titled block in the sidebar. */
 interface SidebarSection {
     title: string;
-    /** Starts collapsed. The open/closed state itself is the region's. */
+    /** Starts collapsed, until the trial remembers a fold of its own. */
     defaultCollapsed?: boolean;
     /** Offer the tear-out control. On by default; a section that only makes
      *  sense beside its trial sets this false. */
@@ -79,7 +83,8 @@ interface ViewportControl {
     icon: IconComponent;
     label: string;
     disabled?: boolean;
-    onActivate: () => void;
+    /** Handed the trial's chrome context, as `ToolbarItem.onActivate` is. */
+    onActivate: (ctx: TrialChromeContext) => void;
 }
 /** A readout in the status bar. */
 interface StatusReadout {
@@ -139,6 +144,12 @@ type TrialContribution = (ContributionBase & {
 interface TrialChromeContext {
     trialId: string;
     instrumentName: string;
+    /** What the title bar reads, which is the instrument's name until something
+     *  calls `setTitle`. */
+    title: string;
+    /** Retitle this trial; `null` restores the instrument name. Persisted with
+     *  the trial, so a title survives a reload. */
+    setTitle: (title: string | null) => void;
     isLastTrial: boolean;
     /** Null when the trial holds a view that is not the 2D one. */
     zoom: number | null;
@@ -159,6 +170,13 @@ interface TrialChromeContext {
     configFields: ConfigField[];
     config: unknown;
     setConfig: (key: string, value: unknown) => void;
+    /** Which of this trial's collapsible sections are folded. A sidebar
+     *  section's key is its contribution id; a section *inside* a contribution —
+     *  a control panel's property group — is keyed `<contribution id>/<label>`.
+     *  A section absent here is at its own default. Persisted with the trial. */
+    collapsedSections: Readonly<Record<string, boolean>>;
+    /** Fold or unfold one section, keyed as `collapsedSections` is. */
+    setSectionCollapsed: (key: string, collapsed: boolean) => void;
     /** Section ids this trial currently has torn out of its sidebar. */
     undockedPanels: readonly string[];
     /** Tear a sidebar section out into the workspace. */
@@ -282,12 +300,12 @@ interface RenderContext<TS = unknown, TC = unknown> {
     state: TS;
     config: TC;
     setState: (next: TS | ((prev: TS) => TS)) => void;
-    setConfig: (key: keyof TC, value: unknown) => void;
-    trial: {
-        id: string;
-        /** The trial's view, in whatever shape this instrument chose. labkit persists
-         *  it and restores it on Reset without ever reading into it. */
-        view: unknown;
+    /** Write one config value, by dotted path — `'grid.size'` for a leaf under
+     *  an `f.group`, `'cellSize'` for one at the root. */
+    setConfig: (path: ConfigPath<TC>, value: unknown) => void;
+    /** labkit persists `view` and restores it on Reset without ever reading
+     *  into it. */
+    trial: TrialInfo & {
         setView: (next: unknown) => void;
         /** 2D convenience over `view`. Reads 1 and writes nothing when the trial holds
          *  a view that is not the 2D one. */
@@ -641,7 +659,9 @@ interface AnnotationStorage {
 /** Declares that an instrument accepts marks: which regions take them,
  *  optionally what a mark is allowed to mean, and optionally where they live. */
 interface AnnotationsCapability<TS = unknown, TC = unknown> {
-    targets: (state: TS, config: TC) => readonly AnnotationTarget[];
+    /** `trial` is which trial is asking: a declaration made once per instrument
+     *  is called once per trial, and its targets are that trial's own. */
+    targets: (state: TS, config: TC, trial: TrialInfo) => readonly AnnotationTarget[];
     meaning?: AnnotationMeaning;
     storage?: AnnotationStorage;
     /** Fires after every finished export, labkit's own chrome included. A

package/dist/_dts/{index-FEa1MudK.d.ts → index-DelFfeV0.d.ts}

@@ -1,20 +1,45 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import { ReactNode } from 'react';
-import { R as ResolvedConfig, C as ConfigField, c as ControlRenderer } from './types-lg4TSCb2.js';
+import { R as ResolvedConfig, c as ControlRenderer } from './types-B9_zrHmb.js';
+import { C as ConfigField } from './types-x92Kfeme.js';
 
+/**
+ * How much room a container gives its rows — gaps, padding, and field height,
+ * moved together. Set on any container in the family; it reaches every
+ * descendant, so an inner group can differ from the panel around it.
+ */
+type PropertyDensity = 'tight' | 'normal' | 'roomy';
+/** Where an inline row's label and control sit on the row's cross axis. Set on
+ *  a container to line a whole column of them up. */
+type PropertyAlign = 'start' | 'center' | 'end' | 'baseline';
+/** Metric props every container in the family takes. Both reach descendants,
+ *  so the nearest container that states one wins. */
+interface PropertyMetricProps {
+    /** Room the rows get. Unset inherits from an outer container, else `normal`. */
+    density?: PropertyDensity;
+    /**
+     * Cross-axis alignment of an inline row's label and control. `baseline` sits
+     * the control on the label's first-line baseline, which is what lines a
+     * column of swatches up against labels of different heights. Unset keeps each
+     * variant's own alignment — a color row centers its label and swatch and
+     * sinks the pair to the row's bottom edge, which keeps a paired alpha track
+     * level with its neighbour.
+     */
+    align?: PropertyAlign;
+}
 /** Props for `<PropertyPanel>`. */
-interface PropertyPanelProps {
+interface PropertyPanelProps extends PropertyMetricProps {
     title?: ReactNode;
     children: ReactNode;
     className?: string;
 }
 /** 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;
+declare function PropertyPanel({ title, children, className, density, align, }: PropertyPanelProps): react_jsx_runtime.JSX.Element;
 /** How a property list packs its rows into two columns. */
-type PropertyListPack = 'auto-color' | 'pairs';
+type PropertyListPack = 'auto-color' | 'pairs' | 'one-up';
 /** Props for `<PropertyList>`. */
-interface PropertyListProps {
+interface PropertyListProps extends PropertyMetricProps {
     children: ReactNode;
     className?: string;
     /**
@@ -24,6 +49,8 @@ interface PropertyListProps {
      *   - `'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.
+     *   - `'one-up'`: every row spans the full width, color rows included. Right
+     *     for a palette — a column of swatches read as a group.
      */
     pack?: PropertyListPack;
 }
@@ -31,7 +58,7 @@ interface PropertyListProps {
  * Grid container for PropertyRows. Use standalone for chrome-less layouts, or
  * nest inside <PropertyPanel/> for the standard glass card.
  */
-declare function PropertyList({ children, className, pack }: PropertyListProps): react_jsx_runtime.JSX.Element;
+declare function PropertyList({ children, className, pack, density, align, }: PropertyListProps): react_jsx_runtime.JSX.Element;
 /** Props for `<PropertySpan>`. */
 interface PropertySpanProps {
     children: ReactNode;
@@ -49,7 +76,7 @@ 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 {
+interface PropertyRowProps extends PropertyMetricProps {
     label: ReactNode;
     /** Right-aligned readout shown next to the label (e.g. current value). */
     readout?: ReactNode;
@@ -60,9 +87,9 @@ interface PropertyRowProps {
     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.
+     * Label position relative to the control. Unset takes the variant's own
+     * orientation: `block` — label above control — for the default variant, and
+     * `inline` for the color and checkbox variants, which read as a row.
      */
     layout?: PropertyRowLayout;
     /**
@@ -77,15 +104,26 @@ interface PropertyRowProps {
 }
 /** 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;
+declare function PropertyRow({ label, readout, description, variant, layout, span, children, htmlFor, className, density, align, }: PropertyRowProps): react_jsx_runtime.JSX.Element;
 /** Props for `<SliderRow>`. */
-interface SliderRowProps {
+interface SliderRowProps extends PropertyMetricProps {
     label: ReactNode;
     value: number;
     min: number;
     max: number;
     step?: number;
+    /**
+     * The committed value. Given `onInput` as well, it fires once a drag ends
+     * or a typed readout is accepted; on its own it fires on every move, which
+     * is what a row with one callback has always done.
+     */
     onChange: (next: number) => void;
+    /**
+     * The live value, fired continuously through a drag. Pass it alongside
+     * `onChange` when the write is expensive — cheap state here, the costly
+     * work there. Mirrors `<Slider>`'s `onInput` / `onChange` pair.
+     */
+    onInput?: (next: number) => void;
     /** Override how the value is rendered next to the label. Defaults to `value.toString()`. */
     format?: (value: number) => ReactNode;
     /**
@@ -101,9 +139,9 @@ interface SliderRowProps {
 }
 /** 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, span, }: SliderRowProps): react_jsx_runtime.JSX.Element;
+declare function SliderRow({ label, value, min, max, step, onChange, onInput, format, unit, layout, description, span, density, align, }: SliderRowProps): react_jsx_runtime.JSX.Element;
 /** Props for `<ColorRow>`. */
-interface ColorRowProps {
+interface ColorRowProps extends PropertyMetricProps {
     label: ReactNode;
     value: string;
     onChange: (next: string) => void;
@@ -115,25 +153,29 @@ interface ColorRowProps {
      * Use when the color's consumer drops alpha so the affordance reads dead.
      */
     alphaDisabled?: boolean;
+    /** Label beside the swatch (default) or above it. */
+    layout?: PropertyRowLayout;
     description?: string;
     /** Take the full width of the enclosing grid — see `<PropertyRow span>`. */
     span?: boolean;
 }
 /** A color swatch, optionally with an alpha slider beneath it. */
-declare function ColorRow({ label, value, onChange, alpha, onAlphaChange, alphaDisabled, description, span, }: ColorRowProps): react_jsx_runtime.JSX.Element;
+declare function ColorRow({ label, value, onChange, alpha, onAlphaChange, alphaDisabled, layout, description, span, density, align, }: ColorRowProps): react_jsx_runtime.JSX.Element;
 /** Props for `<CheckboxRow>`. */
-interface CheckboxRowProps {
+interface CheckboxRowProps extends PropertyMetricProps {
     label: ReactNode;
     value: boolean;
     onChange: (next: boolean) => void;
+    /** Label beside the box (default) or above it. */
+    layout?: PropertyRowLayout;
     description?: string;
     /** Take the full width of the enclosing grid — see `<PropertyRow span>`. */
     span?: boolean;
 }
 /** A boolean checkbox. */
-declare function CheckboxRow({ label, value, onChange, span, description }: CheckboxRowProps): react_jsx_runtime.JSX.Element;
+declare function CheckboxRow({ label, value, onChange, layout, span, description, density, align, }: CheckboxRowProps): react_jsx_runtime.JSX.Element;
 /** Props for `<TextRow>`. */
-interface TextRowProps {
+interface TextRowProps extends PropertyMetricProps {
     label: ReactNode;
     value: string;
     onChange: (next: string) => void;
@@ -145,9 +187,9 @@ interface TextRowProps {
     span?: boolean;
 }
 /** A single-line text input. */
-declare function TextRow({ label, value, onChange, placeholder, maxLength, layout, description, span, }: TextRowProps): react_jsx_runtime.JSX.Element;
+declare function TextRow({ label, value, onChange, placeholder, maxLength, layout, description, span, density, align, }: TextRowProps): react_jsx_runtime.JSX.Element;
 /** Props for `<NumberRow>`. */
-interface NumberRowProps {
+interface NumberRowProps extends PropertyMetricProps {
     label: ReactNode;
     value: number;
     onChange: (next: number) => void;
@@ -168,13 +210,13 @@ interface NumberRowProps {
 }
 /** 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, unit, layout, description, span, }: NumberRowProps): react_jsx_runtime.JSX.Element;
+declare function NumberRow({ label, value, onChange, min, max, step, placeholder, unit, layout, description, span, density, align, }: NumberRowProps): react_jsx_runtime.JSX.Element;
 interface PropertyOption<T extends string> {
     value: T;
     label: ReactNode;
 }
 /** Props for `<SelectRow>`. */
-interface SelectRowProps<T extends string> {
+interface SelectRowProps<T extends string> extends PropertyMetricProps {
     label: ReactNode;
     value: T;
     options: ReadonlyArray<PropertyOption<T>>;
@@ -186,9 +228,9 @@ interface SelectRowProps<T extends 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, span, }: SelectRowProps<T>): react_jsx_runtime.JSX.Element;
+declare function SelectRow<T extends string>({ label, value, options, onChange, layout, description, span, density, align, }: SelectRowProps<T>): react_jsx_runtime.JSX.Element;
 /** Props for `<ToggleRow>`. */
-interface ToggleRowProps<T extends string> {
+interface ToggleRowProps<T extends string> extends PropertyMetricProps {
     label: ReactNode;
     value: T;
     options: ReadonlyArray<PropertyOption<T>>;
@@ -200,7 +242,7 @@ interface ToggleRowProps<T extends 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, span, }: ToggleRowProps<T>): react_jsx_runtime.JSX.Element;
+declare function ToggleRow<T extends string>({ label, value, options, onChange, layout, description, span, density, align, }: ToggleRowProps<T>): react_jsx_runtime.JSX.Element;
 
 /** How a panel packs its rows into the two-column property grid.
  *   - `'auto'`: narrow controls (numbers, checkboxes, dropdowns, colours) sit
@@ -217,7 +259,9 @@ interface ControlPanelProps<TC extends Record<string, unknown>> {
     /** @deprecated Pass `schema`. A field list is adapted into one internally. */
     fields?: ConfigField[];
     config: TC;
-    setConfig: (key: keyof TC, value: unknown) => void;
+    /** Writes one value. The path is dotted for a leaf inside an `f.group`, and
+     *  the bare key for one at the root. */
+    setConfig: (path: string, value: unknown) => void;
     /**
      * Control overrides and app-defined kinds, PrefsForm-style. Keys are config
      * paths (checked first) or leaf kinds. A renderer returning `null` collapses
@@ -226,9 +270,33 @@ interface ControlPanelProps<TC extends Record<string, unknown>> {
     renderers?: Record<string, ControlRenderer>;
     /** How rows pack into the two-column grid. Defaults to `'pairs'`. */
     pack?: ControlPack;
-    /** Where a row's label sits relative to its control. Defaults to `'block'`
-     *  — above it, which is what leaves a paired row room for its value. */
+    /**
+     * Where a row's label sits relative to its control. Unset takes each row's
+     * own orientation — `block` (label above, which is what leaves a paired row
+     * room for its value) for most, `inline` for colors and checkboxes.
+     */
     layout?: PropertyRowLayout;
+    /** Room the rows get. Passed straight to the property list. */
+    density?: PropertyDensity;
+    /** Cross-axis alignment of an inline row's label and control. */
+    align?: PropertyAlign;
+    /**
+     * Fold each section away behind a twisty, starting `'open'` or `'closed'`.
+     * Unset draws the heading alone, as the panel always has — unless a section
+     * in the schema declares how it opens, which makes that section foldable on
+     * its own and outranks this for that one section.
+     */
+    collapse?: 'open' | 'closed';
+    /**
+     * Which sections are folded, keyed as `onCollapse` reports them. Given, the
+     * panel keeps no state of its own: every toggle arrives at `onCollapse`
+     * instead, which is where a lab that remembers a trial's sections writes
+     * them.
+     */
+    collapsed?: Readonly<Record<string, boolean>>;
+    /** A fold moved. The key is a section's label — prefixed by its group's
+     *  dotted path when the section sits inside one — or a group's own path. */
+    onCollapse?: (key: string, collapsed: boolean) => void;
     /** Draw leaves marked `hidden`. */
     showHidden?: boolean;
     className?: string;
@@ -236,7 +304,7 @@ interface ControlPanelProps<TC extends Record<string, unknown>> {
 /** Render an instrument's config schema as a stack of controls, each writing
  *  back through `setConfig`. Built on the property rows, so a lab's controls
  *  are the same aligned, themed rows the rest of the kit uses. */
-declare function ControlPanel<TC extends Record<string, unknown>>({ schema, fields, config, setConfig, renderers, pack, layout, showHidden, className, }: ControlPanelProps<TC>): react_jsx_runtime.JSX.Element;
+declare function ControlPanel<TC extends Record<string, unknown>>({ schema, fields, config, setConfig, renderers, pack, layout, density, align, collapse, collapsed, onCollapse, showHidden, className, }: ControlPanelProps<TC>): react_jsx_runtime.JSX.Element;
 
-export { CheckboxRow as C, NumberRow as N, PropertyList as P, SelectRow as S, TextRow as T, ColorRow as b, ControlPanel as d, PropertyPanel as i, PropertyRow as k, PropertySpan as o, SliderRow as r, ToggleRow as u };
-export type { CheckboxRowProps as a, ColorRowProps as c, NumberRowProps as e, PropertyListPack as f, PropertyListProps as g, PropertyOption as h, PropertyPanelProps as j, PropertyRowLayout as l, PropertyRowProps as m, PropertyRowVariant as n, PropertySpanProps as p, SelectRowProps as q, SliderRowProps as s, TextRowProps as t, ToggleRowProps as v };
+export { CheckboxRow as C, NumberRow as N, SelectRow as S, TextRow as T, ColorRow as c, ControlPanel as e, PropertyList as g, PropertyPanel as j, PropertyRow as l, PropertySpan as p, SliderRow as s, ToggleRow as v };
+export type { PropertyMetricProps as P, PropertyListPack as a, CheckboxRowProps as b, ColorRowProps as d, NumberRowProps as f, PropertyListProps as h, PropertyOption as i, PropertyPanelProps as k, PropertyRowLayout as m, PropertyRowProps as n, PropertyRowVariant as o, PropertySpanProps as q, SelectRowProps as r, SliderRowProps as t, TextRowProps as u, ToggleRowProps as w };

package/dist/_dts/types-B9_zrHmb.d.ts

@@ -0,0 +1,166 @@
+import { ToolPrefLeaf, ToolPrefGroup } from '@weasel-js/core';
+import { P as PrefRenderer } from './PrefsForm.d-DDHFANkc.js';
+
+/**
+ * Renders the control cell for one config leaf. Identical to weasel-ui's
+ * `PrefRenderer` on purpose — aliased rather than redeclared so the two
+ * cannot drift.
+ */
+type ControlRenderer = PrefRenderer;
+/** One labeled choice in an `enum` leaf. */
+interface ConfigOption {
+    value: string;
+    label: string;
+}
+/** Everything a leaf can carry beyond its kind and default. A flat union of
+ *  every `Pref*` leaf's extras, plus labkit's own `debounceMs`. */
+interface Annotations {
+    name?: string;
+    description?: string;
+    hidden?: boolean;
+    block?: boolean;
+    pair?: string;
+    min?: number;
+    max?: number;
+    step?: number;
+    suffix?: string;
+    control?: string;
+    options?: readonly ConfigOption[];
+    placeholder?: string;
+    maxLength?: number;
+    /** Milliseconds to debounce a string leaf's live writes. Default 150. */
+    debounceMs?: number;
+}
+/** What a rule contributes. `kind` is honored only while it is still unset,
+ *  which is what makes `f.value` claimable and a kinded factory final. */
+type LeafPatch = Annotations & {
+    kind?: string;
+};
+/** What a rule is given for the leaf it is deciding about. */
+interface ConfigRuleContext {
+    /** The leaf's own key — its last path segment, and what a label is titled
+     *  from. */
+    key: string;
+    /** Dotted path within the schema, which is the path the value is written
+     *  at. Equal to `key` for a leaf sitting at the root. */
+    path: string;
+    /** The leaf's default value. A rule may read it but never change it. */
+    default: unknown;
+    /** What earlier rules and the author's own annotations have settled. */
+    leaf: Readonly<LeafPatch>;
+}
+/**
+ * Decides part of how a leaf is presented. Returns a patch, or null to
+ * abstain. Merging is gap-filling: a property already settled is never
+ * overwritten, so the author's annotations beat every rule and a consumer's
+ * rules beat labkit's built-ins.
+ */
+type ConfigRule = (ctx: ConfigRuleContext) => LeafPatch | null;
+/** A presentational bucket of nodes, rendered under one heading. Buckets
+ *  siblings: a section never nests a value, which is what separates it from
+ *  `f.group`. */
+interface SectionSpec {
+    /** Dotted path of the group whose children this buckets. `''` is the root,
+     *  which is where every section of a flat schema sits. */
+    at: string;
+    label: string;
+    /** Full dotted paths, so a section under a group names its children the way
+     *  everything else does. */
+    paths: readonly string[];
+    /** Whether the section opens folded. Set, the panel folds this section
+     *  whether or not it was given a panel-wide `collapse`; a fold the reader
+     *  has since toggled outranks it. */
+    collapsed?: boolean;
+}
+/** A schema resolved against a set of rules: the vocabulary weasel-ui renders,
+ *  plus the three things labkit keeps on the side because `PrefLeaf` has no
+ *  field for them. */
+interface ResolvedConfig {
+    /** The schema as a `PrefGroup` tree: an `f.group` is a nested group, so a
+     *  leaf's dotted path within it is the path its value is written at. */
+    group: ToolPrefGroup;
+    sections: readonly SectionSpec[];
+    showIf: ReadonlyMap<string, (config: Record<string, unknown>) => boolean>;
+    /** Node-level `.render` overrides, keyed by path. */
+    renderers: Readonly<Record<string, ControlRenderer>>;
+}
+/** How a node names the section it belongs to: the heading, and how that
+ *  section opens. Every node in one section repeats the heading; only one of
+ *  them has to say `collapsed`. */
+interface SectionOption {
+    label: string;
+    collapsed?: boolean;
+}
+/** Per-node extras that do not belong on a `PrefLeaf`. */
+interface NodeOptions extends BranchOptions {
+    render?: ControlRenderer;
+    validate?: (leaf: ToolPrefLeaf) => string[];
+}
+/** What a branch can say about itself, beyond its children. */
+interface BranchOptions {
+    section?: SectionOption;
+    /** Show this node only while the predicate holds. On a group it hides the
+     *  whole subtree; the values stay in config either way. */
+    showIf?: (config: Record<string, unknown>) => boolean;
+}
+/** A group's own annotations: what it is called and, optionally, why. */
+interface BranchAnnotations {
+    name?: string;
+    description?: string;
+}
+/** The builder's leaf: a kind (or null, to be decided by rules), a default,
+ *  an annotation bag, and the extras above. */
+interface ConfigNode<T = unknown> {
+    readonly kind: string | null;
+    readonly default: T;
+    readonly annotations: Readonly<Annotations>;
+    readonly options: Readonly<NodeOptions>;
+}
+/** The builder's branch: named children, nested as deeply as the schema
+ *  wants. A branch nests the value too — `grid: f.group({ size })` puts the
+ *  value at `grid.size`, where `.section('Grid')` would have left it at
+ *  `size`. */
+interface ConfigBranch<S extends ConfigShape = ConfigShape> {
+    readonly children: S;
+    readonly annotations: Readonly<BranchAnnotations>;
+    readonly options: Readonly<BranchOptions>;
+}
+/** Either half of a schema tree. */
+type ConfigEntry = ConfigNode | ConfigBranch;
+/** The children of a schema or a group. */
+type ConfigShape = {
+    readonly [key: string]: ConfigEntry;
+};
+/** The value type a node produces. */
+type NodeValue<N> = N extends ConfigNode<infer T> ? T : never;
+/** The value type a schema entry produces — a leaf's own, or a branch's
+ *  nested record. */
+type EntryValue<E> = E extends ConfigBranch<infer S> ? InferConfig<S> : E extends ConfigNode<infer T> ? T : never;
+/** The config type a builder shape produces. */
+type InferConfig<S> = {
+    [K in keyof S]: EntryValue<S[K]>;
+};
+/** Whether a config value has children a path can descend into. Arrays and
+ *  functions are values, not branches. */
+type Branching<V> = V extends readonly unknown[] ? false : V extends (...args: never[]) => unknown ? false : V extends object ? true : false;
+/**
+ * Every dotted path a config offers, a group's own path included. A config
+ * whose shape is not known — `unknown`, or a bare record — gives `string`,
+ * which is what keeps a generic instrument writable.
+ */
+type ConfigPath<T> = unknown extends T ? string : T extends object ? {
+    [K in keyof T & string]: Branching<T[K]> extends true ? K | `${K}.${ConfigPath<T[K]>}` : K;
+}[keyof T & string] : never;
+/** The type at a dotted path, or `unknown` where the path is not one the
+ *  config's type spells out. */
+type ValueAtPath<T, P extends string> = unknown extends T ? unknown : P extends `${infer Head}.${infer Rest}` ? Head extends keyof T ? ValueAtPath<T[Head], Rest> : unknown : P extends keyof T ? T[P] : unknown;
+/** An instrument's config, declared once. */
+interface ConfigSchema<TC> {
+    readonly nodes: ConfigShape;
+    /** The starting config — what `defaultConfig()` would have returned. */
+    defaults(): TC;
+}
+/** The config type behind a schema: `ConfigOf<typeof sceneConfig>`. */
+type ConfigOf<S> = S extends ConfigSchema<infer TC> ? TC : never;
+
+export type { Annotations as A, BranchAnnotations as B, ConfigPath as C, EntryValue as E, InferConfig as I, LeafPatch as L, NodeOptions as N, ResolvedConfig as R, SectionSpec as S, ValueAtPath as V, ConfigSchema as a, ConfigNode as b, ControlRenderer as c, ConfigOption as d, ConfigShape as e, ConfigBranch as f, BranchOptions as g, ConfigEntry as h, ConfigRule as i, ConfigRuleContext as j, ConfigOf as k, NodeValue as l };