@weasel-js/routing 1.5.0

package/dist/index-BOlkWrA-.d.ts

@@ -0,0 +1,2446 @@
+import { CapabilityTag } from '@weasel-js/modes';
+import * as react from 'react';
+import { ReactNode } from 'react';
+import { CursorSpec } from '@weasel-js/cursor';
+import { ClaimableGesture, GestureSpec, InputEvent, TargetSpec, ParsedModifiers, GestureName, IngestItem } from '@weasel-js/gestures';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { Op } from '@weasel-js/history';
+
+/**
+ * The primitives the routing surface is typed in.
+ *
+ * Routing decides which action a gesture runs. To do that it has to name a
+ * viewport, a rect, a node id and a selection — but it never constructs,
+ * projects or renders any of them. So they are declared here as structural
+ * interfaces with no dependencies, and `@weasel-js/core` re-exports each from
+ * the path its own call sites have always used. Same arrangement as `Op`,
+ * which is declared in `@weasel-js/history` and re-exported by
+ * `core/ops/types`.
+ *
+ * Authority for the *behavior* behind each of these stays in core: `View` is
+ * what `core/viewport` maintains, `SelectionApi` is what `useSelection`
+ * returns, `DeviceProfile` is what `resolveDeviceProfile` detects. Changing
+ * one of these shapes is a change to core's contract that happens to be
+ * spelled here.
+ */
+/** An opaque scene-node identifier. Branded so a bare string cannot stand in. */
+type NodeId = string & {
+    readonly __brand: 'NodeId';
+};
+/**
+ * Viewport state. `(view.x, view.y)` is the world point currently rendered at
+ * the canvas top-left; `view.scale.x` / `view.scale.y` is pixels per world
+ * unit on each axis.
+ *
+ * The one outright 2D dead end in the routing surface: a `View` names no
+ * orientation, so a kernel with a camera cannot express its viewport as one.
+ */
+interface View {
+    x: number;
+    y: number;
+    scale: {
+        x: number;
+        y: number;
+    };
+}
+/**
+ * Axis-aligned rectangle in world space. The optional `rotation` (radians,
+ * around the AABB center) lets chrome attach an orientation to an otherwise
+ * axis-aligned rect without a parallel type.
+ */
+interface Bounds {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    rotation?: number;
+}
+/** Selection click policy. `single` always replaces; `multi` toggles when the
+ *  configured extend key is held, otherwise replaces. */
+type SelectionMode = 'single' | 'multi';
+/** Modifier key used to extend the selection in `multi` mode. */
+type SelectionExtendKey = 'shift' | 'meta' | 'ctrl';
+/** The selection as routing reads and writes it. */
+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;
+    };
+}
+/**
+ * Facts about the device the canvas is running on, as the eligibility rules
+ * read them (`coarsePointer`, `canHover`). Deliberately not a form-factor
+ * concept — there is no `isPhone` here and there should never be one.
+ */
+interface DeviceProfile {
+    /** `matchMedia('(pointer: coarse)')` — the primary pointer is imprecise. */
+    readonly coarsePointer: boolean;
+    /** `matchMedia('(hover: hover)')` — the primary pointer can hover. */
+    readonly canHover: boolean;
+    /** Live device pixel ratio. */
+    readonly dpr: number;
+    /** Multiplier for handle sizes and hit radii. Derived from `coarsePointer`
+     *  unless explicitly overridden. */
+    readonly targetScale: number;
+}
+/** Which kind of handle a recorded hit region belongs to. */
+type HandleKind = 'corner' | 'rotation' | 'anchor';
+/** The geometry a hit region actually tests against, as reported to the debug
+ *  sink so the overlay can draw the real shape rather than its bounding box. */
+type HitShape = {
+    kind: 'rect';
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    rotation?: number;
+} | {
+    kind: 'circle';
+    cx: number;
+    cy: number;
+    r: number;
+} | {
+    kind: 'path';
+    d: Path2D;
+};
+/**
+ * Where a tool reports its internal hit math so the debug overlay can draw it.
+ * Routing threads a sink through `ToolCtx` and never calls one.
+ */
+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;
+}
+/**
+ * Snapshot of modifier-key state at dispatch. Distinct from
+ * `EventModifiers` in `@weasel-js/gestures`, which mirrors the DOM's
+ * `altKey`/`ctrlKey` spelling; this is the kit-facing one.
+ */
+interface ModifierState {
+    alt: boolean;
+    shift: boolean;
+    meta: boolean;
+    ctrl: boolean;
+}
+/** Which edges a resize gesture pins. `free` means the axis is unconstrained. */
+type ResizeAnchor = {
+    x: 'min' | 'max' | 'free';
+    y: 'min' | 'max' | 'free';
+};
+
+/**
+ * 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;
+    /**
+     * How far the viewport is zoomed in, as one number — `1` at native scale.
+     *
+     * A scalar rather than the `View` this used to carry, because `zoomAtLeast`
+     * is the only selector that ever read one and a number is all it needs. A
+     * host whose viewport is a camera has no `View` to hand over and would
+     * otherwise have to invent one to use eligibility at all; it omits this
+     * instead, and `zoomAtLeast` declines rather than matching on a fiction.
+     */
+    readonly zoom?: number;
+    /** 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;
+    /** Device facts — pointer coarseness, hover capability, density.
+     *
+     *  Absent (legacy ctx builders) is treated as
+     *  {@link DEFAULT_DEVICE_PROFILE}: a fine pointer that can hover, at
+     *  density 1. That is what the kit assumed before this field existed, so
+     *  an absent profile is behavior-preserving by construction. */
+    readonly device?: DeviceProfile;
+}
+/** The live state a `RuleCtx` is assembled from — the chrome context plus
+ *  what the active mode allows. */
+interface BuildRuleCtxArgs {
+    focused: boolean;
+    selection: readonly NodeId[];
+    multiActive: boolean;
+    modifiers: ModifierState;
+    action: {
+        kind: string | null;
+        id: string | null;
+    };
+    hover: NodeId | null;
+    /** See {@link RuleCtx.zoom}. */
+    zoom?: number;
+    mode: string;
+    allowedCapabilities: ReadonlySet<CapabilityTag>;
+    /** Optional — omitted means "resizable" (handles show). See {@link RuleCtx}. */
+    selectionResizable?: boolean;
+    /** Optional — omitted means "no path is being anchor-edited". */
+    editingAnchors?: boolean;
+    /** Optional — omitted means {@link DEFAULT_DEVICE_PROFILE}. */
+    device?: DeviceProfile;
+}
+/**
+ * Capability set to assume when no mode registry is wired.
+ *
+ * "No modes configured" means *everything the default mode permits*, not
+ * *nothing permitted*. The empty set is the wrong default: it makes every
+ * `capability:` rule evaluate false, so a kit default written the
+ * recommended way (capability rules outlive new modes; mode rules have to
+ * be edited) would silently hide its chrome for every consumer that hasn't
+ * opted into modality. `NORMAL.allows` plus the implicit tags is what a
+ * mode-less canvas actually behaves like.
+ */
+declare const DEFAULT_ALLOWED_CAPABILITIES: ReadonlySet<CapabilityTag>;
+/** Gather the current canvas and mode state into the context that action
+ *  eligibility and chrome-visibility rules are evaluated against. */
+declare function buildRuleCtx(args: BuildRuleCtxArgs): RuleCtx;
+
+/**
+ * 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;
+    /** Matches `ctx.device.coarsePointer` — the primary pointer is imprecise
+     *  (touch, most styluses). Absent device is treated as `false`. */
+    coarsePointer?: boolean;
+    /** Matches `ctx.device.canHover` — the primary pointer can hover. Absent
+     *  device is treated as `true`. */
+    canHover?: 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;
+};
+/** Constant rules. Kept here so they have a single source. */
+declare const ALWAYS: Rule;
+/** A rule that never passes. `any` of nothing is false. */
+declare const NEVER: Rule;
+/**
+ * Render a {@link Rule} as a short human-readable string, for inspectors and
+ * diagnostics that need to say WHICH rule decided something.
+ *
+ * ```
+ * { capability: 'edits-page' }               → capability:edits-page
+ * { all: [{ mode: 'normal' }, { focused: true }] } → all(mode:normal, focused:true)
+ * { not: { selection: { empty: true } } }    → not(selection:empty=true)
+ * { when: function hasPath() { … } }         → when(hasPath)
+ * ```
+ *
+ * Never throws and always terminates — unlike `JSON.stringify`, which throws
+ * on a cyclic value and renders the `when` arm as a useless `{}`.
+ */
+declare function describeRule(rule: Rule): string;
+/** Evaluate a rule against a context. Pure, and cheap enough to run per
+ *  frame for every piece of chrome. */
+declare function evaluate(rule: Rule, ctx: RuleCtx): boolean;
+/**
+ * Composable eligibility predicate with a fluent surface. Carries its
+ * underlying `Rule` tree at `.rule` so the dispatcher's eligibility filter and
+ * the chrome resolver can introspect and share trees.
+ *
+ * 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;
+}
+
+/** The detected half of a profile — everything except the derived scale. */
+type DetectedDeviceFacts = Omit<DeviceProfile, 'targetScale'>;
+/**
+ * Handle/hit multiplier applied on a coarse pointer.
+ *
+ * 8px handle → 14px; 24px rotation distance → 42px. Counting the
+ * surrounding grab zone, that lands in the Apple HIG 44pt / Material 48dp
+ * minimum-touch-target band. One constant so it is tunable in one place.
+ */
+declare const COARSE_TARGET_SCALE = 1.75;
+/**
+ * Fold consumer overrides over detected facts and derive `targetScale`.
+ *
+ * `targetScale` is re-derived AFTER the merge, so an override of
+ * `coarsePointer` alone scales the chrome as expected. An explicit
+ * `targetScale` override wins over the derivation.
+ */
+declare function resolveDeviceProfile(detected: DetectedDeviceFacts, overrides?: Partial<DeviceProfile>): DeviceProfile;
+/**
+ * Assumed when `matchMedia` is unavailable (SSR, jsdom) and used as the
+ * absent-means value for `RuleCtx.device`.
+ *
+ * Derived from `resolveDeviceProfile` rather than hand-written, so it can
+ * never drift from what the function would compute for the same facts. A
+ * mouse-like device is the safe default: it is what the kit has always
+ * assumed, so an absent profile changes nothing for existing consumers.
+ */
+declare const DEFAULT_DEVICE_PROFILE: DeviceProfile;
+
+/**
+ * Invoker — pluggable invocation strategy for an Action.
+ *
+ * An Action's `invoker` field describes how it's run. `immediate` invokers
+ * fire once (delete, align, undo). `ongoing` invokers open a phase machine
+ * driven by the dispatcher (move, resize, pinch-zoom).
+ *
+ * See `docs/superpowers/specs/2026-05-16-registry-unification-design.md`
+ * § "Types" for the full design.
+ */
+
+/** 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;
+    /** Id of whatever produced this hit — a kit affordance's `id`, or the
+     *  registered layer's id. Read only by the dispatcher's dead-claim warning today. */
+    owner?: string;
+    /** `'exclusive'` means no binding may act on this point unless its target
+     *  consults the affordance. `'shared'` (the default) competes on scope and
+     *  specificity as bindings always have. */
+    strength?: 'exclusive' | 'shared';
+    /** Which gestures an exclusive claim bars. Omitted bars all of them. */
+    claimedKinds?: readonly ClaimableGesture[];
+    /** 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;
+    /** 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?: CursorSpec;
+    /**
+     * 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;
+    /**
+     * The pointer in client/screen pixels, for an action that has to place DOM
+     * at the pointer. Absent on every invocation whose event carries no client
+     * coordinates — a keystroke, a UI-driven trigger, a synthetic probe — so
+     * read it with a fallback rather than assuming a point.
+     *
+     * A view-mutating drag wants `drag.screenDelta`, not the difference of two
+     * of these: world deltas are self-referential mid-pan, and so is any delta
+     * taken across a view change.
+     */
+    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 {
+    /** Gesture behaviors the action's own invoker runs. Routing carries the
+     *  array to the action and never reads an element, so the element type is
+     *  open here; `@weasel-js/core` narrows it to `ActionBehavior<unknown,
+     *  unknown, unknown>[]`, which is what a behavior is authored against. */
+    behaviors?: 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>);
+}
+/** Resolve `BindingOpts.params` to a concrete record (calling the thunk if
+ *  needed). Returns `undefined` for absent params. */
+declare function resolveParams(params: BindingOpts['params']): Record<string, unknown> | undefined;
+/** 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;
+}
+/**
+ * What a `polyline` overlay is, in a word — the narrowest thing an action can
+ * say about how its run should look without naming a paint.
+ *
+ * The named roles are the kit's; a painter maps each to a style and falls back
+ * to plain chrome for one it does not know, so a package outside core can coin
+ * its own and still be drawn.
+ */
+type OverlayRole = 
+/** Generic in-flight chrome — the marquee/lasso paint. */
+'chrome'
+/** A cut the gesture would make. */
+ | 'cut'
+/** An edge the gesture would author between two points. */
+ | 'connector' | (string & {});
+/**
+ * What an in-flight gesture proposes to paint *beside* the scene, returned by
+ * `OngoingHandle.overlay()` — a marquee rect, a lasso trail, the outline of a
+ * shape being dragged out, the line a slice would cut along.
+ *
+ * Every variant is world geometry and nothing else. No `DrawCommand`, no
+ * color, no coordinate space to choose: an action that reached for any of
+ * those would be publishing core's own 2D vocabulary, and a surface rendering
+ * the same gesture some other way could not read it. `resolveOverlays`
+ * normalizes this into `ResolvedOverlay`, which is what a painter consumes —
+ * `useDispatcherOverlayLayer` is core's, and it owns every style decision.
+ */
+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;
+} | {
+    /**
+     * An open run of world points the gesture is proposing — the slice
+     * action's cut line, `@weasel-js/diagram`'s routed connector.
+     *
+     * Geometry only, like every other variant: `role` is the whole of what
+     * an action says about appearance, and the painting surface is what
+     * turns it into a stroke. An action that picked its own color would be
+     * unpaintable by any renderer but the one it had in mind.
+     */
+    kind: 'polyline';
+    /** At least two points. Anything shorter is dropped in resolution. */
+    points: ReadonlyArray<{
+        x: number;
+        y: number;
+    }>;
+    /** What the run means. Omitted reads as {@link OverlayRole} `'chrome'`. */
+    role?: OverlayRole;
+} | {
+    /**
+     * 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';
+    /** Which preview the dispatcher's overlay draws. The kit's own shape
+     *  kinds are the ones it knows how to render; a consumer-defined kind
+     *  is legal and simply gets no live preview. */
+    shape: string;
+    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;
+    /**
+     * Subset of `previewIds()` the ghost layer paints at full opacity. The
+     * ghost alpha says "this is in flight under the pointer"; a node the
+     * gesture merely displaces — a layout sibling reflowing into its
+     * destination slot — is not, and reads better settled. Honored at
+     * subtree-root granularity.
+     */
+    previewOpaqueIds?(): Iterable<string> | null;
+    /**
+     * When `false`, the preview-ghost layer paints the ghost AND the
+     * source node stays visible at its committed pose. Defaults to
+     * `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. Invoked from the
+     *  command palette, or anywhere else 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;
+
+/**
+ * GestureBinding — connects a GestureSpec to an Action id (with per-binding
+ * options). Tools own arrays of these on their `bindings` field; ambient
+ * gesture-bindings are registered globally.
+ *
+ * See `docs/superpowers/specs/2026-05-16-registry-unification-design.md`.
+ */
+
+/** An interaction: a gesture spec composed with the id of the action it
+ *  invokes. Tools declare arrays of these; the dispatcher matches an incoming
+ *  input event against them and runs the winner's action. */
+interface GestureBinding {
+    spec: GestureSpec;
+    actionId: string;
+    opts?: BindingOpts;
+}
+/**
+ * @experimental
+ * 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.
+ */
+type BoundGesture = GestureSpec | {
+    spec: GestureSpec;
+    opts: BindingOpts;
+};
+/**
+ * @experimental
+ * The whole of an action `actionBindings` reads. Routing needs this much and
+ * none of `Action`'s palette fields, so it is the narrowest type the
+ * dispatcher's binding walk can be written against.
+ */
+interface BindingSource {
+    id: 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[];
+}
+/**
+ * @experimental
+ * Flatten an action's `defaultBinding` into `GestureBinding`s. A bare
+ * `GestureSpec` has `kind` at top level; the object form has `spec`.
+ */
+declare function actionBindings(action: BindingSource): GestureBinding[];
+
+/**
+ * @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.
+ */
+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";
+};
+/** Why an action is unavailable right now. */
+type ActionDisabledReason = (typeof ActionDisabledReason)[keyof typeof ActionDisabledReason];
+/**
+ * @experimental
+ * What a palette, menu or toolbar renders for an action. No part of this is
+ * read during dispatch.
+ */
+interface ActionPresentation {
+    label: string;
+    /** 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;
+}
+/**
+ * @experimental
+ * What routing consults: the bindings that reach the action, the deps its
+ * invoker reads, the gates it passes, and the cursors it claims.
+ */
+interface ActionDispatch extends BindingSource {
+    /** 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[];
+    /** 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';
+    /**
+     * @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.
+     *
+     * **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)'`.
+     *
+     * 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.
+     *
+     * 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.
+     */
+    enabled?: (deps?: ActionDeps) => true | ActionDisabledReason;
+    /**
+     * Declarative eligibility rule, evaluated against the current
+     * `RuleCtx` by the dispatcher before invoking `start()`. Omitted =
+     * always eligible.
+     *
+     * 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.
+     */
+    eligible?: Rule | Condition;
+    /**
+     * 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 value 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.
+     */
+    cursor?: CursorSpec;
+    /**
+     * 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.
+     */
+    activeCursor?: CursorSpec;
+}
+/**
+ * @experimental
+ * Single registered action. v1: one binding per action.
+ */
+interface Action extends ActionDispatch, ActionPresentation {
+}
+/**
+ * @experimental
+ * The whole of an actions registry the dispatcher reads. It walks the list
+ * once per event to build its actionId lookup and never mutates it, so the
+ * routing side depends on this rather than on `ActionsRegistry`, whose
+ * register / mute / trigger surface is the React provider's.
+ */
+interface ActionSource {
+    list(): readonly Action[];
+}
+
+/**
+ * @experimental
+ * Palette-side evaluation of `Action.enabled`. The dispatcher calls the
+ * predicate raw as a gate; this is the surface that also enforces the
+ * contract the predicate's JSDoc states — no throwing, under 4ms in dev.
+ */
+
+/**
+ * @experimental
+ * Result of evaluating an Action's `enabled` predicate.
+ */
+interface ActionEnabledResult {
+    enabled: boolean;
+    reason?: ActionDisabledReason;
+}
+/**
+ * @experimental
+ * Safely evaluate an action's `enabled` predicate. Returns `{enabled: true}`
+ * when no predicate is supplied. Catches throws and treats them as disabled
+ * with reason `'(predicate threw)'`. In dev mode, warns once per action id
+ * when a single call exceeds 4ms (single frame at 240fps — generous; real
+ * predicates should be sub-millisecond).
+ */
+declare function evaluateEnabled(action: Action, deps?: ActionDeps): ActionEnabledResult;
+
+/** Holds the live sources an action's declared dependencies resolve to.
+ *  Sources are thunks, read at invocation time, so an action never captures
+ *  stale state. */
+interface DepRegistry {
+    register<K extends DepName>(name: K, source: () => DepSchema[K]): () => void;
+    get<K extends DepName>(name: K): DepSchema[K] | undefined;
+}
+/** Provides the dep registry for a canvas. `<SceneCanvas>` mounts one; a
+ *  consumer registering its own dep sources must be inside it. */
+declare function DepRegistryProvider({ children }: {
+    children: ReactNode;
+}): react_jsx_runtime.JSX.Element;
+/** The dep registry in scope. Throws outside a `<DepRegistryProvider>`. */
+declare function useDepRegistry(): DepRegistry;
+/**
+ * Like `useDepRegistry`, but returns `null` when no `<DepRegistryProvider>` is
+ * in scope instead of throwing. Used by `useStandardActions` to preserve its
+ * silent-no-op contract when neither provider is present.
+ */
+declare function useOptionalDepRegistry(): DepRegistry | null;
+/** Register a live source for `name` for the lifetime of the calling
+ *  component. The `source` thunk is called at dispatch time and should
+ *  return the latest value. */
+declare function useDepSource<K extends DepName>(name: K, source: () => DepSchema[K]): void;
+
+/**
+ * Shared dep-bag builder — the single implementation behind both the gesture
+ * dispatcher's per-invocation `buildDeps` and `ActionsRegistry.trigger`'s
+ * `requires` branch. Reads the action's declared `requires`, resolves each
+ * name against the `DepRegistry`, and (dev builds only) wraps the bag in a
+ * Proxy that warns on undeclared reads.
+ */
+
+/** Build the deps bag for an action from its declared `requires`. */
+declare function buildDepsFromRequires(action: Action, depRegistry: DepRegistry): ActionDeps;
+
+/** Hotkey-slot trigger key. The slot is engaged while this key is held —
+ *  hence "hotkey": active as long as the key is hot. `null` (or omitted)
+ *  means the tool is not eligible for the hotkey slot. */
+type HotkeyTrigger = 'space' | 'alt' | 'ctrl' | 'meta' | 'shift';
+/** Presentation metadata for tool palettes / menus. Optional on every
+ *  tool — consumers that render a palette (`<ToolPalette>`) read these
+ *  fields to display the tool; consumers that don't can ignore them.
+ *
+ *  Note: cursor is NOT here. `Tool.cursor` (inherited from `Contribution`)
+ *  is already plumbed through `<Canvas>` to `style.cursor` on the host. */
+interface ToolPresentation<TScratch = unknown> {
+    /** Human-readable label, distinct from the `id`. Falls back to `id`. */
+    label?: string;
+    /** Inline-SVG icon component output. May be a static `ReactNode` or a
+     *  function of scratch state (rare; useful for shape-aware affordances). */
+    icon?: react.ReactNode | ((scratch?: TScratch) => react.ReactNode);
+    /** Palette grouping key. Tools sharing a group render contiguously
+     *  with separators between groups. Free-form string; the kit
+     *  recommends 'select' | 'shape' | 'draw' | 'type' | 'view'. */
+    group?: string;
+    /** Display override for the keyboard shortcut. When omitted the palette
+     *  derives one from `Tool.keybinding` via its own formatter. */
+    shortcut?: string;
+}
+/**
+ * When an entry's bindings are live. A set, not one value: the hand tool is
+ * palette-selectable AND engaged by holding space, and both hold at once.
+ */
+interface Eligibility {
+    /** Selectable as the focused entry — exclusive, one at a time. */
+    focus?: boolean;
+    /** Also live while this key is held. */
+    offhand?: HotkeyTrigger;
+    /** Live regardless of what is focused. */
+    always?: boolean;
+    /** Live only for input this entry's own affordances produced. */
+    claimed?: boolean;
+    /** Modality filter, applied wherever it would otherwise be live. */
+    capabilities?: CapabilityTag[];
+}
+/**
+ * Where an entry's overlay sits in the layer stack, relative to the
+ * selection chrome. `'top'` is the default and renders above everything;
+ * the other two exist for chrome that belongs under the selection handles
+ * (a snap-target highlight, say). With no selection overlay in the stack,
+ * all three collapse to `'top'`.
+ */
+type OverlayPosition = 'top' | 'before-selection' | 'after-selection';
+/**
+ * What routing reads off an entry: when its bindings are live, which they
+ * are, and the actions they name.
+ */
+interface ContributionRouting {
+    id: string;
+    eligibility: Eligibility;
+    bindings?: GestureBinding[];
+    actions?: Action[];
+}
+/**
+ * What an entry draws and how a palette shows it. None of it reaches the
+ * dispatcher.
+ */
+interface ContributionChrome<TOverlay = unknown> {
+    /** One layer, or several composed in the given order.
+     *
+     *  Routing never reads a layer — it collects the live ones and hands them
+     *  back in scope order. `TOverlay` is what the consuming kernel draws;
+     *  `@weasel-js/core` binds it to `RenderLayer<unknown>`. */
+    overlay?: TOverlay | TOverlay[];
+    /** Defaults to `'top'`. Applies to every layer in `overlay`. */
+    overlayPosition?: OverlayPosition;
+    presentation?: ToolPresentation;
+}
+/**
+ * A registry entry: what it contributes, and when it is eligible. Every role
+ * is optional and independent — an entry that only routes input declares only
+ * `bindings` and `actions`.
+ */
+interface Contribution<TOverlay = unknown> extends ContributionRouting, ContributionChrome<TOverlay> {
+    /** Reflection escape hatch — the authored form, when there was one. */
+    def?: unknown;
+}
+
+/**
+ * Configurable activation-key descriptor for tools that expose their
+ * keybinding to the host (currently Lasso and Eyedropper). Captures
+ * only the fields meaningful to a caller-supplied tool-select key —
+ * dispatcher-internal fields (`skipInEditable`, `enabled`,
+ * `preventDefault`) live on `KeyBinding` in keyHelpers.ts and are
+ * not part of the configurable surface.
+ */
+interface ToolKeybinding {
+    /** Key or list of keys to match (case-insensitive against `event.key`). */
+    key: string | readonly string[];
+    /** Require Cmd (mac) / Ctrl (others). Default `false`. */
+    mod?: boolean;
+    /** Require Alt. Default `false`. */
+    alt?: boolean;
+    /**
+     * Shift policy. `undefined`/`false` forbids shift, `true` requires
+     * shift, `'optional'` allows either.
+     */
+    shift?: boolean | 'optional';
+}
+/** Modifier-key snapshot at event dispatch time. */
+type ToolModifiers = ModifierState;
+/** Per-event context passed to every channel handler. `scratch` is typed
+ *  via the tool's `TScratch` parameter; it survives across a single
+ *  gesture (pointer-down through end/cancel) and is replaced on next
+ *  gesture start by `initScratch()`. */
+interface ToolCtx<TScratch = unknown> {
+    worldX: number;
+    worldY: number;
+    modifiers: ToolModifiers;
+    selection: SelectionApi;
+    /** Adapter/scene access — opaque at this layer; tools that need it
+     *  cast to a known shape. This layer doesn't constrain it. */
+    adapter: unknown;
+    applyOps: (ops: Op[], label: string) => void;
+    /** Current viewport. Reflects camera-position semantics — see
+     *  `View` JSDoc. */
+    view: View;
+    /** Mutate the viewport. In controlled mode this calls the consumer's
+     *  `onViewChange`; in uncontrolled mode it updates Canvas's internal
+     *  state. View changes are not undoable. */
+    setView: (next: View) => void;
+    /** Bounding rect of the canvas element in viewport coords. Used by
+     *  zoom/pan tools to convert event clientX/clientY to canvas-relative
+     *  anchors. */
+    canvasRect: DOMRect;
+    /** Screen-space pointer coords relative to `canvasRect`. Useful for
+     *  viewport tools that pan/zoom in screen space (e.g. hand-pan
+     *  computes deltas in pixels, not world units). Optional — populated
+     *  by the dispatcher on pointer events; absent on keyboard events. */
+    screenPoint?: {
+        x: number;
+        y: number;
+    };
+    /** Optional debug sink. When `<Canvas debug={...}>` is enabled, Canvas
+     *  threads its sink here so tool-internal hit math (handle hitboxes,
+     *  rotation handle, etc.) lands in the same overlay as Canvas's own
+     *  bounds/origin records. Tools should call this conditionally with `?.`. */
+    debug?: DebugSink;
+    scratch: TScratch;
+}
+/** 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). */
+type ToolBounds = Bounds;
+/**
+ * The focus-declaring case of a `Contribution`: a mode the user switches
+ * into, plus the hooks that only make sense for one (`initScratch`,
+ * activate/deactivate, live preview, `cursor`). Everything else — bindings,
+ * actions, overlay, presentation — is inherited.
+ */
+interface Tool<TScratch = unknown, TOverlay = unknown> extends Contribution<TOverlay> {
+    /** 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
+     *  host (currently Lasso and Eyedropper). The dynamic loop in
+     *  `useKeybindings.ts` picks this up and appends a binding entry to the
+     *  consolidated `tool.activate` action (with `opts.params.toolId` set so
+     *  the invoker knows which tool to switch to). */
+    keybinding?: ToolKeybinding;
+    initScratch?: () => TScratch;
+    cursor?: CursorSpec | ((ctx: ToolCtx<TScratch>) => CursorSpec);
+    onActivate?: (ctx: ToolCtx<TScratch>) => void;
+    onDeactivate?: (ctx: ToolCtx<TScratch>) => void;
+    /** Returns the in-flight preview pose for `id` if this tool is mid-gesture
+     *  on it; otherwise `null`. Lets `Canvas.helpersRef.getEffectivePose`
+     *  reflect live gesture state without reaching into hook internals. The
+     *  return type is `unknown` here because the Tool interface is pose-agnostic;
+     *  callers that know the pose shape (e.g. Canvas typed by `TPose`) cast at
+     *  the use site. */
+    previewPose?: (id: string) => unknown;
+    /** Returns the in-flight preview bounds for `id` if this tool is mid-gesture
+     *  on it; otherwise `null`. Optional companion to `previewPose` for tools that
+     *  can compute bounds without round-tripping through a geometry adapter. */
+    previewBounds?: (id: string) => ToolBounds | null;
+    /** Returns ids whose committed scene-render should be suppressed while this
+     *  tool is mid-gesture (e.g. cascade move's dragged + descendant ids whose
+     *  preview ghosts replace the committed pose). The standard scene slot
+     *  consults this alongside `previewPose` to avoid double-rendering. Returns
+     *  `null` when no gesture is in flight. */
+    previewIds?: () => Iterable<string> | null;
+}
+/** Internal — which slot a tool occupies in the dispatch order. */
+type ToolSlot = 'hotkey' | 'active' | 'ambient';
+/** Internal alias for "a Tool of any scratch type" — used in registries and
+ *  dispatchers that hold tools of heterogeneous scratch shapes. `any` is
+ *  intentional: `Tool<TScratch>` is invariant in TScratch, so `Tool<unknown>`
+ *  is too strict for containers that accept any concrete `Tool<T>`. */
+type AnyTool = Tool<any, any>;
+/** "A tool of any scratch type that draws `TOverlay`" — the container form for
+ *  registries that hold heterogeneous scratch shapes but one overlay type. */
+type AnyToolOf<TOverlay> = Tool<any, TOverlay>;
+
+/**
+ * Pure matcher primitives live in `@weasel-js/gestures`. This file
+ * re-exports them for kit-internal consumers and layers the actions-layer
+ * binding-scope / matchBest logic on top.
+ */
+
+/** Where a binding came from, which is also its priority: a held hotkey beats
+ *  the active tool, which beats bindings that are always in scope. */
+type BindingScope = 'ambient' | 'active' | 'hotkey';
+/** A binding paired with where it came from, ready to be matched against an
+ *  event. */
+interface ScopedBinding {
+    binding: GestureBinding;
+    scope: BindingScope;
+    /** Tool id that owns this binding — `'&'`-channel phase atoms resolve
+     *  to this. `null` for ambient bindings that came from a registered
+     *  Action with no owning tool. */
+    ownerToolId: string | null;
+}
+/** The binding that won a match. */
+interface MatchResult {
+    binding: GestureBinding;
+    scope: BindingScope;
+    /** Tool id that owns the binding — propagated from `ScopedBinding`
+     *  so the dispatcher can record it as the handle owner. */
+    ownerToolId: string | null;
+}
+/**
+ * True when a spec's target actually consults the affordance hit rather than
+ * only the body classification. `kindOf` predicates are handed the hit;
+ * `affordance:<k>` matches on its `kind`. The body-class strings (`'empty'`,
+ * `'selected-body'`, `'unselected-body'`) and the `kind:` forms resolve from
+ * `bodyTarget` / `bodyKind` and never see it — which is why chrome floating
+ * over empty canvas used to read as empty canvas.
+ *
+ * A predicate carrying `readsAffordance: false` says the same about itself;
+ * the kit's own body predicates do. Shape stays the fallback for predicates
+ * that declare nothing.
+ */
+declare function targetConsultsAffordance(specTarget: TargetSpec | undefined): boolean;
+/** CSS-style specificity tuple for a GestureSpec. Higher tuple wins under
+ *  lexicographic compare. Dimensions, in order of precedence:
+ *
+ *    [0] target — how much the spec's target narrows; see `targetRank`.
+ *    [1] mods   — count of required modifier keys (shift/alt/ctrl/meta/mod).
+ *                 `'optional'` does NOT count.
+ *    [2] phase  — how much the spec's `phase` narrows; see `phaseRank`.
+ *    [3] exact  — per-kind tiebreak: 2 for a drop/paste spec with a
+ *                 non-empty `types` MIME filter, else 1.
+ *
+ *  Identical tuples fall back to registration order in the matcher's
+ *  stable sort, preserving the pre-specificity tiebreaker. */
+declare function specificity(spec: GestureSpec): readonly [number, number, number, number];
+/**
+ * Find the best-matching binding across all scopes.
+ *
+ * Precedence: hotkey > active > ambient.
+ * Within a scope, more-specific bindings win; same-specificity bindings keep
+ * registration order (see `matchSorted`).
+ * Returns null when nothing matches.
+ *
+ * Note: this returns only the single best match. The dispatcher uses
+ * `matchSorted` so it can fall through to lower-specificity matches when a
+ * higher-specificity match's `enabled()` reports disabled.
+ */
+declare function matchBest(e: InputEvent, bindings: readonly ScopedBinding[], isMac: boolean, engagedChannels?: ReadonlySet<string>): MatchResult | null;
+/**
+ * Find every binding that matches the event, sorted by precedence
+ * (best → worst). Ordering rules:
+ *
+ *   - Scopes by priority: hotkey > active > ambient.
+ *   - Within a scope, more-specific bindings beat less-specific (see
+ *     `specificity()`).
+ *   - Among same-specificity bindings, first-declared wins (stable sort
+ *     preserves registration order — same tiebreaker as pre-specificity).
+ *
+ * Used by the dispatcher to implement specificity-ordered fall-through:
+ * when the top match's `enabled()` returns a disabled reason (or the
+ * action's `start()` returns an empty handle), the next match is tried.
+ */
+declare function matchSorted(e: InputEvent, bindings: readonly ScopedBinding[], isMac: boolean, engagedChannels?: ReadonlySet<string>, warn?: (message: string) => void): MatchResult[];
+
+/**
+ * Dispatcher orchestrator — pure module, no React, no DOM.
+ *
+ * Assembles `ScopedBinding[]` from the actions registry, active tool, and
+ * hotkey stack; matches input events via `matchSorted`; gates each candidate
+ * on `enabled()`; then invokes `immediate` or `ongoing` invokers and tracks
+ * in-flight handles.
+ *
+ * ## Specificity-ordered fall-through
+ * `matchSorted` returns every matching binding in precedence order
+ * (hotkey > active > ambient, first-declared within scope). The dispatcher
+ * walks that list and fires the first action whose `enabled()` returns
+ * `true`. If every candidate's `enabled()` returns a disabled reason, the
+ * event is unhandled. This mirrors CSS-style specificity matching with a
+ * `:not(:disabled)` filter, and lets a tool declare a high-specificity
+ * binding (e.g. drag-on-empty → areaSelect) that gracefully falls through
+ * to a lower-specificity ambient binding (e.g. drag → viewport.dragPan)
+ * when its required deps aren't wired.
+ *
+ * ## gestureId scheme
+ * - `key-held` ongoing actions: `key-held-<key>` (e.g. `key-held- ` for Space).
+ *   Chosen because key-held gestures are identified by the held key alone.
+ * - `pointerdown` / drag ongoing actions: `pointer-<pointerId>`, taken from
+ *   the originating DOM `PointerEvent`. Each physical pointer — mouse, each
+ *   touch, the stylus — gets its own handle slot. Events with no
+ *   `pointerId` (synthesized probes, programmatic drags, most tests) key to
+ *   `pointer-mouse`, so a single synthetic pointer behaves as it always has.
+ * - `multitouch` ongoing actions: `multitouch-<fingers>`.
+ * - Fallback for any other kind that triggers an ongoing invoker: `ongoing-<kind>`.
+ *
+ * ## Action-lookup miss behavior
+ * When `matchBest` resolves a binding whose `actionId` has no entry in
+ * `ctx.actions.list()`, the dispatcher emits `console.warn` and returns
+ * `'unhandled'`. The user's input gesture falls through as if unmatched.
+ * This preserves input flow (nothing is swallowed silently) while flagging
+ * the misconfiguration at dev time.
+ */
+
+/**
+ * The in-flight handle slot a pointer's gestures key into.
+ *
+ * Exported because the React seam (`useGestureDispatcher`) has to name the
+ * same slot when it asks `dispatcher.inFlight()` whether a given pointer is
+ * mid-drag. That used to be the string literal `'pointer-mouse'` on both
+ * sides, which was correct only because `gestureIdFor` ignored the pointer id
+ * entirely — the two lies cancelled out.
+ *
+ * @param pointerId - `PointerEvent.pointerId`, or `undefined` for a
+ *   synthesized event with no originating DOM pointer.
+ */
+declare function pointerGestureId(pointerId: number | undefined): string;
+/** One entry per `handleInput` call. */
+interface DispatchLogEntry {
+    kind: 'dispatch';
+    ts: number;
+    eventKind: string;
+    /** For `key` / `key-held` events, the key id (`'Escape'`, `' '`, `'a'`).
+     *  Lives on the event side of the entry — `fired` should describe
+     *  what dispatched, not which key triggered it. */
+    key?: string;
+    candidates: Array<{
+        actionId: string;
+        scope: BindingScope;
+        enabledResult: boolean | string;
+    }>;
+    fired: string | null;
+    outcome: 'handled' | 'unhandled';
+}
+/** One entry per "mode change" — a kit state transition that isn't a
+ *  dispatched input event but is load-bearing for understanding why an
+ *  input was (or wasn't) handled later. Pushed via `recordModeSwitch()`;
+ *  consumers include the editAnchors dep (editingId changes), and
+ *  could expand to active-tool / hotkey-stack / focus changes. */
+interface ModeSwitchLogEntry {
+    kind: 'mode';
+    ts: number;
+    /** Logical mode name, e.g. `'editAnchors.editingId'`. */
+    mode: string;
+    from: string | null;
+    to: string | null;
+    /** Optional free-form context — `'enterPathEdit'`, `'exitPathEdit'`,
+     *  `'selection-dropped target'`, etc. */
+    detail?: string;
+}
+type TraceLogEntry = DispatchLogEntry | ModeSwitchLogEntry;
+/** Push a mode-switch record into the trace log. Safe to call from
+ *  anywhere; no-ops outside DEV. */
+declare function recordModeSwitch(mode: string, from: string | null, to: string | null, detail?: string): void;
+/** Everything the dispatcher must consult to route one input event: the
+ *  registered actions and their deps, which tool is active, which hotkeys are
+ *  held, and — optionally — the chrome state that action eligibility rules are
+ *  evaluated against. Rebuilt per event rather than held, so the dispatcher
+ *  itself stays stateless apart from in-flight gestures. */
+interface DispatcherContext {
+    /** All registered actions; the dispatcher walks `.defaultBinding` for ambient bindings. */
+    actions: ActionSource;
+    /** Dep sources keyed by name. */
+    depRegistry: DepRegistry;
+    /** Active tool's id (from ActiveToolContext). */
+    activeToolId: string;
+    /** Held-hotkey stack, top of stack last. */
+    hotkeyStack: readonly string[];
+    /** Lookup for tool definitions. */
+    toolsById: ReadonlyMap<string, Tool>;
+    /** Platform flag for `mod` shorthand resolution. */
+    isMac: boolean;
+    /**
+     * Thunk returning a fresh `RuleCtx` for the current frame — the routed
+     * view's, when the surface hosts several. When it answers, the dispatcher
+     * filters matched candidates by their declared `Action.eligible` rule
+     * (omitted => always eligible). Absent, or answering `undefined`, applies
+     * no eligibility filtering.
+     */
+    getRuleCtx?: () => RuleCtx | undefined;
+}
+/**
+ * Filter `matches` to only those whose backing action has no `eligible`
+ * rule, or whose rule evaluates true against `ruleCtx`. Exported for
+ * unit testing.
+ *
+ * @internal
+ */
+declare function filterEligible<M extends {
+    binding: {
+        actionId: string;
+    };
+}>(matches: readonly M[], actionLookup: (id: string) => Action | undefined, ruleCtx: RuleCtx): M[];
+/**
+ * Handle returned by `Dispatcher.beginUiOngoing()` for driving an
+ * ongoing invoker from a UI control (color picker, slider).
+ *
+ *  - `update(params)` rebuilds an `InvocationCtx` with the new params and
+ *    calls the handle's `onMove`. Safe to call many times.
+ *  - `end(reason)` calls `onEnd(ctx, reason)` once and removes the handle
+ *    from the in-flight map. Idempotent — further calls are no-ops.
+ */
+interface UiOngoingControl {
+    readonly gestureId: string;
+    update(params?: Record<string, unknown>): void;
+    end(reason: 'commit' | 'cancel'): void;
+}
+/**
+ * Successful `Dispatcher.resolveOnly` prediction: the binding + action that
+ * would fire if `event` were dispatched for real. `action` is the resolved
+ * descriptor so callers (the hover-cursor pump) can read metadata like
+ * `Action.cursor` without a second registry lookup.
+ */
+interface ResolveOnlyResult {
+    actionId: string;
+    action: Action;
+    scope: BindingScope;
+    /** Tool id owning the winning binding; `null` for ambient action bindings. */
+    ownerToolId: string | null;
+}
+/**
+ * One candidate from `Dispatcher.resolveAll` — a binding that matched the
+ * event, with why it did or didn't get to fire.
+ *
+ * Verdicts:
+ *  - `would-fire`  — eligible, `enabled()` passed, and nothing above it fired.
+ *    At most one candidate per call carries this.
+ *  - `ineligible`  — the action's `eligible` rule evaluated false against the
+ *    live `RuleCtx`. `reason` is the rule, serialized.
+ *  - `disabled`    — `enabled()` returned a disabled reason, carried verbatim.
+ *  - `shadowed`    — never asked, for one of two reasons: something above it
+ *    already fired, or it is a repeat binding of the action that itself won
+ *    higher in the list (several bindings may point at one action, and the
+ *    dispatcher runs each action at most once). A repeat of an action that was
+ *    already judged `ineligible` or `disabled` is NOT shadowed — it inherits
+ *    that action's verdict, since that is the reason it doesn't fire.
+ */
+interface ResolvedCandidate {
+    actionId: string;
+    action: Action;
+    binding: GestureBinding;
+    scope: BindingScope;
+    ownerToolId: string | null;
+    /** The tuple from `specificity(binding.spec)`, surfaced so a reader can see
+     *  why one candidate outranks another rather than inferring it. */
+    specificity: readonly [number, number, number, number];
+    verdict: {
+        kind: 'would-fire';
+    } | {
+        kind: 'ineligible';
+        reason: string;
+    } | {
+        kind: 'disabled';
+        reason: string;
+    } | {
+        kind: 'shadowed';
+    };
+}
+/** Options for {@link Dispatcher.resolveAll}. */
+interface ResolveAllOptions {
+    /**
+     * Evaluate eligibility and `enabled()` for candidates below the winner
+     * instead of short-circuiting them to `shadowed`.
+     *
+     * Off by default, and deliberately so: the default walk's early exit is what
+     * keeps `resolveOnly`'s `enabled()` call count identical to a real dispatch,
+     * and `enabled()` predicates are only contractually pure — not free.
+     *
+     * Turn it on for diagnostics, where "this one was outranked" is a less
+     * useful answer than "this one was outranked AND would have been disabled
+     * anyway". With it on, `shadowed` narrows to its precise meaning: this
+     * candidate would have fired, but something above it did.
+     */
+    evaluateShadowed?: boolean;
+}
+/**
+ * Routes input events to actions.
+ *
+ * For each event it assembles the bindings in scope (hotkey, then active tool,
+ * then ambient), matches them in specificity order, filters by eligibility and
+ * each action's `enabled` gate, and invokes the first survivor. Ongoing
+ * actions — anything that runs across a drag — are kept in flight here and
+ * pumped with subsequent moves until the gesture ends.
+ */
+interface Dispatcher {
+    /**
+     * Route an input event through the binding pipeline. Returns `'handled'`
+     * when a binding matched and the action invoked successfully (whether it
+     * returned ops or not). Returns `'unhandled'` when no binding matched or
+     * the matched action's `enabled()` returned a disabled reason.
+     */
+    handleInput(event: InputEvent, ctx: DispatcherContext): 'handled' | 'unhandled';
+    /**
+     * Predict which action `event` would route to WITHOUT invoking it. Replays
+     * the same walk as `handleInput` — scope assembly, specificity-sorted
+     * match, eligibility filter, per-candidate `enabled()` gate — and returns
+     * the first candidate that would fire, or `null` when the event would go
+     * unhandled. Pure query: no invoker runs, no in-flight state changes, no
+     * trace-log entry.
+     *
+     * Known divergence from a real dispatch: an ongoing invoker that matches
+     * but returns an empty handle at `start()` (runtime bail) makes the real
+     * dispatch fall through to the next candidate; prediction cannot see that
+     * and reports the bailing action. Keep `enabled()` accurate on actions
+     * that rely on prediction (hover cursors).
+     */
+    resolveOnly(event: InputEvent, ctx: DispatcherContext): ResolveOnlyResult | null;
+    /**
+     * Every binding that matches `event`, in dispatch precedence order, each
+     * with a verdict explaining whether it would fire. Same walk as
+     * `resolveOnly` — scope assembly, specificity-sorted match, eligibility
+     * check, per-candidate `enabled()` gate — without stopping at the winner
+     * and without invoking anything. Nothing is dropped: candidates that
+     * `resolveOnly`'s walk would filter out are kept here and labelled
+     * `ineligible` instead. Pure query: no invoker runs, no in-flight state
+     * changes, no trace-log entry.
+     *
+     * `resolveOnly` is the first `would-fire` entry of this list.
+     *
+     * Shares `resolveOnly`'s known divergence from a real dispatch: an ongoing
+     * invoker that matches but returns an empty handle at `start()` makes the
+     * real dispatch fall through, and this cannot see that.
+     *
+     * By default everything below the winner is `shadowed` without being asked,
+     * which is what keeps this walk as cheap as the dispatch it replays. Pass
+     * `{ evaluateShadowed: true }` to keep evaluating past the winner, so a
+     * lower candidate that is ALSO ineligible or disabled says so — see
+     * {@link ResolveAllOptions.evaluateShadowed}.
+     */
+    resolveAll(event: InputEvent, ctx: DispatcherContext, opts?: ResolveAllOptions): ResolvedCandidate[];
+    /**
+     * Synthesize an end-of-gesture for every in-flight ongoing handle.
+     * Used by tool-switch cancellation (Q2 decision).
+     */
+    cancelAll(reason: 'commit' | 'cancel'): void;
+    /**
+     * Read-only view of currently in-flight ongoing handles, keyed by gestureId.
+     * For debug/testing.
+     */
+    inFlight(): ReadonlyMap<string, OngoingHandle>;
+    /**
+     * CSS cursor for the gesture currently in flight, or `null` when nothing
+     * is. Reads `Action.activeCursor` (falling back to `Action.cursor`) off the
+     * action whose handle is open — the hover pump applies this instead of its
+     * prediction once a gesture starts, which is how `grab` becomes `grabbing`.
+     */
+    inFlightCursor(): string | null;
+    /**
+     * Read-only iterator over currently in-flight `OngoingHandle` instances.
+     *
+     * Surface for the canvas's preview-ghost layer (`usePreviewGhostLayer`)
+     * to walk each handle's `previewIds()` / `previewPose(id)` and render
+     * dispatcher-driven gesture previews. Read-only by design:
+     * external consumers must not mutate the in-flight map.
+     */
+    getInFlightHandles(): Iterable<OngoingHandle>;
+    /**
+     * Subscribe to in-flight state changes. The callback fires after every
+     * mutation that affects what the preview-ghost / dispatcher-overlay
+     * layers read — handle start, every `onMove` pump, end, cancel,
+     * cancel-all. Consumers re-read `getInFlightHandles()` and re-render.
+     *
+     * Returns an unsubscribe function.
+     */
+    subscribe(fn: () => void): () => void;
+    /**
+     * Monotonic counter bumped on exactly the events {@link subscribe} fires
+     * on. The snapshot half of the `useSyncExternalStore` contract: pair it
+     * with `subscribe` to drive a render off in-flight gesture state without
+     * a `useReducer` force-rerender.
+     *
+     * Starts at 0 and only ever increases. Two reads returning the same number
+     * mean nothing pumped in between; it does **not** guarantee that a bump
+     * changed anything observable (a pump that matched no binding still
+     * counts — see `subscribe`).
+     */
+    getVersion(): number;
+    /**
+     * Snapshot of the currently active action, for surfaces (chrome-caps
+     * visibility rules, debug HUDs) that need to react to "what action
+     * is in flight right now."
+     *
+     * - `kind` — the `OngoingHandle.kind` reported by the in-flight
+     *   handle (e.g. `'marquee'`, `'move'`). `null` when no action is
+     *   in flight OR the handle didn't declare a kind.
+     * - `id` — the dispatcher's internal `gestureId` (`pointer-1`,
+     *   `key-held-Space`, …) — the pointer/key channel the action rode
+     *   in on. `null` when no action is in flight.
+     *
+     * When multiple handles are in flight simultaneously (e.g. a key-held
+     * action overlapping a pointer action), the most-recently-started
+     * handle wins. This matches user intent: the latest interaction is
+     * the one consumers care about.
+     *
+     * That rule used to be near-vacuous on the pointer side, because every
+     * pointer shared one handle slot and two pointer drags could not coexist.
+     * With per-pointer keying they can — but only via paths that bypass the
+     * multi-pointer policy in `useGestureDispatcher` (which stops a second
+     * finger from opening a drag while a pinch is live), such as a mouse and
+     * a pen used together. Latest-start remains the right answer there.
+     */
+    getActiveAction(): {
+        kind: string | null;
+        id: string | null;
+    };
+    /**
+     * Start an ongoing action driven by UI (not a gesture). Builds an
+     * `InvocationCtx` with the given `deps` and `params`, calls
+     * `action.invoker.start(ctx, { params })`, and registers the returned
+     * handle in the in-flight map so `getInFlightHandles()` reports it —
+     * enabling preview rendering via `SceneCanvas`.
+     *
+     * Returns `null` if `actionId` is unknown, the action's invoker is not
+     * ongoing, or `start` returned an empty handle.
+     *
+     * If a UI-driven handle for the same `actionId` is already in flight,
+     * it is committed (`end('commit')`) before the new one starts.
+     */
+    beginUiOngoing(actionId: string, deps: ActionDeps, params?: Record<string, unknown>): UiOngoingControl | null;
+}
+/** Build a dispatcher. `getAction` overrides how action ids are resolved;
+ *  by default the `DispatcherContext`'s registry is used. */
+declare function createDispatcher(opts?: {
+    getAction?: (id: string) => Action | undefined;
+}): Dispatcher;
+
+/**
+ * @experimental
+ * Partial override or full descriptor passed via `<SceneCanvas actions={...}>`.
+ * `null` disables a default at this id.
+ */
+type ActionEntry = null | Partial<Action> | Action;
+/**
+ * @experimental
+ * Shape of the `actions` prop on `<SceneCanvas>`. `null` disables all defaults.
+ */
+type ActionsProp = null | Record<string, ActionEntry>;
+/**
+ * @experimental
+ * Imperative API exposed by `useActionsRegistry()`.
+ */
+interface ActionsRegistry {
+    /** Add an action and return its release. Registrants for one id stack,
+     *  newest live, so releasing yours uncovers whoever you displaced. Call it
+     *  from an effect and release it in that effect's cleanup — registering from
+     *  a render body pushes an entry per render and releases none. */
+    register(action: Action): () => void;
+    /** Drop every registrant of `id`. This is the "this action should not exist"
+     *  door, not a release — for that, call what `register` returned. */
+    unregister(id: string): void;
+    /** Declare `id` not for this scope: it stays registered, and every other
+     *  scope over the same store still resolves it, but here it lists as absent
+     *  and neither `trigger` nor `begin` will fire it. Returns a release; an
+     *  `<ActionsScope>` drops what it muted when it unmounts. This is the
+     *  "not for me" door — `unregister` is the "should not exist" one. */
+    mute(id: string): () => void;
+    list(): readonly Action[];
+    /** Fire an immediate-invoker action by id. The optional `params` arg is
+     *  forwarded to `ImmediateInvoker.run` as its second argument — use it for
+     *  parametric actions (e.g. `trigger('tool.activate', { toolId: 'rect' })`).
+     *  Ongoing-invoker actions are not reachable from `trigger`. */
+    trigger(id: string, params?: Record<string, unknown>): boolean;
+    /**
+     * Subscribe to registry mutations. The callback fires after any
+     * `register`/`unregister` that changes the version. Returns an
+     * unsubscribe function. Designed for `useSyncExternalStore`-driven
+     * surfaces (e.g. `<ActionBar>` in `@weasel-js/ui`) that need to
+     * re-render when the action set changes.
+     */
+    subscribe(listener: () => void): () => void;
+    /**
+     * Start an ongoing action driven by UI (color picker, opacity slider).
+     * Returns a control object with `update(params)` and `end(reason)`.
+     *
+     * Returns `null` if no dispatcher is wired into this registry, the
+     * action is unknown, or its invoker is not ongoing.
+     *
+     * See `Dispatcher.beginUiOngoing` for full semantics including
+     * auto-commit when a prior UI handle for the same action is in flight.
+     */
+    begin(id: string, params?: Record<string, unknown>): UiOngoingControl | null;
+    /** Wire a dispatcher into the registry so `begin()` can delegate to it.
+     *  Returns a release that clears the slot only while this dispatcher still
+     *  holds it: a canvas displaced by a later one must not take input away from
+     *  the canvas now on screen. Call with `null` to detach unconditionally. */
+    setDispatcher(d: Dispatcher | null): () => void;
+    /** Wire a `DepRegistry` into the registry so `trigger()` / `begin()` can
+     *  resolve action deps even when this provider is mounted ABOVE the dep
+     *  registry (e.g. a consumer's root `<ActionsProvider>` reused by
+     *  SceneCanvas's `ActionsProviderIfRoot`). Takes precedence over the dep
+     *  registry read from context at the provider's own level. Call with
+     *  `null` to detach unconditionally; the returned release clears the slot
+     *  only while this registry still holds it. */
+    setDepRegistry(r: DepRegistry | null): () => void;
+}
+/** Validate that `id` is usable as an action id in the route grammar.
+ *  Rejects ids that start with a reserved sigil (would shadow future
+ *  grammar extensions) and ids that collide with phase keywords (would
+ *  parse as the bare-phase shorthand). Mirrors `defineTool`'s tool-id
+ *  validation. */
+declare function validateActionId(id: string): void;
+/** Reject any '&'-channel phase atom in an Action's defaultBinding —
+ *  actions have no owning tool, so '&' can't resolve. Tool-side bindings
+ *  (Tool.bindings) are the right place for '&' atoms. */
+declare function validateActionDefaultBinding(action: Action): void;
+
+/** Canonical id of the consolidated tool-offhand action. One descriptor
+ *  serves every tool; the matched binding supplies `params.toolId` to select
+ *  which tool to engage while the key is held. */
+declare const TOOL_OFFHAND_ID = "tool.offhand";
+/** Per-tool spec consumed by `buildToolOffhandBindings`. The key is the
+ *  held-key trigger (e.g. ' ' for Space-for-hand). */
+interface ToolOffhandBindingSpec {
+    toolId: string;
+    key: string | string[];
+}
+/** `KeyboardEvent.key` for a declared `Eligibility.offhand` trigger. Only
+ *  `space` is exercised today; the modifier arms follow the DOM's names. */
+declare function offhandKeyFor(trigger: HotkeyTrigger): string;
+/** Build the per-tool `BoundGesture` list for the consolidated action's
+ *  `defaultBinding`. Each entry pairs a `key-held` spec with
+ *  `opts.params.toolId` so the invoker's `start` can pick out which tool
+ *  to engage. */
+declare function buildToolOffhandBindings(specs: readonly ToolOffhandBindingSpec[]): BoundGesture[];
+/** Build the consolidated `tool.offhand` action — "hold a key to engage a
+ *  secondary tool" (e.g. Space-for-hand). `bindings` enumerates one
+ *  `{ spec: keyHeld, opts: { params: { toolId } } }` per tool; the invoker
+ *  reads `params.toolId` from the matched binding, pushes the tool id onto
+ *  the active-tool context's hotkey stack on `start`, and pops it on `onEnd`.
+ *  Mirrors the parametric shape of `tool.activate`. */
+declare function makeToolOffhandAction(bindings: BoundGesture[]): Action;
+
+/**
+ * Named predicates for `defaultBinding.target.kindOf`. Each matches the
+ * existing `kindOf` signature `(target: unknown, bodyTarget?: string) => boolean`
+ * so they drop into action descriptors without a wrapper:
+ *
+ *     target: { kindOf: isAnchor }
+ *
+ * Single source of truth for "what does this affordance kind mean" — adding
+ * a new predicate here is what enables every action that needs the same
+ * shape to read it. Drift prevention.
+ */
+/** A predicate that resolves from `bodyTarget` alone. The exclusive-claim
+ *  filter reads `readsAffordance`: without it a body predicate looks like it
+ *  consults the hit, and survives a claim that should have barred it. */
+type BodyPredicate = ((target: unknown, bodyTarget?: string) => boolean) & {
+    readsAffordance: false;
+};
+/** Matches any body hit — selected or unselected node body. */
+declare const isBody: BodyPredicate;
+/** Body hit specifically already in the selection. */
+declare const isSelectedBody: BodyPredicate;
+/** Body hit specifically NOT in the selection. */
+declare const isUnselectedBody: BodyPredicate;
+/** Empty-canvas hit — no node beneath cursor. */
+declare const isEmpty: BodyPredicate;
+/** Any corner resize handle — top-left/top-right/bottom-left/bottom-right. */
+declare const isResizeHandle: (target: unknown) => boolean;
+/** The rotate-around-center handle above the bounding box. */
+declare const isRotateHandle: (target: unknown) => boolean;
+/** Any path anchor (the on-curve dot). */
+declare const isAnchor: (target: unknown) => boolean;
+/** Either control handle (controlIn or controlOut). */
+declare const isControlHandle: (target: unknown) => boolean;
+/** Any of the three anchor-editing affordances (anchor + both controls). */
+declare const isAnchorOrControl: (target: unknown) => boolean;
+
+/**
+ * The DOM half of a drag: one pointer, held down, from press to release.
+ *
+ * Every pointerdown-to-pointerup lifecycle in the kit used to answer capture,
+ * pointer identity, teardown and lost-pointer recovery for itself, and each
+ * answered them differently. This is the one place those are decided; anything
+ * above it — thresholds, coordinate spaces, what the drag *means* — belongs to
+ * its caller.
+ */
+/** Why a session ended without the pointer being released. */
+type PointerSessionCancelReason = 
+/** The browser cancelled the pointer (touch interrupted, palm rejection). */
+'pointercancel'
+/** The origin left the document mid-gesture, taking capture with it. */
+ | 'lostcapture'
+/** `cancel()` — an unmount, a window blur, Escape, a consumer's own rule. */
+ | 'aborted'
+/** A new press arrived on this pointer, so the tracked one had ended. */
+ | 'superseded';
+interface PointerSessionCallbacks {
+    /** Every move belonging to this pointer, while it is still held. */
+    onMove?: (e: PointerEvent) => void;
+    /** The pointer was released. Fires once, before teardown completes. */
+    onEnd?: (e: PointerEvent) => void;
+    /** The session ended without a release. Fires once. */
+    onCancel?: (reason: PointerSessionCancelReason) => void;
+}
+interface PointerSessionOptions {
+    /** Ask the origin element to capture the pointer. Default `true`. Capture
+     *  keeps hover and click off everything the drag passes over; the session
+     *  does not depend on it to keep receiving events. */
+    capture?: boolean;
+}
+interface PointerSession {
+    readonly pointerId: number;
+    /** False once the session has ended, by any route. */
+    readonly active: boolean;
+    /** End the session now, reporting `'aborted'`. Idempotent. */
+    cancel: () => void;
+}
+/**
+ * Open a session for the pointer that `down` belongs to.
+ *
+ * Listens on the origin's document rather than on the element: a captured
+ * element that is removed mid-drag stops receiving events, and every listener
+ * hung on it goes with it. Three recovery rules close the gaps a plain
+ * pointerup/pointercancel pair leaves — losing capture cancels only once the
+ * origin has left the document, a move reporting no held button is read as
+ * the release that never arrived, and a fresh press on the same pointer says
+ * the tracked one had already ended.
+ */
+declare function openPointerSession(origin: Element, down: PointerEvent | React.PointerEvent, cb: PointerSessionCallbacks, opts?: PointerSessionOptions): PointerSession;
+
+/** What the registry knows at dispatch time. */
+interface EligibilityState {
+    focusedId: string | null;
+    heldTriggers: ReadonlySet<string>;
+    /** Ids the host reports as hotkey-engaged. A declared `offhand` registers
+     *  the binding, but `tool.offhand`'s invoker still reports engagement by
+     *  pushing an id — this retires only if that contract changes. */
+    engagedIds?: ReadonlySet<string>;
+    /** Whether the active mode allows these capability tags. Omitted → allow. */
+    allows?: (tags: readonly CapabilityTag[]) => boolean;
+}
+/**
+ * The scope tier an entry's bindings are live at, or null when none are.
+ * Ordered hotkey > active > ambient to match the dispatcher's own walk.
+ */
+declare function liveScope(id: string, eligibility: Eligibility, state: EligibilityState): BindingScope | null;
+
+/**
+ * Every binding the entry set contributes right now, each tiered by the
+ * entry's own declared eligibility. Entries with no live tier are omitted.
+ *
+ * Order is preserved: `matchSorted` sorts by specificity within a scope and
+ * breaks ties by declaration order, so the caller's entry order decides which
+ * of two same-specificity bindings in one tier wins.
+ */
+declare function scopeBindings(entries: Iterable<Contribution>, state: EligibilityState): ScopedBinding[];
+
+/**
+ * Concatenate contribution bundles into one registry, preserving order —
+ * entry order decides which of two same-specificity bindings in one scope
+ * tier wins, so it is part of the result, not an accident of it.
+ *
+ * Throws on a duplicate id rather than dropping one: a feature silently
+ * losing its bindings is the failure this registry exists to make loud.
+ */
+declare function mergeContributions(...bundles: readonly Contribution[][]): Contribution[];
+
+/**
+ * What a tool declares.
+ *
+ * A tool is a declarative shell, not an event handler: it names the gestures
+ * it responds to and, for each, the action to invoke. The dispatcher owns the
+ * gesture, and the action owns the preview and the commit — so a tool
+ * definition is mostly `bindings`, plus presentation and any actions the tool
+ * itself introduces.
+ */
+interface ToolDef<TScratch = void, TOverlay = unknown> {
+    id: string;
+    /** Capability tags for modality eligibility. Forwarded onto `Tool.capabilities`. */
+    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[];
+    /** Hook name as exported from the kit barrel (e.g. `'useHandTool'`).
+     *  Set by built-in hooks for inspector / debugging. Consumer-authored
+     *  tools may set this to surface their hook name; omitted is fine.
+     *  Introspection-only — do not make this load-bearing in production.
+     *  Read off the def via `Tool.def` (the reflection escape hatch). */
+    hookName?: string;
+    presentation?: ToolPresentation<TScratch>;
+    /** Optional caller-supplied activation 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 host (currently Lasso and Eyedropper). The dynamic
+     *  loop in `useKeybindings.ts` picks this up and appends a binding entry
+     *  to the consolidated `tool.activate` action (with `opts.params.toolId`
+     *  set so the invoker knows which tool to switch to). */
+    keybinding?: ToolKeybinding;
+    /** Held-key trigger: this tool engages while the key is down and
+     *  disengages on release. Carried onto `Tool.eligibility.offhand`, which
+     *  assembly reads to register the consolidated `tool.offhand` action — the
+     *  declaration is the wiring, with nothing for the host to do. */
+    hotkey?: HotkeyTrigger;
+    onActivate?: (ctx: ToolCtx<TScratch>) => void;
+    onDeactivate?: (ctx: ToolCtx<TScratch>) => void;
+    cursor?: CursorSpec | ((ctx: ToolCtx<TScratch>) => CursorSpec);
+    /** Override the default scratch initializer. Default is `() => null`
+     *  cast to `TScratch`, which works for tools whose scratch is fresh
+     *  every gesture. Tools that need scratch identity to survive across
+     *  gesture boundaries (e.g. the pen tool's multi-click subpath state)
+     *  pass a stable-ref-returning thunk here. The factory forwards this
+     *  onto the returned `Tool.initScratch`. */
+    initScratch?: () => TScratch;
+    /** Declarative gesture bindings, forwarded onto `Tool.bindings`. The
+     *  gesture dispatcher consults these at active scope while this tool is the
+     *  active one, and at hotkey scope while it is held. This is the tool's
+     *  entire input surface — the `initial` / `engaged` phase tables that used
+     *  to sit beside it are gone, along with the second dispatcher that read
+     *  them. */
+    bindings?: GestureBinding[];
+    /** Optional overlay layer rendered while the tool occupies any slot
+     *  (active, hotkey, or ambient), surfaced on `Tool.overlay`.
+     *
+     *  The layer's `draw` closure should read dynamic state through refs or
+     *  closures captured in the enclosing render scope, and gate on it there —
+     *  `if (!scratch.something) return []` — rather than expecting the kit to
+     *  swap layers as the gesture progresses.
+     *
+     *  Pass an array to contribute several layers; they render in order. */
+    overlay?: TOverlay | TOverlay[];
+    /** Where `overlay` sits relative to the selection chrome. Defaults to
+     *  `'top'`, above everything. */
+    overlayPosition?: OverlayPosition;
+}
+/** Viewport-tool spec. Once phase tables went away this stopped differing
+ *  from `ToolDef` in any structural way; `defineViewportTool` survives as the
+ *  authoring signal that a tool pans/zooms the view rather than the scene. */
+type ViewportToolDef<TScratch = void, TOverlay = unknown> = ToolDef<TScratch, TOverlay>;
+
+/**
+ * Build a `Tool<TScratch>` from a declarative `ToolDef<TScratch>`.
+ *
+ * This used to be a translator: `ToolDef` carried `initial` / `engaged` phase
+ * tables of hit-keyed route handlers, and `defineTool` compiled them into the
+ * imperative `pointer` / `drag` / `keyboard` / `wheel` handlers the
+ * tool-routing dispatcher called. Both ends of that are gone — tools declare
+ * `bindings` and the gesture dispatcher routes them — so what remains is
+ * identity plumbing plus the id check and the cursor resolver.
+ *
+ * It stays a function rather than becoming a spread because the id validation
+ * and the `initScratch` / `cursor` defaults are worth applying uniformly, and
+ * because `Tool.def` gives reflection a handle on the authored form.
+ */
+declare function defineTool<TScratch = void, TOverlay = unknown>(def: ToolDef<TScratch, TOverlay>): Tool<TScratch, TOverlay>;
+
+/**
+ * Define a tool that acts on the viewport rather than the scene.
+ *
+ * This used to do real work: `ViewportPhaseDef` was a narrowed `PhaseDef`
+ * (no click routes, drag restricted to the function form), and the factory
+ * lifted it back to the permissive shape before handing it to `defineTool`.
+ * With phase tables gone there is no shape left to narrow — a viewport tool
+ * declares `bindings` like any other, pointing at `viewport.*` actions.
+ *
+ * It survives as an authoring signal. `defineViewportTool` at the top of a
+ * hook says "this tool moves the camera, not the drawing", which is worth
+ * more than the type gymnastics it replaced.
+ */
+declare function defineViewportTool<TScratch = void, TOverlay = unknown>(def: ViewportToolDef<TScratch, TOverlay>): Tool<TScratch, TOverlay>;
+
+/**
+ * One row in the route registry — a single `GestureBinding` on one tool,
+ * flattened into the route grammar's vocabulary so the inspector, the
+ * conflict checker, and `describeRoute` can all read the same shape.
+ *
+ * Multiple rows can share (gesture, arg, target, modifiers) if different tools
+ * declare them; consumers walk the list and group client-side.
+ */
+interface RegistryEntry {
+    toolId: string;
+    /** Which phase the binding's `phase` spec restricts it to. `'any'` when it
+     *  declares none, declares `'*'`, or declares an atom list whose atoms
+     *  don't agree on one phase — such a binding fires in either phase, and
+     *  reporting it as `'initial'` made it collide with genuinely-initial
+     *  bindings in `findConflicts`' bucket key. */
+    phase: 'initial' | 'engaged' | 'any';
+    /** Structured v3 modifier requirements. Empty object = "no modifiers
+     *  held" (the strict default). */
+    modifiers: ParsedModifiers;
+    gesture: GestureName;
+    /** Resolved arg value for arg-bearing gestures (wheel direction,
+     *  key name, multiTouchTap fingers). Undefined for gestures whose
+     *  descriptor has no `arg`. */
+    arg: string | undefined;
+    /** Every arg value this binding actually answers to, when the spec names
+     *  more than one — `key: ['Delete','Backspace']` answers to both, and
+     *  `matchKey` matches any member case-insensitively. `arg` collapses them
+     *  into one display token, which is right for a route string and wrong for
+     *  deciding whether two bindings collide. Absent when there is only one. */
+    argAlternatives?: readonly string[];
+    /** Target class for hit-testing gestures. `undefined` when the descriptor
+     *  has `hasTarget: false` or the spec declares no target;
+     *  {@link PREDICATE_TARGET} when the spec uses a `kindOf` predicate, which
+     *  the route grammar has no notation for. */
+    target: string | undefined;
+    /** The action this binding fires. */
+    actionId: string;
+    /** The `GestureSpec` this row was flattened from, by reference. Reflection
+     *  consumers that need something the grammar doesn't capture — the
+     *  specificity tuple, a `kindOf` predicate identity — read it here rather
+     *  than re-walking `Tool.bindings`. */
+    spec: GestureSpec;
+}
+/**
+ * Stand-in target for a `{ kindOf }` predicate spec.
+ *
+ * The route grammar can name target *classes* (`empty`, `selected-body`,
+ * `kind:rect`) but not arbitrary predicates, so three distinct select-tool
+ * bindings all render as this one token. Narrowing it would mean giving the
+ * grammar a way to describe a function, which is a real design question and
+ * not one this reflection layer should answer by inventing syntax.
+ */
+declare const PREDICATE_TARGET = "predicate";
+/**
+ * Flatten every tool's `bindings` into route-registry rows.
+ *
+ * This was `buildActionRegistry`, and it walked `ToolDef.initial` /
+ * `.engaged` phase tables — the grammar that no longer exists. It was also
+ * blind to `Tool.bindings` the entire time the two lived side by side, which
+ * is why the inspector under-reported select by more than half. The rename
+ * fixes a second thing: it never had anything to do with the Actions
+ * Registry, and reading `buildActionRegistry` next to `ActionsRegistry`
+ * suggested otherwise.
+ */
+declare function buildRouteRegistry(tools: readonly Tool<unknown>[]): RegistryEntry[];
+/** The route-grammar gesture a `GestureSpec.kind` routes as, or `undefined`
+ *  for kinds the grammar has no name for. */
+declare function routeGestureForSpecKind(kind: GestureSpec['kind']): GestureName | undefined;
+/**
+ * Every route string one `GestureSpec` declares, in route-grammar notation.
+ *
+ * One string per arg alternative — a spec bound to `['ArrowUp','ArrowDown']`
+ * yields two routes, because each is separately conflictable and separately
+ * readable. Returns `[]` for spec kinds the grammar can't name.
+ *
+ * This is the display counterpart to {@link buildRouteRegistry}: same
+ * projection of a spec onto the grammar, rendered as text instead of as a
+ * conflict-checkable row.
+ */
+declare function routesForSpec(spec: GestureSpec): readonly string[];
+
+/** Two or more tools declare the same exact (phase, gesture, arg, target,
+ *  modifiers) tuple — the dispatcher's slot precedence picks one
+ *  arbitrarily (well, deterministically by slot order, but the author
+ *  probably didn't intend the duplication). */
+interface Conflict {
+    phase: 'initial' | 'engaged' | 'any';
+    gesture: GestureName;
+    arg: string | undefined;
+    target: string | undefined;
+    modifiers: ParsedModifiers;
+    /** All tool ids that registered the same tuple. At least 2 by
+     *  construction. Order matches the input tools[] order. */
+    toolIds: string[];
+}
+/** Detect exact-tuple overlaps across a tool registration set.
+ *
+ *  Intentionally NOT flagged:
+ *  - Broad vs. narrow targets (e.g. an untargeted `click` alongside
+ *    `click` on `empty`) — the dispatcher's specificity ordering resolves
+ *    those cleanly, and the broad one is usually the intended fallback.
+ *  - Different modifier requirements on the same target — they fire on
+ *    different inputs.
+ *  - A binding whose action declines via `enabled()` so a lower-priority
+ *    one can take the gesture. Detecting that intent would mean evaluating
+ *    the action; consumers can suppress known-intentional compositions in
+ *    their UI layer.
+ *
+ *  - Two `{ kindOf }` predicate targets. The route grammar renders every
+ *    predicate as the single token {@link PREDICATE_TARGET}, so bucketing on
+ *    the rendered target alone reported select's `resize` / `rotate` / `move`
+ *    drags — three genuinely different predicates — as a three-way conflict.
+ *    Predicate entries bucket by function identity instead, which means two
+ *    *separately written but equivalent* predicates go unflagged. That's the
+ *    right way to be wrong here: this check has to be silent when nothing is
+ *    wrong or nobody will keep it on.
+ *
+ *  Note that two bindings sharing a tuple on the SAME tool are now possible
+ *  (bindings are an array, where phase tables were objects with unique
+ *  keys) — so a conflict may name one tool twice.
+ *
+ *  This is the raw same-tuple detector. Feeding it a whole tool *registry*
+ *  over-reports, because registry tools take turns in the active slot and
+ *  can't collide with each other — see {@link findScopedConflicts}.
+ */
+declare function findConflicts(tools: readonly Tool<unknown>[]): Conflict[];
+/**
+ * The tool scopes as the dispatcher sees them — which is what decides whether
+ * two same-tuple bindings can actually collide.
+ */
+interface ToolScopes {
+    /** Tools eligible for the active slot, keyed by id or as a flat list. */
+    registry: readonly Tool<unknown>[] | Readonly<Record<string, Tool<unknown>>>;
+    /** Always-on tools. Every one of these is live at once. */
+    ambient?: readonly Tool<unknown>[];
+    /** Registered actions. Their `defaultBinding`s assemble at ambient scope
+     *  (hotkey scope when `Action.scope` says so), alongside the tools above. */
+    actions?: readonly Action[];
+}
+/**
+ * Detect reachable route conflicts in an assembled tool set and report each one.
+ *
+ * This is the wiring `findConflicts` spent its first life without: the kit
+ * could detect the one class of genuine routing ambiguity it has and never
+ * looked. Call it once wherever a tool set is assembled (`useTools` does),
+ * behind a `process.env.NODE_ENV !== 'production'` guard.
+ *
+ * **Warn, never throw.** A conflict between a consumer's tool and a kit tool
+ * is a design question — sometimes deliberate, since the loser can still take
+ * the gesture by declining through `enabled()` — and exploding in a running
+ * app is the wrong way to raise it. A conflict between two *kit* tools is
+ * always a bug, but the place to fail on that is the kit's own test suite
+ * (`canvas/SceneCanvas.routeConflicts.test.tsx`), not a consumer's console.
+ *
+ * @returns The conflicts found, so callers can dedupe repeat reports.
+ */
+declare function reportRouteConflicts(scopes: ToolScopes, warn?: (message: string) => void): Conflict[];
+
+/**
+ * Pure keyboard-binding helpers shared between the tool dispatcher
+ * (`useKeybindings`), the gesture dispatcher (`useGestureDispatcher`), and
+ * individual Tool declarations.
+ *
+ * Extracted from the deleted singular `useKeybinding` hook so the remaining
+ * consumers don't depend on its disappearance.
+ */
+/**
+ * @internal — runtime shape consumed by `matchesKeyBinding`. Public tool authors
+ * should use `ToolKeybinding` from `@weasel-js/core` for declaring
+ * configurable activation keys.
+ */
+interface KeyBinding {
+    /**
+     * Key or list of keys to match. Compared case-insensitively against
+     * `event.key`, so `'a'` matches both `'a'` and `'A'`.
+     */
+    key: string | readonly string[];
+    /**
+     * Require Cmd (mac) or Ctrl (others). When `true`, exactly one of
+     * `metaKey`/`ctrlKey` must be held. Default `false` (both forbidden).
+     */
+    mod?: boolean;
+    /** Require Alt. Default `false` (forbidden). */
+    alt?: boolean;
+    /**
+     * Shift policy. `undefined`/`false` forbids shift, `true` requires
+     * shift, `'optional'` allows either. Default `undefined`.
+     */
+    shift?: boolean | 'optional';
+    /** Skip when focus is in an editable element. Default `true`. */
+    skipInEditable?: boolean;
+    /** When `false`, the listener is not attached. Default `true`. */
+    enabled?: boolean;
+    /** Call `preventDefault` before the handler. Default `true`. */
+    preventDefault?: boolean;
+}
+/** Returns true when the target is an input, textarea, or contenteditable element. */
+declare function isEditableTarget(target: EventTarget | null): boolean;
+/**
+ * Pure matcher for `KeyBinding` against a `KeyboardEvent`. Only checks key +
+ * modifier policy — does NOT apply the editable-target skip or
+ * `preventDefault`. Shared by the tool dispatcher (`useKeybindings`) and the
+ * gesture dispatcher so the rules can't drift.
+ */
+declare function matchesKeyBinding(e: KeyboardEvent, b: KeyBinding): boolean;
+
+/**
+ * Typed keys for the gesture/behavior scratch store.
+ *
+ * Gestures expose `ctx.scratch: Record<string, unknown>` as a per-gesture
+ * mutable bag that behaviors use to stash state across `onDown` / `onMove`
+ * / `onEnd` calls. The store is `unknown`-valued because behaviors are
+ * tool-agnostic — a single behavior may run under different tools with
+ * different scratch shapes. Without a typing convention every read site
+ * has to `(ctx.scratch as <some shape>)[KEY]`, and a writer changing the
+ * shape can silently break readers with no compile-time signal.
+ *
+ * `ScratchKey<T>` is a phantom-typed string that carries its payload type
+ * via a branded interface. `getScratch` and `setScratch` use the brand to
+ * narrow / constrain at the typing layer; at runtime the key is just its
+ * underlying string and the store remains a plain `Record`.
+ *
+ * @example
+ * ```ts
+ * // Module-level (or behavior-level) constant, shared by writer + reader:
+ * const LASSO_VERTICES = scratchKey<readonly { x: number; y: number }[]>('lasso.vertices');
+ *
+ * // Writer (a tool's onMove):
+ * setScratch(ctx.scratch, LASSO_VERTICES, vertices);
+ *
+ * // Reader (a behavior's onEnd):
+ * const vertices = getScratch(ctx.scratch, LASSO_VERTICES) ?? [];
+ * //    ^?  readonly { x: number; y: number }[] | undefined
+ * ```
+ */
+/** Phantom-typed key for a scratch slot. The `__scratchKeyPayload` phantom
+ *  field carries the value type without occupying any runtime memory. */
+interface ScratchKey<T> {
+    readonly name: string;
+    /** Phantom — never read at runtime. Only present so TypeScript can
+     *  recover `T` at use sites. */
+    readonly __scratchKeyPayload?: (_: T) => T;
+}
+/** Compatible scratch store shape. The kit's gesture context's `scratch`
+ *  field already satisfies this; consumers don't need to construct one. */
+type ScratchStore = Record<string, unknown>;
+/**
+ * Make a typed scratch key. Use module-level constants so the same key
+ * is shared by writer and reader.
+ *
+ * Namespace the name by behavior or feature to avoid collisions
+ * (`'behavior.field'` is a good convention). Two keys with the same
+ * `name` refer to the same slot at runtime — the type parameter is a
+ * compile-time contract, not a uniqueness guarantee.
+ */
+declare function scratchKey<T>(name: string): ScratchKey<T>;
+/** Read a typed slot from the scratch store. Returns `undefined` if
+ *  nothing has been written under the key. */
+declare function getScratch<T>(store: ScratchStore, key: ScratchKey<T>): T | undefined;
+/** Write a value to a typed slot. Overwrites whatever was there. */
+declare function setScratch<T>(store: ScratchStore, key: ScratchKey<T>, value: T): void;
+/** Remove a slot from the scratch store. Returns `true` if it was set,
+ *  `false` if it wasn't. */
+declare function deleteScratch<T>(store: ScratchStore, key: ScratchKey<T>): boolean;
+
+/**
+ * IngestItem materialization — turns a live `DataTransfer` (drop) or
+ * clipboard `DataTransfer` (paste) into fully-owned `IngestItem[]`.
+ *
+ * `DataTransfer` items are only readable while the originating DOM event is
+ * on the stack, so BOTH functions must be called synchronously from the event
+ * handler. `itemsFromDataTransfer` kicks off every `getAsString` read
+ * immediately and resolves once all strings are collected;
+ * `itemsFromClipboardData` is fully synchronous (`getData` + `files`).
+ *
+ * MIME strings are normalized to bare lowercase `type/subtype` (parameters
+ * like `;charset=utf-8` stripped) — downstream exact matching (binding
+ * `types`, content-handler `match`) assumes the bare form.
+ *
+ * Output shape: **files first (source order), then strings (item order)**.
+ * For paste (`itemsFromClipboardData`) string flavors are emitted in
+ * `INGEST_STRING_MIMES` order: text/plain, text/html, text/uri-list.
+ */
+
+/** The string flavors the kit normalizes. Everything else (browser-internal
+ *  custom flavors, etc.) is dropped at materialization. */
+declare const INGEST_STRING_MIMES: ReadonlySet<string>;
+/** Wrap raw `File`s (file picker, `CanvasExtensionApi.ingest`) as
+ *  `IngestItem`s, normalizing each MIME the same way the drop/paste paths
+ *  do. Synchronous — `File` objects are already fully owned. */
+declare function itemsFromFiles(files: File[]): IngestItem[];
+/** Materialize a drop's `DataTransfer`. MUST be called during the `drop`
+ *  event dispatch (see module doc). */
+declare function itemsFromDataTransfer(dt: DataTransfer): Promise<IngestItem[]>;
+/** Materialize a paste's `clipboardData`. Fully synchronous. */
+declare function itemsFromClipboardData(cd: DataTransfer): IngestItem[];
+
+/**
+ * Convert client coords to element CSS-pixel coords (relative to the element's
+ * top-left). Apps drawing in CSS-pixel space feed the result directly into
+ * world math when pan/zoom is identity. With pan/zoom, compose this with
+ * your inverse-viewport transform.
+ */
+declare function clientToCanvas(canvas: HTMLElement, clientX: number, clientY: number): [number, number];
+/**
+ * Rect-taking variant of `clientToCanvas` for call sites that already hold a
+ * `DOMRect` (or any `{ left, top }` object) and don't have a canvas element
+ * in scope.
+ */
+declare function clientToCanvasRect(rect: {
+    left: number;
+    top: number;
+}, clientX: number, clientY: number): [number, number];
+
+/** Conditional `console.debug` — no-op unless `namespace` (or `*`) is enabled.
+ *  Each call is prefixed with `[namespace]` so the source is searchable. */
+declare function dlog(namespace: string, ...args: unknown[]): void;
+
+/**
+ * @weasel-js/routing — binding-to-action routing.
+ *
+ * The pure half: no React, no DOM. The React seam that pumps browser events
+ * into the dispatcher, and the providers that feed it, live behind
+ * `@weasel-js/routing/react`.
+ */
+
+/**
+ * The dependency schema — the map of dep name → value type that
+ * `Action.requires`, `DepRegistry.register`/`get` and `useDepSource` are all
+ * keyed on.
+ *
+ * It is declared **empty** here on purpose. Routing knows that an action names
+ * its dependencies and that the registry resolves them at invocation time; it
+ * does not know what a selection, a scene or a viewport is. Whoever supplies
+ * those merges them in:
+ *
+ * ```ts
+ * declare module '@weasel-js/routing' {
+ *   interface DepSchema { selection: SelectionApi }
+ * }
+ * ```
+ *
+ * `@weasel-js/core` merges the kit's own 24 deps this way and re-exports
+ * `DepSchema`, so a consumer adds its own against `'@weasel-js/core'` and
+ * never has to know this module exists. The merge carries through the
+ * re-export in both directions — `scripts/smoke-consumer-bundle.mjs` asserts
+ * it against the published `.d.ts`, which is where it once broke: a
+ * cross-module augmentation stops merging when `rollup-plugin-dts` flattens
+ * both files into one chunk.
+ */
+interface DepSchema {
+}
+/** Every dep name declared by anything that has merged into {@link DepSchema}. */
+type DepName = keyof DepSchema;
+
+export { INGEST_STRING_MIMES as $, type ActionsRegistry as A, type BindingOpts as B, type Contribution as C, type Dispatcher as D, type Condition as E, type Conflict as F, type ContributionChrome as G, type ContributionRouting as H, DEFAULT_ALLOWED_CAPABILITIES as I, DEFAULT_DEVICE_PROFILE as J, type DebugSink as K, type DepName as L, type DetectedDeviceFacts as M, type DeviceProfile as N, type OverlayPosition as O, type DispatchLogEntry as P, type DispatcherContext as Q, type RuleCtx as R, type ScopedBinding as S, type Tool as T, type DragSample as U, type Eligibility as V, type EligibilityState as W, type GestureBinding as X, type HandleKind as Y, type HitShape as Z, type HotkeyTrigger as _, type AffordanceHit as a, isAnchorOrControl as a$, type ImmediateInvoker as a0, type InvocationCtx as a1, type Invoker as a2, type KeyBinding as a3, type MatchResult as a4, type ModeSwitchLogEntry as a5, type ModifierState as a6, NEVER as a7, type NodeId as a8, type OngoingHandle as a9, type ToolModifiers as aA, type ToolOffhandBindingSpec as aB, type ToolPresentation as aC, type ToolSlot as aD, type TraceLogEntry as aE, type UiOngoingControl as aF, type View as aG, type ViewportToolDef as aH, actionBindings as aI, buildDepsFromRequires as aJ, buildRouteRegistry as aK, buildRuleCtx as aL, buildToolOffhandBindings as aM, clientToCanvas as aN, clientToCanvasRect as aO, createDispatcher as aP, defineTool as aQ, defineViewportTool as aR, deleteScratch as aS, describeRule as aT, dlog as aU, evaluate as aV, evaluateEnabled as aW, filterEligible as aX, findConflicts as aY, getScratch as aZ, isAnchor as a_, type OngoingInvoker as aa, type OngoingOverlay as ab, type OverlayRole as ac, PREDICATE_TARGET as ad, type Point2 as ae, type PointerSession as af, type PointerSessionCallbacks as ag, type PointerSessionCancelReason as ah, type PointerSessionOptions as ai, type RegistryEntry as aj, type ResizeAnchor as ak, type ResolveAllOptions as al, type ResolveOnlyResult as am, type ResolvedCandidate as an, type Rule as ao, type ScratchKey as ap, type ScratchStore as aq, type SelectionApi as ar, type SelectionExtendKey as as, type SelectionMode as at, type Selector as au, TOOL_OFFHAND_ID as av, type ToolBounds as aw, type ToolCtx as ax, type ToolDef as ay, type ToolKeybinding as az, type DepSchema as b, isBody as b0, isControlHandle as b1, isEditableTarget as b2, isEmpty as b3, isResizeHandle as b4, isRotateHandle as b5, isSelectedBody as b6, isUnselectedBody as b7, itemsFromClipboardData as b8, itemsFromDataTransfer as b9, itemsFromFiles as ba, liveScope as bb, makeToolOffhandAction as bc, matchBest as bd, matchSorted as be, matchesKeyBinding as bf, mergeContributions as bg, offhandKeyFor as bh, openPointerSession as bi, pointerGestureId as bj, recordModeSwitch as bk, reportRouteConflicts as bl, resolveDeviceProfile as bm, resolveParams as bn, routeGestureForSpecKind as bo, routesForSpec as bp, scopeBindings as bq, scratchKey as br, setScratch as bs, specificity as bt, targetConsultsAffordance as bu, validateActionDefaultBinding as bv, validateActionId as bw, type Action as c, type AnyToolOf as d, type DepRegistry as e, DepRegistryProvider as f, useDepSource as g, useOptionalDepRegistry as h, ALWAYS as i, type ActionDeps as j, ActionDisabledReason as k, type ActionDispatch as l, type ActionEnabledResult as m, type ActionEntry as n, type ActionPresentation as o, type ActionSource as p, type ActionsProp as q, type AnyTool as r, type BindingScope as s, type BindingSource as t, useDepRegistry as u, type BodyPredicate as v, type BoundGesture as w, type Bounds as x, type BuildRuleCtxArgs as y, COARSE_TARGET_SCALE as z };