@weasel-js/labkit 0.1.0 → 0.7.1

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, PointerEvent as PointerEvent$1, KeyboardEvent as KeyboardEvent$1, RefCallback } from 'react';
-import { b as NodeId, O as Op, V as View, B as Bounds, D as DrawCommand } from '../_dts/fitViewToBounds-rWrBI4a6.js';
+import { ReactNode, CSSProperties, ButtonHTMLAttributes, ReactElement, MutableRefObject, PointerEvent as PointerEvent$1, KeyboardEvent, RefCallback } from 'react';
+import { O as Op, V as View, D as DrawCommand, b as NodeId, c as Path, S as Scene, H as History, d as PoseComposition, B as Bounds } from '../_dts/DrawCommand-CEvS5AdV.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';
 
 /**
@@ -1031,6 +1031,23 @@ type ToggleBarProps<V extends string | number = string> = (CommonProps & {
     mode: 'multiple';
     items: readonly ToggleBarItem<V>[];
     value: readonly V[];
+    /**
+     * Values that are neither on nor off — the sources this bar
+     * aggregates disagree (a text range that is bold in part of it, a
+     * multi-selection whose nodes differ). Rendered `aria-pressed="mixed"`,
+     * the ARIA tri-state a toggle button actually has, rather than
+     * `SelectionPanel`'s reduced-opacity-plus-`title` workaround for
+     * `Switch`, which has no indeterminate state to render.
+     *
+     * `value` wins where the two lists overlap, so a caller that can't
+     * cheaply keep them disjoint doesn't get an ambiguous segment.
+     *
+     * Clicking a mixed segment turns it fully **on**, matching the
+     * everywhere-else convention (and `toggleFlagInRange`'s rule for a
+     * partially-styled text range) that a mixed toggle resolves toward
+     * the affirmative rather than clearing.
+     */
+    mixedValues?: readonly V[];
     onChange: (next: V[]) => void;
 });
 declare function ToggleBar<V extends string | number = string>(props: ToggleBarProps<V>): ReactElement;
@@ -1107,422 +1124,189 @@ interface PowerlineProps {
 }
 declare function Powerline({ segments, startCap, size, variant, depth, gap, className, ...rest }: PowerlineProps): react_jsx_runtime.JSX.Element;
 
-/** API returned by {@link useSelection}. */
-interface SelectionApi {
-    /** Current selection. Re-renders trigger when this reference changes. */
-    current: readonly NodeId[];
-    /** Imperative read for use inside event callbacks (avoids stale closures). */
-    get(): NodeId[];
-    /** Replace selection. */
-    set(ids: NodeId[]): void;
-    /** Add id (multi-mode appends; single-mode replaces). */
-    add(id: NodeId): void;
-    /** Remove id from selection. */
-    remove(id: NodeId): void;
-    /** Toggle id in/out of selection. */
-    toggle(id: NodeId): void;
-    /** Clear selection. */
-    clear(): void;
-    /** True if id is selected. */
-    contains(id: NodeId): boolean;
-    /**
-     * Apply a click to the selection per the configured mode/extend key.
-     * - `single`: replaces selection with `[id]`, regardless of modifiers.
-     * - `multi`: with the extend key held, toggles `id` in/out of the selection;
-     *   otherwise replaces with `[id]`.
-     */
-    applyClick(id: NodeId, modifiers: {
-        shift: boolean;
-        meta: boolean;
-        ctrl: boolean;
-    }): void;
-    /** Pre-built methods for spreading into an adapter that needs them. */
-    adapterMethods: {
-        getSelection: () => NodeId[];
-        setSelection: (ids: NodeId[]) => void;
-    };
-}
-
-type HandleKind = 'corner' | 'rotation' | 'anchor';
-type HitShape = {
-    kind: 'rect';
+type ContainerBounds = {
     x: number;
     y: number;
     width: number;
     height: number;
-    rotation?: number;
-} | {
-    kind: 'circle';
-    cx: number;
-    cy: number;
-    r: number;
-} | {
-    kind: 'path';
-    d: Path2D;
 };
-interface DebugSink {
-    recordHitbox(id: string, kind: 'body' | 'handle' | 'rotation' | 'anchor', shape: HitShape): void;
-    recordHandle(id: string, position: {
+interface LayoutChild<TPose> {
+    id: string;
+    pose: TPose;
+}
+interface DropTarget<TPose> {
+    /** Where the dragged child lands if this target is picked. */
+    pose: TPose;
+    /** Reference point for distance metrics (snap algorithms). */
+    origin: {
         x: number;
         y: number;
-    }, kind: HandleKind): void;
-    recordBounds(id: string, bounds: {
+    };
+    /** Optional axis-aligned region (world units) used by region-aware snaps
+     *  (e.g. `containedThenNearest`). When present, a pointer inside this rect
+     *  is treated as a containment hit on this target. Strategies that emit
+     *  region-shaped targets (gutters, drop-zones) should populate this.
+     *  Strategies whose targets are point-like (free-form, snap-point) can omit
+     *  it and rely on `origin`-distance snaps. */
+    hitBounds?: {
         x: number;
         y: number;
         width: number;
         height: number;
-    }): void;
-    recordOrigin(id: string, point: {
+    };
+    /** Strategy-private metadata (e.g. cell coords for tile-grid). */
+    meta?: unknown;
+}
+interface LayoutSnap<TPose> {
+    pickTarget(targets: DropTarget<TPose>[], pointer: {
         x: number;
         y: number;
-    }): void;
-    recordSnapCandidate(point: {
+    }): DropTarget<TPose> | null;
+}
+interface LayoutContainer {
+    id: string;
+    bounds: ContainerBounds;
+}
+interface LayoutDragged<TPose> {
+    id: string;
+    /** The pose the dragged child currently has (pre-drop). */
+    originPose: TPose;
+    /** The pose the gesture proposes (pointer-driven, pre-snap). */
+    pose: TPose;
+    sourceContainerId: string | null;
+}
+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>[];
+    reflowPoses(container: LayoutContainer, children: ReadonlyArray<LayoutChild<TPose>>, dragged: LayoutDragged<TPose>, target: DropTarget<TPose> | null): Map<string, TPose>;
+    commitDrop(container: LayoutContainer, children: ReadonlyArray<LayoutChild<TPose>>, dragged: LayoutDragged<TPose>, target: DropTarget<TPose> | null): Op[];
+    snap: LayoutSnap<TPose>;
+    /** Optional: predicate for whether a world-space point is inside this
+     *  container. When absent, callers fall back to an axis-aligned bounding-box
+     *  test on the container's pose. Strategies whose containers aren't
+     *  rectangular (circles, irregular zones) implement this to override the
+     *  AABB default. */
+    contains?(containerPose: TPose, point: {
         x: number;
         y: number;
-    }, accepted: boolean): void;
-    recordLayer(id: string, label: string, space: 'world' | 'screen', index: number): void;
-    /** Clears every non-snap array. Called at the start of each Canvas render. */
-    beginFrame(): void;
-    /** Clears the snap array. Called at gesture end. */
-    clearSnap(): void;
+    }): boolean;
 }
 
 /**
- * Declarative gesture taxonomy. Single source of truth for:
- *   - which gestures hit-test (have a `.target` slot in the route string)
- *   - which gestures carry an argument and what values are legal
- *   - the default arg value (used when none is specified in a route)
+ * Opaque clipboard payload. `items` is `unknown[]` so each app's clipboard
+ * adapter stores whatever shape it wants; the kit never inspects entries.
  *
- * Reflection, matcher, and inspector UI all read this table. Adding a new
- * gesture name in one place updates every consumer.
+ * The adapter is responsible for both producing snapshots
+ * (`snapshotSelection`) and consuming them (`commitPaste`). Type safety lives
+ * at that boundary, not in the kit.
  */
-type GestureName = 'click' | 'pointerDown' | 'dblTap' | 'drag' | 'wheel' | 'keyDown' | 'keyUp' | 'keyHeld' | 'contextMenu' | 'multiTouchTap';
-
-/** All valid keys for a modifier sub-table in a route entry. Canonical
- *  order: mod → shift → alt (matches formatShortcut). */
-type ModifierCombo = 'default' | 'mod' | 'shift' | 'alt' | 'mod+shift' | 'mod+alt' | 'shift+alt' | 'mod+shift+alt';
-
-/** Phase of a gesture lifecycle. `initial` means the tool is idle
- *  (scratch null); `engaged` means a gesture is in progress (scratch
- *  populated). The route-grammar's `[phase]` slot draws from this set. */
-type RoutePhase$1 = 'initial' | 'engaged';
-
+interface ClipboardSnapshot {
+    items: unknown[];
+}
 /**
- * Route-string grammar v3:
- *
- *   route       = phaseSlot WS gesture WS argSlot? WS targetSlot? WS modSlot?
- *   phaseSlot   = '[' phaseList ']'
- *   phaseList   = phaseAtom (WS ',' WS phaseAtom)*
- *   phaseAtom   = (channel ':')? phaseValue            -- bare phaseValue ≡ '&:phaseValue'
- *   channel     = '&' | '*' | toolId                   -- '&' = the binding's own tool
- *   phaseValue  = 'initial' | 'engaged' | '*'
- *   argSlot     = '(' argValue ')'                     -- whitespace inside parens is significant
- *   targetSlot  = '=>' WS targetValue                  -- omitted slot defaults to '*' for hasTarget
- *   modSlot     = modAtom (WS modAtom)*
- *   modAtom     = sigil modName
- *   sigil       = '+' | '?'                            -- ! @ # $ % ^ & * reserved as id-prefix
- *   modName     = 'mod' | 'shift' | 'alt' | 'ctrl' | 'meta'
- *
- * Shorthand: a bare phaseValue (no `:`) implies channel `&` ("this tool's
- * own phase"). `[engaged]` ≡ `[&:engaged]`; `[*]` ≡ `[&:*]`. The truly-loose
- * form (any channel, any phase) is `[*:*]`.
+ * SnapTarget — where a dragged node would re-parent to if released.
  *
- * Examples:
- *   [initial] click => empty +shift            -- self idle
- *   [engaged] wheel                            -- self mid-gesture
- *   [rect:engaged] wheel                        -- when rect tool is mid-gesture
- *   [*:engaged] keyDown(Delete)                -- when any tool is mid-gesture
- *   [initial,engaged] contextMenu => empty     -- either self phase
- *   [*] click => empty                         -- self, any phase
+ * `slotPose` is the pose (in world coordinates) the node should snap to
+ * within the target. `metadata` is an opaque pass-through for app-specific
+ * snap details (slot index, visual hint, etc.).
  */
-
-/** Channel reference for a phase atom. `'&'` = the binding's own tool;
- *  `'*'` = any tool; otherwise a registered tool id. */
-type ChannelRef = '&' | '*' | string;
-/** One element of a phase list: a (channel, phase) pair. The default
- *  channel (omitted in the shorthand) is `'&'`. `phase: '*'` means
- *  "any phase of the given channel". */
-interface PhaseAtom {
-    channel: ChannelRef;
-    phase: RoutePhase$1 | '*';
+interface SnapTarget<TPose = unknown> {
+    parentId: string;
+    slotPose: TPose;
+    metadata?: unknown;
 }
-
 /**
- * GestureSpec — describes the form of a user input event that can fire an action.
- *
- * Used by `Action.defaultBinding` (the action's preferred gesture) and by
- * `GestureBinding.spec` (a tool's binding table entry). The dispatcher matches
- * incoming input events against registered specs to determine which action to
- * invoke.
- *
- * See `docs/superpowers/specs/2026-05-16-registry-unification-design.md` § "Types".
+ * Narrow adapter for `useMove`. Includes optional snap-target
+ * lookup; apps without container-snapping leave it out.
  */
-/** Optional modifier-key requirement for a gesture spec.
- *
- *  Matching semantics (strict): an omitted modifier field means the
- *  modifier MUST NOT be held — i.e., a bare `{ kind: 'key', key: 'Escape' }`
- *  matches only unmodified Escape, NOT Cmd+Escape. A `true` means the
- *  modifier MUST be held; `false` is the same as omitted (must be absent).
- *  This mirrors today's `KeyBinding` matcher and keeps conflict detection
- *  coherent.
+interface MoveAdapter<TNode extends {
+    id: string;
+}, TPose> {
+    getNode(id: string): TNode | undefined;
+    /** Enumerate all nodes. `<Canvas>` derives a default rect-pose `pickEvery`
+     *  and the scene-iteration loop from this. */
+    getNodes(): TNode[];
+    getPose(id: string): TPose;
+    /** Optional. Required only by hierarchy-aware paths: layout-pass drop
+     *  targeting (`getLayout` present), nested-hit collapse
+     *  (`pickTopMostHit`), and group-pose composition. Flat scenes may omit. */
+    getParent?(id: string): string | null;
+    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. */
+    setParent?(id: string, parentId: string | null): void;
+    /** Optional: see SceneAdapter.applyOps. */
+    applyOps?(ops: Op[], label: string): void;
+    findSnapTarget?(draggedId: string, worldX: number, worldY: number): SnapTarget<TPose> | null;
+    /** Optional: direct children of `id`. When present (alongside the
+     *  `cascadeWorldPose` option on `useMove`), dragging a node
+     *  auto-cascades its descendants in the live overlay so structurally-
+     *  grouped children visually follow the parent during the drag. No
+     *  additional ops are generated — children's local poses don't change
+     *  when the parent's local pose moves. */
+    getChildren?(id: string): string[];
+    /** Optional: layout strategy attached to a container, or null if the
+     *  container uses absolute positioning (default behavior). When present,
+     *  `useMove` uses the strategy to compute drop targets, sibling reflow,
+     *  and the commit op batch when a drag ends over the container. */
+    getLayout?(containerId: string): LayoutStrategy<TPose> | null;
+}
+/**
+ * Narrow adapter for `useInsert` and `useClipboardOps`. The kit knows
+ * nothing about what tool is active or what shape to construct; it asks the
+ * adapter to produce node(s) given gesture or paste inputs.
  *
- *  `mod` is a platform-aware shorthand: matches `metaKey` on mac, `ctrlKey`
- *  elsewhere (mirrors `KeyBinding.mod`).
+ * Drag-rectangle path: `commitInsert(bounds)` returns one new node or null.
+ * Clipboard paste path: `commitPaste(clipboard, offset)` returns the array of
+ *   newly-materialized nodes (in order). Both empty array and array of
+ *   length N are valid; the kit wraps each entry in an `InsertOp`.
  *
- *  `shift` additionally accepts `'optional'` meaning "shifted or unshifted
- *  both acceptable" — the explicit opt-in for loose matching, used by
- *  actions like nudge whose step size depends on shift but whose firing
- *  does not. To widen other modifiers similarly, extend their type when
- *  a real consumer needs it.
+ * `snapshotSelection(ids)` builds the payload that paste later consumes.
+ * `getPasteOffset` is optional; the kit defaults to a fixed grid-cell offset
+ * supplied by the consumer (passed to `useClipboardOps` options if needed; see
+ * the hook for resolution order).
  */
-type ModSpec = Partial<{
-    alt: boolean | 'optional';
-    ctrl: boolean | 'optional';
-    meta: boolean | 'optional';
-    mod: boolean | 'optional';
-    shift: boolean | 'optional';
-}>;
-/** Target selector for click and drag gesture specs. String forms are sugar
- *  for the kit-owned object-kind registry (TODO.md Tier 1 follow-up); until
- *  that ships, consumers can pass `{ kindOf: predicate }` to classify hits
- *  themselves. */
-type TargetSpec = 'empty' | 'selected-body' | 'unselected-body' | `kind:${string}` | `kind:${string}:selected` | `affordance:${string}` | {
-    /** Predicate. `hit` is the raw target (affordance for drag,
-     *  `e.target` otherwise); `bodyTarget` is the optional body-class
-     *  string ('empty' | 'selected-body' | 'unselected-body') when
-     *  `classifyTarget` is wired. Predicates that only need one of the
-     *  two can ignore the other. */
-    kindOf: (hit: unknown, bodyTarget?: string) => boolean;
-};
-/** Phase qualifier on a gesture spec. Restricts when the spec matches based
- *  on per-tool gesture-lifecycle state.
- *
- *  Shorthand forms (most common case — gate on the binding's own tool):
- *    `'engaged'` → `[{ channel: '&', phase: 'engaged' }]`  // self mid-gesture
- *    `'initial'` → `[{ channel: '&', phase: 'initial' }]`  // self idle
- *    `'*'`       → `[{ channel: '&', phase: '*' }]`        // either self phase
- *
- *  Array form for explicit channel:phase atoms — e.g. `[{ channel: 'rect',
- *  phase: 'engaged' }]` for "when the rect tool is mid-gesture, regardless of
- *  which scope I'm in." See the v3 route grammar in
- *  `@weasel-js/gestures/grammar` for the full lattice.
- *
- *  When omitted, matches in any phase (preserves pre-phase behavior). */
-type PhaseSpec = 'initial' | 'engaged' | '*' | readonly PhaseAtom[];
-/** Single-keystroke gesture (keydown). */
-interface KeySpec {
-    kind: 'key';
-    /** A single key, or an array of acceptable keys (case-insensitive match). */
-    key: string | string[];
-    mods?: ModSpec;
-    phase?: PhaseSpec;
-}
-/** Key-held gesture (keydown opens, keyup closes). Drives "hold space for
- *  hand tool"-style interactions. */
-interface KeyHeldSpec {
-    kind: 'key-held';
-    /** A single key, or an array of acceptable keys (case-insensitive match). */
-    key: string | string[];
-    mods?: ModSpec;
-    phase?: PhaseSpec;
-}
-/** Wheel-event gesture. `direction` filters by deltaY sign; default `'*'`.
- *  - `'up'`   → matches only deltaY < 0
- *  - `'down'` → matches only deltaY > 0
- *  - `'*'`    → matches either sign (default; universal-wildcard convention) */
-interface WheelSpec {
-    kind: 'wheel';
-    direction?: 'up' | 'down' | '*';
-    mods?: ModSpec;
-    phase?: PhaseSpec;
-}
-/** Click gesture (pointerdown + pointerup without movement past the
- *  threshold). */
-interface ClickSpec {
-    kind: 'click';
-    target?: TargetSpec;
-    mods?: ModSpec;
-    phase?: PhaseSpec;
-}
-/** Double-click: two `click` events within ~500ms and ~5px of each other.
- *  Synthesized by `useGestureDispatcher`; emitted AFTER the second
- *  `click`. Bindings that want to handle a double-click should declare
- *  this kind rather than chasing two `click` events. */
-interface DoubleClickSpec {
-    kind: 'doubleClick';
-    target?: TargetSpec;
-    mods?: ModSpec;
-    phase?: PhaseSpec;
-}
-/** Right-click (contextmenu) gesture. The dispatcher calls
- *  `preventDefault()` on the underlying DOM event so the native menu
- *  doesn't appear — tools/actions fully own the right-click UX. */
-interface ContextMenuSpec {
-    kind: 'contextMenu';
-    target?: TargetSpec;
-    mods?: ModSpec;
-    phase?: PhaseSpec;
-}
-/** Drag gesture (pointerdown + pointermove past the threshold). */
-interface DragSpec {
-    kind: 'drag';
-    target?: TargetSpec;
-    mods?: ModSpec;
-    phase?: PhaseSpec;
-}
-/** Multi-touch gesture. `fingers` is the required touch count. */
-interface MultiTouchSpec {
-    kind: 'multiTouch';
-    fingers: number;
-    mods?: ModSpec;
-    phase?: PhaseSpec;
-}
-/** Multi-touch tap gesture — fires when N fingers touch down then release
- *  together without movement past the tap threshold. Synthesized by the
- *  dispatcher from the underlying multitouch tracking. */
-interface MultiTouchTapSpec {
-    kind: 'multiTouchTap';
-    fingers: number;
-    mods?: ModSpec;
-    phase?: PhaseSpec;
-}
-/** OS drag-and-drop of external content onto the canvas. `types` filters by
- *  MIME glob (`'image/*'`, `'text/plain'`); the spec matches when ANY item's
- *  MIME matches ANY glob. Omitted or empty = matches any drop. */
-interface DropSpec {
-    kind: 'drop';
-    types?: string[];
-    mods?: ModSpec;
-    phase?: PhaseSpec;
-}
-/** System-clipboard paste of external content. Same `types` semantics as
- *  {@link DropSpec} — omitted or empty = matches any paste. */
-interface PasteSpec {
-    kind: 'paste';
-    types?: string[];
-    mods?: ModSpec;
-    phase?: PhaseSpec;
-}
-/** The full union of supported gesture spec kinds. New invocation forms
- *  (long-press, two-stage, modal-dialog) extend this union without touching
- *  the `Action` type. */
-type GestureSpec = KeySpec | KeyHeldSpec | WheelSpec | ClickSpec | DoubleClickSpec | ContextMenuSpec | DragSpec | MultiTouchSpec | MultiTouchTapSpec | DropSpec | PasteSpec;
-
-type ContainerBounds = {
-    x: number;
-    y: number;
-    width: number;
-    height: number;
-};
-interface LayoutChild<TPose> {
+interface InsertAdapter<TNode extends {
     id: string;
-    pose: TPose;
-}
-interface DropTarget<TPose> {
-    /** Where the dragged child lands if this target is picked. */
-    pose: TPose;
-    /** Reference point for distance metrics (snap algorithms). */
-    origin: {
-        x: number;
-        y: number;
-    };
-    /** Optional axis-aligned region (world units) used by region-aware snaps
-     *  (e.g. `containedThenNearest`). When present, a pointer inside this rect
-     *  is treated as a containment hit on this target. Strategies that emit
-     *  region-shaped targets (gutters, drop-zones) should populate this.
-     *  Strategies whose targets are point-like (free-form, snap-point) can omit
-     *  it and rely on `origin`-distance snaps. */
-    hitBounds?: {
+}> {
+    /** Materialize a new node from drag-rect bounds (drag-to-insert tools).
+     *  Optional — hooks that don't drive insertion (e.g. `useClone`,
+     *  read-only clipboard) won't call it, and `sceneToAdapter` only fills
+     *  it in when `options.commitInsert` is supplied. Hooks that *do* call
+     *  it (insert tools) document the requirement at their own surface. */
+    commitInsert?(bounds: {
         x: number;
         y: number;
         width: number;
         height: number;
+    }): TNode | null;
+    /** Materialize one or more new nodes from a clipboard snapshot. Optional
+     *  — required by `useClipboard.paste`, ignored by other consumers. */
+    commitPaste?(clipboard: ClipboardSnapshot, offset: {
+        dx: number;
+        dy: number;
+    }, ctx?: {
+        dropPoint?: {
+            worldX: number;
+            worldY: number;
+        };
+    }): TNode[];
+    /** Snapshot the current selection into the clipboard payload shape.
+     *  Optional — required by `useClipboard.copy` / `cut` and `useClone`'s
+     *  ghost capture, ignored by other consumers. */
+    snapshotSelection?(ids: string[]): ClipboardSnapshot;
+    getPasteOffset?(clipboard: ClipboardSnapshot): {
+        dx: number;
+        dy: number;
     };
-    /** Strategy-private metadata (e.g. cell coords for tile-grid). */
-    meta?: unknown;
-}
-interface LayoutSnap<TPose> {
-    pickTarget(targets: DropTarget<TPose>[], pointer: {
-        x: number;
-        y: number;
-    }): DropTarget<TPose> | null;
-}
-interface LayoutContainer {
-    id: string;
-    bounds: ContainerBounds;
-}
-interface LayoutDragged<TPose> {
-    id: string;
-    /** The pose the dragged child currently has (pre-drop). */
-    originPose: TPose;
-    /** The pose the gesture proposes (pointer-driven, pre-snap). */
-    pose: TPose;
-    sourceContainerId: string | null;
-}
-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>[];
-    reflowPoses(container: LayoutContainer, children: ReadonlyArray<LayoutChild<TPose>>, dragged: LayoutDragged<TPose>, target: DropTarget<TPose> | null): Map<string, TPose>;
-    commitDrop(container: LayoutContainer, children: ReadonlyArray<LayoutChild<TPose>>, dragged: LayoutDragged<TPose>, target: DropTarget<TPose> | null): Op[];
-    snap: LayoutSnap<TPose>;
-    /** Optional: predicate for whether a world-space point is inside this
-     *  container. When absent, callers fall back to an axis-aligned bounding-box
-     *  test on the container's pose. Strategies whose containers aren't
-     *  rectangular (circles, irregular zones) implement this to override the
-     *  AABB default. */
-    contains?(containerPose: TPose, point: {
-        x: number;
-        y: number;
-    }): boolean;
-}
-
-/**
- * SnapTarget — where a dragged node would re-parent to if released.
- *
- * `slotPose` is the pose (in world coordinates) the node should snap to
- * within the target. `metadata` is an opaque pass-through for app-specific
- * snap details (slot index, visual hint, etc.).
- */
-interface SnapTarget<TPose = unknown> {
-    parentId: string;
-    slotPose: TPose;
-    metadata?: unknown;
-}
-/**
- * Narrow adapter for `useMove`. Includes optional snap-target
- * lookup; apps without container-snapping leave it out.
- */
-interface MoveAdapter<TNode extends {
-    id: string;
-}, TPose> {
-    getNode(id: string): TNode | undefined;
-    /** Enumerate all nodes. `<Canvas>` derives a default rect-pose `pickEvery`
-     *  and the scene-iteration loop from this. */
-    getNodes(): TNode[];
-    getPose(id: string): TPose;
-    /** Optional. Required only by hierarchy-aware paths: layout-pass drop
-     *  targeting (`getLayout` present), nested-hit collapse
-     *  (`pickTopMostHit`), and group-pose composition. Flat scenes may omit. */
-    getParent?(id: string): string | null;
-    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. */
-    setParent?(id: string, parentId: string | null): void;
+    /** Mutator wired by `insertNode`-using ops (kit-side InsertOp). */
+    insertNode(node: TNode): void;
+    /** Mutator wired by `setSelection` ops batched alongside paste. */
+    setSelection(ids: string[]): void;
     /** Optional: see SceneAdapter.applyOps. */
     applyOps?(ops: Op[], label: string): void;
-    findSnapTarget?(draggedId: string, worldX: number, worldY: number): SnapTarget<TPose> | null;
-    /** Optional: direct children of `id`. When present (alongside the
-     *  `cascadeWorldPose` option on `useMove`), dragging a node
-     *  auto-cascades its descendants in the live overlay so structurally-
-     *  grouped children visually follow the parent during the drag. No
-     *  additional ops are generated — children's local poses don't change
-     *  when the parent's local pose moves. */
-    getChildren?(id: string): string[];
-    /** Optional: layout strategy attached to a container, or null if the
-     *  container uses absolute positioning (default behavior). When present,
-     *  `useMove` uses the strategy to compute drop targets, sibling reflow,
-     *  and the commit op batch when a drag ends over the container. */
-    getLayout?(containerId: string): LayoutStrategy<TPose> | null;
+    /** Returns the current selection. Used by clone behaviors. */
+    getSelection(): string[];
 }
 
 /** Snapshot of modifier-key state at gesture dispatch. */
@@ -1581,25 +1365,1836 @@ interface ActionBehavior<TPose, TProposed, TMoveResult> {
     onMove?(ctx: GestureContext<TPose>, proposed: TProposed): TMoveResult | void;
     onEnd?(ctx: GestureContext<TPose>): Op[] | null | void;
 }
+/** Which corner/edge of the rect stays fixed during a resize. */
+type ResizeAnchor = {
+    x: 'min' | 'max' | 'free';
+    y: 'min' | 'max' | 'free';
+};
+/** Minimum rect-shaped pose required by the resize machinery. */
+interface ResizePose {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/** Per-frame proposed resize: pose plus the anchor pinning the opposite corner. */
+interface ResizeProposed<TPose extends ResizePose> {
+    pose: TPose;
+    anchor: ResizeAnchor;
+}
+/** Per-frame result a `BoundsConstraint.onMove` can return to override the proposed pose. */
+interface ResizeMoveResult<TPose extends ResizePose> {
+    pose?: TPose;
+}
+/** A bounds-frame constraint plugged into `useResize` / `resizeAction`.
+ *  Reads/writes `{x,y,width,height}` and can override the proposed pose
+ *  on each frame (e.g. lock-aspect, clamp-min-size, snap-to-grid). */
+type BoundsConstraint<TPose extends ResizePose> = ActionBehavior<TPose, ResizeProposed<TPose>, ResizeMoveResult<TPose>>;
+/** Frames a point-snap behavior can return for the hook to back-solve. */
+type PointSnapFrame = 'dragged-corner' | 'fixed-corner' | 'center' | 'origin';
+/** Per-frame world-space context handed to `PointSnapBehavior.onMove`.
+ *  `draggedCorner` and `fixedCorner` are `null` for edge drags
+ *  (`anchor.x === 'free'` or `anchor.y === 'free'`). `center` and
+ *  `origin` are always present. */
+interface PointSnapContext<TPose extends ResizePose> {
+    draggedCorner: {
+        worldX: number;
+        worldY: number;
+    } | null;
+    fixedCorner: {
+        worldX: number;
+        worldY: number;
+    } | null;
+    center: {
+        worldX: number;
+        worldY: number;
+    };
+    origin: {
+        worldX: number;
+        worldY: number;
+    };
+    rotation: number;
+    anchor: ResizeAnchor;
+    proposed: TPose;
+    modifiers: ModifierState;
+}
+/** Per-frame snap result. A behavior returns at most one. */
+interface PointSnapResult {
+    frame: PointSnapFrame;
+    worldX: number;
+    worldY: number;
+}
+/** A point-snap behavior plugged into `useResize`'s `pointSnapBehaviors`. */
+interface PointSnapBehavior<TPose extends ResizePose> {
+    id?: string;
+    onMove(ctx: PointSnapContext<TPose>): PointSnapResult | null | undefined;
+}
 
-/** Per-invocation options the dispatcher reads from a `GestureBinding`'s
- *  `opts` field and passes to `OngoingInvoker.start`. Today carries
- *  behaviors; extensible. */
-interface BindingOpts {
-    behaviors?: ActionBehavior<unknown, unknown, unknown>[];
-    /** Per-binding action parameters. The action's invoker reads
-     *  these via the second arg to `run` (or via InvocationCtx for ongoing
-     *  invokers, when needed). Loose typing (Record<string, unknown>) for
-     *  now; consider per-action typing later via BindingOpts<A>.
+/**
+ * @experimental
+ * Result of an affordance hit — what the region computed about itself.
+ *
+ * `initialScratch` is the payload: what the region already knows (which
+ * corner, which target id) so the action that picks up the drag doesn't
+ * re-derive it. `<SceneCanvas>` reads it out of the layer hit-test and packs
+ * it into `AffordanceHit`, which flows to the matching action through
+ * `InvocationCtx.drag.affordance`.
+ *
+ * This used to also carry a `drag: DragChannel` naming the handlers the
+ * tool-routing dispatcher should wire up. Every implementation supplied a
+ * no-op stub that claimed, because the real routing had already moved to
+ * bindings; the field went with that dispatcher.
+ */
+interface AffordanceBinding<TScratch = unknown> {
+    initialScratch?: TScratch;
+}
+
+/**
+ * Canvas size in CSS pixels — passed to `draw` for layers that anchor to
+ * canvas edges (e.g. the debug overlay's layer-list panel). The GL backend
+ * supplies it explicitly so layers don't have to know about DPR.
+ */
+interface Dims {
+    width: number;
+    height: number;
+}
+/**
+ * A single named render sub-layer within a canvas renderer.
+ *
+ * @template TData - The data object passed to each draw call.
+ */
+interface RenderLayer<TData> {
+    /** Unique identifier used in visibility maps and ordering arrays. */
+    id: string;
+    /** Human-readable name for UI toggles. */
+    label: string;
+    /**
+     * Emit a DrawCommand tree for the GL backend to dispatch.
+     *
+     * For world-space layers (the default), emit commands in WORLD COORDS —
+     * `drawLayers` automatically wraps them in `{ kind: 'group', transform:
+     * viewToMat3(view), ... }` before handing them to the renderer. Do NOT
+     * apply the view transform yourself.
+     *
+     * For screen-space layers (`space: 'screen'`), emit commands in CSS-pixel
+     * coords directly; `drawLayers` passes them through unchanged. If part
+     * of a screen-space layer's output needs to track the view, wrap that
+     * subset manually with `viewToMat3(view)`.
+     */
+    draw: (data: TData, view: View, dims: Dims) => DrawCommand[];
+    /**
+     * Whether the layer is shown when no explicit visibility entry exists.
+     * Defaults to `true` when absent.
+     */
+    defaultVisible?: boolean;
+    /**
+     * When true, the layer is always drawn regardless of the visibility map.
+     * Useful for layers that must never be hidden (e.g. base grid).
+     */
+    alwaysOn?: boolean;
+    /**
+     * Coordinate space the layer draws in.
+     *
+     * - `'world'` (default): the layer's `draw` returns world-space commands;
+     *   `drawLayers` wraps them in a `kind: 'group'` with `viewToMat3(view)`
+     *   automatically.
+     * - `'screen'`: the layer's `draw` returns screen-space (CSS-pixel)
+     *   commands; `drawLayers` passes them through unchanged. World-anchored
+     *   chrome inside a screen-space layer must call `worldToScreen` or wrap
+     *   the relevant subset with `viewToMat3(view)` manually.
+     */
+    space?: 'world' | 'screen';
+    /**
+     * Optional hit-test for **consumer-attached** layers.
+     *
+     * Only layers registered through `CanvasExtensionApi.registerLayer` are
+     * hit-tested: `hitTestExtras` walks them last-registered-first on
+     * pointerdown, and `<SceneCanvas>` folds the result into its `affordanceAt`
+     * thunk ahead of the kit's own selection chrome. First non-null result
+     * wins; null means "I don't claim this hit, try the next layer."
+     *
+     * Layers that reach the draw stack some other way — a `Tool.overlay`, an
+     * entry in the `layers` map — are painted but never hit-tested, so defining
+     * `hitTest` on one has no effect. (The kit's own chrome doesn't need it: it
+     * goes through `buildAffordanceAt`.)
+     *
+     * Coordinates are world-space. The `data` arg is the layer's
+     * configured data slot (same as `draw`); `view` and `dims` mirror
+     * `draw`'s arguments.
+     */
+    hitTest?: (worldX: number, worldY: number, data: TData, view: View, dims: Dims, 
+    /** Chrome-caps visibility predicate. When supplied, the layer must
+     *  not return a hit from any chrome element whose id reports
+     *  `false`. Absent → every element is hittable. */
+    isVisible?: (id: string) => boolean) => AffordanceBinding | null;
+    /**
+     * Called on every pointermove when no gesture is currently captured.
+     * Lets layers (e.g. HUD widgets) track hover state without participating
+     * in the drag pipeline. Coords are world-space; the layer is responsible
+     * for any further conversion (e.g. world→screen for screen-space layers)
+     * and for its own throttling.
+     */
+    onUncapturedMove?: (worldX: number, worldY: number, evt: PointerEvent, view: View, dims: Dims) => void;
+    /**
+     * Called when the cursor leaves the canvas element. Lets layers clear
+     * any hover state they're holding.
+     */
+    onUncapturedLeave?: () => void;
+}
+
+/** The full vocabulary of capability tags shipped in the default preset.
+ *  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"];
+type CapabilityTag = (typeof ALL_TAGS)[number] | (string & {});
+
+interface WorkspaceVisual {
+    tint?: string;
+    gradient?: 'top-down' | 'bottom-up';
+    intensity?: number;
+}
+interface ModeDefinition {
+    id: string;
+    kind: 'soft' | 'strict';
+    /** Capability tags this mode allows beyond IMPLICIT_TAGS. */
+    allows: CapabilityTag[];
+    /** When true, out-of-target objects dim at the renderer layer. */
+    scoping: boolean;
+    workspace?: WorkspaceVisual;
+    entry?: {
+        shortcut?: string;
+        trigger?: 'double-click-target';
+    };
+    exit?: {
+        shortcut?: string;
+    };
+    commit?: {
+        shortcut?: string;
+    };
+    cancel?: {
+        shortcut?: string;
+    };
+}
+
+interface ModeRegistry {
+    current(): ModeDefinition;
+    setMode(id: string): void;
+    byId(id: string): ModeDefinition;
+    getVersion(): number;
+    subscribe(listener: () => void): () => void;
+}
+
+/**
+ * Live state read by rule evaluation. Built once per frame on the consuming
+ * surface — chrome-caps, the affordance pipeline, the dispatcher's
+ * eligibility filter — and discarded.
+ *
+ * Adding a new field is additive: existing rules don't change, new
+ * selector atoms can read it.
+ */
+interface RuleCtx {
+    readonly focused: boolean;
+    readonly selection: readonly NodeId[];
+    readonly multiActive: boolean;
+    readonly modifiers: ModifierState;
+    readonly action: {
+        readonly kind: string | null;
+        readonly id: string | null;
+    };
+    readonly hover: NodeId | null;
+    readonly view: View;
+    /** Active mode id. `'normal'` when no non-default mode is engaged. */
+    readonly mode: string;
+    /** Capability tags allowed by the active mode (the union of
+     *  `ModeDefinition.allows` plus implicit tags). The `capability:`
+     *  selector reads this to determine whether a tag is permitted. */
+    readonly allowedCapabilities: ReadonlySet<CapabilityTag>;
+    /** Whether the current selection may be resized. `<SceneCanvas>` folds
+     *  `selectTool.resize.resizable` over the selection (true only when every
+     *  selected node is resizable). Read by the `resizable:` selector to gate
+     *  `selection.resize-handles`. Absent (legacy ctx builders) is treated as
+     *  resizable — back-compat: handles show unless a consumer opts a node out. */
+    readonly selectionResizable?: boolean;
+    /** Whether a path is currently in anchor-edit mode. Read by the
+     *  `editingAnchors:` selector, which gates the path-edit chrome.
+     *
+     *  This is deliberately a fact about state, not about permission: the
+     *  anchor overlay and the anchor hit-test must agree, and the thing they
+     *  must agree on is "is there an edited path right now", which no
+     *  capability or mode id answers. A mode that allows `edits-anchors`
+     *  with nothing being edited should draw no anchors. Absent is treated
+     *  as false. */
+    readonly editingAnchors?: boolean;
+}
+
+/**
+ * A selector is a conjunction of key/value tests. Multiple keys at the same
+ * level AND together. Each key maps to a selector primitive in the evaluator.
+ */
+interface Selector {
+    selection?: {
+        is?: number;
+        atLeast?: number;
+        empty?: boolean;
+    };
+    mode?: string | {
+        not: string;
+    } | {
+        in: readonly string[];
+    };
+    capability?: CapabilityTag | readonly CapabilityTag[] | {
+        in: readonly CapabilityTag[];
+    } | {
+        not: CapabilityTag;
+    };
+    gesturing?: boolean;
+    actionIs?: string;
+    modifierHeld?: keyof ModifierState;
+    focused?: boolean;
+    hovering?: boolean;
+    hoveringSelected?: boolean;
+    zoomAtLeast?: number;
+    /** Matches `ctx.editingAnchors` — true while a path is in anchor-edit
+     *  mode. Absent flag is treated as `false`. */
+    editingAnchors?: boolean;
+    /** Matches `ctx.selectionResizable`. Absent flag is treated as `true`
+     *  (resizable), so `{ resizable: true }` passes for legacy ctx builders
+     *  that don't compute it. */
+    resizable?: boolean;
+}
+/**
+ * Composable visibility/eligibility rule. Trees of `all`/`any`/`not` nodes
+ * over `Selector` leaves. `when` is the escape hatch — its closure is
+ * opaque to introspection and should be avoided when a declarative form
+ * exists. Empty `all` is true; empty `any` is false.
+ */
+type Rule = Selector | {
+    all: readonly Rule[];
+} | {
+    any: readonly Rule[];
+} | {
+    not: Rule;
+} | {
+    when: (ctx: RuleCtx) => boolean;
+};
+
+/**
+ * Composable visibility predicate with fluent surface. Carries its underlying
+ * `Rule` tree at `.rule` so the resolver can introspect / share trees with
+ * the affordance pipeline and the dispatcher's eligibility filter.
+ *
+ * Callable form `cond(ctx)` evaluates the tree against ctx. The fluent
+ * methods return new Conditions wrapping new trees.
+ *
+ * **Chain semantics: strict left-to-right, no precedence.**
+ * `a.and(b).or(c)` is `(a && b) || c`; `a.or(b).and(c)` is
+ * `(a || b) && c`. Mix `.and` and `.or` only when you mean
+ * left-to-right evaluation. For grouped disjunction, name the
+ * subexpression or use the top-level `or(...)`.
+ */
+interface Condition {
+    (ctx: RuleCtx): boolean;
+    readonly rule: Rule;
+    /** `this && other` */
+    and(other: Condition | Rule): Condition;
+    /** `this || other` */
+    or(other: Condition | Rule): Condition;
+    /** `this && !other` */
+    andNot(other: Condition | Rule): Condition;
+    /** `this || !other` */
+    orNot(other: Condition | Rule): Condition;
+}
+
+/** Phase of a gesture lifecycle. `initial` means the tool is idle
+ *  (scratch null); `engaged` means a gesture is in progress (scratch
+ *  populated). The route-grammar's `[phase]` slot draws from this set. */
+type RoutePhase = 'initial' | 'engaged';
+
+/**
+ * Route-string grammar v3:
+ *
+ *   route       = phaseSlot WS gesture WS argSlot? WS targetSlot? WS modSlot?
+ *   phaseSlot   = '[' phaseList ']'
+ *   phaseList   = phaseAtom (WS ',' WS phaseAtom)*
+ *   phaseAtom   = (channel ':')? phaseValue            -- bare phaseValue ≡ '&:phaseValue'
+ *   channel     = '&' | '*' | toolId                   -- '&' = the binding's own tool
+ *   phaseValue  = 'initial' | 'engaged' | '*'
+ *   argSlot     = '(' argValue ')'                     -- whitespace inside parens is significant
+ *   targetSlot  = '=>' WS targetValue                  -- omitted slot defaults to '*' for hasTarget
+ *   modSlot     = modAtom (WS modAtom)*
+ *   modAtom     = sigil modName
+ *   sigil       = '+' | '?'                            -- ! @ # $ % ^ & * reserved as id-prefix
+ *   modName     = 'mod' | 'shift' | 'alt' | 'ctrl' | 'meta'
+ *
+ * Shorthand: a bare phaseValue (no `:`) implies channel `&` ("this tool's
+ * own phase"). `[engaged]` ≡ `[&:engaged]`; `[*]` ≡ `[&:*]`. The truly-loose
+ * form (any channel, any phase) is `[*:*]`.
+ *
+ * Examples:
+ *   [initial] click => empty +shift            -- self idle
+ *   [engaged] wheel                            -- self mid-gesture
+ *   [rect:engaged] wheel                        -- when rect tool is mid-gesture
+ *   [*:engaged] keyDown(Delete)                -- when any tool is mid-gesture
+ *   [initial,engaged] contextMenu => empty     -- either self phase
+ *   [*] click => empty                         -- self, any phase
+ */
+
+/** Channel reference for a phase atom. `'&'` = the binding's own tool;
+ *  `'*'` = any tool; otherwise a registered tool id. */
+type ChannelRef = '&' | '*' | string;
+/** One element of a phase list: a (channel, phase) pair. The default
+ *  channel (omitted in the shorthand) is `'&'`. `phase: '*'` means
+ *  "any phase of the given channel". */
+interface PhaseAtom {
+    channel: ChannelRef;
+    phase: RoutePhase | '*';
+}
+
+/**
+ * GestureSpec — describes the form of a user input event that can fire an action.
+ *
+ * Used by `Action.defaultBinding` (the action's preferred gesture) and by
+ * `GestureBinding.spec` (a tool's binding table entry). The dispatcher matches
+ * incoming input events against registered specs to determine which action to
+ * invoke.
+ *
+ * See `docs/superpowers/specs/2026-05-16-registry-unification-design.md` § "Types".
+ */
+/** Optional modifier-key requirement for a gesture spec.
+ *
+ *  Matching semantics (strict): an omitted modifier field means the
+ *  modifier MUST NOT be held — i.e., a bare `{ kind: 'key', key: 'Escape' }`
+ *  matches only unmodified Escape, NOT Cmd+Escape. A `true` means the
+ *  modifier MUST be held; `false` is the same as omitted (must be absent).
+ *  This mirrors today's `KeyBinding` matcher and keeps conflict detection
+ *  coherent.
+ *
+ *  `mod` is a platform-aware shorthand: matches `metaKey` on mac, `ctrlKey`
+ *  elsewhere (mirrors `KeyBinding.mod`).
+ *
+ *  `shift` additionally accepts `'optional'` meaning "shifted or unshifted
+ *  both acceptable" — the explicit opt-in for loose matching, used by
+ *  actions like nudge whose step size depends on shift but whose firing
+ *  does not. To widen other modifiers similarly, extend their type when
+ *  a real consumer needs it.
+ */
+type ModSpec = Partial<{
+    alt: boolean | 'optional';
+    ctrl: boolean | 'optional';
+    meta: boolean | 'optional';
+    mod: boolean | 'optional';
+    shift: boolean | 'optional';
+}>;
+/** Target selector for click and drag gesture specs. String forms are sugar
+ *  for the kit-owned object-kind registry (TODO.md Tier 1 follow-up); until
+ *  that ships, consumers can pass `{ kindOf: predicate }` to classify hits
+ *  themselves. */
+type TargetSpec = 'empty' | 'selected-body' | 'unselected-body' | `kind:${string}` | `kind:${string}:selected` | `affordance:${string}` | {
+    /** Predicate. `hit` is the raw target (affordance for drag,
+     *  `e.target` otherwise); `bodyTarget` is the optional body-class
+     *  string ('empty' | 'selected-body' | 'unselected-body') when
+     *  `classifyTarget` is wired. Predicates that only need one of the
+     *  two can ignore the other. */
+    kindOf: (hit: unknown, bodyTarget?: string) => boolean;
+};
+/** Phase qualifier on a gesture spec. Restricts when the spec matches based
+ *  on per-tool gesture-lifecycle state.
+ *
+ *  Shorthand forms (most common case — gate on the binding's own tool):
+ *    `'engaged'` → `[{ channel: '&', phase: 'engaged' }]`  // self mid-gesture
+ *    `'initial'` → `[{ channel: '&', phase: 'initial' }]`  // self idle
+ *    `'*'`       → `[{ channel: '&', phase: '*' }]`        // either self phase
+ *
+ *  Array form for explicit channel:phase atoms — e.g. `[{ channel: 'rect',
+ *  phase: 'engaged' }]` for "when the rect tool is mid-gesture, regardless of
+ *  which scope I'm in." See the v3 route grammar in
+ *  `@weasel-js/gestures/grammar` for the full lattice.
+ *
+ *  When omitted, matches in any phase (preserves pre-phase behavior). */
+type PhaseSpec = 'initial' | 'engaged' | '*' | readonly PhaseAtom[];
+/** Single-keystroke gesture (keydown). */
+interface KeySpec {
+    kind: 'key';
+    /** A single key, or an array of acceptable keys (case-insensitive match). */
+    key: string | string[];
+    mods?: ModSpec;
+    phase?: PhaseSpec;
+}
+/** Key-held gesture (keydown opens, keyup closes). Drives "hold space for
+ *  hand tool"-style interactions. */
+interface KeyHeldSpec {
+    kind: 'key-held';
+    /** A single key, or an array of acceptable keys (case-insensitive match). */
+    key: string | string[];
+    mods?: ModSpec;
+    phase?: PhaseSpec;
+}
+/** Wheel-event gesture. `direction` filters by deltaY sign; default `'*'`.
+ *  - `'up'`   → matches only deltaY < 0
+ *  - `'down'` → matches only deltaY > 0
+ *  - `'*'`    → matches either sign (default; universal-wildcard convention) */
+interface WheelSpec {
+    kind: 'wheel';
+    direction?: 'up' | 'down' | '*';
+    mods?: ModSpec;
+    phase?: PhaseSpec;
+}
+/** Click gesture (pointerdown + pointerup without movement past the
+ *  threshold). */
+interface ClickSpec {
+    kind: 'click';
+    target?: TargetSpec;
+    mods?: ModSpec;
+    phase?: PhaseSpec;
+}
+/** Double-click: two `click` events within ~500ms and ~5px of each other.
+ *  Synthesized by `useGestureDispatcher`; emitted AFTER the second
+ *  `click`. Bindings that want to handle a double-click should declare
+ *  this kind rather than chasing two `click` events. */
+interface DoubleClickSpec {
+    kind: 'doubleClick';
+    target?: TargetSpec;
+    mods?: ModSpec;
+    phase?: PhaseSpec;
+}
+/** Right-click (contextmenu) gesture. The dispatcher calls
+ *  `preventDefault()` on the underlying DOM event so the native menu
+ *  doesn't appear — tools/actions fully own the right-click UX. */
+interface ContextMenuSpec {
+    kind: 'contextMenu';
+    target?: TargetSpec;
+    mods?: ModSpec;
+    phase?: PhaseSpec;
+}
+/** Drag gesture (pointerdown + pointermove past the threshold). */
+interface DragSpec {
+    kind: 'drag';
+    target?: TargetSpec;
+    mods?: ModSpec;
+    phase?: PhaseSpec;
+}
+/**
+ * Bare pointer press, matched at down time — before the dispatcher knows
+ * whether the gesture will become a click or a drag.
+ *
+ * Reach for this only when the effect must be visible while the button is
+ * still held. Selection is the motivating case: pressing an unselected node
+ * highlights it immediately, and the drag that may follow then starts from an
+ * already-correct selection. Anything that can wait for the release belongs on
+ * a `click` spec, which does not fire on a press that turns into a drag.
+ *
+ * A matching binding does NOT own the gesture: the same press goes on to open
+ * a drag or synthesize a click as usual. Bind an immediate action here, not an
+ * ongoing one.
+ */
+interface PointerDownSpec {
+    kind: 'pointerDown';
+    target?: TargetSpec;
+    mods?: ModSpec;
+    phase?: PhaseSpec;
+}
+/** Multi-touch gesture. `fingers` is the required touch count. */
+interface MultiTouchSpec {
+    kind: 'multiTouch';
+    fingers: number;
+    mods?: ModSpec;
+    phase?: PhaseSpec;
+}
+/** Multi-touch tap gesture — fires when N fingers touch down then release
+ *  together without movement past the tap threshold. Synthesized by the
+ *  dispatcher from the underlying multitouch tracking. */
+interface MultiTouchTapSpec {
+    kind: 'multiTouchTap';
+    fingers: number;
+    mods?: ModSpec;
+    phase?: PhaseSpec;
+}
+/** OS drag-and-drop of external content onto the canvas. `types` filters by
+ *  MIME glob (`'image/*'`, `'text/plain'`); the spec matches when ANY item's
+ *  MIME matches ANY glob. Omitted or empty = matches any drop. */
+interface DropSpec {
+    kind: 'drop';
+    types?: string[];
+    mods?: ModSpec;
+    phase?: PhaseSpec;
+}
+/** System-clipboard paste of external content. Same `types` semantics as
+ *  {@link DropSpec} — omitted or empty = matches any paste. */
+interface PasteSpec {
+    kind: 'paste';
+    types?: string[];
+    mods?: ModSpec;
+    phase?: PhaseSpec;
+}
+/** The full union of supported gesture spec kinds. New invocation forms
+ *  (long-press, two-stage, modal-dialog) extend this union without touching
+ *  the `Action` type. */
+type GestureSpec = KeySpec | KeyHeldSpec | WheelSpec | ClickSpec | DoubleClickSpec | ContextMenuSpec | DragSpec | PointerDownSpec | MultiTouchSpec | MultiTouchTapSpec | DropSpec | PasteSpec;
+
+/** A 2D point in either world or screen coordinates. */
+interface Point2 {
+    x: number;
+    y: number;
+}
+/**
+ * Information about which UI affordance was hit at pointerdown.
+ *
+ * Populated by the dispatcher when the `affordanceAt` thunk is provided to
+ * `useGestureDispatcher`. Tools / action invokers that only fire on a specific
+ * affordance (e.g. a resize handle) use this field as a guard — if the
+ * affordance is absent or is the wrong kind, they return `{}` and let other
+ * bindings handle the drag.
+ *
+ * `kind` is a discriminator string:
+ *   - `'handle:top-left'` / `'handle:top-right'` / `'handle:bottom-left'` /
+ *     `'handle:bottom-right'` — corner resize handles.
+ *   - `'rotate-handle'` — the rotation affordance.
+ *   - `'anchor:N'` — a path anchor at index N.
+ *
+ * `fixedPoint` is the world-space point that should remain stationary during
+ * the gesture. For resize handles this is the opposite (diagonally fixed)
+ * corner; for rotate it is the pivot.
+ *
+ * `targetIds` are the node ids this affordance belongs to.
+ */
+interface AffordanceHit {
+    /** Discriminator string, e.g. `'handle:bottom-right'`. */
+    kind: string;
+    /** World-space fixed/pivot point. For resize: opposite corner. For rotate: pivot. */
+    fixedPoint?: {
+        x: number;
+        y: number;
+    };
+    /** Which nodes this affordance belongs to. */
+    targetIds?: string[];
+    /** Set when `kind` matches `'handle:*'`. Identifies which corner stays
+     *  fixed during a resize so consumers (resizeAction) don't re-parse `kind`.
+     *  Other affordance kinds (rotate-handle, anchor:N, controlIn:N, controlOut:N)
+     *  leave this undefined. */
+    anchor?: ResizeAnchor;
+    /** CSS cursor to show while the pointer hovers this affordance (no
+     *  gesture in flight). Consumed by the hover-cursor pump in
+     *  `useGestureDispatcher`; unset = the pump falls through to
+     *  action-cursor prediction, then to the active tool's cursor. */
+    cursor?: string;
+    /**
+     * Free-form payload from whatever produced the hit, carried through to the
+     * matching action untouched.
+     *
+     * Kit affordances describe themselves fully in the fields above and leave
+     * this unset. It exists for affordances the kit doesn't know the shape of —
+     * a registered layer's own chrome, where the hit-test already resolved
+     * *which* of its pieces was hit and the action would otherwise have to
+     * redo that work. `@weasel-js/hud` passes the hit widget here.
+     */
+    payload?: unknown;
+}
+/**
+ * One accumulated point on a drag trail: world-space position plus whatever
+ * stylus state the originating `PointerEvent` carried.
+ *
+ * The stylus fields are absent for mouse/touch on browsers that don't report
+ * them, and for synthetic events. Consumers that want pressure-driven output
+ * (e.g. `Stroke.vertexWidths` from a pencil stroke) read them off the samples
+ * their `insert` dep receives — see `apps/site/demos/VertexWidthsDemo.tsx`.
+ */
+interface DragSample extends Point2 {
+    /** 0..1. Mouse/touch report 0.5 while a button is held, per the spec. */
+    pressure?: number;
+    /** Degrees, ±90. Zero for mouse/touch. */
+    tiltX?: number;
+    /** Degrees, ±90. Zero for mouse/touch. */
+    tiltY?: number;
+}
+/** Per-invocation runtime context the dispatcher hands to an Invoker.
+ *  Gesture-kind-specific fields (`drag`, `wheel`, `multiTouch`, `key`) are
+ *  populated only for matching gesture kinds. */
+interface InvocationCtx {
+    world: Point2;
+    screen: Point2;
+    modifiers: ModifierState;
+    deps: ActionDeps;
+    drag?: {
+        start: Point2;
+        current: Point2;
+        delta: Point2;
+        /**
+         * Drag delta in client/screen coordinates (CSS pixels from the drag
+         * origin). Use this — never `delta` — for any action whose effect
+         * mutates the viewport itself (pan, view-zoom), because world-space
+         * deltas become self-referential as the view shifts mid-drag.
+         *
+         * Populated when the dispatcher received `clientX`/`clientY` on the
+         * underlying pointer events. Absent for legacy callers that don't
+         * provide them.
+         */
+        screenDelta?: Point2;
+        affordance?: AffordanceHit;
+        /**
+         * Full pointermove history for the current drag, in world space, with
+         * per-sample stylus state when the browser reported it.
+         * Accumulated by the dispatcher on every `pointermove` pump event.
+         * Available only during `onMove` and `onEnd` calls (not on `start`).
+         * Used by `lassoSelectAction` to build its polygon vertex list and by
+         * `insertAction`'s pencil kind to carry the freehand stroke.
+         */
+        points?: DragSample[];
+    };
+    wheel?: {
+        deltaX: number;
+        deltaY: number;
+        deltaZ: number;
+    };
+    multiTouch?: {
+        centroid: Point2;
+        spread: number;
+        rotation: number;
+        /**
+         * Pinch-zoom geometry. Populated by the dispatcher when a multitouch
+         * handle is in flight and a pointermove-pump fires.
+         * `startSpread` is the spread at the moment the gesture began.
+         * `currentSpread` is the spread at the current frame.
+         */
+        pinch?: {
+            startSpread: number;
+            currentSpread: number;
+            centroid: Point2;
+        };
+    };
+    key?: {
+        key: string;
+        repeat: boolean;
+    };
+    /**
+     * Per-invocation parameters. Populated by `ActionsRegistry.begin()` for
+     * UI-driven ongoing actions (color picker, opacity slider) so handles can
+     * read the current value on `start` and updated values on `onMove`. The
+     * gesture dispatcher does not populate this field; gesture-driven actions
+     * receive params via `BindingOpts.params` on `start` (the `opts` arg).
+     */
+    params?: Record<string, unknown>;
+}
+/** Per-invocation options the dispatcher reads from a `GestureBinding`'s
+ *  `opts` field and passes to `OngoingInvoker.start`. Today carries
+ *  behaviors; extensible. */
+interface BindingOpts {
+    behaviors?: ActionBehavior<unknown, unknown, unknown>[];
+    /** Per-binding action parameters. The action's invoker reads
+     *  these via the second arg to `run` (or via InvocationCtx for ongoing
+     *  invokers, when needed). Loose typing (Record<string, unknown>) for
+     *  now; consider per-action typing later via BindingOpts<A>.
+     *
+     *  params may also be a thunk evaluated each time the
+     *  dispatcher (or invoker) needs the value. Thunks let tools close over
+     *  refs that mutate during a gesture (e.g. polygon `sides` adjusted
+     *  mid-drag via ArrowUp). For ongoing invokers that want the latest
+     *  values at commit, the invoker can re-call the thunk inside `onEnd`
+     *  via `resolveParams(opts?.params)`. */
+    params?: Record<string, unknown> | (() => Record<string, unknown>);
+}
+/** Convention-shaped action dependencies bag. Actions declare which
+ *  contexts they consume; the dispatcher composes them per call.
+ *  Consumer-side contexts (e.g. ColorContext) plug in by extending. */
+interface ActionDeps {
+    selection?: unknown;
+    view?: unknown;
+    scene?: unknown;
+    pointer?: unknown;
+    activeTool?: unknown;
+    [k: string]: unknown;
+}
+/**
+ * Discriminated overlay shape returned by `OngoingHandle.overlay()`.
+ * Dispatcher-side chrome surface for in-flight
+ * gestures that paint non-ghost visuals. The canvas's
+ * `useDispatcherOverlayLayer` walks every in-flight handle, calls
+ * `overlay()`, and dispatches on `kind` to draw the appropriate shape.
+ *
+ * `marquee` mirrors `AreaSelectOverlay`; `lasso` mirrors `LassoSelectOverlay`.
+ * `commands` is the generic escape hatch — actions emit arbitrary
+ * `DrawCommand[]` for previews the typed variants can't express (insert
+ * shape outlines, paste ghosts of synthetic nodes, custom chrome). World-
+ * space is the default; the layer wraps in `viewToMat3` so commands track
+ * the camera. Set `space: 'screen'` for projections you've already done
+ * yourself (rare).
+ */
+type OngoingOverlay = {
+    kind: 'marquee';
+    start: {
+        x: number;
+        y: number;
+    };
+    current: {
+        x: number;
+        y: number;
+    };
+    shiftHeld: boolean;
+} | {
+    kind: 'lasso';
+    vertices: ReadonlyArray<{
+        x: number;
+        y: number;
+    }>;
+    current: {
+        x: number;
+        y: number;
+    };
+    shiftHeld: boolean;
+} | {
+    kind: 'commands';
+    commands: readonly DrawCommand[];
+    /** Coordinate space the commands are authored in. Default `'world'`
+     *  — the layer wraps them in `viewToMat3(view)` so they track the
+     *  camera. `'screen'` emits them as-is (CSS pixels). */
+    space?: 'world' | 'screen';
+} | {
+    /**
+     * Live insert-drag preview — dispatched by `insertAction` while the
+     * user is dragging out a new shape. Pre-commit there is no scene node
+     * to ghost via `previewIds()`/`previewPose()`, so insert paints its
+     * preview through the dispatcher overlay layer instead.
+     *
+     * `shape` is the kit's built-in insert kind. `bounds` is the AABB of
+     * the current drag (start/current normalized). `extras` is the
+     * per-kind extras the action already collected — the overlay
+     * renderer rebuilds the shape using the same path builders the
+     * commit factory uses, so the preview matches the eventual node.
+     *
+     * `extras` is opaque (`unknown`) at the union level; the overlay
+     * renderer narrows on `shape` and casts the field shape it expects.
+     */
+    kind: 'insertPreview';
+    shape: 'rect' | 'ellipse' | 'line' | 'polygon' | 'star' | 'pencil';
+    bounds: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    extras: unknown;
+    /** World-space point to paint a small "anchor" dot at. Sells the
+     *  click point as the drag's anchor — particularly useful for
+     *  radial shapes (polygon/star) where no vertex sits on the
+     *  click point, and for any shape in center mode where the dot
+     *  marks the center the shape grows around. */
+    anchorPoint?: {
+        x: number;
+        y: number;
+    };
+};
+/** Handle returned from an `OngoingInvoker.start`. The dispatcher pumps
+ *  `onMove` on subsequent input events of the same gesture and calls
+ *  `onEnd` exactly once (with `'commit'` on natural completion or `'cancel'`
+ *  on pointercancel / blur / escape). */
+interface OngoingHandle {
+    /**
+     * Optional logical action kind — a stable, human-readable tag the
+     * dispatcher exposes via `getActiveAction()` for chrome-visibility
+     * rules and any other surface that wants to react to "what action
+     * is currently in flight" without inspecting handles directly.
+     *
+     * Examples: `'marquee'`, `'lasso'`, `'move'`, `'resize'`, `'rotate'`,
+     * `'pan'`, `'pinch'`.
+     *
+     * Distinct from the dispatcher's internal `gestureId` (`pointer-mouse`,
+     * `key-held-Space`, etc.) which keys per-pointer state and is not
+     * meaningful to consumers.
+     *
+     * When omitted, the action is "anonymous" — `getActiveAction().kind`
+     * reports `null` even though a handle is in flight. This is fine for
+     * actions that don't have visible chrome of their own.
+     */
+    kind?: string;
+    onMove?(ctx: InvocationCtx): void;
+    onEnd?(ctx: InvocationCtx, reason: 'commit' | 'cancel'): void;
+    /**
+     * Optional preview surface — dispatcher-side ghost overlay.
+     *
+     * An ongoing-action implementation may populate `previewIds()` +
+     * `previewPose(id)` to expose its in-flight preview state for the
+     * canvas's preview-ghost layer (`usePreviewGhostLayer`) to render on
+     * top of the committed scene during the gesture.
+     *
+     * Returning `null` (or omitting the method entirely) means "no preview
+     * this gesture" — the canvas will skip this handle as a source.
+     *
+     * Semantics mirror the tool-side `Tool.previewIds` / `Tool.previewPose`
+     * pair: `previewIds()` enumerates the displaced node ids; `previewPose(id)`
+     * returns the interim pose for one of those ids (shape opaque — the
+     * canvas casts to its `TPose` parameter). The preview-ghost layer
+     * merges all sources via first-non-null semantics, with tool-side
+     * previews taking precedence over dispatcher-side (preserves
+     * backwards-compat during the registry-unification migration).
+     */
+    previewIds?(): Iterable<string> | null;
+    previewPose?(id: string): unknown | null;
+    /**
+     * When `false`, the preview-ghost layer paints the ghost AND the
+     * source node stays visible at its committed pose. Defaults to
+     * `true` (move/resize/rotate semantics: ghost replaces the source
+     * during the gesture). Clone overrides to `false` so the original
+     * stays put and the ghost appears at the drag target.
+     */
+    previewHidesSource?: boolean;
+    /**
+     * Optional per-id preview *data*. Falls back to the committed
+     * `node.data` when null/absent. Use when the gesture mutates
+     * `node.data` (e.g. anchor-edit on nodes that store the polygon on
+     * `data.path`) rather than (or in addition to) the pose. The preview-
+     * ghost layer assembles a synthetic node from `{ ...node, pose:
+     * previewPose ?? node.pose, data: previewData ?? node.data }` before
+     * calling the scene slot's `drawOne`.
+     *
+     * Sources compose first-non-null per axis: an action can emit only
+     * `previewPose` (translation), only `previewData` (data-only edit),
+     * or both (pose + data both change, e.g. anchor drag on a data.path
+     * node where the bounds shift).
+     */
+    previewData?(id: string): unknown | null;
+    /**
+     * Optional chrome surface — dispatcher-side overlay layer.
+     *
+     * An ongoing-action implementation may populate `overlay()` to expose a
+     * non-ghost visual (marquee rectangle, lasso polyline) for the canvas's
+     * `useDispatcherOverlayLayer` to paint while the gesture is in flight.
+     * Returning `null` (or omitting the method) means "no overlay this
+     * gesture" — the canvas will skip this handle as a chrome source.
+     *
+     * Distinct from the `previewIds()`/`previewPose(id)` ghost surface,
+     * which paints displaced scene-node silhouettes. Marquee and lasso
+     * gestures don't displace any node, but still need on-screen feedback.
+     */
+    overlay?(): OngoingOverlay | null;
+}
+/** Fire-once invocation. Runs to completion synchronously (or fires off an
+ *  async side-effect; the registry doesn't wait). */
+interface ImmediateInvoker {
+    timing: 'immediate';
+    /** `params` carries the matched binding's opts.params. When
+     *  invoked via the legacy `Action.run` bridge or from the command palette
+     *  with no per-binding context, `params` is undefined; descriptors should
+     *  default to a sensible variant. */
+    run(deps: ActionDeps, params?: Record<string, unknown>): void;
+}
+/** Phase-machine invocation. `start` opens the phase and returns the handle
+ *  the dispatcher pumps. */
+interface OngoingInvoker {
+    timing: 'ongoing';
+    start(ctx: InvocationCtx, opts?: BindingOpts): OngoingHandle;
+}
+/** Pluggable invocation strategy for an Action. Future variants
+ *  (`longPress`, `twoStage`, `modal`) extend this union without touching
+ *  the `Action` type. */
+type Invoker = ImmediateInvoker | OngoingInvoker;
+
+/** Boolean op identifiers — five Pathfinder primaries plus Crop. */
+type BooleanOp = 'union' | 'intersect' | 'subtract' | 'exclude' | 'divide' | 'crop';
+/**
+ * z-position descriptor for a path node. `parentId` is the direct parent
+ * (or `null` for a top-level node); `index` is the position within that
+ * parent's child order. Used by the optional `getZOrder` hook below to
+ * reposition the result of a boolean op at the topmost source's slot.
+ */
+/** @internal */
+interface BooleanZOrder {
+    parentId: string | null;
+    index: number;
+}
+/** Adapter the hook and the pure core both consume. */
+interface BooleansAdapter {
+    getSelection(): NodeId[];
+    getWorldPath(id: NodeId): Path | undefined;
+    compareZ(a: NodeId, b: NodeId): number;
+    /**
+     * Mint a new node from a boolean-op result `Path`. `producedBy` names the
+     * op that synthesized it — adapters that store provenance (e.g. for a
+     * layer-panel icon) record it; others ignore the arg.
+     */
+    createPathNode(path: Path, producedBy: BooleanOp): {
+        id: string;
+    };
+    /**
+     * Optional: return the full object for an id, used by the delete ops so
+     * their `invert` (an insert) can restore the complete object on undo.
+     * If omitted, a `{ id }` stub is captured — undo will reinstate the id
+     * but consumers reading other fields (path, fill, etc.) will see them as
+     * undefined. Mirrors `DeleteAdapter.getNode`; should be provided whenever
+     * undo over boolean ops is expected to be lossless.
+     */
+    getNode?(id: NodeId): {
+        id: string;
+    } | undefined | null;
+    /**
+     * Optional: return the parent + child-index of `id` so the result of a
+     * boolean op can be placed in the topmost source's z-slot. Adapters that
+     * also expose `getChildren`/`setChildOrder` (the `ReorderAdapter`
+     * contract) will have the kit emit a `createMoveToIndexOp` after the
+     * inserts. Adapters that omit this method get v1 behavior — the result
+     * lands wherever the adapter's plain `insertNode` defaults to.
+     */
+    getZOrder?(id: NodeId): BooleanZOrder | undefined;
+    applyOps?(ops: Op[], label?: string): void;
+    setSelection?(ids: NodeId[]): void;
+    insertNode?(node: {
+        id: string;
+    }): void;
+    removeNode?(id: string): void;
+}
+
+/** API returned by {@link useSelection}. */
+interface SelectionApi {
+    /** Current selection. Re-renders trigger when this reference changes. */
+    current: readonly NodeId[];
+    /** Imperative read for use inside event callbacks (avoids stale closures). */
+    get(): NodeId[];
+    /** Replace selection. */
+    set(ids: NodeId[]): void;
+    /** Add id (multi-mode appends; single-mode replaces). */
+    add(id: NodeId): void;
+    /** Remove id from selection. */
+    remove(id: NodeId): void;
+    /** Toggle id in/out of selection. */
+    toggle(id: NodeId): void;
+    /** Clear selection. */
+    clear(): void;
+    /** True if id is selected. */
+    contains(id: NodeId): boolean;
+    /**
+     * Apply a click to the selection per the configured mode/extend key.
+     * - `single`: replaces selection with `[id]`, regardless of modifiers.
+     * - `multi`: with the extend key held, toggles `id` in/out of the selection;
+     *   otherwise replaces with `[id]`.
+     */
+    applyClick(id: NodeId, modifiers: {
+        shift: boolean;
+        meta: boolean;
+        ctrl: boolean;
+    }): void;
+    /** Pre-built methods for spreading into an adapter that needs them. */
+    adapterMethods: {
+        getSelection: () => NodeId[];
+        setSelection: (ids: NodeId[]) => void;
+    };
+}
+
+/** Context handed to every content handler for one ingest event. */
+interface IngestCtx {
+    /** World-space arrival point (drop / pointed imperative ingest); `null`
+     *  for paste and point-less calls — handlers pick their own policy
+     *  (the kit image handler centers on the viewport). */
+    point: {
+        x: number;
+        y: number;
+    } | null;
+    /** Visible canvas area in world coordinates. */
+    viewportWorldRect(): {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    /** The kit insert dep — id/layer/undoable-op supplied; the canonical way
+     *  for a handler to mint a node (`insert.commit(bounds, { kind, ... })`). */
+    insert: InsertDep;
+    /** Raw op commit for handlers that build their own ops. */
+    applyOps(ops: Op[], label?: string): void;
+    scene: Scene<unknown, string, unknown>;
+    selection: SelectionApi;
+    /** Consumer file→src resolver (SceneCanvas `ingestion.resolveSrc`).
+     *  When absent, the kit image handler embeds as a `data:` URI. */
+    resolveSrc?: (file: File) => Promise<string>;
+    /** Kit SVG-handler options (SceneCanvas `ingestion.svg`) — e.g.
+     *  `{ unpack: unpackSvgFiles }` (from `@weasel-js/svg`) to parse SVG files
+     *  into scene nodes. */
+    svg?: SvgIngestOptions;
+    /** Clipboard-paste seam — present when the hosting `SceneCanvas` supplied
+     *  an adapter with `commitPaste`. `reviver` comes from
+     *  `SceneCanvasProps.ingestion.clipboard`. Absent ⇒ the kit weasel-JSON
+     *  handler declines inert (dwarn, nothing ingested) — its matched items
+     *  were already consumed at match time, so they do NOT fall through;
+     *  only match-level misses flow on to other handlers. */
+    clipboard?: ClipboardIngestCtx;
+    /** Set to `true` by the kit weasel-JSON handler when it successfully
+     *  pastes a payload in this event. The `ctx` object is shared across all
+     *  handlers in one `runIngest` call, and higher-priority handlers' `handle`
+     *  bodies run (synchronously) before lower ones — so `kit:svg`'s
+     *  `text/plain` SVG fallback reads this to decline the SVG flavor of a copy
+     *  whose canonical weasel-JSON flavor already ingested (avoids a
+     *  double-paste when both flavors ride one clipboard event). */
+    consumedWeaselPayload?: boolean;
+    /** Full action-deps bag, for consumer handlers that need more. */
+    deps: ActionDeps;
+}
+
+/**
+ * @experimental
+ * PointerContext — a tiny ambient context that publishes the world-space
+ * position of the canvas pointer, refreshed on every `pointermove` over
+ * the canvas. Cleared (set to `null`) on `pointerleave`.
+ *
+ * Why ref-based and not state-based: cursor moves fire dozens of times per
+ * second; routing those through React state would re-render every consumer
+ * in the tree. The context exposes a stable `pointerRef` whose `.current`
+ * is mutated directly by the publisher, plus a thunk `getDropPoint()` that
+ * reads it on demand. Consumers (e.g. `useClipboard`) pull via the thunk
+ * inside their callbacks — no subscription, no re-render.
+ *
+ * `<SceneCanvas>` publishes automatically. `useClipboardOps` consumes when
+ * the caller didn't pass an explicit `getDropPoint` option. Other future
+ * hit-on-cursor consumers (drop-zone hover, context-menu anchor) can reuse
+ * the same context.
+ */
+
+/** @experimental World-space pointer position, or `null` when the pointer
+ *  isn't over the publishing canvas. */
+type PointerWorldPos = {
+    worldX: number;
+    worldY: number;
+} | null;
+/** @experimental */
+interface PointerContextValue {
+    /** Live ref — mutate to publish, read for the latest snapshot. The
+     *  identity is stable for the lifetime of the provider. */
+    readonly pointerRef: MutableRefObject<PointerWorldPos>;
+    /** Convenience thunk equivalent to `() => pointerRef.current`. Stable
+     *  identity for the lifetime of the provider; safe to pass to hooks. */
+    readonly getDropPoint: () => PointerWorldPos;
+}
+
+interface ActiveToolContextValue {
+    active: string;
+    hotkeyStack: string[];
+    setActive(id: string): void;
+    pushHotkey(id: string): void;
+    popHotkey(): void;
+}
+
+/**
+ * `enterTextEditAction` — immediate Action descriptor for entering in-place
+ * text editing on a selected text node.
+ *
+ * ## Status: REAL
+ *
+ * Fires via `useTextTool.bindings` when the user clicks on a
+ * selected text node. Calls `deps.textEdit.startEdit(id)` to activate the
+ * contenteditable overlay managed by `useTextEdit` / `useSceneTextEdit`.
+ *
+ * ## No defaultBinding / defaultBinding
+ *
+ * This action has no ambient key or gesture binding — it fires ONLY via
+ * `useTextTool`'s `Tool.bindings` entry:
+ *
+ * ```ts
+ * bindings: [
+ *   { spec: { kind: 'click', target: 'selected-body' }, actionId: 'enterTextEdit' },
+ * ]
+ * ```
+ *
+ * Keeping it binding-free avoids ambient double-fire and scopes the action to
+ * the text tool context where `classifyTarget` is already wired.
+ *
+ * ## Self-guard: only act on text nodes
+ *
+ * The `'selected-body'` target yields a match for any selected node kind. To
+ * avoid entering text-edit mode when the text tool happens to have a non-text
+ * node selected, the action self-guards via an optional `isTextNode` predicate
+ * on `TextEditDep`:
+ *
+ * - When `isTextNode` is absent: action fires unconditionally (the binding
+ *   spec is the real gate — consumers should only bind this action from the
+ *   text tool).
+ * - When `isTextNode(id)` returns `false`: action is a no-op for that node.
+ *
+ * ### Pre-filtering at dispatch time
+ *
+ * `classifyTarget` now surfaces node kind, so a binding can pre-filter instead
+ * of relying on the self-guard:
+ *
+ * ```ts
+ * { spec: { kind: 'click', target: 'kind:text:selected' }, actionId: 'enterTextEdit' }
+ * ```
+ *
+ * That reads the *routing trait's* kind, so it matches whatever names the
+ * consumer registered in `<SceneCanvas routing>` — `'text'` under the kit's
+ * inferred default. `isTextNode` stays on `TextEditDep` because it also covers
+ * consumers who bind the broader `'selected-body'` target, and because it is
+ * the only guard for a consumer who opted out of routing entirely.
+ *
+ * ## Migration plan for useTextTool
+ *
+ * When wiring `useTextTool` to `Tool.bindings`:
+ *
+ * 1. Add to `useTextTool`'s `bindings`:
+ *    ```ts
+ *    { spec: { kind: 'click', target: 'selected-body' }, actionId: 'enterTextEdit' }
+ *    ```
+ * 2. Register a `textEdit` dep sourced from the `useTextEdit` / `useSceneTextEdit`
+ *    return value, plus an `isTextNode` predicate that checks `data.kind === 'text'`
+ *    (or however the consumer identifies text nodes).
+ * 3. The existing `hitExisting` gate in `useTextTool`'s click route becomes
+ *    redundant — remove it in the same pass.
+ */
+
+/**
+ * Dep for `enterTextEditAction`.
+ *
+ * Wrap the return value of `useTextEdit` / `useSceneTextEdit` to source this
+ * dep. The `isTextNode` predicate is optional — when absent the action fires
+ * unconditionally (the binding spec acts as the gate).
+ *
+ * @example
+ * ```ts
+ * const textEdit = useSceneTextEdit({ scene, container });
+ * useDepSource('textEdit', () => ({
+ *   startEdit: textEdit.startEdit,
+ *   isTextNode: (id) => scene.get(id as NodeId)?.data?.kind === 'text',
+ * }));
+ * ```
+ */
+interface TextEditDep {
+    /**
+     * Begin editing the node with `id`. Activates the contenteditable overlay
+     * managed by `useTextEdit` / `useSceneTextEdit`.
+     */
+    startEdit(id: string, opts?: {
+        caret?: number | 'all';
+    }): void;
+    /**
+     * Optional predicate: returns `true` when the node with `id` is a text node.
+     * When absent the action fires on any selected node (binding spec is the gate).
+     * When present and returning `false`, the invocation is a no-op.
+     */
+    isTextNode?(id: string): boolean;
+}
+
+/**
+ * Consumer-supplied commit for the Slice action. `commit` receives the finite
+ * slice segment (world coords); the consumer scans the scene, splits crossed
+ * paths via `splitPathByLine`, and applies the result as one undoable batch.
+ */
+interface SliceDep {
+    commit(a: Point2, b: Point2): void;
+}
+
+/**
+ * Bridges arbitrary `TPose` shapes into the resize hook's bounds-driven math.
+ * The hook reads bounds via `getBounds`, runs anchor-relative math on those
+ * bounds, then asks `remapBounds` to project the result back into TPose.
+ *
+ * `remapBounds(pose, src, dst)` is a single operation that subsumes both
+ * "set my own AABB to dst" (single-leaf resize) and "scale me as a leaf
+ * inside parent's src→dst rect" (group resize) — they're the same affine
+ * map. For rect-shaped poses the default geometry interprets the pose as
+ * its own bounds; for Path or polygon poses the consumer supplies a
+ * projection that knows how to read and rewrite the underlying geometry.
+ */
+interface PoseProjection<TPose> {
+    getBounds(pose: TPose): ResizePose;
+    remapBounds(pose: TPose, src: ResizePose, dst: ResizePose): TPose;
+    /** Translate the pose by (dx, dy). Optional — when omitted, callers fall
+     *  back to a translation derived from `remapBounds` (origin shifted, no
+     *  scale). Path-shaped poses should provide this for performance. */
+    translate?(pose: TPose, dx: number, dy: number): TPose;
+    /** True iff any portion of the pose's geometry intersects `rect`. Optional
+     *  — when omitted, area-select and similar callers test against `getBounds`
+     *  AABB (looser, but correct for axis-aligned rect poses). */
+    intersectsRect?(pose: TPose, rect: ResizePose): boolean;
+    /** Interpolate between two poses. Optional — animation helpers fall back to
+     *  rect-shape lerp when omitted (which fails for non-rect poses). */
+    lerp?(a: TPose, b: TPose, t: number): TPose;
+    /** Read the pose's rotation in radians. Pivot is the AABB center
+     *  (`getBounds(pose)` center). Default 0 when omitted — descriptor
+     *  declares "this pose has no rotation." When supplied and non-zero,
+     *  `useResize` projects the drag delta into the leaf's local frame,
+     *  runs anchor math there, and translates the resulting pose so the
+     *  diagonally opposite world-space corner is pinned. */
+    getRotation?(pose: TPose): number;
+    /** True iff this pose shape can carry a rotation. Consulted by the
+     *  rotation affordance to decide whether to render the rotate cursor /
+     *  drag-band over a selection. When omitted, the kit assumes `true` for
+     *  back-compat — descriptors whose poses lack `x/y/width/height/rotation`
+     *  fields (e.g. polygon Paths) should return `false` so the affordance
+     *  hides instead of exposing a non-functional rotate cursor. */
+    supportsRotation?(pose: TPose): boolean;
+}
+
+/**
+ * 2D affine transforms in canvas/DOMMatrix order: [a, b, c, d, e, f].
+ *   x' = a·x + c·y + e
+ *   y' = b·x + d·y + f
+ * Represented as a 6-element number[] (f64). The affine tier of the kernel.
+ *
+ * Convention alignment: the renderer already has a `Mat3` in
+ * `src/renderer/math/mat3.ts`. That one is a 9-element column-major
+ * `Float32Array` (a full 3×3) shaped for `uniformMatrix3fv` — a deliberately
+ * different *representation* for the WebGL upload path. Its *logical element
+ * order* is identical to ours: `create(a, b, c, d, tx, ty)` maps
+ * `x' = a·x + c·y + tx`, `y' = b·x + d·y + ty` (canvas/DOMMatrix a,b,c,d,e,f).
+ * We keep the pure 6-tuple f64 form here (the kernel form); the 9-element f32
+ * form stays a render-layer concern. No second logical convention is created.
+ */
+type Mat3 = number[];
+
+/** Optional consumer seam: given a node and the affine `m` that a pose-transform
+ *  action applied to the node's POSE, return updated `data` with the node's
+ *  data-held geometry transformed by `m`, or `null` if this node has no
+ *  data-held geometry (the kit leaves `data` alone). */
+interface GeometryProjection {
+    transform(node: {
+        id?: string;
+        data: unknown;
+        pose: unknown;
+    }, m: Mat3): unknown | null;
+}
+
+/** Minimal view API the action layer consumes. May be refined later. */
+interface ViewApi {
+    get(): View;
+    set(v: View): void;
+    /** Optional recenter callback. When wired, `viewportZoomAction`'s
+     *  `reset` branch (Cmd-0) calls this instead of resetting to identity —
+     *  letting consumers re-fit the page (or other reference bounds) into
+     *  the workspace. Receives no args; the consumer reads its own bounds
+     *  + host dims and dispatches `setView(...)`. */
+    recenter?(): void;
+    /** Optional canvas-local host dimensions (CSS px). When wired,
+     *  `viewportZoomAction`'s keyboard branches (Cmd+= / Cmd+-) anchor at the
+     *  host center instead of the top-left origin. Null when the host isn't
+     *  measurable (unmounted). */
+    hostSize?(): {
+        width: number;
+        height: number;
+    } | null;
+}
+/**
+ * Adapter dep for `areaSelectAction`.
+ *
+ * Provided by `<SceneCanvas>` / `<StandardActionsRegistrar>` via AABB
+ * overlap over scene nodes. Consumers with custom hit-testing override this
+ * dep entry in their own registrar.
+ */
+/**
+ * Topmost-node-at-world-point dep, consumed by `moveAction` for
+ * reparent-on-drop and available to any action that needs a single-best
+ * pick. Mirrors the same hit-test plumbing `<SceneCanvas>` feeds to the
+ * tool dispatcher; consumers with custom hit-testing override here.
+ *
+ * `exclude` is iterated once per call and treated as a set membership
+ * test — the dep walks hits front-to-back and returns the first id not
+ * in the exclude set. Pass moving-node roots + their descendants when
+ * the caller wants to ignore the nodes it's manipulating.
+ */
+type NodeAtPointDep = (point: {
+    x: number;
+    y: number;
+}, exclude?: Iterable<NodeId>) => NodeId | null;
+interface AreaSelectDep {
+    /** Return ids of all scene nodes whose AABB overlaps `bounds`. */
+    hitTestArea(bounds: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    }): NodeId[];
+    /** Return the current selection id list. */
+    getSelection(): NodeId[];
+    /** Replace the current selection. */
+    setSelection(ids: NodeId[]): void;
+}
+/**
+ * Adapter dep for `editAnchorsAction`.
+ *
+ * Provides narrow read/write access to the editable polygon for a single
+ * node. Consumers register this dep so anchor-edit actions can read/write
+ * the polygon WITHOUT knowing whether it lives directly on the node's
+ * pose (`pose.kind === 'polygon'`) or on `node.data.path` (the kit's
+ * built-in pen-tool default, also WeaselDraw's shape).
+ *
+ * Note on live previews: in-flight edit state is surfaced through the
+ * dispatcher's standard `OngoingHandle.previewIds/previewPose/previewData`
+ * triple (not this dep), so chrome and preview-ghost stay in lock-step
+ * via one source of truth.
+ */
+interface EditAnchorsDep {
+    /** Id of the node currently being edited. Empty string means no node is
+     *  currently in edit mode — the chrome and gesture both opt out. */
+    editingId: string;
+    /** Enter/exit edit mode for a specific node. Pass `null` (or an empty
+     *  string) to exit. `enterPathEditAction` and `exitPathEditAction` call
+     *  this; consumers can call it directly to drive edit mode programmatically. */
+    setEditingId(id: string | null): void;
+    /** Returns the COMMITTED editable polygon in world coordinates, or
+     *  null if this node has no editable polygon. Does NOT consult in-
+     *  flight previews — callers that need live state read the dispatcher's
+     *  in-flight handles. */
+    getEditablePath(id: string): unknown;
+    /** Returns where the polygon is stored — `'pose'` when `node.pose`
+     *  IS the polygon, `'data'` when it lives on `node.data.path` with a
+     *  rect pose, or `null` when the node has no editable polygon. The
+     *  action uses this to know which preview-ghost axis to populate
+     *  (`previewPose` only / `previewData` + `previewPose` for data.path). */
+    getStorageKind(id: string): 'pose' | 'data' | null;
+    /** Returns the node's raw `pose` and `data` so storage-aware actions
+     *  can capture origin state at gesture-start and synthesize a matching
+     *  `previewPose` / `previewData` during `onMove`. Used by
+     *  `editAnchorsAction` for the data.path branch (rect pose + data
+     *  carrying extra fields like fill / stroke that must be preserved
+     *  through the preview). Returns null when the node is gone. */
+    getNodeShape(id: string): {
+        pose: unknown;
+        data: unknown;
+    } | null;
+    /** Commit `worldPath` as the new value for `id`. Implementation routes
+     *  to setPose (when pose IS the polygon) or batched setPose+update
+     *  (when the polygon lives on data.path). Records one history entry
+     *  labelled `label`. */
+    applyEdit(id: string, worldPath: unknown, label: string): void;
+    /**
+     * Anchors currently selected within the edited path, as **flat anchor
+     * indices** — the same numbering `enumerateAnchors` produces and the
+     * `anchor:N` affordance kinds carry.
+     *
+     * Selection is transient UI state, deliberately not part of the scene:
+     * it is cleared whenever `editingId` changes, and any edit that
+     * renumbers anchors (insert, delete) is responsible for leaving it
+     * coherent. Empty means "no anchor selected" — the keyboard actions
+     * (nudge, delete) no-op rather than acting on all anchors, matching
+     * Illustrator.
+     */
+    selectedAnchors: ReadonlySet<number>;
+    /** Replace the anchor selection. Pass an empty iterable to clear. */
+    setSelectedAnchors(next: Iterable<number>): void;
+    /**
+     * In-flight anchor-marquee rect in world coords, or null when no
+     * marquee drag is active. Written by `marqueeAnchorsAction` and read by
+     * the path-editing overlay — the same "ongoing action owns the preview,
+     * chrome just draws it" split the move/resize ghosts use.
+     */
+    marquee: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    } | null;
+    /** Set or clear the in-flight marquee rect. */
+    setMarquee(rect: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    } | null): void;
+}
+/**
+ * Adapter dep for `lassoSelectAction`.
+ *
+ * Provides polygon-lasso hit-testing + selection read/write.
+ * Consumers that don't implement `hitTestLasso` can omit it; the action
+ * falls back to a bounding-box AABB test via `hitTestArea`.
+ */
+interface LassoSelectDep {
+    /**
+     * Hit-test against a closed polygon (vertex order CW or CCW; last→first
+     * closing edge is implicit). Returns matching node ids.
+     * Optional — when absent, `lassoSelectAction` falls back to AABB via
+     * `hitTestArea`.
+     */
+    hitTestLasso?(polygon: ReadonlyArray<{
+        x: number;
+        y: number;
+    }>, mode: 'centers' | 'intersect' | 'enclosed'): string[];
+    /** Return ids of nodes whose AABB overlaps the given rect (fallback). */
+    hitTestArea(bounds: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    }): string[];
+    /** Return the current selection id list. */
+    getSelection(): string[];
+    /** Replace the current selection. */
+    setSelection(ids: string[]): void;
+}
+/**
+ * Options for the kit `image/svg+xml` content handler, threaded from
+ * SceneCanvas's `ingestion={{ svg }}` prop.
+ */
+interface SvgIngestOptions {
+    /** Parse dropped/pasted/picked SVG files into native scene nodes (path /
+     *  text leaves under containers mirroring the source `<g>` structure)
+     *  instead of the default single embedded-image node.
+     *
+     *  Pass `unpackSvgFiles` from `@weasel-js/svg`:
+     *
+     *  ```ts
+     *  import { unpackSvgFiles } from '@weasel-js/svg';
+     *  <SceneCanvas ingestion={{ svg: { unpack: unpackSvgFiles } }} />
+     *  ```
+     *
+     *  It is injected rather than flagged on with `true` because the SVG parser
+     *  lives in `@weasel-js/svg`, which depends on this package — core importing
+     *  it back would make the two mutually dependent and unpublishable
+     *  separately. Passing the function keeps the parser out of core's bundle
+     *  for consumers who never unpack. */
+    unpack?: SvgUnpacker;
+}
+/** Parses SVG files and inserts the resulting nodes into `ctx.scene`, as one
+ *  `applyOps` batch per file. Implemented by `unpackSvgFiles` in
+ *  `@weasel-js/svg`; see {@link SvgIngestOptions.unpack}. */
+type SvgUnpacker = (files: File[], ctx: IngestCtx) => Promise<void>;
+/**
+ * Clipboard-paste seam consumed by the kit weasel-JSON content handler
+ * (`IngestCtx.clipboard`). Built by `<SceneCanvas>` from its own synthesized
+ * adapter + the `ingestion.clipboard` prop; absent when the consumer set
+ * `ingestion.clipboard.enabled === false` or the adapter lacks `commitPaste`.
+ * Absence makes the handler decline inert (dwarn, nothing ingested) — its
+ * matched items were already consumed at match time and do not fall through
+ * to other handlers.
+ */
+interface ClipboardIngestCtx {
+    /** The hosting canvas's adapter — `commitPaste` materializes the pasted
+     *  nodes (fresh ids, offset applied); insertion still goes through ops. */
+    adapter: InsertAdapter<{
+        id: string;
+    }>;
+    /** JSON reviver for the weasel wire payload (typed arrays etc.) — from
+     *  `SceneCanvasProps.ingestion.clipboard.reviver`. */
+    reviver?: (key: string, value: unknown) => unknown;
+}
+/**
+ * Dep for the `ingest` action (external-content ingestion).
+ * Sourced from `<SceneCanvas>` / `<StandardActionsRegistrar>` via
+ * `useIngestionDepSource` — canvas rect + current view.
+ */
+interface IngestionDep {
+    /** Visible canvas area in world coordinates. */
+    viewportWorldRect(): {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    /** Consumer file→src resolver (from SceneCanvas's `ingestion` prop).
+     *  Live accessor — read it at use time. Destructuring (or copying the
+     *  property early) snapshots the current value and won't track later
+     *  prop changes across an `await`. */
+    resolveSrc?: (file: File) => Promise<string>;
+    /** Kit SVG-handler options (from SceneCanvas's `ingestion` prop).
+     *  Live accessor, same caveat as `resolveSrc`. */
+    svg?: SvgIngestOptions;
+    /** Clipboard-paste seam for the kit weasel-JSON handler.
+     *  Live accessor, same caveat as `resolveSrc`. */
+    clipboard?: ClipboardIngestCtx;
+}
+/**
+ * Per-kind extra geometry passed to `InsertDep.commit`.
+ *
+ * Built-in tools populate a typed variant so the kit's default factory can
+ * render the true tool params (line endpoints, polygon side count, star
+ * geometry, pencil sample list). Consumer-defined tools may pass any
+ * `{ kind: string; ... }` payload; the kit's factory falls back to AABB
+ * inscription for unknown kinds.
+ *
+ * `bounds` is still passed alongside as a useful AABB pose hint — factories
+ * may use it as the node's pose even when richer geometry is available.
+ */
+type InsertExtras = {
+    kind: 'rect';
+} | {
+    kind: 'ellipse';
+} | {
+    kind: 'line';
+    a: {
+        x: number;
+        y: number;
+    };
+    b: {
+        x: number;
+        y: number;
+    };
+} | {
+    kind: 'polygon';
+    sides: number;
+    rotation: number;
+    center?: {
+        x: number;
+        y: number;
+    };
+    radius?: number;
+} | {
+    kind: 'star';
+    points: number;
+    innerRadiusRatio: number;
+    rotation: number;
+    center?: {
+        x: number;
+        y: number;
+    };
+    outerRadius?: number;
+} | {
+    kind: 'pencil';
+    samples: ReadonlyArray<DragSample>;
+} | {
+    kind: 'text';
+    text?: string;
+} | {
+    kind: string;
+    [extra: string]: unknown;
+};
+/**
+ * World-space point snapping — grid, guides, or any consumer rule.
+ *
+ * Sourced by `<SceneCanvas>` from its `toolOptions.snapPoint`. Actions apply
+ * it to the coords they ingest so the live preview and the committed
+ * geometry agree; `insertAction` snaps the drag's start and current point.
+ *
+ * Optional: when the dep is absent, actions treat it as identity.
+ */
+interface SnapDep {
+    /** Snap a world-space point. Return `p` unchanged to opt out. */
+    point(p: {
+        x: number;
+        y: number;
+    }): {
+        x: number;
+        y: number;
+    };
+}
+/**
+ * Adapter dep for `insertAction`.
+ *
+ * Provided by `<SceneCanvas>` / `<StandardActionsRegistrar>`. The `extras`
+ * carry the active tool's kind + per-kind geometry. Callers
+ * that need typed data must supply a richer `insert` dep.
+ */
+interface InsertDep {
+    /**
+     * Materialise a new node from the given drag-rect bounds and typed
+     * per-kind extras. Returns the new node's id, or `null` if the consumer
+     * rejected the insert (e.g. sub-threshold bounds, unknown kind).
+     */
+    commit(bounds: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    }, extras: InsertExtras): NodeId | null;
+}
+/**
+ * Adapter dep for `resizeAction`.
+ *
+ * Carries the four behavior-shaping options the legacy `useResize` hook
+ * exposed through `UseResizeOptions`: bounds-frame behaviors (e.g.
+ * `lockAspectWithModifier`), world-space anchor-point snap behaviors (e.g.
+ * `pointSnapToGrid`), group-expansion (`expandIds`), and pose↔bounds
+ * projection (`geometry`).
+ *
+ * Optional in `DepSchema`: when absent, `resizeAction` falls back to
+ * identity defaults (no behaviors, identity expandIds, `RECT_POSE_DESCRIPTOR`
+ * geometry). Consumers wire the dep via `useDepSource('resizePolicy', ...)`
+ * from any descendant of `<DepRegistryProvider>` / `<SceneCanvas>`.
+ *
+ * The generic is erased to `unknown` at the schema entry; consumers cast at
+ * the call site (mirrors the `scene` entry's convention).
+ */
+interface ResizePolicy<TPose> {
+    /** Bounds-frame constraints. Constrained to `TPose extends ResizePose` since
+     *  constraints read/write `{x,y,width,height}`. For non-rect TPose pass `[]`. */
+    constraints: TPose extends ResizePose ? BoundsConstraint<TPose>[] : never[];
+    /** World-space anchor-point snap behaviors. Same TPose constraint as
+     *  `constraints`. */
+    pointSnap: TPose extends ResizePose ? PointSnapBehavior<TPose>[] : never[];
+    /** Group-expansion at gesture start. Identity (`ids => ids`) when group
+     *  resize isn't wanted. */
+    expandIds: (ids: string[]) => string[];
+    /** Projection from `TPose` to bounds and back. Use `RECT_POSE_DESCRIPTOR`
+     *  for plain rect poses. */
+    projection: PoseProjection<TPose>;
+}
+/**
+ * Layout-strategy lookup by container id, consumed by `moveAction` to run
+ * the drag-time reflow pass. Sourced by `<SceneCanvas>` from its `layouts`
+ * prop. Optional: `getLayout` returns null for any container when no layout
+ * is configured, so the reflow pass is a no-op then.
+ */
+interface LayoutDep {
+    getLayout(containerId: string): LayoutStrategy<unknown> | null;
+}
+interface DepSchema {
+    /** Kit selection state — ids of currently selected nodes. */
+    selection: SelectionApi;
+    /** Current viewport — camera position + scale. */
+    view: ViewApi;
+    /**
+     * Scene tree — structural reads + undoable mutations.
+     *
+     * The entry uses the fully-erased form `Scene<unknown, string, unknown>`
+     * because `DepSchema` must be concrete. Actions that need a typed scene
+     * should cast: `deps.scene as Scene<MyData, MyLayer, MyPose>`.
+     */
+    scene: Scene<unknown, string, unknown>;
+    /** Undo/redo history bound to the current scene. */
+    history: History;
+    /**
+     * Canvas pointer position in world space.
+     *
+     * Exposes `pointerRef` (mutable live ref) and `getDropPoint()` thunk.
+     * Marked `@experimental` in the source.
+     */
+    pointer: PointerContextValue;
+    /** Currently active tool id + hotkey-hold stack. */
+    activeTool: ActiveToolContextValue;
+    /**
+     * Area-select dep — AABB hit-test + selection read/write.
+     *
+     * Sourced from `<SceneCanvas>` via AABB overlap over all scene
+     * nodes. Override per-consumer for custom hit-testing (e.g. contain-mode,
+     * lock-aware filtering).
+     */
+    areaSelect: AreaSelectDep;
+    /**
+     * Topmost node at a world-space point. Sourced by `<SceneCanvas>` from
+     * the same picker that feeds the tool dispatcher's `getNodeAtPoint`.
+     * Optional: actions that read this (e.g. `moveAction` reparent-on-drop)
+     * fall back to a no-op when the dep isn't registered.
+     */
+    nodeAtPoint?: NodeAtPointDep;
+    /**
+     * Insert dep — node factory for drag-to-insert.
+     *
+     * Sourced from `<SceneCanvas>`. The `kind` param comes from
+     * the active binding's `opts.params.kind`. Override per-consumer to
+     * provide a typed node factory (e.g. with custom data payloads).
+     */
+    insert: InsertDep;
+    /**
+     * Snap dep — world-space point snapping (grid / guides).
+     *
+     * Sourced by `<SceneCanvas>` from `toolOptions.snapPoint`. Optional:
+     * absent means no snapping (identity).
+     */
+    snap?: SnapDep;
+    /**
+     * Lasso-select dep — polygon hit-test + selection read/write.
+     *
+     * Sourced from `<SceneCanvas>` / `<StandardActionsRegistrar>`.
+     * Falls back to AABB hit-test when `hitTestLasso` is absent.
+     */
+    lassoSelect: LassoSelectDep;
+    /**
+     * Edit-anchors dep — narrow read/write of one polygon's path pose.
+     *
+     * Sourced from consumer. Wraps `getPose`/`setPose`/`applyOps`
+     * for the currently-being-edited polygon node.
+     *
+     * The `editAnchorsAction` requires this dep to be registered when anchor
+     * editing is active. If absent, `start` returns an empty handle (no-op).
+     */
+    editAnchors: EditAnchorsDep;
+    /**
+     * Text-edit dep — activates the in-place text editing overlay.
+     *
+     * Sourced from consumer via `useTextEdit` / `useSceneTextEdit`.
+     * The `enterTextEditAction` requires this dep to be registered by the text
+     * tool when text editing is available.
+     *
+     * The optional `isTextNode` predicate guards against entering edit mode on
+     * non-text nodes. A binding can pre-filter instead with a
+     * `target: 'kind:text:selected'` spec; the guard remains for consumers who
+     * bind the broader `'selected-body'` target or opted out of routing.
+     */
+    textEdit: TextEditDep;
+    /**
+     * Resize-policy dep — bounds constraints, point-snap behaviors,
+     * group expansion, and pose↔bounds projection for `resizeAction`.
+     *
+     * Optional: when omitted, `resizeAction` falls back to identity defaults
+     * (no constraints, no snap, identity expandIds, `RECT_POSE_DESCRIPTOR`).
+     * Consumers wire via `useDepSource('resizePolicy', ...)` or the
+     * `useResizePolicy` helper.
+     */
+    resizePolicy?: ResizePolicy<unknown>;
+    /**
+     * Booleans adapter — read selection ids, fetch world-space `Path`s,
+     * compare z-order, and mint result nodes for Pathfinder ops.
+     *
+     * Consumers wire via `useBooleansAdapter(adapter)` (a thin wrapper
+     * around `useDepSource('booleansAdapter', ...)`). The descriptor's
+     * `enabled` predicate reads `deps.selection` for the count check; the
+     * invoker reads `deps.booleansAdapter` to execute the op.
+     */
+    booleansAdapter?: BooleansAdapter;
+    /**
+     * Gesture dispatcher control surface — exposes `cancelAll(reason)` so
+     * actions that need to abort an in-flight handle (Escape cancels a
+     * drag, etc.) can do so. Sourced by `<SceneCanvas>` from the
+     * dispatcher instance it already owns.
+     */
+    dispatcher?: {
+        cancelAll(reason: 'commit' | 'cancel'): void;
+    };
+    /**
+     * Layout-strategy lookup. Sourced by `<SceneCanvas>` from `layouts`.
+     * Optional: absent (or all-null) → `moveAction` skips reflow.
+     */
+    layout?: LayoutDep;
+    /**
+     * Slice dep — consumer-supplied commit for the Slice action.
+     *
+     * Receives the finite slice segment in world coordinates; the consumer
+     * scans the scene, splits crossed paths via `splitPathByLine`, and
+     * applies the result as one undoable batch.
+     *
+     * Optional: when absent, `sliceAction` is a no-op.
+     */
+    slice?: SliceDep;
+    /**
+     * Optional consumer commit hook. When present, `moveAction` (and other
+     * default actions) submit their committed ops through it instead of
+     * `scene.applyBatch`, so apps with their own history integration
+     * (checkpoint + push entry) capture the gesture as one undo entry.
+     * When absent, commits fall back to `scene.applyBatch`.
+     */
+    applyOps?: (ops: Op[], label: string) => void;
+    /** Optional pose-composition strategy for hierarchical (local-pose) scenes.
+     *  When absent, defaults to IDENTITY (absolute-pose: nodes store world
+     *  coords). Local-pose consumers supply { compose: composeRectPose,
+     *  decompose: decomposeRectPose } (or their pose shape's equivalent). */
+    poseComposition?: PoseComposition<unknown>;
+    /**
+     * Ingestion dep — canvas viewport rect + consumer file→src resolver.
      *
-     *  params may also be a thunk evaluated each time the
-     *  dispatcher (or invoker) needs the value. Thunks let tools close over
-     *  refs that mutate during a gesture (e.g. polygon `sides` adjusted
-     *  mid-drag via ArrowUp). For ongoing invokers that want the latest
-     *  values at commit, the invoker can re-call the thunk inside `onEnd`
-     *  via `resolveParams(opts?.params)`. */
-    params?: Record<string, unknown> | (() => Record<string, unknown>);
+     * Sourced from `<SceneCanvas>` / `<StandardActionsRegistrar>` via
+     * `useIngestionDepSource`. Feeds `ingestAction` with the world-space
+     * viewport rect for paste-placement and image fit-clamping, and forwards
+     * the consumer's optional `resolveSrc` seam.
+     *
+     * Optional: when absent, the `ingest` action no-ops (there is no
+     * placement geometry to work with).
+     */
+    ingestion?: IngestionDep;
+    /**
+     * Optional consumer seam for the eager-sync layer: lets pose-transform
+     * actions (resize/move/nudge/flip — NOT rotate) ALSO rewrite a node's
+     * data-held geometry. Given a node and the affine `m` applied to its pose,
+     * `transform(node, m)` returns updated `data` (geometry mapped by `m`) or
+     * `null` for nodes with no data-held geometry.
+     *
+     * Strictly opt-in: when absent (or when `transform` returns null), the kit
+     * emits only the pose op and leaves `data` untouched. apps/draw wires this
+     * to mirror `data.path` through `transformPath`. Rotate intentionally never
+     * consults this seam (rotation lives on the pose, baked at render).
+     */
+    geometryProjection?: GeometryProjection;
 }
+/**
+ * Every dep name the registry knows about — derived from {@link DepSchema} so
+ * the two can't drift.
+ *
+ * Declared here rather than beside the registry so that this `keyof` reference
+ * resolves to the exported `DepSchema` declaration; from another module it
+ * resolves to that module's import alias, which the API docs can't link.
+ */
+type DepName = keyof DepSchema;
 
 /**
  * GestureBinding — connects a GestureSpec to an Action id (with per-binding
@@ -1615,136 +3210,50 @@ interface GestureBinding {
     opts?: BindingOpts;
 }
 
-/** The full vocabulary of capability tags shipped in the default preset.
- *  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"];
-type CapabilityTag = (typeof ALL_TAGS)[number] | (string & {});
-
-interface WorkspaceVisual {
-    tint?: string;
-    gradient?: 'top-down' | 'bottom-up';
-    intensity?: number;
-}
-interface ModeDefinition {
-    id: string;
-    kind: 'soft' | 'strict';
-    /** Capability tags this mode allows beyond IMPLICIT_TAGS. */
-    allows: CapabilityTag[];
-    /** When true, out-of-target objects dim at the renderer layer. */
-    scoping: boolean;
-    workspace?: WorkspaceVisual;
-    entry?: {
-        shortcut?: string;
-        trigger?: 'double-click-target';
-    };
-    exit?: {
-        shortcut?: string;
-    };
-    commit?: {
-        shortcut?: string;
-    };
-    cancel?: {
-        shortcut?: string;
-    };
-}
-
-interface ModeRegistry {
-    current(): ModeDefinition;
-    setMode(id: string): void;
-    byId(id: string): ModeDefinition;
-    getVersion(): number;
-    subscribe(listener: () => void): () => void;
-}
-
-/**
- * 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';
-}
-
-/** Common payload for any hit that references a scene node. */
-interface NodeRef {
-    id: NodeId;
-    pose: unknown;
-    data: unknown;
-    meta?: Record<string, unknown>;
-}
-/** No hit — pointer landed on the background. */
-interface EmptyHit {
-    category: 'empty';
-    kind: 'empty';
-}
-/** Hit on a scene node's body. */
-interface NodeHit extends NodeRef {
-    category: 'node';
-    kind: string;
-}
-/** Hit on a node's affordance chrome (handle, anchor, etc.). */
-interface AffordanceHit extends NodeRef {
-    category: 'affordance';
-    kind: string;
-}
-/** Hit on a tool-defined target (anchor, handle, segment, etc.) supplied
- *  via the tool's `hitOverride`. The `kind` string is the tool's own
- *  vocabulary; the dispatcher does not interpret it. */
-interface ToolHit {
-    category: 'tool';
-    kind: string;
-    extra?: unknown;
+type HandleKind = 'corner' | 'rotation' | 'anchor';
+type HitShape = {
+    kind: 'rect';
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    rotation?: number;
+} | {
+    kind: 'circle';
+    cx: number;
+    cy: number;
+    r: number;
+} | {
+    kind: 'path';
+    d: Path2D;
+};
+interface DebugSink {
+    recordHitbox(id: string, kind: 'body' | 'handle' | 'rotation' | 'anchor', shape: HitShape): void;
+    recordHandle(id: string, position: {
+        x: number;
+        y: number;
+    }, kind: HandleKind): void;
+    recordBounds(id: string, bounds: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    }): void;
+    recordOrigin(id: string, point: {
+        x: number;
+        y: number;
+    }): void;
+    recordSnapCandidate(point: {
+        x: number;
+        y: number;
+    }, accepted: boolean): void;
+    recordLayer(id: string, label: string, space: 'world' | 'screen', index: number): void;
+    /** Clears every non-snap array. Called at the start of each Canvas render. */
+    beginFrame(): void;
+    /** Clears the snap array. Called at gesture end. */
+    clearSnap(): void;
 }
-/** Full discriminated union — every routed action's `ctx.target`. */
-type HitResult = EmptyHit | NodeHit | AffordanceHit | ToolHit;
 
-/** Phase the route was resolved against. Mirrors the spec's two-phase
- *  vocabulary — `initial` (idle, scratch null) or `engaged` (mid-gesture). */
-type RoutePhase = 'initial' | 'engaged';
-/** Gesture channel the route fired on. */
-type RouteGesture = GestureName;
-/** Snapshot of one route resolution, emitted by the factory on each
- *  successful lookup. Captured by the dispatcher as the "last resolved
- *  route" for debug-overlay consumers. */
-interface RouteResolvedInfo {
-    toolId: string;
-    phase: RoutePhase;
-    gesture: RouteGesture;
-    /** Argument captured at match time for arg-bearing gestures
-     *  (`wheel` direction, `keyDown`/`keyUp` key, `multiTouchTap` fingers).
-     *  Undefined for no-arg gestures. */
-    arg: string | undefined;
-    /** Route-table key that matched (post-precedence). E.g. 'rect:selected',
-     *  '*:selected', 'rect', '*', 'empty'. For function-form `drag` (no
-     *  table), this is '*'. For keyDown/keyUp, it's the key name ('Escape',
-     *  'Enter', etc.). */
-    matchedKey: string;
-    modifiers: ModifierCombo;
-    /** The full HitResult at resolution time (snapshot — safe to read). */
-    target: HitResult;
-    /** Monotonic timestamp (ms since page load via performance.now()).
-     *  Used for "resolved Nms ago" displays. */
-    timestamp: number;
-}
-
-/** Outcome of a channel handler. `'claim'` stops dispatch for this event;
- *  `'pass'` lets the next slot try. Handlers that return nothing are
- *  treated as `'pass'`. */
-type Decision = 'claim' | 'pass' | void;
 /** 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. */
@@ -1763,11 +3272,6 @@ interface ToolCtx<TScratch = unknown> {
     worldX: number;
     worldY: number;
     modifiers: ToolModifiers;
-    /** Hit-test result for the current event. Populated by the dispatcher
-     *  before each handler call. Tools that don't use declarative routing
-     *  can ignore this. Optional for migration; will become
-     *  required once the routing migration is complete. */
-    target?: HitResult;
     selection: SelectionApi;
     /** Adapter/scene access — opaque at this layer; tools that need it
      *  cast to a known shape. This layer doesn't constrain it. */
@@ -1797,40 +3301,8 @@ interface ToolCtx<TScratch = unknown> {
      *  rotation handle, etc.) lands in the same overlay as Canvas's own
      *  bounds/origin records. Tools should call this conditionally with `?.`. */
     debug?: DebugSink;
-    /** Kit-internal: route-resolution reporter. The dispatcher populates
-     *  this; the declarative routing factory calls it after each successful
-     *  resolveRoute() hit so the dispatcher can publish the last-resolved
-     *  snapshot to debug-overlay consumers. Underscore prefix signals
-     *  "do not consume in tool code." */
-    __reportRoute?: (info: RouteResolvedInfo) => void;
     scratch: TScratch;
 }
-interface PointerChannel<TScratch> {
-    onDown?: (e: PointerEvent, ctx: ToolCtx<TScratch>) => Decision;
-    onClick?: (e: PointerEvent, ctx: ToolCtx<TScratch>) => Decision;
-}
-interface DragChannel<TScratch> {
-    onStart?: (e: PointerEvent, ctx: ToolCtx<TScratch>) => Decision;
-    onMove?: (e: PointerEvent, ctx: ToolCtx<TScratch>) => Decision;
-    onEnd?: (e: PointerEvent, ctx: ToolCtx<TScratch>) => Decision;
-    onCancel?: (ctx: ToolCtx<TScratch>) => void;
-}
-interface KeyboardChannel<TScratch> {
-    onDown?: (e: KeyboardEvent, ctx: ToolCtx<TScratch>) => Decision;
-    onUp?: (e: KeyboardEvent, ctx: ToolCtx<TScratch>) => Decision;
-}
-interface WheelChannel<TScratch> {
-    onWheel?: (e: WheelEvent, ctx: ToolCtx<TScratch>) => Decision;
-}
-/** Double-tap (double-click) channel. Fires on the pointerup of the second
- *  sub-threshold tap when it follows a previous sub-threshold tap within the
- *  dispatcher's `dblTap.windowMs` and `dblTap.maxDistance` (CSS px). The
- *  scratch handed to the handler is fresh — `dblTap` is not part of a drag
- *  pipeline, so `initScratch()` runs immediately before the call. A `'claim'`
- *  return suppresses the regular `pointer.onClick` for this gesture. */
-interface DblTapChannel<TScratch> {
-    onTap?: (e: PointerEvent, ctx: ToolCtx<TScratch>) => Decision;
-}
 /** World-space AABB shape used by `previewBounds`. Alias of the kit-wide
  *  `Bounds` type — the optional `rotation` field carries through so a tool
  *  can report an oriented preview rect (e.g. mid-rotate). */
@@ -1867,6 +3339,22 @@ interface Tool<TScratch = unknown> {
      * every implicit-or-declared tag (i.e. `normal` in the default preset).
      */
     capabilities?: CapabilityTag[];
+    /**
+     * Actions this tool owns and needs registered while it is in the tools
+     * registry — e.g. polygon's `polygon.adjustSides`, which its own bindings
+     * reference by id.
+     *
+     * Declared here rather than registered by the hook with `useAction`,
+     * because tool hooks run wherever the consumer calls them — for
+     * `<SceneCanvas>` that is ABOVE `<ActionsProviderIfRoot>`, where
+     * `useActionsRegistry()` returns null and `useAction` silently no-ops. The
+     * result was a binding pointing at an action id nothing had registered, so
+     * the gesture fell through to whatever matched next (polygon's
+     * wheel/arrow-key side adjustment did nothing and `nudge.*` moved the
+     * selection instead). `<ToolActionsMounter>` registers these from inside
+     * the provider.
+     */
+    actions?: Action[];
     /** Optional caller-supplied key. Most built-in tools have their activation
      *  key declared in `BUILTIN_SELECT_KEYS` in `useKeybindings.ts`; this field
      *  is for tools that want their activation key to be configurable by the
@@ -1878,25 +3366,6 @@ interface Tool<TScratch = unknown> {
     initScratch?: () => TScratch;
     onActivate?: (ctx: ToolCtx<TScratch>) => void;
     onDeactivate?: (ctx: ToolCtx<TScratch>) => void;
-    pointer?: PointerChannel<TScratch>;
-    drag?: DragChannel<TScratch>;
-    keyboard?: KeyboardChannel<TScratch>;
-    wheel?: WheelChannel<TScratch>;
-    /** Double-tap channel — fires when two sub-threshold taps land within
-     *  `dblTap.windowMs` / `dblTap.maxDistance` of each other. Lets tools
-     *  enter modal modes (e.g. select → edit-anchors) without consumers
-     *  attaching `onDoubleClick` to a wrapper DOM node. */
-    dblTap?: DblTapChannel<TScratch>;
-    /**
-     * State-aware predicate. When true, this tool claims every pointerdown
-     * and bypasses the affordance layer hit-test pipeline. Used by tools
-     * in modal states (pen mid-path, text mid-edit) where affordance hits
-     * would otherwise interrupt the in-progress gesture.
-     *
-     * Default: undefined (treated as false). Called once per pointerdown
-     * with the tool's current ctx (scratch + view + modifiers).
-     */
-    claimsAll?: (ctx: ToolCtx<TScratch>) => boolean;
     cursor?: string | ((ctx: ToolCtx<TScratch>) => string);
     /** Presentation metadata for tool palettes. See `ToolPresentation`. */
     presentation?: ToolPresentation<TScratch>;
@@ -1924,37 +3393,18 @@ interface Tool<TScratch = unknown> {
      *  nothing — typically gated on a scratch field like
      *  `if (!scratch.overlay) return`. */
     overlay?: RenderLayer<unknown>;
-    /** Declarative gesture-bindings the
-     *  dispatcher consults while this tool is active. Empty/undefined keeps
-     *  legacy imperative-channel behavior. See
+    /** Declarative gesture bindings — the tool's entire input surface. The
+     *  gesture dispatcher consults these at active scope while this tool is
+     *  active, and at hotkey scope while it is held. See
      *  `docs/superpowers/specs/2026-05-16-registry-unification-design.md`. */
     bindings?: GestureBinding[];
-    /**
-     * Optional. When set, the dispatcher consults this before its built-in
-     * node/empty hit-test. If it returns a value, that target replaces the
-     * default `target` on the routed action's ctx. The string `target` is
-     * the tool's own vocabulary — the dispatcher does not interpret it.
-     *
-     * Used for tools that need richer sub-object hit categories (e.g., pen
-     * edit-mode's anchor/handle/segment vs the default node/empty).
-     */
-    hitOverride?(ctx: {
-        worldX: number;
-        worldY: number;
-        scratch: TScratch;
-        view: View;
-        modifiers: ToolModifiers;
-    }): {
-        target: string;
-        extra?: unknown;
-    } | null;
     /** Reflection escape hatch: when this `Tool` was produced by `defineTool`,
      *  the source `ToolDef` is attached here so introspection consumers
-     *  (`buildActionRegistry`, `findConflicts`, the toolkit-builder UI, the
-     *  reflection demo) can walk the declarative source rather than the
-     *  translated runtime channels. Tools constructed without `defineTool`
-     *  may leave this undefined. Typed as `unknown` to keep this file from
-     *  importing the routing types — consumers cast at the use site. */
+     *  (`buildRouteRegistry`, `findConflicts`, the toolkit-builder UI, the
+     *  reflection demo) can read the authored form — `hookName` in particular,
+     *  which the runtime `Tool` doesn't carry. Tools constructed without
+     *  `defineTool` may leave this undefined. Typed as `unknown` to keep this
+     *  file from importing the routing types — consumers cast at the use site. */
     def?: unknown;
 }
 /** Internal alias for "a Tool of any scratch type" — used in registries and
@@ -1965,161 +3415,187 @@ type AnyTool = Tool<any>;
 
 /**
  * @experimental
- * Result of an affordance hit — what the dispatcher wires up as the gesture.
- * Nominates the drag channel and (optionally) initial scratch state.
- */
-interface AffordanceBinding<TScratch = unknown> {
-    drag: DragChannel<TScratch>;
-    /** Initial scratch passed to drag.onStart. Lets the affordance pre-fill
-     *  state from what its region's binding already computed (anchor: 'br',
-     *  targetId: 'g1', etc.) so the tool's onStart doesn't re-derive it. */
-    initialScratch?: TScratch;
-}
-
-/**
- * Canvas size in CSS pixels — passed to `draw` for layers that anchor to
- * canvas edges (e.g. the debug overlay's layer-list panel). The GL backend
- * supplies it explicitly so layers don't have to know about DPR.
+ * A single entry in `Action.defaultBinding[]`. Either a bare `GestureSpec`
+ * (no per-binding opts) or an object form that pairs a spec with
+ * `BindingOpts` for parametric actions (e.g. `{ params: { axis: 'x' } }`).
+ * Use the object form when two bindings for the same action differ only in
+ * a runtime parameter — the dispatcher extracts `opts.params` and passes
+ * them to `ImmediateInvoker.run` as its second argument.
  */
-interface Dims {
-    width: number;
-    height: number;
-}
+type BoundGesture = GestureSpec | {
+    spec: GestureSpec;
+    opts: BindingOpts;
+};
 /**
- * A single named render sub-layer within a canvas renderer.
- *
- * @template TData - The data object passed to each draw call.
+ * @experimental
+ * Single registered action. v1: one binding per action.
  */
-interface RenderLayer<TData> {
-    /** Unique identifier used in visibility maps and ordering arrays. */
+interface Action {
     id: string;
-    /** Human-readable name for UI toggles. */
     label: string;
+    /** The gesture-spec form of the binding, read by the gesture dispatcher.
+     *  May be a single `GestureSpec`, a bare `GestureSpec[]` (any-of semantics),
+     *  or a `BoundGesture[]` where each entry is either a bare `GestureSpec` or
+     *  `{ spec, opts }` — use the object form for parametric actions where two
+     *  bindings for the same action differ only by `opts.params` (e.g. `flip`
+     *  with `axis: 'x'` vs `'y'`). The dispatcher extracts `opts.params` and
+     *  passes them to `ImmediateInvoker.run` as its second argument. */
+    defaultBinding?: GestureSpec | BoundGesture[];
+    /** Names of the deps this action's invoker reads (keys of `DepSchema`).
+     *  The dispatcher (and `trigger`, when `requires` is present) resolves
+     *  each name against the `DepRegistry` at invocation time and passes the
+     *  resulting bag to the invoker. Dev builds warn when the invoker reads a
+     *  dep it didn't declare here — see `buildDepsFromRequires`. */
+    requires?: readonly DepName[];
+    /** Inline-SVG icon for palette / toolbar surfaces. Mirrors
+     *  `ToolPresentation.icon` so a generic `<ActionBar>` can render from
+     *  action metadata the same way `<ToolPalette>` renders from tool
+     *  metadata. May be a static `ReactNode` or a function (rare; useful
+     *  for state-aware icons like a "lock" toggle). */
+    icon?: ReactNode | (() => ReactNode);
+    /** Grouping key for palette/menu surfaces. Free-form string; the kit
+     *  ships defaults for `'align'` (six edges/centers), `'distribute'`
+     *  (two axes), and recommends `'pathfinder'` for boolean ops. */
+    group?: string;
+    /** Display override for the keyboard shortcut. When omitted, palette
+     *  surfaces derive a label from `defaultBinding` via their own
+     *  formatter. */
+    shortcut?: string;
+    /** Pluggable invocation strategy. The gesture dispatcher routes matched
+     *  bindings through `invoker.start` / `invoker.run` depending on timing.
+     *  All kit-standard descriptors ship one; consumer-supplied actions
+     *  without an invoker can still register but won't be triggered. */
+    invoker?: Invoker;
+    /** When set to `'hotkey'`, this action's `defaultBinding` rides the hotkey
+     *  `BindingScope` instead of the ambient scope — meaning it beats any
+     *  active-tool binding on the same input shape. Use for tool-switch
+     *  shortcuts and global held-key triggers. Default: ambient. */
+    scope?: 'hotkey';
     /**
-     * Emit a DrawCommand tree for the GL backend to dispatch.
+     * @experimental
+     * Optional predicate the command palette consults when rendering. Return
+     * `true` when the action is currently triggerable. Return a reason string
+     * (e.g. `'Selection required'`) when disabled — the palette greys out
+     * the row, skips it in keyboard nav, ignores clicks, and shows the
+     * reason next to the label. Keystroke dispatch (the registered binding)
+     * is unaffected; the action's own `run` should self-guard.
      *
-     * For world-space layers (the default), emit commands in WORLD COORDS —
-     * `drawLayers` automatically wraps them in `{ kind: 'group', transform:
-     * viewToMat3(view), ... }` before handing them to the renderer. Do NOT
-     * apply the view transform yourself.
+     * **Contract:** must be pure (no side effects), fast (< 4ms in dev), and
+     * must not throw. If a call throws or exceeds the budget in dev mode,
+     * `evaluateEnabled` logs a one-time warning per action id; throws are
+     * caught and treated as disabled with reason `'(predicate threw)'`.
      *
-     * For screen-space layers (`space: 'screen'`), emit commands in CSS-pixel
-     * coords directly; `drawLayers` passes them through unchanged. If part
-     * of a screen-space layer's output needs to track the view, wrap that
-     * subset manually with `viewToMat3(view)`.
-     */
-    draw: (data: TData, view: View, dims: Dims) => DrawCommand[];
-    /**
-     * Whether the layer is shown when no explicit visibility entry exists.
-     * Defaults to `true` when absent.
-     */
-    defaultVisible?: boolean;
-    /**
-     * When true, the layer is always drawn regardless of the visibility map.
-     * Useful for layers that must never be hidden (e.g. base grid).
-     */
-    alwaysOn?: boolean;
-    /**
-     * Coordinate space the layer draws in.
+     * Snapshot-on-open semantics: the palette evaluates `enabled` once when
+     * opened and does NOT re-evaluate on selection changes while open. Live
+     * reactive updates are deferred — palette is short-lived.
      *
-     * - `'world'` (default): the layer's `draw` returns world-space commands;
-     *   `drawLayers` wraps them in a `kind: 'group'` with `viewToMat3(view)`
-     *   automatically.
-     * - `'screen'`: the layer's `draw` returns screen-space (CSS-pixel)
-     *   commands; `drawLayers` passes them through unchanged. World-anchored
-     *   chrome inside a screen-space layer must call `worldToScreen` or wrap
-     *   the relevant subset with `viewToMat3(view)` manually.
+     * The reason set is a closed enum — to add a new reason, edit
+     * `ActionDisabledReason` and the consumer's display map.
+     *
+     * The optional `deps` argument is the same bag passed to
+     * `ImmediateInvoker.run`; callers (`evaluateEnabled` / the ActionBar) may
+     * synthesize it from the surrounding `DepRegistry` so predicates can
+     * inspect selection / scene / etc. Predicates that don't need deps just
+     * ignore the arg.
      */
-    space?: 'world' | 'screen';
+    enabled?: (deps?: ActionDeps) => true | ActionDisabledReason;
     /**
-     * Optional hit-test. When defined, the dispatcher consults this on
-     * pointerdown (top-down layer order) before falling through to the
-     * active tool's slot walk. First non-null result wins; null means
-     * "I don't claim this hit, try the next layer."
+     * Declarative eligibility rule, evaluated against the current
+     * `RuleCtx` by the dispatcher before invoking `start()`. Omitted =
+     * always eligible.
      *
-     * Coordinates are world-space. The `data` arg is the layer's
-     * configured data slot (same as `draw`); `view` and `dims` mirror
-     * `draw`'s arguments.
+     * Accepts either a fluent `Condition` (callable with `.rule`) or a
+     * raw `Rule` tree; the dispatcher normalizes via `.rule` unwrap.
+     *
+     * Prefer `capability:`-based rules (e.g. `{ capability: 'transforms-selection' }`)
+     * over `mode:` rules — capability rules survive new modes being added
+     * that allow the same capability.
      */
-    hitTest?: (worldX: number, worldY: number, data: TData, view: View, dims: Dims, 
-    /** Chrome-caps visibility predicate. When supplied, the layer must
-     *  not return a hit from any chrome element whose id reports
-     *  `false`. Absent → every element is hittable. */
-    isVisible?: (id: string) => boolean) => AffordanceBinding | null;
+    eligible?: Rule | Condition;
     /**
-     * Called on every pointermove when no gesture is currently captured.
-     * Lets layers (e.g. HUD widgets) track hover state without participating
-     * in the drag pipeline. Coords are world-space; the layer is responsible
-     * for any further conversion (e.g. world→screen for screen-space layers)
-     * and for its own throttling.
+     * CSS cursor shown while the pointer hovers a spot where this action
+     * would win the drag. The hover-cursor pump (in `useGestureDispatcher`)
+     * runs `Dispatcher.resolveOnly` on each idle pointermove — the same
+     * match walk a real pointerdown takes — and applies the winning
+     * action's `cursor`, so the hint and the actual click target stay in
+     * sync by construction. Omitted = no override (the active tool's
+     * `Tool.cursor` shows). Affordance hits are resolved earlier in the
+     * pump via `AffordanceRegion.cursor` and never reach this field.
+     *
+     * Static string only. Prediction runs `enabled()` but cannot run the
+     * invoker, so an action that matches yet bails at `start()` (empty
+     * handle) may still show its cursor — keep `enabled` accurate for
+     * actions that declare one.
      */
-    onUncapturedMove?: (worldX: number, worldY: number, evt: PointerEvent, view: View, dims: Dims) => void;
+    cursor?: string;
     /**
-     * Called when the cursor leaves the canvas element. Lets layers clear
-     * any hover state they're holding.
+     * CSS cursor shown while THIS action's ongoing handle is in flight —
+     * grabbing while panning, `move` while dragging a selection, `crosshair`
+     * while pulling a marquee.
+     *
+     * Separate from `cursor` because the two answer different questions:
+     * `cursor` is a prediction ("a drag from here would pan"), this is a state
+     * ("you are panning"). An action can declare either, both, or neither;
+     * with only `cursor` set, the hover hint holds for the duration of the
+     * gesture.
+     *
+     * This is where mid-gesture cursors live now. They used to come from the
+     * tool side — `ViewportToolDef.engaged.cursor` for a phase-gated string,
+     * or a function-form `Tool.cursor` reading the gesture scratch out of the
+     * tool-routing dispatcher. Both belonged to a pipeline whose whole job was
+     * being taken over by bindings, and neither could describe a cursor for an
+     * action a tool doesn't own.
      */
-    onUncapturedLeave?: () => void;
+    activeCursor?: string;
 }
+/**
+ * @experimental
+ * Closed enum of reasons an action might report itself as disabled. The
+ * consumer (palette, menu, etc.) maps these symbolic values to display
+ * strings via its own label map — see `demo/CommandPalette.tsx` for the
+ * canonical mapping.
+ */
+declare const ActionDisabledReason: {
+    readonly SelectionRequired: "selection-required";
+    readonly SceneEmpty: "scene-empty";
+    readonly NotApplicable: "not-applicable";
+    /** Sentinel: the predicate threw. Surfaced by `evaluateEnabled`'s catch. */
+    readonly PredicateThrew: "predicate-threw";
+};
+type ActionDisabledReason = (typeof ActionDisabledReason)[keyof typeof ActionDisabledReason];
 
-interface ToolsDispatcher {
-    onPointerDown: (e: PointerEvent) => void;
-    onPointerMove: (e: PointerEvent) => void;
-    onPointerUp: (e: PointerEvent) => void;
-    onKeyDown: (e: KeyboardEvent) => void;
-    onKeyUp: (e: KeyboardEvent) => void;
-    onWheel: (e: WheelEvent) => void;
-    /** Force-cancel any in-flight gesture (used on explicit tool switch). */
-    cancelGesture: () => void;
-    /** Whether a gesture is currently in flight. Used by `useTools` to
-     *  decide whether a modifier-key press should engage the hotkey slot
-     *  (no, if mid-gesture). */
-    hasActiveGesture: () => boolean;
-    /** Scratch of the in-flight gesture, or `null` when idle. Exposed so
-     *  consumers (cursor resolution, debug overlays) can read what the active
-     *  tool is currently tracking. Read-only — do NOT mutate via this getter. */
-    getActiveScratch: () => unknown;
-    /** Most recent route resolution emitted by a declarative tool, or null
-     *  if none has fired yet. Snapshot — safe to read on every render. */
-    getLastRoute: () => RouteResolvedInfo | null;
-    /** Resolve a synthetic (phase, gesture, hit, modifiers) query against the
-     *  current slot occupants WITHOUT executing the matched action. Walks slots
-     *  in real precedence order (hotkey > active > ambient) and consults each
-     *  tool's attached `def` (the declarative `ToolDef` produced by
-     *  `defineTool`). Tools without an attached `def` (imperative-only) are
-     *  invisible to this query. Returns the first match, or null if no slot
-     *  resolves the query. Pure: no scratch mutation, no scene mutation, no
-     *  RouteResolvedInfo emission. */
-    resolveOnly: (query: ResolveQuery) => ResolveResult | null;
-}
-/** Synthetic resolution query — what the static widget asks "if a pointer
- *  event landed on `hit` with these `modifiers`, which declarative route
- *  would the dispatcher fire in this phase + gesture?" */
-interface ResolveQuery {
-    phase: 'initial' | 'engaged';
-    gesture: 'click' | 'drag' | 'pointerDown' | 'dblTap' | 'wheel';
-    hit: HitResult;
-    modifiers: ToolModifiers;
-}
-/** Successful resolution: which tool, in which slot, matched which route-table
- *  key. `matchedKey` is `'*'` for function-form drag (no table to discriminate)
- *  and for wheel routes (single ActionFn). */
-interface ResolveResult {
-    toolId: string;
-    slot: 'hotkey' | 'active' | 'ambient';
-    gesture: 'click' | 'drag' | 'pointerDown' | 'dblTap' | 'wheel';
-    phase: 'initial' | 'engaged';
-    matchedKey: string;
+/**
+ * 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';
 }
 
 interface ToolsApi {
     /** Current active-slot tool id. */
     active: string;
-    /** Set the active-slot tool. Cancels any in-flight gesture. */
+    /** Set the active-slot tool. The gesture dispatcher watches the active
+     *  tool and cancels any in-flight handle itself. */
     setActive: (id: string) => void;
     /** Currently hotkey-engaged tool id (or `null`). Derived as the top of
      *  the hotkey stack for backwards compat with the pre-stack API. */
     hotkeyEngaged: string | null;
-    /** Engage a hotkey-slot tool by id. No-op if a gesture is in flight. */
+    /** Engage a hotkey-slot tool by id. */
     engageHotkey: (id: string) => void;
     /** Disengage the hotkey-slot tool, if any. */
     disengageHotkey: () => void;
@@ -2127,13 +3603,6 @@ interface ToolsApi {
     ambient: readonly AnyTool[];
     /** Full registry — for userland UI (palette buttons, etc.). */
     registry: Readonly<Record<string, AnyTool>>;
-    /** The dispatcher `<Canvas>` wires to its DOM events. */
-    dispatcher: ToolsDispatcher;
-    /** Increments whenever an in-flight gesture starts, transitions phase, or
-     *  ends. Consumers (e.g. `<Canvas>` cursor resolution) include this in
-     *  their render deps to re-evaluate derived state on real DOM events
-     *  rather than waiting for an unrelated re-render. */
-    gestureTick: number;
     /** 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
@@ -2445,6 +3914,13 @@ type SelectOption = {
     value: string;
     label: ReactNode;
     isDisabled?: boolean;
+    /**
+     * Plain-text form of `label`, for type-to-select and screen readers.
+     * Only needed when `label` isn't a bare string — a label built from
+     * elements has no text React Aria can read off it. A string label
+     * supplies this itself.
+     */
+    textValue?: string;
 };
 type Key$1 = string | number;
 type SelectProps<T extends Key$1 = string> = Omit<SelectProps$1<object>, 'children' | 'className' | 'selectedKey' | 'defaultSelectedKey' | 'onSelectionChange'> & {
@@ -2475,7 +3951,7 @@ type SelectItemProps = Omit<ListBoxItemProps, 'className' | 'children'> & {
     children?: ReactNode;
     className?: string;
 };
-declare function SelectItem({ children, className, ...rest }: SelectItemProps): react_jsx_runtime.JSX.Element;
+declare function SelectItem({ children, className, textValue, ...rest }: SelectItemProps): react_jsx_runtime.JSX.Element;
 
 type ComboBoxOption = {
     value: string;
@@ -2600,7 +4076,7 @@ interface Plot2DProps {
     /** Pointer down on the SVG. Receives both plot- and model-space coords
      *  pre-computed so consumers don't repeat the rect/transform dance. */
     onPointerDown?: (e: PointerEvent$1<SVGSVGElement>, coords: Plot2DCoords) => void;
-    onKeyDown?: (e: KeyboardEvent$1<SVGSVGElement>) => void;
+    onKeyDown?: (e: KeyboardEvent<SVGSVGElement>) => void;
     children?: ReactNode;
 }
 interface Plot2DHandle {