@weasel-js/labkit 1.0.1 → 1.0.3

package/dist/passthrough/weasel-ui.d.ts

@@ -1,7 +1,7 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import * as react from 'react';
-import { ReactNode, CSSProperties, ButtonHTMLAttributes, ReactElement, MutableRefObject, PointerEvent as PointerEvent$1, KeyboardEvent, RefCallback, RefObject } from 'react';
-import { V as View, D as DrawCommand, O as Op, b as NodeId, c as Path, S as Scene, H as History, B as Bounds } from '../_dts/DrawCommand-CitWPxMY.js';
+import { ReactNode, CSSProperties, ButtonHTMLAttributes, ReactElement, MutableRefObject, KeyboardEvent, PointerEvent as PointerEvent$1, RefCallback, RefObject } from 'react';
+import { V as View, D as DrawCommand, O as Op, b as NodeId, c as Path, S as Scene, H as History, B as Bounds } from '../_dts/DrawCommand-uKHt4Vul.js';
 import { TextFieldProps, ValidationResult, CheckboxProps as CheckboxProps$1, SwitchProps as SwitchProps$1, TabProps as TabProps$1, TabListProps as TabListProps$1, TabPanelProps as TabPanelProps$1, TabsProps as TabsProps$1, RadioProps as RadioProps$1, RadioGroupProps as RadioGroupProps$1, NumberFieldProps as NumberFieldProps$1, SelectProps as SelectProps$1, ListBoxItemProps, ComboBoxProps as ComboBoxProps$1, SliderProps as SliderProps$1, ModalOverlayProps, DialogProps as DialogProps$1 } from 'react-aria-components';
 
 /**
@@ -37,6 +37,7 @@ declare function isDebugEnabled(namespace: string): boolean;
  *  Each call is prefixed with `[namespace]` so the source is searchable. */
 declare function dlog(namespace: string, ...args: unknown[]): void;
 
+/** Props for {@link ActionBar}. */
 interface ActionBarProps {
     /** Group key — only actions with `action.group === group` are rendered. */
     group: string;
@@ -72,9 +73,20 @@ interface ActionBarProps {
  */
 declare function ActionBar(props: ActionBarProps): react_jsx_runtime.JSX.Element;
 
+/**
+ * Built-in badge silhouettes. `pill`, `plain` and `square` are drawn in CSS;
+ * the rest are SVG outlines, several of which route through the compose
+ * pipeline (a base shape plus perimeter effects).
+ */
 type BadgeShape = 'pill' | 'plain' | 'square' | 'notched' | 'perforated' | 'hexagon' | 'starburst' | 'scalloped' | 'shield' | 'ribbon' | 'beavis' | 'sparkler' | 'postage' | 'cloud' | 'house' | 'plaque' | 'crest' | 'urn' | 'coffin' | 'receipt' | 'wood' | 'quatrefoil';
+/**
+ * Semantic color of a badge. `custom` paints from the `--badge-edge` custom
+ * property instead of a theme token, so a call site can supply its own color.
+ */
 type BadgeTone = 'accent' | 'info' | 'warn' | 'danger' | 'muted' | 'neutral' | 'custom';
+/** How a badge's tone is applied: outline only, filled, or a soft tinted fill. */
 type BadgeVariant = 'outline' | 'solid' | 'subtle';
+/** Badge type scale and padding step. */
 type BadgeSize = 'sm' | 'md';
 
 interface SquareParams {
@@ -437,9 +449,17 @@ interface RibbonParams {
     taperWidth?: number;
 }
 
+/**
+ * Shapes one vertical edge of a badge base. Given a position down the edge
+ * (`t`, 0 at the top to 1 at the bottom) and the configured depth in CSS px,
+ * returns the horizontal displacement of that point, positive to the right.
+ */
 type EdgeProfile = (t: number, depth: number) => number;
+/** The named edge profiles in {@link EDGE_PROFILES}. */
 type BuiltInEdgeName = 'flat' | 'chevron' | 'slant' | 'slant-up' | 'round' | 'scallop' | 'concave-chevron';
+/** An edge profile, either by name or as a function. */
 type EdgeCap = BuiltInEdgeName | EdgeProfile;
+/** The built-in {@link EdgeProfile} implementations, by name. */
 declare const EDGE_PROFILES: Record<BuiltInEdgeName, EdgeProfile>;
 
 interface PowerlineParams {
@@ -749,10 +769,26 @@ type BadgePropsByShape = {
         shapeParams?: BadgeShapeParams[S];
     };
 }[BadgeShape];
+/**
+ * Props for {@link Badge}. Discriminated on `shape` so `shapeParams` is typed
+ * to the chosen shape's own parameters.
+ */
 type BadgeProps = BadgePropsByShape;
+/**
+ * A small labelled chip. Renders as a `<span>`, or as a `<button>`/`<a>` when
+ * given `onClick`/`href` — override with `as`.
+ *
+ * Beyond the built-in {@link BadgeShape} silhouettes, a badge can be composed:
+ * `base` picks the underlying outline and `effects` layer perimeter treatments
+ * over it, which stack additively. `bloat` pushes the whole silhouette outward
+ * along its normals before effects run, and `crawl` animates perimeter
+ * patterns.
+ */
 declare function Badge(props: BadgeProps): react_jsx_runtime.JSX.Element;
 
+/** Visual weight of a button. Defaults to `secondary`. */
 type ButtonVariant = 'primary' | 'secondary' | 'ghost';
+/** Button height and type scale. */
 type ButtonSize = 'sm' | 'md';
 type ButtonBase = {
     variant?: ButtonVariant;
@@ -776,9 +812,24 @@ type ButtonIconOnly = ButtonBase & {
     iconOnly: true;
     ariaLabel: string;
 };
+/**
+ * Props for {@link Button}. Setting `iconOnly` makes `ariaLabel` required,
+ * since an icon-only button has no text for a screen reader to announce.
+ */
 type ButtonProps = ButtonRegular | ButtonIconOnly;
+/**
+ * Standard button. `loading` swaps the leading icon for a spinner, marks the
+ * button `aria-busy`, and leaves the label in place; it does not disable the
+ * button, so pass `disabled` too if the click should be blocked.
+ *
+ * `ref` forwards to the underlying `<button>`.
+ */
 declare const Button: react.ForwardRefExoticComponent<ButtonProps & react.RefAttributes<HTMLButtonElement>>;
 
+/**
+ * One column of a {@link DataGrid}. `id` doubles as the default property name
+ * read off each row when no `accessor` is given.
+ */
 interface DataGridColumn<Row> {
     id: string;
     header: ReactNode;
@@ -791,6 +842,7 @@ interface DataGridColumn<Row> {
     /** Optional CSS class on every <td> in this column. */
     className?: string;
 }
+/** Props for {@link DataGrid}. */
 interface DataGridProps<Row extends {
     id: string;
 }> {
@@ -808,13 +860,30 @@ interface DataGridProps<Row extends {
     empty?: ReactNode;
     className?: string;
 }
+/**
+ * Sortable table for inspector-style data. Rows are keyed by `id`. Clicking a
+ * sortable header cycles ascending, descending, unsorted; nullish values sort
+ * last regardless of direction. Passing `onReorder` adds a leading drag-handle
+ * column — note that the drag indices it reports are into the *sorted* row
+ * order, not the input order.
+ */
 declare function DataGrid<Row extends {
     id: string;
 }>(props: DataGridProps<Row>): react_jsx_runtime.JSX.Element;
 
+/**
+ * Width class of a keycap: a modifier glyph, a multi-character legend that
+ * needs a wider chip, or a single character in a square one.
+ */
 type KeycapKind = 'modifier' | 'wide' | 'square';
+/**
+ * Picks the chip width for a legend — modifier glyphs and anything longer
+ * than one character get the wider forms.
+ */
 declare function inferKeycapKind(label: string): KeycapKind;
+/** Visual style of a keycap chip. */
 type KeyCapVariant = 'default' | 'minimal';
+/** Props for {@link KeyCap}. */
 interface KeyCapProps {
     /** Glyph rendered in the chip (modifier or key). */
     label: string;
@@ -845,6 +914,7 @@ interface KeyCapProps {
  *  `KeySequence` to render a full shortcut. */
 declare function KeyCap({ label, inverted, variant, className, style, font }: KeyCapProps): react_jsx_runtime.JSX.Element;
 
+/** One key in a shortcut. */
 interface KeySpec$1 {
     /** Glyph rendered in the chip (modifier or key). */
     label: string;
@@ -852,6 +922,7 @@ interface KeySpec$1 {
      *  trigger the action (e.g. an optional modifier). Defaults to false. */
     optional?: boolean;
 }
+/** Props for {@link KeySequence}. */
 interface KeySequenceProps {
     /** Keys to render. `undefined` or empty renders a muted em-dash.
      *  Modifiers are always rendered first regardless of input order; relative
@@ -898,12 +969,14 @@ type Platform = 'macos' | 'windows' | 'linux';
  *    back to text.
  *  - `'text'` always spells the label out (Cmd / Option / Esc / Enter). */
 type LegendStyle = 'auto' | 'symbol' | 'text';
+/** A modifier to render, named platform-independently. */
 interface LogicalModSpec {
     name: LogicalMod;
     /** Marks this modifier as optional (may be held but isn't required).
      *  Forwarded as the resulting `KeySpec.optional`. */
     optional?: boolean;
 }
+/** Options for {@link keySpecsFromMods}. */
 interface KeySpecsFromModsOptions {
     /** Override OS detection. Defaults to the detected platform, or
      *  `'macos'` when detection is unavailable (e.g. in tests, or when
@@ -960,32 +1033,65 @@ declare function keySpecFromKey(raw: string, opts?: KeySpecsFromModsOptions & {
     optional?: boolean;
 }): KeySpec$1;
 
+/**
+ * Passed to a custom thumb renderer: the thumb box in CSS px, and whether
+ * this thumb is the one being dragged.
+ */
 type ThumbRenderCtx = {
     width: number;
     height: number;
     isActive: boolean;
 };
+/**
+ * A thumb's appearance — one of the two built-in shapes, or a custom
+ * renderer.
+ */
 type ThumbShape = 'round' | 'notched' | {
     render: (ctx: ThumbRenderCtx) => ReactNode;
 };
+/**
+ * One handle on a {@link Slider}. `bounds` narrows the range this particular
+ * thumb may move within, either fixed or computed from the current thumb
+ * list.
+ */
 type Thumb = {
     value: number;
     label?: string;
     shape?: ThumbShape;
     bounds?: [number, number] | ((ctx: BoundsCtx) => [number, number]);
 };
+/**
+ * Passed to a thumb's `bounds` function: the full thumb list and this thumb's
+ * index in it, so a bound can be expressed relative to its neighbors.
+ */
 type BoundsCtx = {
     thumbs: readonly Thumb[];
     index: number;
 };
+/**
+ * Passed to `renderTrack`: the track's width in CSS px and a mapping from a
+ * slider value to its 0..1 position along the track.
+ */
 type TrackCtx = {
     trackWidth: number;
     valueToFraction: (v: number) => number;
 };
+/**
+ * Props for {@link Slider}.
+ *
+ * `onInput` fires continuously through a drag; `onChange` fires once when it
+ * ends and is the one to write to history.
+ *
+ * `constraint: 'ordered'` keeps thumbs from crossing each other. Supplying
+ * `onAddThumb` makes a click on empty track create a thumb, and supplying
+ * `onRemoveThumb` lets a right-click or a drag off the track remove one —
+ * both callbacks can decline by returning `null`/`false`. `allowShiftAll`
+ * makes shift-drag translate every thumb together.
+ */
 type SliderProps<T extends Thumb = Thumb> = {
     thumbs: readonly T[];
-    onChange: (next: T[]) => void;
-    onCommit?: (next: T[]) => void;
+    onInput: (next: T[]) => void;
+    onChange?: (next: T[]) => void;
     min: number;
     max: number;
     step?: number;
@@ -1000,15 +1106,26 @@ type SliderProps<T extends Thumb = Thumb> = {
     ariaLabel?: string;
     className?: string;
 };
+/**
+ * Multi-thumb slider over a shared track. The thumb list is fully controlled:
+ * every change, live or committed, arrives as a whole new array.
+ *
+ * Thumbs are draggable, and arrow/Home/End move the focused thumb — those
+ * keystrokes fire `onInput` and `onChange` together, since there is no
+ * in-flight state to buffer.
+ */
 declare function Slider<T extends Thumb = Thumb>(props: SliderProps<T>): ReactElement;
 
+/** One segment of a {@link ToggleBar}, identified by its `value`. */
 type ToggleBarItem<V extends string | number = string> = {
     value: V;
     label?: ReactNode;
     ariaLabel?: string;
     disabled?: boolean;
 };
+/** Segment height and type scale for a {@link ToggleBar}. */
 type ToggleBarSize = 'sm' | 'md';
+/** Visual treatment of a {@link ToggleBar}. */
 type ToggleBarVariant = 'default' | 'minimal';
 type CommonProps = {
     ariaLabel?: string;
@@ -1021,6 +1138,11 @@ type CommonProps = {
      *  selection becomes a flat accent. For dense diagnostic surfaces. */
     variant?: ToggleBarVariant;
 };
+/**
+ * Props for {@link ToggleBar}, discriminated on `mode`. Single mode is
+ * controlled by one value or `null`; multiple mode by an array, and only it
+ * accepts `mixedValues`.
+ */
 type ToggleBarProps<V extends string | number = string> = (CommonProps & {
     mode?: 'single';
     items: readonly ToggleBarItem<V>[];
@@ -1050,8 +1172,20 @@ type ToggleBarProps<V extends string | number = string> = (CommonProps & {
     mixedValues?: readonly V[];
     onChange: (next: V[]) => void;
 });
+/**
+ * Segmented control for choosing among a fixed set of values — one of them
+ * (`mode: 'single'`, the default) or any number (`mode: 'multiple'`).
+ *
+ * Single mode ignores a click on the already-selected segment unless
+ * `allowDeselect` is set. Arrow keys move focus without changing the value;
+ * Space and Enter commit.
+ */
 declare function ToggleBar<V extends string | number = string>(props: ToggleBarProps<V>): ReactElement;
 
+/**
+ * One segment of an {@link OptionsBar}. Unlike `ToggleBar`, each item carries
+ * its own selected state and its own `onChange`.
+ */
 type OptionsBarItem<V extends string | number = string> = {
     value: V;
     label?: ReactNode;
@@ -1060,8 +1194,11 @@ type OptionsBarItem<V extends string | number = string> = {
     selected: boolean;
     onChange: (next: boolean) => void;
 };
+/** Segment height and type scale for an {@link OptionsBar}. */
 type OptionsBarSize = 'sm' | 'md';
+/** Visual treatment of an {@link OptionsBar}. */
 type OptionsBarVariant = 'default' | 'minimal';
+/** Props for {@link OptionsBar}. */
 type OptionsBarProps<V extends string | number = string> = {
     items: readonly OptionsBarItem<V>[];
     ariaLabel?: string;
@@ -1074,8 +1211,17 @@ type OptionsBarProps<V extends string | number = string> = {
      *  selection becomes a flat accent. For dense diagnostic surfaces. */
     variant?: OptionsBarVariant;
 };
+/**
+ * Segmented strip of independent on/off options, each owning its own state.
+ * Use it when the segments are unrelated booleans; use `ToggleBar` when they
+ * are values of one setting.
+ */
 declare function OptionsBar<V extends string | number = string>(props: OptionsBarProps<V>): ReactElement;
 
+/**
+ * One button in an {@link ActionsBar}. `value` is only a React key; the item
+ * carries no selected state.
+ */
 type ActionsBarItem<V extends string | number = string> = {
     value: V;
     label?: ReactNode;
@@ -1083,8 +1229,11 @@ type ActionsBarItem<V extends string | number = string> = {
     disabled?: boolean;
     onAction: () => void;
 };
+/** Segment height and type scale for an {@link ActionsBar}. */
 type ActionsBarSize = 'sm' | 'md';
+/** Visual treatment of an {@link ActionsBar}. */
 type ActionsBarVariant = 'default' | 'minimal';
+/** Props for {@link ActionsBar}. */
 type ActionsBarProps<V extends string | number = string> = {
     items: readonly ActionsBarItem<V>[];
     ariaLabel?: string;
@@ -1093,8 +1242,20 @@ type ActionsBarProps<V extends string | number = string> = {
     size?: ActionsBarSize;
     variant?: ActionsBarVariant;
 };
+/**
+ * Segmented strip of momentary buttons — each press fires and nothing stays
+ * selected. Shares the look and the arrow-key navigation of `ToggleBar` and
+ * `OptionsBar`.
+ *
+ * This is a plain callback bar. For buttons driven by the kit's actions
+ * registry, use `ActionBar` instead.
+ */
 declare function ActionsBar<V extends string | number = string>(props: ActionsBarProps<V>): ReactElement;
 
+/**
+ * One segment of a {@link Powerline}. Giving it `onClick` or `href` makes it
+ * interactive, the same way it does on a `Badge`.
+ */
 interface PowerlineSegment {
     text: ReactNode;
     /** Cap on this segment's right edge. Next segment's left edge adopts the same profile. */
@@ -1106,6 +1267,7 @@ interface PowerlineSegment {
     href?: string;
     'aria-label'?: string;
 }
+/** Props for {@link Powerline}. */
 interface PowerlineProps {
     segments: PowerlineSegment[];
     /** Left edge of the first segment. Defaults to 'flat'. */
@@ -1122,6 +1284,14 @@ interface PowerlineProps {
     className?: string;
     'aria-label'?: string;
 }
+/**
+ * A row of chevron-linked badge segments, in the style of a shell powerline
+ * prompt. Each segment's `endCap` shapes both its own right edge and the next
+ * segment's left edge, so the run reads as one continuous chain.
+ *
+ * Built for showing a path through a sequence of steps — the inspector uses
+ * it to display how input routes from tool to gesture to action to target.
+ */
 declare function Powerline({ segments, startCap, size, variant, depth, gap, className, ...rest }: PowerlineProps): react_jsx_runtime.JSX.Element;
 
 /**
@@ -1299,16 +1469,21 @@ interface DeviceProfile {
     readonly targetScale: number;
 }
 
+/** A layout container's extent in world units. */
 type ContainerBounds = {
     x: number;
     y: number;
     width: number;
     height: number;
 };
+/** A child a layout strategy is arranging. */
 interface LayoutChild<TPose> {
     id: string;
     pose: TPose;
 }
+/** One place a dragged child could land. A strategy offers these as the drag
+ *  moves, a `LayoutSnap` picks between them, and the chosen one decides both
+ *  the preview and the committed poses. */
 interface DropTarget<TPose> {
     /** Where the dragged child lands if this target is picked. */
     pose: TPose;
@@ -1332,16 +1507,22 @@ interface DropTarget<TPose> {
     /** Strategy-private metadata (e.g. cell coords for tile-grid). */
     meta?: unknown;
 }
+/** Chooses which of a strategy's drop targets the pointer means, or `null`
+ *  to reject the drop. Separate from the strategy so the same arrangement can
+ *  be paired with different snapping rules. */
 interface LayoutSnap<TPose> {
     pickTarget(targets: DropTarget<TPose>[], pointer: {
         x: number;
         y: number;
     }): DropTarget<TPose> | null;
 }
+/** The container a layout strategy is arranging children within. */
 interface LayoutContainer {
     id: string;
     bounds: ContainerBounds;
 }
+/** The child currently being dragged: where it started, where the pointer
+ *  currently proposes it goes, and which container it came from. */
 interface LayoutDragged<TPose> {
     id: string;
     /** The pose the dragged child currently has (pre-drop). */
@@ -1350,6 +1531,15 @@ interface LayoutDragged<TPose> {
     pose: TPose;
     sourceContainerId: string | null;
 }
+/**
+ * How a container arranges its children, and what happens when one is dragged
+ * into or around it.
+ *
+ * The four required methods cover the whole cycle: `childPoses` is the resting
+ * arrangement, `getDropTargets` enumerates where a drag could land,
+ * `reflowPoses` is the live preview once a target is picked, and `commitDrop`
+ * turns the result into ops so the drop is undoable.
+ */
 interface LayoutStrategy<TPose> {
     childPoses(container: LayoutContainer, children: ReadonlyArray<LayoutChild<TPose>>): Map<string, TPose>;
     getDropTargets(container: LayoutContainer, children: ReadonlyArray<LayoutChild<TPose>>, dragged: LayoutDragged<TPose>): DropTarget<TPose>[];
@@ -1365,6 +1555,12 @@ interface LayoutStrategy<TPose> {
         x: number;
         y: number;
     }): boolean;
+    /** Optional: reject a drag before any drop-target work happens. A type-aware
+     *  container (a palette that only takes swatches, say) returns `false` and
+     *  the drag falls through to whatever container is under it next. When
+     *  absent, every drag is considered — rejection is still possible later, by
+     *  `snap.pickTarget` returning null. */
+    acceptsDrop?(container: LayoutContainer, dragged: LayoutDragged<TPose>): boolean;
 }
 
 /**
@@ -1406,6 +1602,12 @@ interface MoveAdapter<TNode extends {
      *  targeting (`getLayout` present), nested-hit collapse
      *  (`pickTopMostHit`), and group-pose composition. Flat scenes may omit. */
     getParent?(id: string): string | null;
+    /** Optional paint depth, read by `pickTopMostHit` to resolve two *siblings*
+     *  whose bodies both cover the pointer. Without it the hit list's own order
+     *  decides, which is right for a back-to-front walk and wrong for anything
+     *  else. See `PickTopMostHitAdapter` for the `compareZ` alternative. */
+    getZIndex?(id: string): number | null | undefined;
+    compareZ?(a: string, b: string): number;
     setPose(id: string, pose: TPose): void;
     /** Optional. Used only by reparent ops (e.g. drag-into-container drops via
      *  layout strategies). Flat scenes that never reparent may omit. */
@@ -1602,13 +1804,28 @@ interface PointSnapBehavior<TPose extends ResizePose> {
  *  Apps and other consumers can add their own tags; this list is what
  *  `weasel-modes` itself uses. */
 declare const ALL_TAGS: readonly ["navigation", "creates-selection", "creates-paths", "creates-shapes", "creates-text", "edits-anchors", "edits-text", "transforms-selection", "samples-color", "applies-fill", "edits-page"];
+/** One capability a tool or contribution declares, and a mode allows. Any
+ *  string is accepted so apps can add tags of their own; `ALL_TAGS` is the
+ *  set this package ships. */
 type CapabilityTag = (typeof ALL_TAGS)[number] | (string & {});
 
+/** How a mode tints the workspace — the area around the page — so the user
+ *  can see at a glance which mode is active. */
 interface WorkspaceVisual {
     tint?: string;
     gradient?: 'top-down' | 'bottom-up';
     intensity?: number;
 }
+/**
+ * A mode: an app-level editing context that narrows which tools are usable and
+ * how the workspace looks. Tools live inside modes; a tool is never "in" one.
+ *
+ * `kind` picks the lifecycle. A `soft` mode (path-edit, isolation, text-edit)
+ * is a scoped context with no commit ceremony — every edit inside it is
+ * independently undoable and `exit` is non-destructive. A `strict` mode
+ * (free-transform, crop) is a transaction: the whole session collapses to one
+ * undoable step and leaving requires an explicit `commit` or `cancel`.
+ */
 interface ModeDefinition {
     id: string;
     kind: 'soft' | 'strict';
@@ -1632,6 +1849,10 @@ interface ModeDefinition {
     };
 }
 
+/** Holds the set of available modes and which one is active, and notifies
+ *  subscribers when that changes. `getVersion` is a monotonic counter for
+ *  render-cache invalidation. Unknown mode ids throw rather than being
+ *  ignored. */
 interface ModeRegistry {
     current(): ModeDefinition;
     setMode(id: string): void;
@@ -2272,7 +2493,7 @@ type OngoingOverlay = {
      * renderer narrows on `shape` and casts the field shape it expects.
      */
     kind: 'insertPreview';
-    shape: 'rect' | 'ellipse' | 'line' | 'polygon' | 'star' | 'pencil';
+    shape: 'rect' | 'ellipse' | 'line' | 'polygon' | 'star' | 'pencil' | 'image';
     bounds: {
         x: number;
         y: number;
@@ -2336,6 +2557,14 @@ interface OngoingHandle {
      */
     previewIds?(): Iterable<string> | null;
     previewPose?(id: string): unknown | null;
+    /**
+     * Subset of `previewIds()` the ghost layer paints at full opacity. The
+     * ghost alpha says "this is in flight under the pointer"; a node the
+     * gesture merely displaces — a layout sibling reflowing into its
+     * destination slot — is not, and reads better settled. Honored at
+     * subtree-root granularity.
+     */
+    previewOpaqueIds?(): Iterable<string> | null;
     /**
      * When `false`, the preview-ghost layer paints the ghost AND the
      * source node stays visible at its committed pose. Defaults to
@@ -2403,6 +2632,9 @@ type Invoker = ImmediateInvoker | OngoingInvoker;
  * See `docs/superpowers/specs/2026-05-16-registry-unification-design.md`.
  */
 
+/** An interaction: a gesture spec composed with the id of the action it
+ *  invokes. Tools declare arrays of these; the dispatcher matches an incoming
+ *  input event against them and runs the winner's action. */
 interface GestureBinding {
     spec: GestureSpec;
     actionId: string;
@@ -2613,6 +2845,9 @@ interface PointerContextValue {
     readonly getDropPoint: () => PointerWorldPos;
 }
 
+/** Which tool is active, plus the stack of tools temporarily held active by a
+ *  hotkey (space-for-hand and the like). The dispatcher reads this to decide
+ *  whose bindings are in scope. */
 interface ActiveToolContextValue {
     active: string;
     hotkeyStack: string[];
@@ -2854,6 +3089,8 @@ type NodeAtPointDep = (point: {
     x: number;
     y: number;
 }, exclude?: Iterable<NodeId>) => NodeId | null;
+/** What an area-selecting action needs: a way to ask what a region covers,
+ *  and a way to read and replace the selection. */
 interface AreaSelectDep {
     /** Return ids of all scene nodes whose AABB overlaps `bounds`. */
     hitTestArea(bounds: {
@@ -3102,6 +3339,13 @@ type InsertExtras = {
 } | {
     kind: 'text';
     text?: string;
+} | {
+    kind: 'image';
+    src?: string;
+    opacity?: number;
+    /** Chrome-only: what the in-flight drag paints. Read by the overlay
+     *  layer, ignored by the insert dep. */
+    preview?: 'bitmap' | 'outline';
 } | {
     kind: string;
     [extra: string]: unknown;
@@ -3185,6 +3429,14 @@ interface ResizePolicy<TPose> {
 interface LayoutDep {
     getLayout(containerId: string): LayoutStrategy<unknown> | null;
 }
+/**
+ * The names an action may declare in `requires`, and what each resolves to.
+ *
+ * This is the whole vocabulary of things an action can reach — selection,
+ * scene, view, history, and the rest. Consumers add their own entries by
+ * augmenting the interface (`declare module '@weasel-js/core'`), which is what
+ * makes a custom dep name type-check in `requires` and in the deps bag.
+ */
 interface DepSchema {
     /** Kit selection state — ids of currently selected nodes. */
     selection: SelectionApi;
@@ -3371,7 +3623,10 @@ interface DepSchema {
  */
 type DepName = keyof DepSchema;
 
+/** Which kind of handle a recorded handle marker represents. */
 type HandleKind = 'corner' | 'rotation' | 'anchor';
+/** The geometry a hit region actually tests against, as reported to the debug
+ *  sink so the overlay can draw the real shape rather than its bounding box. */
 type HitShape = {
     kind: 'rect';
     x: number;
@@ -3388,6 +3643,14 @@ type HitShape = {
     kind: 'path';
     d: Path2D;
 };
+/**
+ * Where the kit reports what it is doing so the debug overlay can draw it.
+ *
+ * Recording is push-based and cheap: hit-testers, handle painters and snap
+ * strategies call these as they run, whether or not any overlay is watching.
+ * Nothing here affects behavior — a sink that discards everything is a valid
+ * sink.
+ */
 interface DebugSink {
     recordHitbox(id: string, kind: 'body' | 'handle' | 'rotation' | 'anchor', shape: HitShape): void;
     recordHandle(id: string, position: {
@@ -3431,6 +3694,14 @@ interface Eligibility {
     /** Modality filter, applied wherever it would otherwise be live. */
     capabilities?: CapabilityTag[];
 }
+/**
+ * Where an entry's overlay sits in the layer stack, relative to the
+ * selection chrome. `'top'` is the default and renders above everything;
+ * the other two exist for chrome that belongs under the selection handles
+ * (a snap-target highlight, say). With no selection overlay in the stack,
+ * all three collapse to `'top'`.
+ */
+type OverlayPosition = 'top' | 'before-selection' | 'after-selection';
 /**
  * A registry entry: what it contributes, and when it is eligible. Every role
  * is optional and independent — an entry that only routes input declares only
@@ -3441,12 +3712,37 @@ interface Contribution {
     eligibility: Eligibility;
     bindings?: GestureBinding[];
     actions?: Action[];
-    overlay?: RenderLayer<unknown>;
+    /** One layer, or several composed in the given order. */
+    overlay?: RenderLayer<unknown> | RenderLayer<unknown>[];
+    /** Defaults to `'top'`. Applies to every layer in `overlay`. */
+    overlayPosition?: OverlayPosition;
     presentation?: ToolPresentation;
     /** Reflection escape hatch — the authored form, when there was one. */
     def?: unknown;
 }
 
+/**
+ * Configurable activation-key descriptor for tools that expose their
+ * keybinding to the host (currently Lasso and Eyedropper). Captures
+ * only the fields meaningful to a caller-supplied tool-select key —
+ * dispatcher-internal fields (`skipInEditable`, `enabled`,
+ * `preventDefault`) live on `KeyBinding` in keyHelpers.ts and are
+ * not part of the configurable surface.
+ */
+interface ToolKeybinding {
+    /** Key or list of keys to match (case-insensitive against `event.key`). */
+    key: string | readonly string[];
+    /** Require Cmd (mac) / Ctrl (others). Default `false`. */
+    mod?: boolean;
+    /** Require Alt. Default `false`. */
+    alt?: boolean;
+    /**
+     * Shift policy. `undefined`/`false` forbids shift, `true` requires
+     * shift, `'optional'` allows either.
+     */
+    shift?: boolean | 'optional';
+}
+
 /** Modifier-key snapshot at event dispatch time. `space` is included
  *  because tools commonly use space as a hotkey-slot trigger and may
  *  also want to read it as a flag mid-gesture. */
@@ -3716,30 +4012,11 @@ declare const ActionDisabledReason: {
     /** Sentinel: the predicate threw. Surfaced by `evaluateEnabled`'s catch. */
     readonly PredicateThrew: "predicate-threw";
 };
+/** Why an action is unavailable right now. */
 type ActionDisabledReason = (typeof ActionDisabledReason)[keyof typeof ActionDisabledReason];
 
-/**
- * Configurable activation-key descriptor for tools that expose their
- * keybinding to the host (currently Lasso and Eyedropper). Captures
- * only the fields meaningful to a caller-supplied tool-select key —
- * dispatcher-internal fields (`skipInEditable`, `enabled`,
- * `preventDefault`) live on `KeyBinding` in keyHelpers.ts and are
- * not part of the configurable surface.
- */
-interface ToolKeybinding {
-    /** Key or list of keys to match (case-insensitive against `event.key`). */
-    key: string | readonly string[];
-    /** Require Cmd (mac) / Ctrl (others). Default `false`. */
-    mod?: boolean;
-    /** Require Alt. Default `false`. */
-    alt?: boolean;
-    /**
-     * Shift policy. `undefined`/`false` forbids shift, `true` requires
-     * shift, `'optional'` allows either.
-     */
-    shift?: boolean | 'optional';
-}
-
+/** The tool registry's runtime surface: which tool is active, which is
+ *  temporarily held by a hotkey, and how to change either. */
 interface ToolsApi {
     /** Current active-slot tool id. */
     active: string;
@@ -3760,12 +4037,13 @@ interface ToolsApi {
     /** Returns true if a tool with the given id is in the registry or ambient list. */
     has(id: string): boolean;
     /** All overlay layers from currently-engaged tools (active slot, hotkey
-     *  slot if engaged, all ambient slot tools). Filters out tools with no
-     *  `overlay` field. Order: active, then hotkey (if engaged), then
-     *  ambient (registration order). */
-    getActiveOverlays(): RenderLayer<unknown>[];
+     *  slot if engaged, all ambient slot tools) that declare `position`.
+     *  Filters out tools with no `overlay` field. Order: active, then hotkey
+     *  (if engaged), then ambient (registration order). */
+    getActiveOverlays(position?: OverlayPosition): RenderLayer<unknown>[];
 }
 
+/** Props for {@link Sidebar}. */
 interface SidebarProps {
     /**
      * Edge the sidebar docks to. Adds a class hook (`s.left` / `s.right`)
@@ -3796,6 +4074,7 @@ interface SidebarProps {
  */
 declare function Sidebar(props: SidebarProps): react_jsx_runtime.JSX.Element;
 
+/** Props for {@link SidebarPanel}. */
 interface SidebarPanelProps {
     /** Title rendered in the panel's header row. */
     title?: ReactNode;
@@ -3830,6 +4109,7 @@ interface SidebarPanelProps {
  */
 declare function SidebarPanel(props: SidebarPanelProps): react_jsx_runtime.JSX.Element;
 
+/** Props for {@link ToolButton}. */
 interface ToolButtonProps {
     /** Icon node (typically an SVG component). */
     icon: ReactNode;
@@ -3856,6 +4136,9 @@ interface ToolButtonProps {
     tabbable?: boolean;
     /** Click handler. */
     onClick(): void;
+    /** Key handler for the underlying button — a toolbar's roving-tabindex
+     *  navigation attaches here. */
+    onKeyDown?(e: KeyboardEvent<HTMLElement>): void;
     /**
      * Tooltip content. Defaults to `label` (plus `shortcut` if provided).
      */
@@ -3870,6 +4153,7 @@ interface ToolButtonProps {
  */
 declare function ToolButton(props: ToolButtonProps): react_jsx_runtime.JSX.Element;
 
+/** Props for {@link ToolGroup}. */
 interface ToolGroupProps {
     children: ReactNode;
     /**
@@ -3911,6 +4195,7 @@ declare function formatShortcutParts(b: ShortcutInput | undefined): readonly str
  *  is treated as falsy. */
 declare function formatShortcut(b: ShortcutInput | undefined): string | undefined;
 
+/** Props for {@link ToolPalette}. */
 interface ToolPaletteProps {
     tools: ToolsApi;
     orientation?: 'vertical' | 'horizontal';
@@ -3933,9 +4218,22 @@ interface ToolPaletteProps {
      */
     groupOrder?: readonly string[];
 }
+/**
+ * Toolbar of the registered tools, split into separator-divided groups by
+ * each tool's presentation group and navigable by arrow keys. Clicking a
+ * button makes that tool active.
+ *
+ * Given a `modeRegistry`, tools whose capabilities the current mode does not
+ * allow render greyed out and inert rather than disappearing.
+ */
 declare function ToolPalette(props: ToolPaletteProps): react_jsx_runtime.JSX.Element;
 
+/**
+ * Whether a {@link Field} stacks its label above the control or sits them
+ * side by side.
+ */
 type FieldOrientation = 'stacked' | 'row';
+/** Props for {@link Field}. */
 type FieldProps = {
     orientation?: FieldOrientation;
     className?: string;
@@ -3951,6 +4249,10 @@ type FieldProps = {
  * control to sit in the same visual rhythm.
  */
 declare function Field({ orientation, className, children }: FieldProps): react_jsx_runtime.JSX.Element;
+/**
+ * The class names {@link Field} paints its slots with, so a control composing
+ * its own layout can match the same form-row rhythm.
+ */
 declare const fieldClasses: {
     root: string;
     row: string;
@@ -3959,6 +4261,7 @@ declare const fieldClasses: {
     error: string;
 };
 
+/** Props for {@link Input}, on top of React Aria's `TextField` props. */
 type InputProps = Omit<TextFieldProps, 'children' | 'className'> & {
     label?: ReactNode;
     description?: ReactNode;
@@ -3985,6 +4288,10 @@ declare const Input: react.ForwardRefExoticComponent<Omit<TextFieldProps, "child
     className?: string;
 } & react.RefAttributes<HTMLInputElement>>;
 
+/**
+ * Props for {@link Checkbox}, on top of React Aria's `Checkbox` props. The
+ * label is passed as children.
+ */
 type CheckboxProps = Omit<CheckboxProps$1, 'children' | 'className'> & {
     children?: ReactNode;
     className?: string;
@@ -3998,35 +4305,58 @@ declare const Checkbox: react.ForwardRefExoticComponent<Omit<CheckboxProps$1, "c
     className?: string;
 } & react.RefAttributes<HTMLLabelElement>>;
 
+/**
+ * Props for {@link Switch}, on top of React Aria's `Switch` props. The label
+ * is passed as children.
+ */
 type SwitchProps = Omit<SwitchProps$1, 'children' | 'className'> & {
     children?: ReactNode;
     className?: string;
 };
+/**
+ * On/off toggle wrapping React Aria's Switch, skinned against the `--wzl-*`
+ * tokens. Use for a setting that takes effect immediately; use `Checkbox`
+ * for one that is submitted with a form.
+ *
+ * `ref` forwards to the underlying label element.
+ */
 declare const Switch: react.ForwardRefExoticComponent<Omit<SwitchProps$1, "children" | "className"> & {
     children?: ReactNode;
     className?: string;
 } & react.RefAttributes<HTMLLabelElement>>;
 
+/** Props for {@link Tabs}, on top of React Aria's `Tabs` props. */
 type TabsProps = Omit<TabsProps$1, 'className' | 'children'> & {
     children?: ReactNode;
     className?: string;
 };
+/**
+ * Tab set wrapping React Aria's Tabs, skinned against the `--wzl-*` tokens.
+ * Holds a {@link TabList} and one {@link TabPanel} per tab.
+ */
 declare function Tabs({ children, className, ...rest }: TabsProps): react_jsx_runtime.JSX.Element;
+/** Props for {@link TabList}, on top of React Aria's `TabList` props. */
 type TabListProps<T extends object> = Omit<TabListProps$1<T>, 'className'> & {
     className?: string;
 };
+/** The row of tab buttons inside a {@link Tabs}. */
 declare function TabList<T extends object>({ className, ...rest }: TabListProps<T>): react_jsx_runtime.JSX.Element;
+/** Props for {@link Tab}, on top of React Aria's `Tab` props. */
 type TabProps = Omit<TabProps$1, 'className' | 'children'> & {
     children?: ReactNode;
     className?: string;
 };
+/** One tab button. Its `id` selects the {@link TabPanel} it reveals. */
 declare function Tab({ children, className, ...rest }: TabProps): react_jsx_runtime.JSX.Element;
+/** Props for {@link TabPanel}, on top of React Aria's `TabPanel` props. */
 type TabPanelProps = Omit<TabPanelProps$1, 'className' | 'children'> & {
     children?: ReactNode;
     className?: string;
 };
+/** The content shown for the {@link Tab} whose `id` matches this panel's. */
 declare function TabPanel({ children, className, ...rest }: TabPanelProps): react_jsx_runtime.JSX.Element;
 
+/** Props for {@link RadioGroup}, on top of React Aria's `RadioGroup` props. */
 type RadioGroupProps = Omit<RadioGroupProps$1, 'children' | 'className'> & {
     label?: ReactNode;
     description?: ReactNode;
@@ -4034,13 +4364,21 @@ type RadioGroupProps = Omit<RadioGroupProps$1, 'children' | 'className'> & {
     children?: ReactNode;
     className?: string;
 };
+/**
+ * A set of mutually exclusive choices, wrapping React Aria's RadioGroup and
+ * supplying the same label / description / errorMessage slots as `Input`.
+ * Holds {@link Radio} children.
+ */
 declare function RadioGroup(props: RadioGroupProps): react_jsx_runtime.JSX.Element;
+/** Props for {@link Radio}, on top of React Aria's `Radio` props. */
 type RadioProps = Omit<RadioProps$1, 'className' | 'children'> & {
     children?: ReactNode;
     className?: string;
 };
+/** One choice in a {@link RadioGroup}. The label is passed as children. */
 declare function Radio({ children, className, ...rest }: RadioProps): react_jsx_runtime.JSX.Element;
 
+/** Props for {@link NumberField}, on top of React Aria's `NumberField` props. */
 type NumberFieldProps = Omit<NumberFieldProps$1, 'children' | 'className'> & {
     label?: ReactNode;
     description?: ReactNode;
@@ -4052,6 +4390,14 @@ type NumberFieldProps = Omit<NumberFieldProps$1, 'children' | 'className'> & {
     placeholder?: string;
     className?: string;
 };
+/**
+ * Numeric input with stepper buttons, wrapping React Aria's NumberField and
+ * supplying the same label / description / errorMessage slots as `Input`.
+ * Arrow keys and scroll step the value; parsing and formatting are React
+ * Aria's.
+ *
+ * `ref` forwards to the underlying `<input>`.
+ */
 declare const NumberField: react.ForwardRefExoticComponent<Omit<NumberFieldProps$1, "children" | "className"> & {
     label?: ReactNode;
     description?: ReactNode;
@@ -4064,6 +4410,7 @@ declare const NumberField: react.ForwardRefExoticComponent<Omit<NumberFieldProps
     className?: string;
 } & react.RefAttributes<HTMLInputElement>>;
 
+/** One option in a {@link Select}'s `options` list. */
 type SelectOption = {
     value: string;
     label: ReactNode;
@@ -4077,6 +4424,10 @@ type SelectOption = {
     textValue?: string;
 };
 type Key$1 = string | number;
+/**
+ * Props for {@link Select}, on top of React Aria's `Select` props, with the
+ * selection key narrowed to the option value type.
+ */
 type SelectProps<T extends Key$1 = string> = Omit<SelectProps$1<object>, 'children' | 'className' | 'selectedKey' | 'defaultSelectedKey' | 'onSelectionChange'> & {
     label?: ReactNode;
     description?: ReactNode;
@@ -4101,12 +4452,23 @@ type SelectProps<T extends Key$1 = string> = Omit<SelectProps$1<object>, 'childr
  * union for `value` (e.g. `'r' | 'g' | 'b'`) get a typed `onSelectionChange`.
  */
 declare function Select<T extends Key$1 = string>(props: SelectProps<T>): react_jsx_runtime.JSX.Element;
+/** Props for {@link SelectItem}, on top of React Aria's `ListBoxItem` props. */
 type SelectItemProps = Omit<ListBoxItemProps, 'className' | 'children'> & {
     children?: ReactNode;
     className?: string;
 };
+/**
+ * One row in a {@link Select}'s list, with a leading check mark when
+ * selected. A string child supplies its own `textValue`; anything richer must
+ * pass one so type-to-select and screen readers have something to read.
+ */
 declare function SelectItem({ children, className, textValue, ...rest }: SelectItemProps): react_jsx_runtime.JSX.Element;
 
+/**
+ * One option in a {@link ComboBox}'s `options` list. `textValue` is the
+ * plain-text form used for filtering and screen readers, needed only when
+ * `label` isn't a bare string.
+ */
 type ComboBoxOption = {
     value: string;
     label: ReactNode;
@@ -4114,6 +4476,10 @@ type ComboBoxOption = {
     isDisabled?: boolean;
 };
 type Key = string | number;
+/**
+ * Props for {@link ComboBox}, on top of React Aria's `ComboBox` props, with
+ * the selection key narrowed to the option value type.
+ */
 type ComboBoxProps<T extends Key = string> = Omit<ComboBoxProps$1<object>, 'children' | 'className' | 'selectedKey' | 'defaultSelectedKey' | 'onSelectionChange'> & {
     label?: ReactNode;
     description?: ReactNode;
@@ -4135,11 +4501,14 @@ type ComboBoxProps<T extends Key = string> = Omit<ComboBoxProps$1<object>, 'chil
  * is in the input, selection clears (key becomes null).
  */
 declare function ComboBox<T extends Key = string>(props: ComboBoxProps<T>): react_jsx_runtime.JSX.Element;
+/** Props for {@link ComboBoxItem}, on top of React Aria's `ListBoxItem` props. */
 type ComboBoxItemProps = Omit<ListBoxItemProps, 'className'> & {
     className?: string;
 };
+/** One row in a {@link ComboBox}'s filtered list. */
 declare function ComboBoxItem({ className, ...rest }: ComboBoxItemProps): react_jsx_runtime.JSX.Element;
 
+/** Props for {@link RangeSlider}, on top of React Aria's `Slider` props. */
 type RangeSliderProps = Omit<SliderProps$1, 'children' | 'className'> & {
     label?: ReactNode;
     /** Show the current value next to the label. Defaults to true when a
@@ -4156,6 +4525,7 @@ type RangeSliderProps = Omit<SliderProps$1, 'children' | 'className'> & {
  */
 declare function RangeSlider(props: RangeSliderProps): react_jsx_runtime.JSX.Element;
 
+/** Props for {@link Dialog}, on top of React Aria's `ModalOverlay` props. */
 type DialogProps = Omit<ModalOverlayProps, 'children' | 'className'> & {
     /** Heading rendered in the dialog's default header. Omit when supplying
      *  a custom `header` slot via children. */
@@ -4195,6 +4565,7 @@ interface Point {
     y: number;
 }
 
+/** Background grid configuration for a {@link Plot2D}. */
 interface GridSettings {
     /** Number of evenly-spaced internal grid lines per axis (excluding
      *  the edges). Applied to both x and y. Default 3. */
@@ -4202,14 +4573,17 @@ interface GridSettings {
     /** Stroke color override. When omitted, uses `var(--plot-grid)`. */
     color?: string;
 }
+/** Axis-line configuration for a {@link Plot2D}. */
 interface AxesSettings {
     /** Stroke color override. When omitted, uses `var(--plot-axis)`. */
     color?: string;
 }
+/** A pointer position given in both of the plot's coordinate systems. */
 interface Plot2DCoords {
     plot: Point;
     model: Point;
 }
+/** Props for {@link Plot2D}. */
 interface Plot2DProps {
     width: number;
     height: number;
@@ -4233,6 +4607,11 @@ interface Plot2DProps {
     onKeyDown?: (e: KeyboardEvent<SVGSVGElement>) => void;
     children?: ReactNode;
 }
+/**
+ * Imperative handle on a {@link Plot2D}: the SVG element, its size, and the
+ * coordinate conversions, including ones that start from a raw DOM event so a
+ * drag tracked on `window` can still map back into the plot.
+ */
 interface Plot2DHandle {
     readonly svg: SVGSVGElement | null;
     plotToModel(pt: Point): Point;
@@ -4251,6 +4630,11 @@ interface Plot2DHandle {
     readonly width: number;
     readonly height: number;
 }
+/**
+ * An SVG plotting surface with an optional grid and axes. It draws the frame
+ * and owns the model-space to plot-space mapping; the plotted content is
+ * whatever children are passed, positioned in plot space.
+ */
 declare const Plot2D: react.ForwardRefExoticComponent<Plot2DProps & react.RefAttributes<Plot2DHandle>>;
 
 /**
@@ -4274,6 +4658,7 @@ type InterpolationMode = 'linear' | 'catmull-rom' | 'catmull-rom-uniform' | 'cat
  * and a derived (read-only) curve on the same chart.
  */
 
+/** One anchor of a curve, in model space. */
 interface ControlPoint {
     x: number;
     y: number;
@@ -4281,9 +4666,27 @@ interface ControlPoint {
      *  user. Render as a smaller diamond with locked styling. */
     locked?: boolean;
 }
+/**
+ * Whether a curve's points keep their x order. In `'1d'` an anchor cannot be
+ * dragged past its neighbors and a new point is inserted at its x position;
+ * in `'2d'` points are free to move anywhere and keep their list order.
+ */
 type CurveDomain = '1d' | '2d';
+/**
+ * How much of a curve's first and last anchor the user may move: everything,
+ * only their y, or nothing.
+ */
 type EndpointMode = 'free' | 'pinned-x' | 'pinned-both';
+/**
+ * Where a click adds a new anchor — on the curve itself, anywhere in the
+ * plot, or nowhere.
+ */
 type AddPointMode = 'click-curve' | 'click-empty' | 'never';
+/**
+ * What a `renderAnchor` function is given for one anchor: the point, its
+ * index, its position in plot space (`cx`/`cy`), and the states that change
+ * how it should look.
+ */
 interface AnchorRenderProps {
     point: ControlPoint;
     index: number;
@@ -4294,17 +4697,26 @@ interface AnchorRenderProps {
     isPinnedEndpoint: boolean;
     isEndpoint: boolean;
 }
+/**
+ * Per-instance curve-rendering overrides. Currently empty — passing `{}`
+ * means "draw the curve", and `false`/`null` means don't.
+ */
 interface CurveSettings {
 }
+/** Shades the region between the curve and one edge of the plot. */
 interface FillSettings {
     side: 'below' | 'above';
     color?: string;
 }
 
+/**
+ * Props for {@link CurveEditor}. `onInput` fires throughout a gesture and
+ * `onChange` once at its end, with the pre-gesture points as `prev`.
+ */
 interface CurveEditorProps {
     value: readonly ControlPoint[];
-    onChange: (next: ControlPoint[]) => void;
-    onChangeCommit?: (next: ControlPoint[], prev: readonly ControlPoint[]) => void;
+    onInput: (next: ControlPoint[]) => void;
+    onChange?: (next: ControlPoint[], prev: readonly ControlPoint[]) => void;
     domain?: CurveDomain;
     interpolation?: InterpolationMode;
     endpoints?: EndpointMode;
@@ -4328,16 +4740,25 @@ interface CurveEditorProps {
     className?: string;
     style?: CSSProperties;
 }
+/**
+ * Editable curve through a list of control points: drag anchors, click to
+ * insert, right-click to delete, with optional built-in undo.
+ *
+ * This is the single-curve API, implemented as one `createFunctionLayer` on
+ * a `LayeredCurveEditor`. Reach for those directly to stack several curves
+ * on one plot.
+ */
 declare function CurveEditor(props: CurveEditorProps): react_jsx_runtime.JSX.Element;
 
+/** Props for {@link PointPlotter}. */
 interface PointPlotterProps {
     /** Plotted points; caller-owned. */
     value: readonly ControlPoint[];
     /** Fires every frame during drag with the live in-flight value. */
-    onChange: (next: ControlPoint[]) => void;
+    onInput: (next: ControlPoint[]) => void;
     /** Fires once per discrete user action (drag-end, add, delete) with
      *  the new value and the value at gesture start. Wire history here. */
-    onChangeCommit?: (next: ControlPoint[], prev: readonly ControlPoint[]) => void;
+    onChange?: (next: ControlPoint[], prev: readonly ControlPoint[]) => void;
     /** Model-space x range. Default [0, 1]. */
     xRange?: readonly [number, number];
     /** Model-space y range. Default [0, 1]. */
@@ -4378,6 +4799,14 @@ interface PointPlotterProps {
  */
 declare function PointPlotter(props: PointPlotterProps): react_jsx_runtime.JSX.Element;
 
+/**
+ * Options for {@link paintGradientTrack}.
+ *
+ * `gradient` maps a normalized position along the track (0 to 1) to a CSS
+ * color; `samples` is how many stops the resulting linear-gradient uses.
+ * `activeRange`, given in the slider's own value units, keeps that span at
+ * full strength and dims + hatches the rest.
+ */
 type GradientTrackOpts = {
     gradient: (t: number) => string;
     samples?: number;
@@ -4389,8 +4818,19 @@ type GradientTrackOpts = {
         dim?: number;
     };
 };
+/**
+ * Builds a `Slider` `renderTrack` function that paints the track as a
+ * sampled color gradient, optionally dimming and hatching the portions
+ * outside an active range.
+ */
 declare function paintGradientTrack(opts: GradientTrackOpts): (ctx: TrackCtx) => ReactNode;
 
+/**
+ * A chroma envelope over lightness, as three linear segments: flat at `cBot`
+ * below `lRange[0]`, rising to `cPeak` at `midL`, falling to `cTop` at
+ * `lRange[1]`, flat beyond. Keeps a color ramp inside gamut at the light and
+ * dark ends while staying saturated through the middle.
+ */
 type ChromaCurve = {
     lRange: [number, number];
     midL: number;
@@ -4398,13 +4838,20 @@ type ChromaCurve = {
     cPeak: number;
     cTop: number;
 };
+/** A single lightness/chroma sample. */
 type ChromaCurvePoint = {
     L: number;
     C: number;
 };
+/**
+ * Converts an OKLCH color to a gamut-clipped `#rrggbb` string. Hue is in
+ * degrees, unlike the kit's OKLab helpers which take radians.
+ */
 declare function oklchToHex(L: number, C: number, Hdeg: number): string;
+/** Evaluates a {@link ChromaCurve} at a lightness, clamping outside its range. */
 declare function chromaAt(L: number, curve: ChromaCurve): number;
 
+/** One row in a reorderable list. */
 interface LayerListItem {
     id: string;
     label: ReactNode;
@@ -4414,6 +4861,10 @@ interface LayerListItem {
     /** Optional color swatch rendered before the label. Any CSS color string. */
     swatch?: string;
 }
+/**
+ * Options for {@link useReorderDragList}. `onReorder` receives the dragged ids
+ * and the index they were dropped at, measured against the pre-drag `items`.
+ */
 interface UseReorderDragListOptions {
     items: LayerListItem[];
     selectedIds: string[];
@@ -4421,10 +4872,18 @@ interface UseReorderDragListOptions {
     /** Pointer-move distance (px) before pending drag engages. Default 4. */
     threshold?: number;
 }
+/**
+ * Live drag state for rendering feedback: which ids are being dragged and the
+ * insertion index the drop would use. Both `null` when no drag is engaged.
+ */
 interface ReorderDragState {
     draggedIds: string[] | null;
     targetIndex: number | null;
 }
+/**
+ * Props to spread onto the list container and each row, plus the live
+ * {@link ReorderDragState}.
+ */
 interface ReorderDragHandlers {
     rowProps(id: string, index: number): {
         onPointerDown(e: PointerEvent$1): void;
@@ -4437,6 +4896,16 @@ interface ReorderDragHandlers {
     };
     state: ReorderDragState;
 }
+/**
+ * Drag-to-reorder for a vertical list of rows. Dragging a row that is part of
+ * the current selection drags the whole selection; dragging any other row
+ * drags just that row. Locked rows can neither be dragged nor crossed by a
+ * drop. A drop that would leave a contiguous block where it already is does
+ * not call `onReorder`.
+ *
+ * The pointer is captured on the row, so a drag that leaves the list still
+ * tracks and still releases cleanly.
+ */
 declare function useReorderDragList(opts: UseReorderDragListOptions): ReorderDragHandlers;
 
 /** The only thing the hook needs to know about a bar's items: which are
@@ -4444,6 +4913,7 @@ declare function useReorderDragList(opts: UseReorderDragListOptions): ReorderDra
 type RovingItem = {
     disabled?: boolean;
 };
+/** Options for {@link useRovingTabIndex}. */
 type UseRovingTabIndexOptions = {
     /** In the same order as the elements carrying `itemClassName`. */
     items: readonly RovingItem[];
@@ -4461,6 +4931,10 @@ type UseRovingTabIndexOptions = {
      *  alone, which on a native `<button>` produces an ordinary click. */
     onActivate?: (index: number) => void;
 };
+/**
+ * What {@link useRovingTabIndex} returns: a container ref plus the per-item
+ * `tabIndex` and `onKeyDown` values to spread onto each item.
+ */
 type RovingTabIndex<T extends HTMLElement = HTMLDivElement> = {
     /** Attach to the container element that holds the items. */
     rootRef: RefObject<T | null>;
@@ -4501,6 +4975,10 @@ declare function useRovingTabIndex<T extends HTMLElement = HTMLDivElement>(optio
  * glyph doesn't get confused with a bullet or list dash.
  */
 declare const MINUS_SIGN = "\u2212";
+/**
+ * Formats a number for display, substituting {@link MINUS_SIGN} for the ASCII
+ * hyphen `toLocaleString` emits. Non-finite values stringify as-is.
+ */
 declare function formatNumber(value: number, options?: Intl.NumberFormatOptions): string;
 
 export { ActionBar, ActionsBar, Badge, Button, Checkbox, ComboBox, ComboBoxItem, CurveEditor, DataGrid, Dialog, EDGE_PROFILES, Field, Input, KeyCap, KeySequence, MINUS_SIGN, NumberField, OptionsBar, Plot2D, PointPlotter, Powerline, Radio, RadioGroup, RangeSlider, Select, SelectItem, Sidebar, SidebarPanel, Slider, Switch, Tab, TabList, TabPanel, Tabs, ToggleBar, ToolButton, ToolGroup, ToolPalette, chromaAt, detectPlatform, dlog, fieldClasses, formatNumber, formatShortcut, formatShortcutParts, inferKeycapKind, isDebugEnabled, keyGlyph, keySpecFromKey, keySpecsFromMods, oklchToHex, paintGradientTrack, useReorderDragList, useRovingTabIndex };