@weasel-js/labkit 1.4.3 → 1.5.0

package/dist/_dts/index-B8uu2ba7.d.ts

@@ -0,0 +1,237 @@
+import { d as ControlRenderer, c as ConfigRule } from './types-Ca2LCnPq.js';
+import { K as Instrument, aq as TrialChromeContext, N as TrialContribution, T as TrialRecord, q as InstrumentList, e as SavedSnapshot, o as LabMode, ao as ToolSlotContext, a2 as ContributionBase, ap as ToolbarItem, an as ToolItem, ah as SidebarSection, ak as StatusReadout, H as TrialTool, ad as RegionContribution, ai as SidebarSlotContext } from './frac-8R6UmlvN.js';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import * as react from 'react';
+import { ReactNode } from 'react';
+
+/**
+ * The contributions a trial gets from what its instrument declared. This is
+ * the whole "declaring a capability provides the chrome" rule — it replaces
+ * the presence checks that used to be spread across the runtime.
+ */
+declare function builtinContributions(instrument: Instrument, ctx: TrialChromeContext, controls?: Record<string, ControlRenderer>): TrialContribution[];
+
+/** 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[];
+    /** 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;
+    reorderTrials: (ids: readonly string[]) => void;
+    savedSnapshots: SavedSnapshot[];
+    saveSnapshot: (trialId: string, name?: string) => void;
+    loadSnapshot: (trialId: string, snapshotId: string) => void;
+    deleteSnapshot: (snapshotId: string) => void;
+    mode: LabMode;
+    setMode: (m: LabMode) => void;
+    /** Lab-wide rules run over every instrument's config leaves, before
+     *  labkit's own inference. */
+    configRules?: readonly ConfigRule[];
+    /** Lab-wide control overrides, keyed by config path or by leaf kind. */
+    controls?: Record<string, ControlRenderer>;
+}
+/** Context carrying the surrounding lab. Prefer `useLabContext`. */
+declare const LabContext: react.Context<LabContextValue | null>;
+/** The surrounding lab. Throws outside a `<Lab>`. */
+declare function useLabContext(): LabContextValue;
+
+/**
+ * A named position in the lab's own chrome — a box the shell owns, outside any
+ * one trial. `header` and `footer` are the shell's two bars, named as
+ * `<LabShell>` names them; `palette` is the tool rail down the side of the
+ * workspace; `sidebar` is a column of sections left of the tool rail.
+ */
+type LabRegion = 'header' | 'palette' | 'sidebar' | 'footer';
+/**
+ * Everything a lab-level contribution can read and command: the lab's own
+ * state and operations, plus the lab's tool slot — which every trial whose
+ * instrument declares no tools of its own reflects and writes.
+ */
+interface LabChromeContext extends LabContextValue, ToolSlotContext {
+}
+/**
+ * A contribution to the lab's chrome. Shaped as `TrialContribution` is, and
+ * merged and suppressed by the same rules, but keyed to the lab's regions and
+ * rendered with the lab's context. Supplying `render` instead of `item` opts
+ * out of the region's layout.
+ *
+ * `TCtx` is what the chrome hands a handler. It defaults to `LabChromeContext`,
+ * which is what `<Lab>` renders its regions with; a consumer mounting the
+ * regions under a bare `<LabShell>` names whatever it passes as `ctx` instead.
+ */
+type LabContribution<TCtx = LabChromeContext> = (ContributionBase & {
+    region: 'header';
+    item: ToolbarItem<TCtx>;
+    render?: never;
+}) | (ContributionBase & {
+    region: 'palette';
+    item: ToolItem;
+    render?: never;
+}) | (ContributionBase & {
+    region: 'sidebar';
+    item: SidebarSection;
+    render?: never;
+}) | (ContributionBase & {
+    region: 'footer';
+    item: StatusReadout;
+    render?: never;
+}) | (ContributionBase & {
+    region: LabRegion;
+    item?: never;
+    render: (ctx: TCtx) => ReactNode;
+});
+
+/** The lab's chrome context: the lab itself, plus the lab's tool slot. Throws
+ *  outside a `<Lab>`. */
+declare function useLabChromeContext(): LabChromeContext;
+/** The lab's contributions for one region, in declaration order. */
+declare function contributionsIn<TCtx = LabChromeContext>(contributions: readonly LabContribution<TCtx>[], region: LabRegion): LabContribution<TCtx>[];
+/** The palette contributions a lab's `tools` stand for. Declaring a tool is
+ *  shorthand for contributing a palette item that writes the lab's tool
+ *  slot. */
+declare function toolContributions(tools: readonly TrialTool[]): LabContribution[];
+/** Everything the lab's chrome renders, from both of the ways a lab declares
+ *  it. Tools and contributions share one id namespace, so a tool colliding
+ *  with a contribution throws here rather than one of them silently losing. */
+declare function labContributions(tools: readonly TrialTool[] | undefined, chrome: readonly LabContribution[] | undefined): LabContribution[];
+/** Props shared by the lab's region mounts. Each takes the lab's whole
+ *  contribution list and lays out the part addressed to it. */
+interface LabRegionProps {
+    contributions: readonly LabContribution[];
+}
+/** The lab's action bar, in the shell header beside the title. */
+declare function LabHeaderRegion({ contributions }: LabRegionProps): react_jsx_runtime.JSX.Element;
+/** The lab's sidebar sections. Fold state is a lab-scoped persisted value, so it
+ *  survives a reload in a stored lab and lasts the session in an unstored one. */
+declare function LabSidebarRegion({ contributions }: LabRegionProps): react_jsx_runtime.JSX.Element;
+/** The lab's readouts, in the shell footer below the workspace. */
+declare function LabFooterRegion({ contributions }: LabRegionProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Concatenate contribution bundles into one list, preserving order — order
+ * decides how a region lays its contributions out, so it is part of the
+ * result, not an accident of it.
+ *
+ * Throws on a duplicate id rather than dropping one: a contribution silently
+ * losing to a later bundle is the failure a registry exists to prevent.
+ */
+declare function mergeContributions<T extends {
+    id: string;
+}>(...bundles: readonly (readonly T[])[]): T[];
+/**
+ * Drop contributions by id. Throws when an id is not present: a typo that
+ * silently suppresses nothing is the same class of bug as a duplicate id
+ * silently winning.
+ */
+declare function suppressContributions<T extends {
+    id: string;
+}>(bundle: readonly T[], ids: readonly string[]): T[];
+
+/** Props for `<PaletteRegion>`. */
+interface PaletteRegionProps<TCtx extends ToolSlotContext = TrialChromeContext> {
+    contributions: readonly RegionContribution<NoInfer<TCtx>>[];
+    ctx: TCtx;
+    /** Which region's items to lay out. The lab's rail names the same box
+     *  `palette` too, so this only moves for a chrome that does not. */
+    region?: string;
+}
+/** A tool strip: a trial's, or the lab's. Selection lives in whichever tool
+ *  slot the context carries; this region only reflects it. */
+declare function PaletteRegion<TCtx extends ToolSlotContext = TrialChromeContext>({ contributions, ctx, region, }: PaletteRegionProps<TCtx>): react_jsx_runtime.JSX.Element | null;
+
+/** Props for `<SidebarRegion>`. */
+interface SidebarRegionProps<TCtx extends SidebarSlotContext = TrialChromeContext> {
+    contributions: readonly RegionContribution<NoInfer<TCtx>>[];
+    ctx: TCtx;
+    /** Which region's items to lay out. */
+    region?: string;
+}
+/** Lays `sidebar` contributions out as titled, collapsible sections — a
+ *  trial's, or the lab's. A section the trial has torn out is not rendered
+ *  here — `Trial` portals its body into the workspace instead. A context with
+ *  no `undockPanel` offers no tear-out. */
+declare function SidebarRegion<TCtx extends SidebarSlotContext = TrialChromeContext>({ contributions, ctx, region, }: SidebarRegionProps<TCtx>): react_jsx_runtime.JSX.Element | null;
+
+/** Props for `<StatusRegion>`. */
+interface StatusRegionProps<TCtx = TrialChromeContext> {
+    contributions: readonly RegionContribution<NoInfer<TCtx>>[];
+    ctx: TCtx;
+    /** Which region's readouts to lay out; the lab's footer is `footer`. */
+    region?: string;
+}
+/** Lays a bar's readouts out. */
+declare function StatusRegion<TCtx = TrialChromeContext>({ contributions, ctx, region, }: StatusRegionProps<TCtx>): react_jsx_runtime.JSX.Element | null;
+
+/** Which end of the title bar a `<TitleBarRegion>` lays out: `'lead'` renders
+ *  the contributions that leave `end` unset, before the title; `'actions'`
+ *  renders the ones that set it, after everything else. */
+type TitleBarPlacement = 'lead' | 'actions';
+/** Props for `<TitleBarRegion>`. */
+interface TitleBarRegionProps {
+    contributions: readonly TrialContribution[];
+    ctx: TrialChromeContext;
+    /** Defaults to `'actions'`, where the built-ins live. */
+    placement?: TitleBarPlacement;
+}
+/** Lays a trial's `titlebar` contributions out at one end of the bar. */
+declare function TitleBarRegion({ contributions, ctx, placement }: TitleBarRegionProps): react_jsx_runtime.JSX.Element | null;
+
+/** Props for `<ToolbarRegion>`. */
+interface ToolbarRegionProps<TCtx = TrialChromeContext> {
+    contributions: readonly RegionContribution<NoInfer<TCtx>>[];
+    ctx: TCtx;
+    /** Which region's items to lay out; the lab's action bar is `header`. */
+    region?: string;
+    /** The bar's accessible name. */
+    label?: string;
+}
+/** Lays a bar's contributions out, grouped by their `group`. */
+declare function ToolbarRegion<TCtx = TrialChromeContext>({ contributions, ctx, region, label, }: ToolbarRegionProps<TCtx>): react_jsx_runtime.JSX.Element | null;
+
+/** Props for `<ViewportRegion>`. */
+interface ViewportRegionProps {
+    contributions: readonly TrialContribution[];
+    ctx: TrialChromeContext;
+}
+/**
+ * Controls acting on the view of a trial. Anchored inside the content well
+ * rather than in the toolbar, which acts on the trial itself.
+ */
+declare function ViewportRegion({ contributions, ctx }: ViewportRegionProps): react_jsx_runtime.JSX.Element | null;
+
+export { suppressContributions as B, toolContributions as C, useLabChromeContext as D, useLabContext as E, PaletteRegion as P, SidebarRegion as S, ViewportRegion as V, LabContext as b, LabFooterRegion as d, LabHeaderRegion as e, LabSidebarRegion as h, StatusRegion as k, TitleBarRegion as m, ToolbarRegion as o, addTrial as r, builtinContributions as s, cloneTrial as t, closeTrial as u, contributionsIn as v, labContributions as w, mergeContributions as x, reorderTrials as y, resetTrial as z };
+export type { AddTrialOptions as A, LabContribution as L, TitleBarPlacement as T, LabChromeContext as a, LabContextValue as c, LabRegion as f, LabRegionProps as g, PaletteRegionProps as i, SidebarRegionProps as j, StatusRegionProps as l, TitleBarRegionProps as n, ToolbarRegionProps as p, ViewportRegionProps as q };

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

@@ -1,7 +1,7 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import { ReactNode } from 'react';
-import { R as ResolvedConfig, c as ControlRenderer } from './types-B9_zrHmb.js';
-import { C as ConfigField } from './types-x92Kfeme.js';
+import { ToolPrefNumberFormat } from '@weasel-js/core';
+import { R as ResolvedConfig, a as ConfigField, d as ControlRenderer } from './types-Ca2LCnPq.js';
 
 /**
  * How much room a container gives its rows — gaps, padding, and field height,
@@ -126,6 +126,8 @@ interface SliderRowProps extends PropertyMetricProps {
     onInput?: (next: number) => void;
     /** Override how the value is rendered next to the label. Defaults to `value.toString()`. */
     format?: (value: number) => ReactNode;
+    /** A named display for the value: `compact` reads `2.0M`. `format` wins when both are given. */
+    notation?: ToolPrefNumberFormat;
     /**
      * Optional suffix rendered next to the readout. A string becomes a
      * baseline-aligned dim "word" unit (e.g. "px"); pass JSX like `<sup>°</sup>`
@@ -139,15 +141,29 @@ interface SliderRowProps extends PropertyMetricProps {
 }
 /** A bounded number edited by dragging, with a live readout whose precision
  *  follows `step`. */
-declare function SliderRow({ label, value, min, max, step, onChange, onInput, format, unit, layout, description, span, density, align, }: SliderRowProps): react_jsx_runtime.JSX.Element;
+declare function SliderRow({ label, value, min, max, step, onChange, onInput, format, notation, unit, layout, description, span, density, align, }: SliderRowProps): react_jsx_runtime.JSX.Element;
 /** Props for `<ColorRow>`. */
 interface ColorRowProps extends PropertyMetricProps {
     label: ReactNode;
     value: string;
+    /**
+     * The committed color. Given `onInput` as well, it fires once the picker
+     * closes; on its own it fires on every move inside it, which is what a row
+     * with one callback has always done.
+     */
     onChange: (next: string) => void;
+    /**
+     * The live color, fired continuously while the picker is open. Pass it
+     * alongside `onChange` when the write is expensive — cheap state here, the
+     * costly work there. Mirrors `<Slider>`'s `onInput` / `onChange` pair.
+     */
+    onInput?: (next: string) => void;
     /** 0..1 alpha. When provided, a translucent slider renders beneath the swatch. */
     alpha?: number;
+    /** The committed alpha, on the same terms as `onChange`. */
     onAlphaChange?: (next: number) => void;
+    /** The live alpha, on the same terms as `onInput`. */
+    onAlphaInput?: (next: number) => void;
     /**
      * Render the alpha track as inert (dimmed, no thumb, not-allowed cursor).
      * Use when the color's consumer drops alpha so the affordance reads dead.
@@ -160,11 +176,12 @@ interface ColorRowProps extends PropertyMetricProps {
     span?: boolean;
 }
 /** A color swatch, optionally with an alpha slider beneath it. */
-declare function ColorRow({ label, value, onChange, alpha, onAlphaChange, alphaDisabled, layout, description, span, density, align, }: ColorRowProps): react_jsx_runtime.JSX.Element;
+declare function ColorRow({ label, value, onChange, onInput, alpha, onAlphaChange, onAlphaInput, alphaDisabled, layout, description, span, density, align, }: ColorRowProps): react_jsx_runtime.JSX.Element;
 /** Props for `<CheckboxRow>`. */
 interface CheckboxRowProps extends PropertyMetricProps {
     label: ReactNode;
-    value: boolean;
+    /** Absent reads as unchecked. */
+    value: boolean | undefined;
     onChange: (next: boolean) => void;
     /** Label beside the box (default) or above it. */
     layout?: PropertyRowLayout;
@@ -177,7 +194,8 @@ declare function CheckboxRow({ label, value, onChange, layout, span, description
 /** Props for `<TextRow>`. */
 interface TextRowProps extends PropertyMetricProps {
     label: ReactNode;
-    value: string;
+    /** Absent reads as an empty field. */
+    value: string | null | undefined;
     onChange: (next: string) => void;
     placeholder?: string;
     maxLength?: number;
@@ -191,8 +209,20 @@ declare function TextRow({ label, value, onChange, placeholder, maxLength, layou
 /** Props for `<NumberRow>`. */
 interface NumberRowProps extends PropertyMetricProps {
     label: ReactNode;
-    value: number;
+    /** Absent reads as an empty field. */
+    value: number | null | undefined;
+    /**
+     * The committed value. Given `onInput` as well, it fires on blur or Enter;
+     * on its own it fires on every keystroke, which is what a row with one
+     * callback has always done.
+     */
     onChange: (next: number) => void;
+    /**
+     * The live value, fired per keystroke. 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;
     min?: number;
     max?: number;
     step?: number;
@@ -210,7 +240,7 @@ interface NumberRowProps extends PropertyMetricProps {
 }
 /** 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, density, align, }: NumberRowProps): react_jsx_runtime.JSX.Element;
+declare function NumberRow({ label, value, onChange, onInput, 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;
@@ -218,9 +248,12 @@ interface PropertyOption<T extends string> {
 /** Props for `<SelectRow>`. */
 interface SelectRowProps<T extends string> extends PropertyMetricProps {
     label: ReactNode;
-    value: T;
+    /** Absent, or not one of `options`, shows a placeholder rather than the first option. */
+    value: T | undefined;
     options: ReadonlyArray<PropertyOption<T>>;
     onChange: (next: T) => void;
+    /** Shown while no option is chosen. Defaults to "Choose option…". */
+    placeholder?: string;
     layout?: PropertyRowLayout;
     description?: string;
     /** Take the full width of the enclosing grid — see `<PropertyRow span>`. */
@@ -228,7 +261,7 @@ interface SelectRowProps<T extends string> extends PropertyMetricProps {
 }
 /** 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, density, align, }: SelectRowProps<T>): react_jsx_runtime.JSX.Element;
+declare function SelectRow<T extends string>({ label, value, options, onChange, placeholder, layout, description, span, density, align, }: SelectRowProps<T>): react_jsx_runtime.JSX.Element;
 /** Props for `<ToggleRow>`. */
 interface ToggleRowProps<T extends string> extends PropertyMetricProps {
     label: ReactNode;
@@ -245,12 +278,12 @@ interface ToggleRowProps<T extends string> extends PropertyMetricProps {
 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
+ *   - `'auto'`: narrow controls (numbers, checkboxes, dropdowns, colors) sit
  *     two per row; the ones that need the width — text, sliders, segmented
  *     toggles — span it.
  *   - `'pairs'`: every row pairs. A control that needs the full width says so
  *     itself, with `<PropertyRow span>`.
- *   - `'one-up'`: one control per row, colours excepted.
+ *   - `'one-up'`: one control per row, colors excepted.
  */
 type ControlPack = 'auto' | 'pairs' | 'one-up';
 interface ControlPanelProps<TC extends Record<string, unknown>> {

package/dist/_dts/{types-B9_zrHmb.d.ts → types-Ca2LCnPq.d.ts}

@@ -1,4 +1,4 @@
-import { ToolPrefLeaf, ToolPrefGroup } from '@weasel-js/core';
+import { ToolPrefNumberFormat, ToolPrefLeaf, ToolPrefGroup } from '@weasel-js/core';
 import { P as PrefRenderer } from './PrefsForm.d-DDHFANkc.js';
 
 /**
@@ -24,6 +24,8 @@ interface Annotations {
     max?: number;
     step?: number;
     suffix?: string;
+    /** How a number's value is shown. `compact` abbreviates from a thousand up. */
+    format?: ToolPrefNumberFormat;
     control?: string;
     options?: readonly ConfigOption[];
     placeholder?: string;
@@ -163,4 +165,65 @@ interface ConfigSchema<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 };
+/** Which control a config field is edited with. */
+type ConfigFieldType = 'slider' | 'checkbox' | 'select' | 'number' | 'text' | 'color';
+/** What every config field carries: the config key it writes, the label shown
+ *  beside it, and which control renders it. */
+interface ConfigFieldBase {
+    key: string;
+    label: string;
+    type: ConfigFieldType;
+}
+/** A bounded number edited by dragging. */
+interface SliderField extends ConfigFieldBase {
+    type: 'slider';
+    default: number;
+    min: number;
+    max: number;
+    step?: number;
+}
+/** A boolean. */
+interface CheckboxField extends ConfigFieldBase {
+    type: 'checkbox';
+    default: boolean;
+}
+/** One choice in a select field. */
+interface SelectOption {
+    value: string;
+    label: string;
+}
+/** A fixed set of labeled choices. */
+interface SelectField extends ConfigFieldBase {
+    type: 'select';
+    default: string;
+    options: SelectOption[];
+}
+/** A number typed directly, optionally bounded. Use a slider field instead
+ *  when the range matters more than the exact value. */
+interface NumberField extends ConfigFieldBase {
+    type: 'number';
+    default: number;
+    min?: number;
+    max?: number;
+    step?: number;
+}
+/** A free-text string. Writes are debounced so typing does not re-run the
+ *  instrument on every keystroke. */
+interface TextField extends ConfigFieldBase {
+    type: 'text';
+    default: string;
+    placeholder?: string;
+    maxLength?: number;
+    /** Milliseconds to debounce live setConfig calls. Default 150 ms. Set to 0 to disable. */
+    debounceMs?: number;
+}
+/** A color, as a CSS color string. */
+interface ColorField extends ConfigFieldBase {
+    type: 'color';
+    default: string;
+}
+/** One field of an instrument's config schema. The schema is what the control
+ *  panel renders, and what `validateConfigSchema` checks. */
+type ConfigField = SliderField | CheckboxField | SelectField | NumberField | TextField | ColorField;
+
+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, TextField as T, ValueAtPath as V, ConfigField as a, ConfigSchema as b, ConfigRule as c, ControlRenderer as d, BranchOptions as e, CheckboxField as f, ColorField as g, ConfigBranch as h, ConfigEntry as i, ConfigFieldBase as j, ConfigFieldType as k, ConfigNode as l, ConfigOf as m, ConfigOption as n, ConfigRuleContext as o, ConfigShape as p, NodeValue as q, NumberField as r, SelectField as s, SelectOption as t, SliderField as u };

package/dist/_dts/usePanZoom-nS798rOF.d.ts

@@ -0,0 +1,160 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode, WheelEvent, PointerEvent as PointerEvent$1 } from 'react';
+import { k as ViewTransform, a as WorldSpec, V as ViewportSize, l as Point, W as WorldFrame } from './frac-8R6UmlvN.js';
+import { C as CanvasLayerDescriptor } from './CanvasStackContext-CqkxkFJW.js';
+
+/** Props for `<CanvasStack>`. */
+interface CanvasStackProps {
+    layers: CanvasLayerDescriptor[];
+    view: ViewTransform;
+    onViewChange: (v: ViewTransform) => void;
+    /** The instrument's coordinate system. Omitted, world (0,0) sits at the
+     *  element's top-left with y running down. */
+    worldSpec?: WorldSpec;
+    minZoom?: number;
+    maxZoom?: number;
+    width?: number | string;
+    height?: number | string;
+    className?: string;
+    /** Fired whenever the stack is measured, so a consumer can place a view that
+     *  only makes sense in terms of the viewport. */
+    onResize?: (size: ViewportSize) => void;
+    onHitTest?: (worldPos: Point) => void;
+    children?: ReactNode;
+}
+/** Stacks one `<canvas>` per layer and drives them from a shared view, so a
+ *  layer that changes rarely is not redrawn with one that changes every frame.
+ *  Handles sizing, device pixel ratio, and pan/zoom. */
+declare function CanvasStack({ layers, view: viewProp, onViewChange, worldSpec, minZoom, maxZoom, width, height, className, onResize, onHitTest, children, }: CanvasStackProps): react_jsx_runtime.JSX.Element;
+
+/** Bounds and coordinate system a {@link zoomAt} works in. */
+interface ZoomAtOptions {
+    /** The instrument's coordinate system, resolved against the viewport.
+     *  Omitted, `at` is measured from the element's top-left. */
+    frame?: WorldFrame;
+    min?: number;
+    max?: number;
+}
+/**
+ * Zoom a view by `factor` about a fixed point, so whatever world coordinate
+ * `at` was over stays under it.
+ *
+ * `at` is in the element's own pixels — a cursor position, or the centre of a
+ * lens. The clamp is applied before the pan is solved, so a zoom that hits a
+ * bound still anchors on the zoom it actually reached.
+ */
+declare function zoomAt(view: ViewTransform, factor: number, at: Point, { frame, min, max }?: ZoomAtOptions): ViewTransform;
+/** The view that puts a world point at the centre of a `size` viewport, at
+ *  `zoom`. What a lens showing a region around one point renders through. */
+declare function centerOn(world: Point, zoom: number, size: ViewportSize, frame?: WorldFrame): ViewTransform;
+
+/** Project a world point into screen coordinates under a view.
+ *
+ *  `frame` is the instrument's declared coordinate system, resolved against the
+ *  viewport; omitting it gives labkit's original one — origin at the top-left,
+ *  y downward. */
+declare function worldToScreen(world: Point, view: ViewTransform, frame?: WorldFrame): Point;
+/** Unproject a screen point back to world coordinates under a view. */
+declare function screenToWorld(screen: Point, view: ViewTransform, frame?: WorldFrame): Point;
+
+/** Props for `<Stage>`. */
+interface StageProps {
+    /** The content's own size in CSS pixels, at zoom 1. */
+    size: ViewportSize;
+    view: ViewTransform;
+    onViewChange: (v: ViewTransform) => void;
+    minZoom?: number;
+    maxZoom?: number;
+    /** Fired whenever the stage's viewport is measured at a non-zero size. */
+    onResize?: (viewport: ViewportSize) => void;
+    /** Handed the viewport element, for a consumer tracking the pointer over it. */
+    hostRef?: {
+        current: HTMLDivElement | null;
+    };
+    /** Drawn over the content in viewport pixels, outside the camera. */
+    overlay?: ReactNode;
+    children?: ReactNode;
+}
+/**
+ * The camera a stage opens at: the content centered in its viewport, shrunk to
+ * fit if it has to be and never enlarged past its own size.
+ */
+declare function fitStage(size: ViewportSize, viewport: ViewportSize): ViewTransform;
+/**
+ * DOM content of a fixed size, panned and zoomed by a camera — what
+ * `<CanvasStack>` is for layers drawn to a canvas. The content is laid out at
+ * its own size and transformed, so everything inside keeps its layout and a
+ * measurement of any element in it reports where it is actually drawn.
+ */
+declare function Stage({ size, view: viewProp, onViewChange, minZoom, maxZoom, onResize, hostRef, overlay, children, }: StageProps): react_jsx_runtime.JSX.Element;
+
+/** A point in the space the instrument works in. */
+interface Vec3 {
+    x: number;
+    y: number;
+    z: number;
+}
+/** An orbit camera as a trial view: where it looks from, and what it looks at.
+ *  labkit does not turn this into a matrix — the host's renderer does. */
+interface OrbitView {
+    yaw: number;
+    pitch: number;
+    distance: number;
+    target: Vec3;
+}
+/** Just short of the pole. At exactly ±PI/2 the azimuth is undefined and the
+ *  camera rolls, which reads as the model jumping rather than as a limit. */
+declare const PITCH_LIMIT: number;
+declare function clampPitch(pitch: number): number;
+declare function wrapYaw(yaw: number): number;
+/** The view a drag of (dx, dy) from `start` produces. Absolute against the drag
+ *  start, so it can be re-applied any number of times without compounding. */
+declare function orbitAfterDrag(start: OrbitView, dx: number, dy: number): OrbitView;
+/** Multiplicative, so one notch covers the same proportion of the distance
+ *  whether the camera is near or far. */
+declare function orbitAfterWheel(view: OrbitView, deltaY: number, minDistance: number, maxDistance: number): OrbitView;
+interface UseOrbitOptions {
+    view: OrbitView;
+    onViewChange: (v: OrbitView) => void;
+    /** Restored on double-click. Defaults to the view the hook first saw. */
+    home?: OrbitView;
+    minDistance?: number;
+    maxDistance?: number;
+}
+interface OrbitHandlers {
+    onWheel: (e: WheelEvent<HTMLElement>) => void;
+    onPointerDown: (e: PointerEvent$1<HTMLElement>) => void;
+    onDoubleClick: () => void;
+    isDragging: () => boolean;
+}
+/** Pointer gestures over an orbit view: drag to turn, wheel or pinch to dolly,
+ *  double-click to go home. The 3D peer of `usePanZoom`. */
+declare function useOrbit({ view, onViewChange, home, minDistance, maxDistance, }: UseOrbitOptions): OrbitHandlers;
+
+interface UsePanZoomOptions {
+    view: ViewTransform;
+    onViewChange: (v: ViewTransform) => void;
+    /** The opening `view.zoom` always stays reachable, widening these past
+     *  whatever is passed here if it would otherwise exclude it. */
+    minZoom?: number;
+    maxZoom?: number;
+    /** The instrument's coordinate system, resolved against the viewport. The
+     *  wheel anchors in this frame; omitting it anchors at the element's
+     *  top-left, which is what labkit did before a frame could be declared. */
+    frame?: WorldFrame;
+    /** A primary-button press released without ever crossing the drag
+     *  threshold. The pointer session owns the release, so the gesture's end is
+     *  reported here rather than left for a consumer's own `onPointerUp`. */
+    onTap?: (e: PointerEvent) => void;
+}
+interface PanZoomHandlers {
+    /** Zoom about the pointer. `anchor` is the element the pointer position is
+     *  measured against, for an event whose `currentTarget` is some other box. */
+    onWheel: (e: WheelEvent<HTMLElement> | globalThis.WheelEvent, anchor?: Element) => void;
+    onPointerDown: (e: PointerEvent$1<HTMLElement>) => void;
+    isDragging: () => boolean;
+}
+declare function usePanZoom({ view, onViewChange, minZoom, maxZoom, frame, onTap, }: UsePanZoomOptions): PanZoomHandlers;
+
+export { CanvasStack as C, PITCH_LIMIT as P, Stage as S, centerOn as f, clampPitch as g, fitStage as h, orbitAfterWheel as i, usePanZoom as j, wrapYaw as k, orbitAfterDrag as o, screenToWorld as s, useOrbit as u, worldToScreen as w, zoomAt as z };
+export type { OrbitHandlers as O, UseOrbitOptions as U, Vec3 as V, ZoomAtOptions as Z, CanvasStackProps as a, OrbitView as b, PanZoomHandlers as c, StageProps as d, UsePanZoomOptions as e };