@weasel-js/core 0.6.0 → 0.7.1

package/dist/index-DOYRTfP0.d.ts

@@ -0,0 +1,2986 @@
+import { N as NodeId, S as Scene, P as PoseComposition } from './types-Cpb4hii1.js';
+import { M as ModifierState, A as ActionBehavior, c as ResizeAnchor, R as ResizePose, B as BoundsConstraint, P as PointSnapBehavior } from './types-Dcaa0tPq.js';
+import { V as View } from './view-DSQgxBJB.js';
+import { CapabilityTag } from '@weasel-js/modes';
+import * as React from 'react';
+import { MutableRefObject, ReactNode, ReactElement } from 'react';
+import { IngestItem, GestureSpec, InputEvent, ParsedModifiers, GestureName, ChannelRef, DescribeRouteOptions, GESTURE_DESCRIPTORS, GestureArgSpec, GestureDescriptor, ModRequirement, ModifierKey, ParsedRoute, PhaseAtom, RESERVED_ID_NAMES, RESERVED_ID_PREFIXES, ROUTE_FIELD_DEFINITIONS, ROUTE_TERMS, RouteDescriptionPart, RouteFieldName, RouteTermLabel, canonicalModifiers, collapseShiftPairs, describeRoute, describeRouteParts, formatPhaseAtom, formatRoute, getGestureDescriptor, isKnownGestureName, parseRoute } from '@weasel-js/gestures';
+import { F as FillStyle, a as Stroke, D as DrawCommand } from './DrawCommand-CJtqqt8H.js';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { P as Path } from './types-B6MMiodD.js';
+import { Op, History } from '@weasel-js/history';
+import { L as LayoutStrategy, I as InsertAdapter } from './types-B_-khFM0.js';
+import { B as Bounds, P as PoseProjection } from './geometry-D9BDMiQi.js';
+import { Mat3 } from '@weasel-js/geom';
+import { D as DebugSink } from './types-BJ8_cyT7.js';
+
+/**
+ * Read-only state that affordances consult on every render and hit-test
+ * call. Built once per Canvas render via `buildChromeState`; affordances
+ * must not cache it across calls.
+ */
+interface ChromeState {
+    /** Currently selected ids. Live; reflects useSelection's React state. */
+    readonly selection: readonly NodeId[];
+    /** True when the canvas is in multi-mode AND >= 2 ids are selected. */
+    readonly multiActive: boolean;
+    /** Bounds for any selection member id. Honors active-tool overlay state
+     *  (move/resize/rotate ghosts → ghost bounds; otherwise → committed
+     *  pose bounds). Returns null for unknown ids or ids whose bounds aren't
+     *  computable. */
+    boundsOf(id: string): Bounds | null;
+    /** Multi-union AABB when `multiActive`. Computed lazily from `boundsOf`
+     *  over every selected id; null otherwise. */
+    readonly unionBounds: Bounds | null;
+    /** Active modifier state at the moment of the call. */
+    readonly modifiers: ModifierState;
+    /** True iff the node's pose-descriptor declares it can carry a rotation.
+     *  Affordances consult this to decide whether to expose rotate cursors /
+     *  drag-bands. Defaults to `true` when the descriptor doesn't declare
+     *  (back-compat) or when the id is unknown — the rotation gesture will
+     *  no-op visually for poses without AABB fields, but the affordance
+     *  doesn't lie about the cursor. Optional on the interface so unit-test
+     *  call sites that construct `ChromeState` by hand keep compiling;
+     *  affordances should treat an absent predicate as "true". */
+    canRotate?(id: string): boolean;
+}
+
+/**
+ * @experimental
+ * A single interactive piece of chrome. Pure functions; the kit composes
+ * multiple affordances into a single RenderLayer per tool via
+ * `composeAffordanceLayer`.
+ *
+ * Affordances declare interactive regions in a target's *local* frame.
+ * The framework (`composeAffordanceLayer`) composes the target's bounds
+ * transform (rotation around the AABB center, when present) for both paint
+ * and hit-test, so the affordance never touches rotation, view.scale, or
+ * world↔screen math.
+ */
+interface Affordance {
+    /** Stable id for debug overlays + visibility maps. */
+    id: string;
+    /** Enumerate this affordance's interactive regions. Each region lives in
+     *  some target id's local frame (or in the world frame when `targetId`
+     *  is `null`). Returning `[]` means "no chrome for this state" (no
+     *  selection, multi-mode disabled, etc.). */
+    regions(state: ChromeState): readonly AffordanceRegion[];
+    /** Optional non-interactive decoration (e.g., a leader line drawn from
+     *  a bounds edge to a handle — visual only, not draggable). Receives
+     *  raw state + view because the decoration may live outside any single
+     *  target's local frame. Most affordances leave this undefined. */
+    decorate?(state: ChromeState, view: View): DrawCommand[];
+}
+/**
+ * @experimental
+ * One interactive region produced by an affordance. The framework owns
+ * the local↔world transform for `targetId` (when non-null), so `shape`,
+ * `paint.sizePx`, and `hitRadiusPx` are always specified in coordinates
+ * the affordance can reason about directly.
+ */
+interface AffordanceRegion<TScratch = unknown> {
+    /** Stable id, e.g. `corner-min-min`. Used for debug overlays + a11y. */
+    id: string;
+    /** Target id whose `state.boundsOf(targetId)` defines this region's
+     *  local frame. `bounds.rotation` (if present) is the only transform
+     *  applied — translation is the AABB origin; scale is identity. Pass
+     *  `null` for affordances anchored to the viewport / world frame
+     *  (identity transform). */
+    targetId: string | null;
+    /** Region geometry, expressed in the target's local frame.
+     *
+     *  - `point` — circular hit (`hitRadiusPx` is screen-space).
+     *  - `rect`  — axis-aligned rect (target rotation applies).
+     *  - `annulus` — outer ellipse minus inner rect cutout. Used for
+     *    invisible zones that sit *around* the AABB (e.g. rotate-on-
+     *    hover band). The outer ellipse is defined by world-space
+     *    semi-axes `rx` / `ry` around `(cx, cy)`; the inner rect is the
+     *    same target-local rect that defines the AABB. Hit-test:
+     *    inside outer ellipse AND outside inner rect. */
+    shape: {
+        kind: 'point';
+        x: number;
+        y: number;
+        hitRadiusPx: number;
+    } | {
+        kind: 'rect';
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    } | {
+        kind: 'annulus';
+        /** Outer-ellipse center (target-local). */
+        cx: number;
+        cy: number;
+        /** Outer-ellipse semi-axes (target-local). */
+        rx: number;
+        ry: number;
+        /** Inner rect (target-local) — the cutout. Typically the
+         *  selection's AABB. */
+        innerX: number;
+        innerY: number;
+        innerWidth: number;
+        innerHeight: number;
+        /** Minimum band thickness outside the inner rect, in **screen**
+         *  pixels. The framework widens `rx`/`ry` to at least
+         *  `innerHalfExtent + minBandPx / meanScale(view.scale)` for both
+         *  paint and hit-test.
+         *
+         *  This exists because the clamp has to know the view and the
+         *  affordance doesn't: `ChromeState` carries no scale. Expressing the
+         *  floor in world units instead (which is what the rotate ring used
+         *  to do) makes the band shrink on screen as you zoom in, until the
+         *  ring around a small shape is too thin to hover. */
+        minBandPx?: number;
+    };
+    /** Optional paint. World position is derived from `shape` + target
+     *  transform; visual size stays in screen pixels (so handles don't
+     *  warp under zoom or non-uniform scale). Omit for hit-only regions.
+     *
+     *  - `square` — small fixed-size square (only valid over `point` shapes).
+     *  - `annulus` — fill + stroke the annulus ring (only valid over
+     *    `annulus` shapes). Uses even-odd fill rule to punch the inner-rect
+     *    cutout.
+     *  - `custom` — emit arbitrary draw commands; receives a {@link CustomPaintContext}. */
+    paint?: {
+        kind: 'square';
+        sizePx: number;
+        fill?: FillStyle;
+        stroke?: Stroke;
+    } | {
+        kind: 'annulus';
+        fill?: FillStyle;
+        stroke?: Stroke;
+        insetPx?: number;
+    } | {
+        kind: 'custom';
+        draw: (ctx: CustomPaintContext) => DrawCommand[];
+    };
+    /** Discriminator a press on this region reports as `AffordanceHit.kind` —
+     *  the string routing specs match on (`'handle:top-left'`,
+     *  `'rotate-handle'`, `'anchor:3'`). Omit for regions that only exist
+     *  inside a consumer-registered layer, where the layer id is the
+     *  discriminator; `buildAffordanceAt` falls back to
+     *  `<affordanceId>:<regionId>`. */
+    hitKind?: string;
+    /** CSS cursor to show while hovering this region. Read by the hover-cursor
+     *  pump in `useGestureDispatcher` via `AffordanceHit.cursor`, which
+     *  `buildAffordanceAt` fills in from the region the walk landed on. */
+    cursor?: string;
+    /** Drag binding produced when this region is hit. Lazily called so
+     *  affordances don't pay binding-construction cost on every paint frame —
+     *  state snapshots (e.g., capturing per-leaf poses at click time) belong
+     *  inside `bind()`, not inside `regions()`. */
+    bind(): AffordanceBinding<TScratch>;
+}
+/** Context passed to a region's `paint.kind === 'custom'` draw callback.
+ *  Provides both the world-space anchor (already transformed) and the
+ *  original local shape, for affordances that want to do additional
+ *  geometry themselves. */
+interface CustomPaintContext {
+    /** World-space mapping of `shape`. For `point`, only `x`/`y` are set.
+     *  For `rect`, all four fields are set. */
+    world: {
+        x: number;
+        y: number;
+        width?: number;
+        height?: number;
+    };
+    /** The original local shape (same object identity as `region.shape`). */
+    local: AffordanceRegion['shape'];
+    view: View;
+    state: ChromeState;
+}
+/**
+ * @experimental
+ * Result of an affordance hit — what the region computed about itself.
+ *
+ * `initialScratch` is the payload: what the region already knows (which
+ * corner, which target id) so the action that picks up the drag doesn't
+ * re-derive it. `<SceneCanvas>` reads it out of the layer hit-test and packs
+ * it into `AffordanceHit`, which flows to the matching action through
+ * `InvocationCtx.drag.affordance`.
+ *
+ * This used to also carry a `drag: DragChannel` naming the handlers the
+ * tool-routing dispatcher should wire up. Every implementation supplied a
+ * no-op stub that claimed, because the real routing had already moved to
+ * bindings; the field went with that dispatcher.
+ */
+interface AffordanceBinding<TScratch = unknown> {
+    initialScratch?: TScratch;
+}
+/**
+ * The fields `buildAffordanceAt` lifts out of a region's `initialScratch`
+ * when it turns a region hit into an `AffordanceHit`.
+ *
+ * Scratch is otherwise opaque — whatever the affordance wants to hand the
+ * action that picks up the drag. These few names are the exception: they mean
+ * the same thing to every affordance, and the actions that consume them
+ * (`resizeAction`, `rotateAction`) read them off `AffordanceHit` rather than
+ * out of scratch. An affordance that doesn't set them simply produces a hit
+ * without those fields.
+ */
+interface CommonAffordanceScratch {
+    /** The node (or `MULTI_RESIZE_TARGET_ID`) this chrome acts on. Becomes
+     *  `AffordanceHit.targetIds`. */
+    targetId?: string;
+    /** For resize chrome: which corner stays pinned. Mirrors the kit's
+     *  `ResizeAnchor`, spelled inline so `affordances/` doesn't take a type
+     *  dependency on the gesture layer for one field. */
+    anchor?: {
+        x: 'min' | 'max' | 'free';
+        y: 'min' | 'max' | 'free';
+    };
+    /** World-space invariant point of the transform — the fixed corner for a
+     *  resize, the pivot for a rotation. */
+    fixedPoint?: {
+        x: number;
+        y: number;
+    };
+}
+
+/**
+ * Canvas size in CSS pixels — passed to `draw` for layers that anchor to
+ * canvas edges (e.g. the debug overlay's layer-list panel). The GL backend
+ * supplies it explicitly so layers don't have to know about DPR.
+ */
+interface Dims {
+    width: number;
+    height: number;
+}
+/**
+ * A single named render sub-layer within a canvas renderer.
+ *
+ * @template TData - The data object passed to each draw call.
+ */
+interface RenderLayer<TData> {
+    /** Unique identifier used in visibility maps and ordering arrays. */
+    id: string;
+    /** Human-readable name for UI toggles. */
+    label: string;
+    /**
+     * Emit a DrawCommand tree for the GL backend to dispatch.
+     *
+     * For world-space layers (the default), emit commands in WORLD COORDS —
+     * `drawLayers` automatically wraps them in `{ kind: 'group', transform:
+     * viewToMat3(view), ... }` before handing them to the renderer. Do NOT
+     * apply the view transform yourself.
+     *
+     * For screen-space layers (`space: 'screen'`), emit commands in CSS-pixel
+     * coords directly; `drawLayers` passes them through unchanged. If part
+     * of a screen-space layer's output needs to track the view, wrap that
+     * subset manually with `viewToMat3(view)`.
+     */
+    draw: (data: TData, view: View, dims: Dims) => DrawCommand[];
+    /**
+     * Whether the layer is shown when no explicit visibility entry exists.
+     * Defaults to `true` when absent.
+     */
+    defaultVisible?: boolean;
+    /**
+     * When true, the layer is always drawn regardless of the visibility map.
+     * Useful for layers that must never be hidden (e.g. base grid).
+     */
+    alwaysOn?: boolean;
+    /**
+     * Coordinate space the layer draws in.
+     *
+     * - `'world'` (default): the layer's `draw` returns world-space commands;
+     *   `drawLayers` wraps them in a `kind: 'group'` with `viewToMat3(view)`
+     *   automatically.
+     * - `'screen'`: the layer's `draw` returns screen-space (CSS-pixel)
+     *   commands; `drawLayers` passes them through unchanged. World-anchored
+     *   chrome inside a screen-space layer must call `worldToScreen` or wrap
+     *   the relevant subset with `viewToMat3(view)` manually.
+     */
+    space?: 'world' | 'screen';
+    /**
+     * Optional hit-test for **consumer-attached** layers.
+     *
+     * Only layers registered through `CanvasExtensionApi.registerLayer` are
+     * hit-tested: `hitTestExtras` walks them last-registered-first on
+     * pointerdown, and `<SceneCanvas>` folds the result into its `affordanceAt`
+     * thunk ahead of the kit's own selection chrome. First non-null result
+     * wins; null means "I don't claim this hit, try the next layer."
+     *
+     * Layers that reach the draw stack some other way — a `Tool.overlay`, an
+     * entry in the `layers` map — are painted but never hit-tested, so defining
+     * `hitTest` on one has no effect. (The kit's own chrome doesn't need it: it
+     * goes through `buildAffordanceAt`.)
+     *
+     * Coordinates are world-space. The `data` arg is the layer's
+     * configured data slot (same as `draw`); `view` and `dims` mirror
+     * `draw`'s arguments.
+     */
+    hitTest?: (worldX: number, worldY: number, data: TData, view: View, dims: Dims, 
+    /** Chrome-caps visibility predicate. When supplied, the layer must
+     *  not return a hit from any chrome element whose id reports
+     *  `false`. Absent → every element is hittable. */
+    isVisible?: (id: string) => boolean) => AffordanceBinding | null;
+    /**
+     * Called on every pointermove when no gesture is currently captured.
+     * Lets layers (e.g. HUD widgets) track hover state without participating
+     * in the drag pipeline. Coords are world-space; the layer is responsible
+     * for any further conversion (e.g. world→screen for screen-space layers)
+     * and for its own throttling.
+     */
+    onUncapturedMove?: (worldX: number, worldY: number, evt: PointerEvent, view: View, dims: Dims) => void;
+    /**
+     * Called when the cursor leaves the canvas element. Lets layers clear
+     * any hover state they're holding.
+     */
+    onUncapturedLeave?: () => void;
+}
+/**
+ * Walk visible layers and concatenate their emitted DrawCommand arrays into
+ * one flat list, ready to feed to `WeaselRenderer.render(commands)`.
+ *
+ * Visibility resolution order:
+ *   1. `alwaysOn` — always drawn, ignores visibility map.
+ *   2. Explicit entry in `visibility` map — overrides default.
+ *   3. `layer.defaultVisible` — falls back to `true` when absent.
+ *
+ * Transform composition: world-space layers (the default; `space` unset or
+ * `'world'`) have their commands wrapped in a `kind: 'group'` with
+ * `viewToMat3(view)` before they reach the renderer. Screen-space layers
+ * (`space: 'screen'`) pass through unchanged.
+ */
+declare function drawLayers<TData>(layers: RenderLayer<TData>[], data: TData, visibility: Record<string, boolean>, order: string[] | undefined, view: View | undefined, dims: Dims): DrawCommand[];
+
+/**
+ * Live state read by rule evaluation. Built once per frame on the consuming
+ * surface — chrome-caps, the affordance pipeline, the dispatcher's
+ * eligibility filter — and discarded.
+ *
+ * Adding a new field is additive: existing rules don't change, new
+ * selector atoms can read it.
+ */
+interface RuleCtx {
+    readonly focused: boolean;
+    readonly selection: readonly NodeId[];
+    readonly multiActive: boolean;
+    readonly modifiers: ModifierState;
+    readonly action: {
+        readonly kind: string | null;
+        readonly id: string | null;
+    };
+    readonly hover: NodeId | null;
+    readonly view: View;
+    /** Active mode id. `'normal'` when no non-default mode is engaged. */
+    readonly mode: string;
+    /** Capability tags allowed by the active mode (the union of
+     *  `ModeDefinition.allows` plus implicit tags). The `capability:`
+     *  selector reads this to determine whether a tag is permitted. */
+    readonly allowedCapabilities: ReadonlySet<CapabilityTag>;
+    /** Whether the current selection may be resized. `<SceneCanvas>` folds
+     *  `selectTool.resize.resizable` over the selection (true only when every
+     *  selected node is resizable). Read by the `resizable:` selector to gate
+     *  `selection.resize-handles`. Absent (legacy ctx builders) is treated as
+     *  resizable — back-compat: handles show unless a consumer opts a node out. */
+    readonly selectionResizable?: boolean;
+    /** Whether a path is currently in anchor-edit mode. Read by the
+     *  `editingAnchors:` selector, which gates the path-edit chrome.
+     *
+     *  This is deliberately a fact about state, not about permission: the
+     *  anchor overlay and the anchor hit-test must agree, and the thing they
+     *  must agree on is "is there an edited path right now", which no
+     *  capability or mode id answers. A mode that allows `edits-anchors`
+     *  with nothing being edited should draw no anchors. Absent is treated
+     *  as false. */
+    readonly editingAnchors?: boolean;
+}
+interface BuildRuleCtxArgs {
+    focused: boolean;
+    selection: readonly NodeId[];
+    multiActive: boolean;
+    modifiers: ModifierState;
+    action: {
+        kind: string | null;
+        id: string | null;
+    };
+    hover: NodeId | null;
+    view: View;
+    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;
+}
+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;
+}
+/**
+ * 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;
+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;
+declare function evaluate(rule: Rule, ctx: RuleCtx): boolean;
+
+/**
+ * Live state read by chrome-visibility {@link Condition}s. Backward-compat
+ * alias for the legacy ChromeCtx shape — kept for consumers that still
+ * import `ChromeCtx`. Subset of `RuleCtx`: legacy ChromeCtx didn't carry
+ * mode/capability info. The resolver builds a `RuleCtx` for evaluation;
+ * surfaces that still operate in `ChromeCtx` shape supply defaults
+ * (mode='normal', empty allowedCapabilities) at the construction site.
+ */
+interface ChromeCtx {
+    readonly focused: boolean;
+    readonly selection: readonly NodeId[];
+    readonly multiActive: boolean;
+    readonly modifiers: ModifierState;
+    readonly action: {
+        readonly kind: string | null;
+        readonly id: string | null;
+    };
+    readonly hover: NodeId | null;
+    readonly view: View;
+}
+/**
+ * Composable visibility predicate with fluent surface. Carries its underlying
+ * `Rule` tree at `.rule` so the resolver can introspect / share trees with
+ * the affordance pipeline and the dispatcher's eligibility filter.
+ *
+ * Callable form `cond(ctx)` evaluates the tree against ctx. The fluent
+ * methods return new Conditions wrapping new trees.
+ *
+ * **Chain semantics: strict left-to-right, no precedence.**
+ * `a.and(b).or(c)` is `(a && b) || c`; `a.or(b).and(c)` is
+ * `(a || b) && c`. Mix `.and` and `.or` only when you mean
+ * left-to-right evaluation. For grouped disjunction, name the
+ * subexpression or use the top-level `or(...)`.
+ */
+interface Condition {
+    (ctx: RuleCtx): boolean;
+    readonly rule: Rule;
+    /** `this && other` */
+    and(other: Condition | Rule): Condition;
+    /** `this || other` */
+    or(other: Condition | Rule): Condition;
+    /** `this && !other` */
+    andNot(other: Condition | Rule): Condition;
+    /** `this || !other` */
+    orNot(other: Condition | Rule): Condition;
+}
+/**
+ * Stable identifier for one user-visible chrome element. The same id
+ * gates both paint and hit-test — there is no separate
+ * `affordance.X` / `selection.X` split — so toggling a rule cannot
+ * leave a visually-present but un-hittable handle (or vice versa).
+ *
+ * Naming convention by lifecycle:
+ *
+ *   - `selection.*` — chrome reflecting committed selection state
+ *     (persists between actions).
+ *   - `action.*` — chrome that only exists during an in-flight
+ *     action (vanishes on commit / cancel).
+ *   - `snap.*` — snapping system chrome (guides, target highlights).
+ *   - `grid`, `debug.*` — environment chrome.
+ *
+ * The intersection `(string & {})` keeps the union open so consumers
+ * can register their own ids; the kit's built-ins are listed
+ * explicitly for autocomplete.
+ */
+type ChromeId = 'selection.outline' | 'selection.resize-handles' | 'selection.rotation-handle' | 'action.marquee' | 'action.lasso' | 'action.move-ghosts' | 'action.insert-preview' | 'action.commands' | 'snap.guides' | 'snap.targets' | 'grid' | (string & {});
+/**
+ * Consumer override map. Merged on top of the kit's
+ * `defaultVisibilityRules`; absent keys fall through to defaults,
+ * absent ids fall through to `always`. Entries may be either fluent
+ * `Condition` instances OR raw `Rule` trees — the resolver normalizes.
+ */
+type VisibilityRules = Partial<Record<ChromeId, Condition | Rule>>;
+
+/** A 2D point in either world or screen coordinates. */
+interface Point2 {
+    x: number;
+    y: number;
+}
+/**
+ * Information about which UI affordance was hit at pointerdown.
+ *
+ * Populated by the dispatcher when the `affordanceAt` thunk is provided to
+ * `useGestureDispatcher`. Tools / action invokers that only fire on a specific
+ * affordance (e.g. a resize handle) use this field as a guard — if the
+ * affordance is absent or is the wrong kind, they return `{}` and let other
+ * bindings handle the drag.
+ *
+ * `kind` is a discriminator string:
+ *   - `'handle:top-left'` / `'handle:top-right'` / `'handle:bottom-left'` /
+ *     `'handle:bottom-right'` — corner resize handles.
+ *   - `'rotate-handle'` — the rotation affordance.
+ *   - `'anchor:N'` — a path anchor at index N.
+ *
+ * `fixedPoint` is the world-space point that should remain stationary during
+ * the gesture. For resize handles this is the opposite (diagonally fixed)
+ * corner; for rotate it is the pivot.
+ *
+ * `targetIds` are the node ids this affordance belongs to.
+ */
+interface AffordanceHit {
+    /** Discriminator string, e.g. `'handle:bottom-right'`. */
+    kind: string;
+    /** World-space fixed/pivot point. For resize: opposite corner. For rotate: pivot. */
+    fixedPoint?: {
+        x: number;
+        y: number;
+    };
+    /** Which nodes this affordance belongs to. */
+    targetIds?: string[];
+    /** Set when `kind` matches `'handle:*'`. Identifies which corner stays
+     *  fixed during a resize so consumers (resizeAction) don't re-parse `kind`.
+     *  Other affordance kinds (rotate-handle, anchor:N, controlIn:N, controlOut:N)
+     *  leave this undefined. */
+    anchor?: ResizeAnchor;
+    /** CSS cursor to show while the pointer hovers this affordance (no
+     *  gesture in flight). Consumed by the hover-cursor pump in
+     *  `useGestureDispatcher`; unset = the pump falls through to
+     *  action-cursor prediction, then to the active tool's cursor. */
+    cursor?: string;
+    /**
+     * Free-form payload from whatever produced the hit, carried through to the
+     * matching action untouched.
+     *
+     * Kit affordances describe themselves fully in the fields above and leave
+     * this unset. It exists for affordances the kit doesn't know the shape of —
+     * a registered layer's own chrome, where the hit-test already resolved
+     * *which* of its pieces was hit and the action would otherwise have to
+     * redo that work. `@weasel-js/hud` passes the hit widget here.
+     */
+    payload?: unknown;
+}
+/**
+ * One accumulated point on a drag trail: world-space position plus whatever
+ * stylus state the originating `PointerEvent` carried.
+ *
+ * The stylus fields are absent for mouse/touch on browsers that don't report
+ * them, and for synthetic events. Consumers that want pressure-driven output
+ * (e.g. `Stroke.vertexWidths` from a pencil stroke) read them off the samples
+ * their `insert` dep receives — see `apps/site/demos/VertexWidthsDemo.tsx`.
+ */
+interface DragSample extends Point2 {
+    /** 0..1. Mouse/touch report 0.5 while a button is held, per the spec. */
+    pressure?: number;
+    /** Degrees, ±90. Zero for mouse/touch. */
+    tiltX?: number;
+    /** Degrees, ±90. Zero for mouse/touch. */
+    tiltY?: number;
+}
+/** Per-invocation runtime context the dispatcher hands to an Invoker.
+ *  Gesture-kind-specific fields (`drag`, `wheel`, `multiTouch`, `key`) are
+ *  populated only for matching gesture kinds. */
+interface InvocationCtx {
+    world: Point2;
+    screen: Point2;
+    modifiers: ModifierState;
+    deps: ActionDeps;
+    drag?: {
+        start: Point2;
+        current: Point2;
+        delta: Point2;
+        /**
+         * Drag delta in client/screen coordinates (CSS pixels from the drag
+         * origin). Use this — never `delta` — for any action whose effect
+         * mutates the viewport itself (pan, view-zoom), because world-space
+         * deltas become self-referential as the view shifts mid-drag.
+         *
+         * Populated when the dispatcher received `clientX`/`clientY` on the
+         * underlying pointer events. Absent for legacy callers that don't
+         * provide them.
+         */
+        screenDelta?: Point2;
+        affordance?: AffordanceHit;
+        /**
+         * Full pointermove history for the current drag, in world space, with
+         * per-sample stylus state when the browser reported it.
+         * Accumulated by the dispatcher on every `pointermove` pump event.
+         * Available only during `onMove` and `onEnd` calls (not on `start`).
+         * Used by `lassoSelectAction` to build its polygon vertex list and by
+         * `insertAction`'s pencil kind to carry the freehand stroke.
+         */
+        points?: DragSample[];
+    };
+    wheel?: {
+        deltaX: number;
+        deltaY: number;
+        deltaZ: number;
+    };
+    multiTouch?: {
+        centroid: Point2;
+        spread: number;
+        rotation: number;
+        /**
+         * Pinch-zoom geometry. Populated by the dispatcher when a multitouch
+         * handle is in flight and a pointermove-pump fires.
+         * `startSpread` is the spread at the moment the gesture began.
+         * `currentSpread` is the spread at the current frame.
+         */
+        pinch?: {
+            startSpread: number;
+            currentSpread: number;
+            centroid: Point2;
+        };
+    };
+    key?: {
+        key: string;
+        repeat: boolean;
+    };
+    /**
+     * Per-invocation parameters. Populated by `ActionsRegistry.begin()` for
+     * UI-driven ongoing actions (color picker, opacity slider) so handles can
+     * read the current value on `start` and updated values on `onMove`. The
+     * gesture dispatcher does not populate this field; gesture-driven actions
+     * receive params via `BindingOpts.params` on `start` (the `opts` arg).
+     */
+    params?: Record<string, unknown>;
+}
+/** Per-invocation options the dispatcher reads from a `GestureBinding`'s
+ *  `opts` field and passes to `OngoingInvoker.start`. Today carries
+ *  behaviors; extensible. */
+interface BindingOpts {
+    behaviors?: ActionBehavior<unknown, unknown, unknown>[];
+    /** Per-binding action parameters. The action's invoker reads
+     *  these via the second arg to `run` (or via InvocationCtx for ongoing
+     *  invokers, when needed). Loose typing (Record<string, unknown>) for
+     *  now; consider per-action typing later via BindingOpts<A>.
+     *
+     *  params may also be a thunk evaluated each time the
+     *  dispatcher (or invoker) needs the value. Thunks let tools close over
+     *  refs that mutate during a gesture (e.g. polygon `sides` adjusted
+     *  mid-drag via ArrowUp). For ongoing invokers that want the latest
+     *  values at commit, the invoker can re-call the thunk inside `onEnd`
+     *  via `resolveParams(opts?.params)`. */
+    params?: Record<string, unknown> | (() => Record<string, unknown>);
+}
+/** Convention-shaped action dependencies bag. Actions declare which
+ *  contexts they consume; the dispatcher composes them per call.
+ *  Consumer-side contexts (e.g. ColorContext) plug in by extending. */
+interface ActionDeps {
+    selection?: unknown;
+    view?: unknown;
+    scene?: unknown;
+    pointer?: unknown;
+    activeTool?: unknown;
+    [k: string]: unknown;
+}
+/**
+ * Discriminated overlay shape returned by `OngoingHandle.overlay()`.
+ * Dispatcher-side chrome surface for in-flight
+ * gestures that paint non-ghost visuals. The canvas's
+ * `useDispatcherOverlayLayer` walks every in-flight handle, calls
+ * `overlay()`, and dispatches on `kind` to draw the appropriate shape.
+ *
+ * `marquee` mirrors `AreaSelectOverlay`; `lasso` mirrors `LassoSelectOverlay`.
+ * `commands` is the generic escape hatch — actions emit arbitrary
+ * `DrawCommand[]` for previews the typed variants can't express (insert
+ * shape outlines, paste ghosts of synthetic nodes, custom chrome). World-
+ * space is the default; the layer wraps in `viewToMat3` so commands track
+ * the camera. Set `space: 'screen'` for projections you've already done
+ * yourself (rare).
+ */
+type OngoingOverlay = {
+    kind: 'marquee';
+    start: {
+        x: number;
+        y: number;
+    };
+    current: {
+        x: number;
+        y: number;
+    };
+    shiftHeld: boolean;
+} | {
+    kind: 'lasso';
+    vertices: ReadonlyArray<{
+        x: number;
+        y: number;
+    }>;
+    current: {
+        x: number;
+        y: number;
+    };
+    shiftHeld: boolean;
+} | {
+    kind: 'commands';
+    commands: readonly DrawCommand[];
+    /** Coordinate space the commands are authored in. Default `'world'`
+     *  — the layer wraps them in `viewToMat3(view)` so they track the
+     *  camera. `'screen'` emits them as-is (CSS pixels). */
+    space?: 'world' | 'screen';
+} | {
+    /**
+     * Live insert-drag preview — dispatched by `insertAction` while the
+     * user is dragging out a new shape. Pre-commit there is no scene node
+     * to ghost via `previewIds()`/`previewPose()`, so insert paints its
+     * preview through the dispatcher overlay layer instead.
+     *
+     * `shape` is the kit's built-in insert kind. `bounds` is the AABB of
+     * the current drag (start/current normalized). `extras` is the
+     * per-kind extras the action already collected — the overlay
+     * renderer rebuilds the shape using the same path builders the
+     * commit factory uses, so the preview matches the eventual node.
+     *
+     * `extras` is opaque (`unknown`) at the union level; the overlay
+     * renderer narrows on `shape` and casts the field shape it expects.
+     */
+    kind: 'insertPreview';
+    shape: 'rect' | 'ellipse' | 'line' | 'polygon' | 'star' | 'pencil';
+    bounds: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    extras: unknown;
+    /** World-space point to paint a small "anchor" dot at. Sells the
+     *  click point as the drag's anchor — particularly useful for
+     *  radial shapes (polygon/star) where no vertex sits on the
+     *  click point, and for any shape in center mode where the dot
+     *  marks the center the shape grows around. */
+    anchorPoint?: {
+        x: number;
+        y: number;
+    };
+};
+/** Handle returned from an `OngoingInvoker.start`. The dispatcher pumps
+ *  `onMove` on subsequent input events of the same gesture and calls
+ *  `onEnd` exactly once (with `'commit'` on natural completion or `'cancel'`
+ *  on pointercancel / blur / escape). */
+interface OngoingHandle {
+    /**
+     * Optional logical action kind — a stable, human-readable tag the
+     * dispatcher exposes via `getActiveAction()` for chrome-visibility
+     * rules and any other surface that wants to react to "what action
+     * is currently in flight" without inspecting handles directly.
+     *
+     * Examples: `'marquee'`, `'lasso'`, `'move'`, `'resize'`, `'rotate'`,
+     * `'pan'`, `'pinch'`.
+     *
+     * Distinct from the dispatcher's internal `gestureId` (`pointer-mouse`,
+     * `key-held-Space`, etc.) which keys per-pointer state and is not
+     * meaningful to consumers.
+     *
+     * When omitted, the action is "anonymous" — `getActiveAction().kind`
+     * reports `null` even though a handle is in flight. This is fine for
+     * actions that don't have visible chrome of their own.
+     */
+    kind?: string;
+    onMove?(ctx: InvocationCtx): void;
+    onEnd?(ctx: InvocationCtx, reason: 'commit' | 'cancel'): void;
+    /**
+     * Optional preview surface — dispatcher-side ghost overlay.
+     *
+     * An ongoing-action implementation may populate `previewIds()` +
+     * `previewPose(id)` to expose its in-flight preview state for the
+     * canvas's preview-ghost layer (`usePreviewGhostLayer`) to render on
+     * top of the committed scene during the gesture.
+     *
+     * Returning `null` (or omitting the method entirely) means "no preview
+     * this gesture" — the canvas will skip this handle as a source.
+     *
+     * Semantics mirror the tool-side `Tool.previewIds` / `Tool.previewPose`
+     * pair: `previewIds()` enumerates the displaced node ids; `previewPose(id)`
+     * returns the interim pose for one of those ids (shape opaque — the
+     * canvas casts to its `TPose` parameter). The preview-ghost layer
+     * merges all sources via first-non-null semantics, with tool-side
+     * previews taking precedence over dispatcher-side (preserves
+     * backwards-compat during the registry-unification migration).
+     */
+    previewIds?(): Iterable<string> | null;
+    previewPose?(id: string): unknown | null;
+    /**
+     * When `false`, the preview-ghost layer paints the ghost AND the
+     * source node stays visible at its committed pose. Defaults to
+     * `true` (move/resize/rotate semantics: ghost replaces the source
+     * during the gesture). Clone overrides to `false` so the original
+     * stays put and the ghost appears at the drag target.
+     */
+    previewHidesSource?: boolean;
+    /**
+     * Optional per-id preview *data*. Falls back to the committed
+     * `node.data` when null/absent. Use when the gesture mutates
+     * `node.data` (e.g. anchor-edit on nodes that store the polygon on
+     * `data.path`) rather than (or in addition to) the pose. The preview-
+     * ghost layer assembles a synthetic node from `{ ...node, pose:
+     * previewPose ?? node.pose, data: previewData ?? node.data }` before
+     * calling the scene slot's `drawOne`.
+     *
+     * Sources compose first-non-null per axis: an action can emit only
+     * `previewPose` (translation), only `previewData` (data-only edit),
+     * or both (pose + data both change, e.g. anchor drag on a data.path
+     * node where the bounds shift).
+     */
+    previewData?(id: string): unknown | null;
+    /**
+     * Optional chrome surface — dispatcher-side overlay layer.
+     *
+     * An ongoing-action implementation may populate `overlay()` to expose a
+     * non-ghost visual (marquee rectangle, lasso polyline) for the canvas's
+     * `useDispatcherOverlayLayer` to paint while the gesture is in flight.
+     * Returning `null` (or omitting the method) means "no overlay this
+     * gesture" — the canvas will skip this handle as a chrome source.
+     *
+     * Distinct from the `previewIds()`/`previewPose(id)` ghost surface,
+     * which paints displaced scene-node silhouettes. Marquee and lasso
+     * gestures don't displace any node, but still need on-screen feedback.
+     */
+    overlay?(): OngoingOverlay | null;
+}
+/** Fire-once invocation. Runs to completion synchronously (or fires off an
+ *  async side-effect; the registry doesn't wait). */
+interface ImmediateInvoker {
+    timing: 'immediate';
+    /** `params` carries the matched binding's opts.params. When
+     *  invoked via the legacy `Action.run` bridge or from the command palette
+     *  with no per-binding context, `params` is undefined; descriptors should
+     *  default to a sensible variant. */
+    run(deps: ActionDeps, params?: Record<string, unknown>): void;
+}
+/** Phase-machine invocation. `start` opens the phase and returns the handle
+ *  the dispatcher pumps. */
+interface OngoingInvoker {
+    timing: 'ongoing';
+    start(ctx: InvocationCtx, opts?: BindingOpts): OngoingHandle;
+}
+/** Pluggable invocation strategy for an Action. Future variants
+ *  (`longPress`, `twoStage`, `modal`) extend this union without touching
+ *  the `Action` type. */
+type Invoker = ImmediateInvoker | OngoingInvoker;
+
+/** Boolean op identifiers — five Pathfinder primaries plus Crop. */
+type BooleanOp = 'union' | 'intersect' | 'subtract' | 'exclude' | 'divide' | 'crop';
+/**
+ * z-position descriptor for a path node. `parentId` is the direct parent
+ * (or `null` for a top-level node); `index` is the position within that
+ * parent's child order. Used by the optional `getZOrder` hook below to
+ * reposition the result of a boolean op at the topmost source's slot.
+ */
+/** @internal */
+interface BooleanZOrder {
+    parentId: string | null;
+    index: number;
+}
+/** Adapter the hook and the pure core both consume. */
+interface BooleansAdapter {
+    getSelection(): NodeId[];
+    getWorldPath(id: NodeId): Path | undefined;
+    compareZ(a: NodeId, b: NodeId): number;
+    /**
+     * Mint a new node from a boolean-op result `Path`. `producedBy` names the
+     * op that synthesized it — adapters that store provenance (e.g. for a
+     * layer-panel icon) record it; others ignore the arg.
+     */
+    createPathNode(path: Path, producedBy: BooleanOp): {
+        id: string;
+    };
+    /**
+     * Optional: return the full object for an id, used by the delete ops so
+     * their `invert` (an insert) can restore the complete object on undo.
+     * If omitted, a `{ id }` stub is captured — undo will reinstate the id
+     * but consumers reading other fields (path, fill, etc.) will see them as
+     * undefined. Mirrors `DeleteAdapter.getNode`; should be provided whenever
+     * undo over boolean ops is expected to be lossless.
+     */
+    getNode?(id: NodeId): {
+        id: string;
+    } | undefined | null;
+    /**
+     * Optional: return the parent + child-index of `id` so the result of a
+     * boolean op can be placed in the topmost source's z-slot. Adapters that
+     * also expose `getChildren`/`setChildOrder` (the `ReorderAdapter`
+     * contract) will have the kit emit a `createMoveToIndexOp` after the
+     * inserts. Adapters that omit this method get v1 behavior — the result
+     * lands wherever the adapter's plain `insertNode` defaults to.
+     */
+    getZOrder?(id: NodeId): BooleanZOrder | undefined;
+    applyOps?(ops: Op[], label?: string): void;
+    setSelection?(ids: NodeId[]): void;
+    insertNode?(node: {
+        id: string;
+    }): void;
+    removeNode?(id: string): void;
+}
+/** Outcome reported back to callers (lets the hook surface no-op signals). */
+type BooleanOpResult = {
+    kind: 'applied';
+    resultIds: string[];
+} | {
+    kind: 'noop';
+    reason: 'no-paths' | 'too-few-for-subtract' | 'empty-result';
+};
+declare function applyBooleanOp(adapter: BooleansAdapter, op: BooleanOp): BooleanOpResult;
+
+/**
+ * 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';
+/** API returned by {@link useSelection}. */
+interface SelectionApi {
+    /** Current selection. Re-renders trigger when this reference changes. */
+    current: readonly NodeId[];
+    /** Imperative read for use inside event callbacks (avoids stale closures). */
+    get(): NodeId[];
+    /** Replace selection. */
+    set(ids: NodeId[]): void;
+    /** Add id (multi-mode appends; single-mode replaces). */
+    add(id: NodeId): void;
+    /** Remove id from selection. */
+    remove(id: NodeId): void;
+    /** Toggle id in/out of selection. */
+    toggle(id: NodeId): void;
+    /** Clear selection. */
+    clear(): void;
+    /** True if id is selected. */
+    contains(id: NodeId): boolean;
+    /**
+     * Apply a click to the selection per the configured mode/extend key.
+     * - `single`: replaces selection with `[id]`, regardless of modifiers.
+     * - `multi`: with the extend key held, toggles `id` in/out of the selection;
+     *   otherwise replaces with `[id]`.
+     */
+    applyClick(id: NodeId, modifiers: {
+        shift: boolean;
+        meta: boolean;
+        ctrl: boolean;
+    }): void;
+    /** Pre-built methods for spreading into an adapter that needs them. */
+    adapterMethods: {
+        getSelection: () => NodeId[];
+        setSelection: (ids: NodeId[]) => void;
+    };
+}
+/** Options for {@link useSelection}. */
+interface UseSelectionOptions {
+    /** Default `'single'`. */
+    mode?: SelectionMode;
+    /** Default `'shift'`. Ignored in single-mode. */
+    extend?: SelectionExtendKey;
+    /** Default `[]`. */
+    initial?: readonly NodeId[];
+    /** When `true`, every mutator (`set`/`add`/`remove`/`toggle`/`clear`/
+     *  `applyClick`) is a no-op — selection stays at whatever `initial`
+     *  pinned it to. Useful for demos that exist to showcase a single
+     *  pre-selected node (e.g. the bezier-edit curve) and don't want a
+     *  stray click to deselect. */
+    lock?: boolean;
+}
+/**
+ * Default implementation of the `getSelection` / `setSelection` adapter
+ * contract every action hook (delete, duplicate, nudge, group, ...) requires.
+ *
+ * Owns selection state, exposes a click-policy helper (single vs multi with
+ * an extend key), and pre-builds the two adapter methods consumers otherwise
+ * hand-roll in every demo:
+ *
+ * ```tsx
+ * const selection = useSelection({ mode: 'multi' });
+ * const adapter = { ...arrayAdapter({...}), ...selection.adapterMethods };
+ * ```
+ */
+declare function useSelection(opts?: UseSelectionOptions): SelectionApi;
+
+/** Context handed to every content handler for one ingest event. */
+interface IngestCtx {
+    /** World-space arrival point (drop / pointed imperative ingest); `null`
+     *  for paste and point-less calls — handlers pick their own policy
+     *  (the kit image handler centers on the viewport). */
+    point: {
+        x: number;
+        y: number;
+    } | null;
+    /** Visible canvas area in world coordinates. */
+    viewportWorldRect(): {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    /** The kit insert dep — id/layer/undoable-op supplied; the canonical way
+     *  for a handler to mint a node (`insert.commit(bounds, { kind, ... })`). */
+    insert: InsertDep;
+    /** Raw op commit for handlers that build their own ops. */
+    applyOps(ops: Op[], label?: string): void;
+    scene: Scene<unknown, string, unknown>;
+    selection: SelectionApi;
+    /** Consumer file→src resolver (SceneCanvas `ingestion.resolveSrc`).
+     *  When absent, the kit image handler embeds as a `data:` URI. */
+    resolveSrc?: (file: File) => Promise<string>;
+    /** Kit SVG-handler options (SceneCanvas `ingestion.svg`) — e.g.
+     *  `{ unpack: unpackSvgFiles }` (from `@weasel-js/svg`) to parse SVG files
+     *  into scene nodes. */
+    svg?: SvgIngestOptions;
+    /** Clipboard-paste seam — present when the hosting `SceneCanvas` supplied
+     *  an adapter with `commitPaste`. `reviver` comes from
+     *  `SceneCanvasProps.ingestion.clipboard`. Absent ⇒ the kit weasel-JSON
+     *  handler declines inert (dwarn, nothing ingested) — its matched items
+     *  were already consumed at match time, so they do NOT fall through;
+     *  only match-level misses flow on to other handlers. */
+    clipboard?: ClipboardIngestCtx;
+    /** Set to `true` by the kit weasel-JSON handler when it successfully
+     *  pastes a payload in this event. The `ctx` object is shared across all
+     *  handlers in one `runIngest` call, and higher-priority handlers' `handle`
+     *  bodies run (synchronously) before lower ones — so `kit:svg`'s
+     *  `text/plain` SVG fallback reads this to decline the SVG flavor of a copy
+     *  whose canonical weasel-JSON flavor already ingested (avoids a
+     *  double-paste when both flavors ride one clipboard event). */
+    consumedWeaselPayload?: boolean;
+    /** Full action-deps bag, for consumer handlers that need more. */
+    deps: ActionDeps;
+}
+interface ContentHandlerEntry {
+    /** Stable identifier — used for unregistration and debugging
+     *  (`'kit:image'`, `'app:csv'`). */
+    id: string;
+    /** MIME glob(s) (`'image/*'`, `'text/csv'`) or an item predicate. */
+    match: string | string[] | ((item: IngestItem) => boolean);
+    /** Higher runs earlier. Kit defaults register at -100 so any consumer
+     *  handler (default 0) beats them. */
+    priority?: number;
+    handle(items: IngestItem[], ctx: IngestCtx): void | Promise<void>;
+}
+/** Register a content handler. Returns a disposer that removes it. */
+declare function registerContentHandler(entry: ContentHandlerEntry): () => void;
+
+/**
+ * @experimental
+ * PointerContext — a tiny ambient context that publishes the world-space
+ * position of the canvas pointer, refreshed on every `pointermove` over
+ * the canvas. Cleared (set to `null`) on `pointerleave`.
+ *
+ * Why ref-based and not state-based: cursor moves fire dozens of times per
+ * second; routing those through React state would re-render every consumer
+ * in the tree. The context exposes a stable `pointerRef` whose `.current`
+ * is mutated directly by the publisher, plus a thunk `getDropPoint()` that
+ * reads it on demand. Consumers (e.g. `useClipboard`) pull via the thunk
+ * inside their callbacks — no subscription, no re-render.
+ *
+ * `<SceneCanvas>` publishes automatically. `useClipboardOps` consumes when
+ * the caller didn't pass an explicit `getDropPoint` option. Other future
+ * hit-on-cursor consumers (drop-zone hover, context-menu anchor) can reuse
+ * the same context.
+ */
+
+/** @experimental World-space pointer position, or `null` when the pointer
+ *  isn't over the publishing canvas. */
+type PointerWorldPos = {
+    worldX: number;
+    worldY: number;
+} | null;
+/** @experimental */
+interface PointerContextValue {
+    /** Live ref — mutate to publish, read for the latest snapshot. The
+     *  identity is stable for the lifetime of the provider. */
+    readonly pointerRef: MutableRefObject<PointerWorldPos>;
+    /** Convenience thunk equivalent to `() => pointerRef.current`. Stable
+     *  identity for the lifetime of the provider; safe to pass to hooks. */
+    readonly getDropPoint: () => PointerWorldPos;
+}
+/**
+ * @experimental
+ * Wrap the part of the React tree that should share a pointer-position
+ * context. Usually placed at the demo / app root, alongside
+ * `<ActionsProvider>` and `<SelectionContextProvider>`.
+ *
+ * Most consumers don't need to mount this directly — `<SceneCanvas>` mounts
+ * an internal provider when no parent provider is in scope, so child hooks
+ * (`useClipboard` without an explicit `getDropPoint`) read the canvas's
+ * tracked pointer for free.
+ */
+declare function PointerContextProvider({ children }: {
+    children: ReactNode;
+}): ReactNode;
+/** @experimental Read the surrounding pointer-context value, or `null` when
+ *  no provider is in scope. */
+declare function usePointerContext(): PointerContextValue | null;
+
+interface ActiveToolContextValue {
+    active: string;
+    hotkeyStack: string[];
+    setActive(id: string): void;
+    pushHotkey(id: string): void;
+    popHotkey(): void;
+}
+interface ActiveToolContextProviderProps {
+    children: ReactNode;
+    initialActive?: string;
+}
+declare function ActiveToolContextProvider({ children, initialActive, }: ActiveToolContextProviderProps): react_jsx_runtime.JSX.Element;
+declare function useActiveToolContext(): ActiveToolContextValue;
+/**
+ * Like `useActiveToolContext`, but returns `null` when no
+ * `<ActiveToolContextProvider>` is in scope instead of throwing. Used by
+ * `useStandardActions` to preserve its silent-no-op contract when no provider
+ * is present.
+ */
+declare function useOptionalActiveToolContext(): ActiveToolContextValue | null;
+/**
+ * Conditional `<ActiveToolContextProvider>` wrapper. Mounts a provider only
+ * when no parent provider is in scope — otherwise renders children unwrapped
+ * so callers (e.g. `<WeaselProvider>`, `<SceneCanvas>`) defer to the host's
+ * existing scope. Mirrors `ActionsProviderIfRoot` / `DepRegistryProviderIfRoot`.
+ */
+declare function ActiveToolContextProviderIfRoot({ children, }: {
+    children: ReactNode;
+}): react_jsx_runtime.JSX.Element;
+
+/**
+ * `enterTextEditAction` — immediate Action descriptor for entering in-place
+ * text editing on a selected text node.
+ *
+ * ## Status: REAL
+ *
+ * Fires via `useTextTool.bindings` when the user clicks on a
+ * selected text node. Calls `deps.textEdit.startEdit(id)` to activate the
+ * contenteditable overlay managed by `useTextEdit` / `useSceneTextEdit`.
+ *
+ * ## No defaultBinding / defaultBinding
+ *
+ * This action has no ambient key or gesture binding — it fires ONLY via
+ * `useTextTool`'s `Tool.bindings` entry:
+ *
+ * ```ts
+ * bindings: [
+ *   { spec: { kind: 'click', target: 'selected-body' }, actionId: 'enterTextEdit' },
+ * ]
+ * ```
+ *
+ * Keeping it binding-free avoids ambient double-fire and scopes the action to
+ * the text tool context where `classifyTarget` is already wired.
+ *
+ * ## Self-guard: only act on text nodes
+ *
+ * The `'selected-body'` target yields a match for any selected node kind. To
+ * avoid entering text-edit mode when the text tool happens to have a non-text
+ * node selected, the action self-guards via an optional `isTextNode` predicate
+ * on `TextEditDep`:
+ *
+ * - When `isTextNode` is absent: action fires unconditionally (the binding
+ *   spec is the real gate — consumers should only bind this action from the
+ *   text tool).
+ * - When `isTextNode(id)` returns `false`: action is a no-op for that node.
+ *
+ * ### Pre-filtering at dispatch time
+ *
+ * `classifyTarget` now surfaces node kind, so a binding can pre-filter instead
+ * of relying on the self-guard:
+ *
+ * ```ts
+ * { spec: { kind: 'click', target: 'kind:text:selected' }, actionId: 'enterTextEdit' }
+ * ```
+ *
+ * That reads the *routing trait's* kind, so it matches whatever names the
+ * consumer registered in `<SceneCanvas routing>` — `'text'` under the kit's
+ * inferred default. `isTextNode` stays on `TextEditDep` because it also covers
+ * consumers who bind the broader `'selected-body'` target, and because it is
+ * the only guard for a consumer who opted out of routing entirely.
+ *
+ * ## Migration plan for useTextTool
+ *
+ * When wiring `useTextTool` to `Tool.bindings`:
+ *
+ * 1. Add to `useTextTool`'s `bindings`:
+ *    ```ts
+ *    { spec: { kind: 'click', target: 'selected-body' }, actionId: 'enterTextEdit' }
+ *    ```
+ * 2. Register a `textEdit` dep sourced from the `useTextEdit` / `useSceneTextEdit`
+ *    return value, plus an `isTextNode` predicate that checks `data.kind === 'text'`
+ *    (or however the consumer identifies text nodes).
+ * 3. The existing `hitExisting` gate in `useTextTool`'s click route becomes
+ *    redundant — remove it in the same pass.
+ */
+
+/**
+ * Dep for `enterTextEditAction`.
+ *
+ * Wrap the return value of `useTextEdit` / `useSceneTextEdit` to source this
+ * dep. The `isTextNode` predicate is optional — when absent the action fires
+ * unconditionally (the binding spec acts as the gate).
+ *
+ * @example
+ * ```ts
+ * const textEdit = useSceneTextEdit({ scene, container });
+ * useDepSource('textEdit', () => ({
+ *   startEdit: textEdit.startEdit,
+ *   isTextNode: (id) => scene.get(id as NodeId)?.data?.kind === 'text',
+ * }));
+ * ```
+ */
+interface TextEditDep {
+    /**
+     * Begin editing the node with `id`. Activates the contenteditable overlay
+     * managed by `useTextEdit` / `useSceneTextEdit`.
+     */
+    startEdit(id: string, opts?: {
+        caret?: number | 'all';
+    }): void;
+    /**
+     * Optional predicate: returns `true` when the node with `id` is a text node.
+     * When absent the action fires on any selected node (binding spec is the gate).
+     * When present and returning `false`, the invocation is a no-op.
+     */
+    isTextNode?(id: string): boolean;
+}
+/**
+ * @experimental
+ * Static descriptor for the `enterTextEdit` Action.
+ *
+ * Requires dep-schema entries: `textEdit`, `selection`.
+ *
+ * No `defaultBinding` / `defaultBinding` — fires only via `Tool.bindings`.
+ * Self-guards via `TextEditDep.isTextNode` when provided.
+ */
+declare const enterTextEditAction: Action & {
+    requires: string[];
+};
+
+/**
+ * Consumer-supplied commit for the Slice action. `commit` receives the finite
+ * slice segment (world coords); the consumer scans the scene, splits crossed
+ * paths via `splitPathByLine`, and applies the result as one undoable batch.
+ */
+interface SliceDep {
+    commit(a: Point2, b: Point2): void;
+}
+/**
+ * @experimental
+ * Static descriptor for the `slice` Action.
+ *
+ * Ongoing drag invoker: tracks a slice line from drag start to current
+ * pointer, renders a live line overlay while the gesture is in flight,
+ * and on commit calls `SliceDep.commit(a, b)`. No-ops gracefully when
+ * the `slice` dep is absent.
+ */
+declare const sliceAction: Action & {
+    requires: string[];
+};
+
+/** Optional consumer seam: given a node and the affine `m` that a pose-transform
+ *  action applied to the node's POSE, return updated `data` with the node's
+ *  data-held geometry transformed by `m`, or `null` if this node has no
+ *  data-held geometry (the kit leaves `data` alone). */
+interface GeometryProjection {
+    transform(node: {
+        id?: string;
+        data: unknown;
+        pose: unknown;
+    }, m: Mat3): unknown | null;
+}
+
+/** Minimal view API the action layer consumes. May be refined later. */
+interface ViewApi {
+    get(): View;
+    set(v: View): void;
+    /** Optional recenter callback. When wired, `viewportZoomAction`'s
+     *  `reset` branch (Cmd-0) calls this instead of resetting to identity —
+     *  letting consumers re-fit the page (or other reference bounds) into
+     *  the workspace. Receives no args; the consumer reads its own bounds
+     *  + host dims and dispatches `setView(...)`. */
+    recenter?(): void;
+    /** Optional canvas-local host dimensions (CSS px). When wired,
+     *  `viewportZoomAction`'s keyboard branches (Cmd+= / Cmd+-) anchor at the
+     *  host center instead of the top-left origin. Null when the host isn't
+     *  measurable (unmounted). */
+    hostSize?(): {
+        width: number;
+        height: number;
+    } | null;
+}
+/**
+ * Adapter dep for `areaSelectAction`.
+ *
+ * Provided by `<SceneCanvas>` / `<StandardActionsRegistrar>` via AABB
+ * overlap over scene nodes. Consumers with custom hit-testing override this
+ * dep entry in their own registrar.
+ */
+/**
+ * Topmost-node-at-world-point dep, consumed by `moveAction` for
+ * reparent-on-drop and available to any action that needs a single-best
+ * pick. Mirrors the same hit-test plumbing `<SceneCanvas>` feeds to the
+ * tool dispatcher; consumers with custom hit-testing override here.
+ *
+ * `exclude` is iterated once per call and treated as a set membership
+ * test — the dep walks hits front-to-back and returns the first id not
+ * in the exclude set. Pass moving-node roots + their descendants when
+ * the caller wants to ignore the nodes it's manipulating.
+ */
+type NodeAtPointDep = (point: {
+    x: number;
+    y: number;
+}, exclude?: Iterable<NodeId>) => NodeId | null;
+interface AreaSelectDep {
+    /** Return ids of all scene nodes whose AABB overlaps `bounds`. */
+    hitTestArea(bounds: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    }): NodeId[];
+    /** Return the current selection id list. */
+    getSelection(): NodeId[];
+    /** Replace the current selection. */
+    setSelection(ids: NodeId[]): void;
+}
+/**
+ * Adapter dep for `editAnchorsAction`.
+ *
+ * Provides narrow read/write access to the editable polygon for a single
+ * node. Consumers register this dep so anchor-edit actions can read/write
+ * the polygon WITHOUT knowing whether it lives directly on the node's
+ * pose (`pose.kind === 'polygon'`) or on `node.data.path` (the kit's
+ * built-in pen-tool default, also WeaselDraw's shape).
+ *
+ * Note on live previews: in-flight edit state is surfaced through the
+ * dispatcher's standard `OngoingHandle.previewIds/previewPose/previewData`
+ * triple (not this dep), so chrome and preview-ghost stay in lock-step
+ * via one source of truth.
+ */
+interface EditAnchorsDep {
+    /** Id of the node currently being edited. Empty string means no node is
+     *  currently in edit mode — the chrome and gesture both opt out. */
+    editingId: string;
+    /** Enter/exit edit mode for a specific node. Pass `null` (or an empty
+     *  string) to exit. `enterPathEditAction` and `exitPathEditAction` call
+     *  this; consumers can call it directly to drive edit mode programmatically. */
+    setEditingId(id: string | null): void;
+    /** Returns the COMMITTED editable polygon in world coordinates, or
+     *  null if this node has no editable polygon. Does NOT consult in-
+     *  flight previews — callers that need live state read the dispatcher's
+     *  in-flight handles. */
+    getEditablePath(id: string): unknown;
+    /** Returns where the polygon is stored — `'pose'` when `node.pose`
+     *  IS the polygon, `'data'` when it lives on `node.data.path` with a
+     *  rect pose, or `null` when the node has no editable polygon. The
+     *  action uses this to know which preview-ghost axis to populate
+     *  (`previewPose` only / `previewData` + `previewPose` for data.path). */
+    getStorageKind(id: string): 'pose' | 'data' | null;
+    /** Returns the node's raw `pose` and `data` so storage-aware actions
+     *  can capture origin state at gesture-start and synthesize a matching
+     *  `previewPose` / `previewData` during `onMove`. Used by
+     *  `editAnchorsAction` for the data.path branch (rect pose + data
+     *  carrying extra fields like fill / stroke that must be preserved
+     *  through the preview). Returns null when the node is gone. */
+    getNodeShape(id: string): {
+        pose: unknown;
+        data: unknown;
+    } | null;
+    /** Commit `worldPath` as the new value for `id`. Implementation routes
+     *  to setPose (when pose IS the polygon) or batched setPose+update
+     *  (when the polygon lives on data.path). Records one history entry
+     *  labelled `label`. */
+    applyEdit(id: string, worldPath: unknown, label: string): void;
+    /**
+     * Anchors currently selected within the edited path, as **flat anchor
+     * indices** — the same numbering `enumerateAnchors` produces and the
+     * `anchor:N` affordance kinds carry.
+     *
+     * Selection is transient UI state, deliberately not part of the scene:
+     * it is cleared whenever `editingId` changes, and any edit that
+     * renumbers anchors (insert, delete) is responsible for leaving it
+     * coherent. Empty means "no anchor selected" — the keyboard actions
+     * (nudge, delete) no-op rather than acting on all anchors, matching
+     * Illustrator.
+     */
+    selectedAnchors: ReadonlySet<number>;
+    /** Replace the anchor selection. Pass an empty iterable to clear. */
+    setSelectedAnchors(next: Iterable<number>): void;
+    /**
+     * In-flight anchor-marquee rect in world coords, or null when no
+     * marquee drag is active. Written by `marqueeAnchorsAction` and read by
+     * the path-editing overlay — the same "ongoing action owns the preview,
+     * chrome just draws it" split the move/resize ghosts use.
+     */
+    marquee: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    } | null;
+    /** Set or clear the in-flight marquee rect. */
+    setMarquee(rect: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    } | null): void;
+}
+/**
+ * Adapter dep for `lassoSelectAction`.
+ *
+ * Provides polygon-lasso hit-testing + selection read/write.
+ * Consumers that don't implement `hitTestLasso` can omit it; the action
+ * falls back to a bounding-box AABB test via `hitTestArea`.
+ */
+interface LassoSelectDep {
+    /**
+     * Hit-test against a closed polygon (vertex order CW or CCW; last→first
+     * closing edge is implicit). Returns matching node ids.
+     * Optional — when absent, `lassoSelectAction` falls back to AABB via
+     * `hitTestArea`.
+     */
+    hitTestLasso?(polygon: ReadonlyArray<{
+        x: number;
+        y: number;
+    }>, mode: 'centers' | 'intersect' | 'enclosed'): string[];
+    /** Return ids of nodes whose AABB overlaps the given rect (fallback). */
+    hitTestArea(bounds: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    }): string[];
+    /** Return the current selection id list. */
+    getSelection(): string[];
+    /** Replace the current selection. */
+    setSelection(ids: string[]): void;
+}
+/**
+ * Options for the kit `image/svg+xml` content handler, threaded from
+ * SceneCanvas's `ingestion={{ svg }}` prop.
+ */
+interface SvgIngestOptions {
+    /** Parse dropped/pasted/picked SVG files into native scene nodes (path /
+     *  text leaves under containers mirroring the source `<g>` structure)
+     *  instead of the default single embedded-image node.
+     *
+     *  Pass `unpackSvgFiles` from `@weasel-js/svg`:
+     *
+     *  ```ts
+     *  import { unpackSvgFiles } from '@weasel-js/svg';
+     *  <SceneCanvas ingestion={{ svg: { unpack: unpackSvgFiles } }} />
+     *  ```
+     *
+     *  It is injected rather than flagged on with `true` because the SVG parser
+     *  lives in `@weasel-js/svg`, which depends on this package — core importing
+     *  it back would make the two mutually dependent and unpublishable
+     *  separately. Passing the function keeps the parser out of core's bundle
+     *  for consumers who never unpack. */
+    unpack?: SvgUnpacker;
+}
+/** Parses SVG files and inserts the resulting nodes into `ctx.scene`, as one
+ *  `applyOps` batch per file. Implemented by `unpackSvgFiles` in
+ *  `@weasel-js/svg`; see {@link SvgIngestOptions.unpack}. */
+type SvgUnpacker = (files: File[], ctx: IngestCtx) => Promise<void>;
+/**
+ * Clipboard-paste seam consumed by the kit weasel-JSON content handler
+ * (`IngestCtx.clipboard`). Built by `<SceneCanvas>` from its own synthesized
+ * adapter + the `ingestion.clipboard` prop; absent when the consumer set
+ * `ingestion.clipboard.enabled === false` or the adapter lacks `commitPaste`.
+ * Absence makes the handler decline inert (dwarn, nothing ingested) — its
+ * matched items were already consumed at match time and do not fall through
+ * to other handlers.
+ */
+interface ClipboardIngestCtx {
+    /** The hosting canvas's adapter — `commitPaste` materializes the pasted
+     *  nodes (fresh ids, offset applied); insertion still goes through ops. */
+    adapter: InsertAdapter<{
+        id: string;
+    }>;
+    /** JSON reviver for the weasel wire payload (typed arrays etc.) — from
+     *  `SceneCanvasProps.ingestion.clipboard.reviver`. */
+    reviver?: (key: string, value: unknown) => unknown;
+}
+/**
+ * Dep for the `ingest` action (external-content ingestion).
+ * Sourced from `<SceneCanvas>` / `<StandardActionsRegistrar>` via
+ * `useIngestionDepSource` — canvas rect + current view.
+ */
+interface IngestionDep {
+    /** Visible canvas area in world coordinates. */
+    viewportWorldRect(): {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    /** Consumer file→src resolver (from SceneCanvas's `ingestion` prop).
+     *  Live accessor — read it at use time. Destructuring (or copying the
+     *  property early) snapshots the current value and won't track later
+     *  prop changes across an `await`. */
+    resolveSrc?: (file: File) => Promise<string>;
+    /** Kit SVG-handler options (from SceneCanvas's `ingestion` prop).
+     *  Live accessor, same caveat as `resolveSrc`. */
+    svg?: SvgIngestOptions;
+    /** Clipboard-paste seam for the kit weasel-JSON handler.
+     *  Live accessor, same caveat as `resolveSrc`. */
+    clipboard?: ClipboardIngestCtx;
+}
+/**
+ * Per-kind extra geometry passed to `InsertDep.commit`.
+ *
+ * Built-in tools populate a typed variant so the kit's default factory can
+ * render the true tool params (line endpoints, polygon side count, star
+ * geometry, pencil sample list). Consumer-defined tools may pass any
+ * `{ kind: string; ... }` payload; the kit's factory falls back to AABB
+ * inscription for unknown kinds.
+ *
+ * `bounds` is still passed alongside as a useful AABB pose hint — factories
+ * may use it as the node's pose even when richer geometry is available.
+ */
+type InsertExtras = {
+    kind: 'rect';
+} | {
+    kind: 'ellipse';
+} | {
+    kind: 'line';
+    a: {
+        x: number;
+        y: number;
+    };
+    b: {
+        x: number;
+        y: number;
+    };
+} | {
+    kind: 'polygon';
+    sides: number;
+    rotation: number;
+    center?: {
+        x: number;
+        y: number;
+    };
+    radius?: number;
+} | {
+    kind: 'star';
+    points: number;
+    innerRadiusRatio: number;
+    rotation: number;
+    center?: {
+        x: number;
+        y: number;
+    };
+    outerRadius?: number;
+} | {
+    kind: 'pencil';
+    samples: ReadonlyArray<DragSample>;
+} | {
+    kind: 'text';
+    text?: string;
+} | {
+    kind: string;
+    [extra: string]: unknown;
+};
+/**
+ * World-space point snapping — grid, guides, or any consumer rule.
+ *
+ * Sourced by `<SceneCanvas>` from its `toolOptions.snapPoint`. Actions apply
+ * it to the coords they ingest so the live preview and the committed
+ * geometry agree; `insertAction` snaps the drag's start and current point.
+ *
+ * Optional: when the dep is absent, actions treat it as identity.
+ */
+interface SnapDep {
+    /** Snap a world-space point. Return `p` unchanged to opt out. */
+    point(p: {
+        x: number;
+        y: number;
+    }): {
+        x: number;
+        y: number;
+    };
+}
+/**
+ * Adapter dep for `insertAction`.
+ *
+ * Provided by `<SceneCanvas>` / `<StandardActionsRegistrar>`. The `extras`
+ * carry the active tool's kind + per-kind geometry. Callers
+ * that need typed data must supply a richer `insert` dep.
+ */
+interface InsertDep {
+    /**
+     * Materialise a new node from the given drag-rect bounds and typed
+     * per-kind extras. Returns the new node's id, or `null` if the consumer
+     * rejected the insert (e.g. sub-threshold bounds, unknown kind).
+     */
+    commit(bounds: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    }, extras: InsertExtras): NodeId | null;
+}
+/**
+ * Adapter dep for `resizeAction`.
+ *
+ * Carries the four behavior-shaping options the legacy `useResize` hook
+ * exposed through `UseResizeOptions`: bounds-frame behaviors (e.g.
+ * `lockAspectWithModifier`), world-space anchor-point snap behaviors (e.g.
+ * `pointSnapToGrid`), group-expansion (`expandIds`), and pose↔bounds
+ * projection (`geometry`).
+ *
+ * Optional in `DepSchema`: when absent, `resizeAction` falls back to
+ * identity defaults (no behaviors, identity expandIds, `RECT_POSE_DESCRIPTOR`
+ * geometry). Consumers wire the dep via `useDepSource('resizePolicy', ...)`
+ * from any descendant of `<DepRegistryProvider>` / `<SceneCanvas>`.
+ *
+ * The generic is erased to `unknown` at the schema entry; consumers cast at
+ * the call site (mirrors the `scene` entry's convention).
+ */
+interface ResizePolicy<TPose> {
+    /** Bounds-frame constraints. Constrained to `TPose extends ResizePose` since
+     *  constraints read/write `{x,y,width,height}`. For non-rect TPose pass `[]`. */
+    constraints: TPose extends ResizePose ? BoundsConstraint<TPose>[] : never[];
+    /** World-space anchor-point snap behaviors. Same TPose constraint as
+     *  `constraints`. */
+    pointSnap: TPose extends ResizePose ? PointSnapBehavior<TPose>[] : never[];
+    /** Group-expansion at gesture start. Identity (`ids => ids`) when group
+     *  resize isn't wanted. */
+    expandIds: (ids: string[]) => string[];
+    /** Projection from `TPose` to bounds and back. Use `RECT_POSE_DESCRIPTOR`
+     *  for plain rect poses. */
+    projection: PoseProjection<TPose>;
+}
+/**
+ * Layout-strategy lookup by container id, consumed by `moveAction` to run
+ * the drag-time reflow pass. Sourced by `<SceneCanvas>` from its `layouts`
+ * prop. Optional: `getLayout` returns null for any container when no layout
+ * is configured, so the reflow pass is a no-op then.
+ */
+interface LayoutDep {
+    getLayout(containerId: string): LayoutStrategy<unknown> | null;
+}
+interface DepSchema {
+    /** Kit selection state — ids of currently selected nodes. */
+    selection: SelectionApi;
+    /** Current viewport — camera position + scale. */
+    view: ViewApi;
+    /**
+     * Scene tree — structural reads + undoable mutations.
+     *
+     * The entry uses the fully-erased form `Scene<unknown, string, unknown>`
+     * because `DepSchema` must be concrete. Actions that need a typed scene
+     * should cast: `deps.scene as Scene<MyData, MyLayer, MyPose>`.
+     */
+    scene: Scene<unknown, string, unknown>;
+    /** Undo/redo history bound to the current scene. */
+    history: History;
+    /**
+     * Canvas pointer position in world space.
+     *
+     * Exposes `pointerRef` (mutable live ref) and `getDropPoint()` thunk.
+     * Marked `@experimental` in the source.
+     */
+    pointer: PointerContextValue;
+    /** Currently active tool id + hotkey-hold stack. */
+    activeTool: ActiveToolContextValue;
+    /**
+     * Area-select dep — AABB hit-test + selection read/write.
+     *
+     * Sourced from `<SceneCanvas>` via AABB overlap over all scene
+     * nodes. Override per-consumer for custom hit-testing (e.g. contain-mode,
+     * lock-aware filtering).
+     */
+    areaSelect: AreaSelectDep;
+    /**
+     * Topmost node at a world-space point. Sourced by `<SceneCanvas>` from
+     * the same picker that feeds the tool dispatcher's `getNodeAtPoint`.
+     * Optional: actions that read this (e.g. `moveAction` reparent-on-drop)
+     * fall back to a no-op when the dep isn't registered.
+     */
+    nodeAtPoint?: NodeAtPointDep;
+    /**
+     * Insert dep — node factory for drag-to-insert.
+     *
+     * Sourced from `<SceneCanvas>`. The `kind` param comes from
+     * the active binding's `opts.params.kind`. Override per-consumer to
+     * provide a typed node factory (e.g. with custom data payloads).
+     */
+    insert: InsertDep;
+    /**
+     * Snap dep — world-space point snapping (grid / guides).
+     *
+     * Sourced by `<SceneCanvas>` from `toolOptions.snapPoint`. Optional:
+     * absent means no snapping (identity).
+     */
+    snap?: SnapDep;
+    /**
+     * Lasso-select dep — polygon hit-test + selection read/write.
+     *
+     * Sourced from `<SceneCanvas>` / `<StandardActionsRegistrar>`.
+     * Falls back to AABB hit-test when `hitTestLasso` is absent.
+     */
+    lassoSelect: LassoSelectDep;
+    /**
+     * Edit-anchors dep — narrow read/write of one polygon's path pose.
+     *
+     * Sourced from consumer. Wraps `getPose`/`setPose`/`applyOps`
+     * for the currently-being-edited polygon node.
+     *
+     * The `editAnchorsAction` requires this dep to be registered when anchor
+     * editing is active. If absent, `start` returns an empty handle (no-op).
+     */
+    editAnchors: EditAnchorsDep;
+    /**
+     * Text-edit dep — activates the in-place text editing overlay.
+     *
+     * Sourced from consumer via `useTextEdit` / `useSceneTextEdit`.
+     * The `enterTextEditAction` requires this dep to be registered by the text
+     * tool when text editing is available.
+     *
+     * The optional `isTextNode` predicate guards against entering edit mode on
+     * non-text nodes. A binding can pre-filter instead with a
+     * `target: 'kind:text:selected'` spec; the guard remains for consumers who
+     * bind the broader `'selected-body'` target or opted out of routing.
+     */
+    textEdit: TextEditDep;
+    /**
+     * Resize-policy dep — bounds constraints, point-snap behaviors,
+     * group expansion, and pose↔bounds projection for `resizeAction`.
+     *
+     * Optional: when omitted, `resizeAction` falls back to identity defaults
+     * (no constraints, no snap, identity expandIds, `RECT_POSE_DESCRIPTOR`).
+     * Consumers wire via `useDepSource('resizePolicy', ...)` or the
+     * `useResizePolicy` helper.
+     */
+    resizePolicy?: ResizePolicy<unknown>;
+    /**
+     * Booleans adapter — read selection ids, fetch world-space `Path`s,
+     * compare z-order, and mint result nodes for Pathfinder ops.
+     *
+     * Consumers wire via `useBooleansAdapter(adapter)` (a thin wrapper
+     * around `useDepSource('booleansAdapter', ...)`). The descriptor's
+     * `enabled` predicate reads `deps.selection` for the count check; the
+     * invoker reads `deps.booleansAdapter` to execute the op.
+     */
+    booleansAdapter?: BooleansAdapter;
+    /**
+     * Gesture dispatcher control surface — exposes `cancelAll(reason)` so
+     * actions that need to abort an in-flight handle (Escape cancels a
+     * drag, etc.) can do so. Sourced by `<SceneCanvas>` from the
+     * dispatcher instance it already owns.
+     */
+    dispatcher?: {
+        cancelAll(reason: 'commit' | 'cancel'): void;
+    };
+    /**
+     * Layout-strategy lookup. Sourced by `<SceneCanvas>` from `layouts`.
+     * Optional: absent (or all-null) → `moveAction` skips reflow.
+     */
+    layout?: LayoutDep;
+    /**
+     * Slice dep — consumer-supplied commit for the Slice action.
+     *
+     * Receives the finite slice segment in world coordinates; the consumer
+     * scans the scene, splits crossed paths via `splitPathByLine`, and
+     * applies the result as one undoable batch.
+     *
+     * Optional: when absent, `sliceAction` is a no-op.
+     */
+    slice?: SliceDep;
+    /**
+     * Optional consumer commit hook. When present, `moveAction` (and other
+     * default actions) submit their committed ops through it instead of
+     * `scene.applyBatch`, so apps with their own history integration
+     * (checkpoint + push entry) capture the gesture as one undo entry.
+     * When absent, commits fall back to `scene.applyBatch`.
+     */
+    applyOps?: (ops: Op[], label: string) => void;
+    /** Optional pose-composition strategy for hierarchical (local-pose) scenes.
+     *  When absent, defaults to IDENTITY (absolute-pose: nodes store world
+     *  coords). Local-pose consumers supply { compose: composeRectPose,
+     *  decompose: decomposeRectPose } (or their pose shape's equivalent). */
+    poseComposition?: PoseComposition<unknown>;
+    /**
+     * Ingestion dep — canvas viewport rect + consumer file→src resolver.
+     *
+     * Sourced from `<SceneCanvas>` / `<StandardActionsRegistrar>` via
+     * `useIngestionDepSource`. Feeds `ingestAction` with the world-space
+     * viewport rect for paste-placement and image fit-clamping, and forwards
+     * the consumer's optional `resolveSrc` seam.
+     *
+     * Optional: when absent, the `ingest` action no-ops (there is no
+     * placement geometry to work with).
+     */
+    ingestion?: IngestionDep;
+    /**
+     * Optional consumer seam for the eager-sync layer: lets pose-transform
+     * actions (resize/move/nudge/flip — NOT rotate) ALSO rewrite a node's
+     * data-held geometry. Given a node and the affine `m` applied to its pose,
+     * `transform(node, m)` returns updated `data` (geometry mapped by `m`) or
+     * `null` for nodes with no data-held geometry.
+     *
+     * Strictly opt-in: when absent (or when `transform` returns null), the kit
+     * emits only the pose op and leaves `data` untouched. apps/draw wires this
+     * to mirror `data.path` through `transformPath`. Rotate intentionally never
+     * consults this seam (rotation lives on the pose, baked at render).
+     */
+    geometryProjection?: GeometryProjection;
+}
+/**
+ * Every dep name the registry knows about — derived from {@link DepSchema} so
+ * the two can't drift.
+ *
+ * Declared here rather than beside the registry so that this `keyof` reference
+ * resolves to the exported `DepSchema` declaration; from another module it
+ * resolves to that module's import alias, which the API docs can't link.
+ */
+type DepName = keyof DepSchema;
+
+interface DepRegistry {
+    register<K extends DepName>(name: K, source: () => DepSchema[K]): () => void;
+    get<K extends DepName>(name: K): DepSchema[K] | undefined;
+}
+declare function DepRegistryProvider({ children }: {
+    children: ReactNode;
+}): react_jsx_runtime.JSX.Element;
+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;
+
+/**
+ * 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`.
+ */
+
+interface GestureBinding {
+    spec: GestureSpec;
+    actionId: string;
+    opts?: BindingOpts;
+}
+
+/** Modifier-key snapshot at event dispatch time. `space` is included
+ *  because tools commonly use space as a hotkey-slot trigger and may
+ *  also want to read it as a flag mid-gesture. */
+interface ToolModifiers {
+    alt: boolean;
+    shift: boolean;
+    meta: boolean;
+    ctrl: boolean;
+    space: boolean;
+}
+/** 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;
+}
+/** 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';
+/** 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;
+/** 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. The top-level `Tool.cursor` field below 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;
+}
+/** Full Tool record. */
+interface Tool<TScratch = unknown> {
+    id: string;
+    /**
+     * App-level capability tags for modality. The `weasel-modes` package's
+     * `eligibleForMode(mode, capabilities)` predicate consumes these to decide
+     * whether the tool is usable in the active mode. Tags are extensible
+     * strings — apps can define their own. Untagged tools are treated as
+     * ineligible by all modes except those whose `allows` list includes
+     * every implicit-or-declared tag (i.e. `normal` in the default preset).
+     */
+    capabilities?: CapabilityTag[];
+    /**
+     * Actions this tool owns and needs registered while it is in the tools
+     * registry — e.g. polygon's `polygon.adjustSides`, which its own bindings
+     * reference by id.
+     *
+     * Declared here rather than registered by the hook with `useAction`,
+     * because tool hooks run wherever the consumer calls them — for
+     * `<SceneCanvas>` that is ABOVE `<ActionsProviderIfRoot>`, where
+     * `useActionsRegistry()` returns null and `useAction` silently no-ops. The
+     * result was a binding pointing at an action id nothing had registered, so
+     * the gesture fell through to whatever matched next (polygon's
+     * wheel/arrow-key side adjustment did nothing and `nudge.*` moved the
+     * selection instead). `<ToolActionsMounter>` registers these from inside
+     * the provider.
+     */
+    actions?: Action[];
+    /** Optional caller-supplied key. Most built-in tools have their activation
+     *  key declared in `BUILTIN_SELECT_KEYS` in `useKeybindings.ts`; this field
+     *  is for tools that want their activation key to be configurable by the
+     *  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;
+    onActivate?: (ctx: ToolCtx<TScratch>) => void;
+    onDeactivate?: (ctx: ToolCtx<TScratch>) => void;
+    cursor?: string | ((ctx: ToolCtx<TScratch>) => string);
+    /** Presentation metadata for tool palettes. See `ToolPresentation`. */
+    presentation?: ToolPresentation<TScratch>;
+    /** 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;
+    /** Optional overlay layer rendered on top of the scene/chrome whenever
+     *  this tool is in any active slot (active, hotkey, or ambient).
+     *  The layer's `draw` function reads from this tool's scratch via React
+     *  closure (re-evaluated each render). Return early from `draw` to render
+     *  nothing — typically gated on a scratch field like
+     *  `if (!scratch.overlay) return`. */
+    overlay?: RenderLayer<unknown>;
+    /** Declarative gesture bindings — the tool's entire input surface. The
+     *  gesture dispatcher consults these at active scope while this tool is
+     *  active, and at hotkey scope while it is held. See
+     *  `docs/superpowers/specs/2026-05-16-registry-unification-design.md`. */
+    bindings?: GestureBinding[];
+    /** Reflection escape hatch: when this `Tool` was produced by `defineTool`,
+     *  the source `ToolDef` is attached here so introspection consumers
+     *  (`buildRouteRegistry`, `findConflicts`, the toolkit-builder UI, the
+     *  reflection demo) can read the authored form — `hookName` in particular,
+     *  which the runtime `Tool` doesn't carry. Tools constructed without
+     *  `defineTool` may leave this undefined. Typed as `unknown` to keep this
+     *  file from importing the routing types — consumers cast at the use site. */
+    def?: unknown;
+}
+/** Internal — 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>;
+
+/**
+ * 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.
+ */
+
+type BindingScope = 'ambient' | 'active' | 'hotkey';
+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;
+}
+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;
+}
+/** 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  — 1 if the spec declares a `phase` field, else 0.
+ *    [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];
+
+/**
+ * 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.
+ */
+
+interface DispatcherContext {
+    /** All registered actions; the dispatcher walks `.defaultBinding` for ambient bindings. */
+    actions: ActionsRegistry;
+    /** 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[];
+    /**
+     * Ids of always-on tools. Their bindings are assembled at AMBIENT scope, so
+     * they lose to the active tool on a tie — which is what "always listening,
+     * never in the way" needs. Chrome that floats over the scene lives here:
+     * `@weasel-js/hud`'s tool is the worked example.
+     *
+     * Without this an ambient tool's `bindings` were assembled nowhere at all:
+     * the walk covered hotkey and active tools plus actions' `defaultBinding`,
+     * and an ambient tool is in neither set.
+     */
+    ambientToolIds?: 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. When
+     * supplied, the dispatcher filters matched candidates by their
+     * declared `Action.eligible` rule (omitted => always eligible).
+     * When omitted, no eligibility filtering is applied — preserves
+     * backward compatibility for callers (tests, legacy harnesses) that
+     * don't wire up chrome-caps state.
+     */
+    getRuleCtx?: () => RuleCtx;
+}
+/**
+ * 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;
+}
+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;
+}
+declare function createDispatcher(opts?: {
+    getAction?: (id: string) => Action | undefined;
+}): Dispatcher;
+
+/**
+ * @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
+ * Single registered action. v1: one binding per action.
+ */
+interface Action {
+    id: string;
+    label: string;
+    /** The gesture-spec form of the binding, read by the gesture dispatcher.
+     *  May be a single `GestureSpec`, a bare `GestureSpec[]` (any-of semantics),
+     *  or a `BoundGesture[]` where each entry is either a bare `GestureSpec` or
+     *  `{ spec, opts }` — use the object form for parametric actions where two
+     *  bindings for the same action differ only by `opts.params` (e.g. `flip`
+     *  with `axis: 'x'` vs `'y'`). The dispatcher extracts `opts.params` and
+     *  passes them to `ImmediateInvoker.run` as its second argument. */
+    defaultBinding?: GestureSpec | BoundGesture[];
+    /** Names of the deps this action's invoker reads (keys of `DepSchema`).
+     *  The dispatcher (and `trigger`, when `requires` is present) resolves
+     *  each name against the `DepRegistry` at invocation time and passes the
+     *  resulting bag to the invoker. Dev builds warn when the invoker reads a
+     *  dep it didn't declare here — see `buildDepsFromRequires`. */
+    requires?: readonly DepName[];
+    /** Inline-SVG icon for palette / toolbar surfaces. Mirrors
+     *  `ToolPresentation.icon` so a generic `<ActionBar>` can render from
+     *  action metadata the same way `<ToolPalette>` renders from tool
+     *  metadata. May be a static `ReactNode` or a function (rare; useful
+     *  for state-aware icons like a "lock" toggle). */
+    icon?: ReactNode | (() => ReactNode);
+    /** Grouping key for palette/menu surfaces. Free-form string; the kit
+     *  ships defaults for `'align'` (six edges/centers), `'distribute'`
+     *  (two axes), and recommends `'pathfinder'` for boolean ops. */
+    group?: string;
+    /** Display override for the keyboard shortcut. When omitted, palette
+     *  surfaces derive a label from `defaultBinding` via their own
+     *  formatter. */
+    shortcut?: string;
+    /** Pluggable invocation strategy. The gesture dispatcher routes matched
+     *  bindings through `invoker.start` / `invoker.run` depending on timing.
+     *  All kit-standard descriptors ship one; consumer-supplied actions
+     *  without an invoker can still register but won't be triggered. */
+    invoker?: Invoker;
+    /** When set to `'hotkey'`, this action's `defaultBinding` rides the hotkey
+     *  `BindingScope` instead of the ambient scope — meaning it beats any
+     *  active-tool binding on the same input shape. Use for tool-switch
+     *  shortcuts and global held-key triggers. Default: ambient. */
+    scope?: 'hotkey';
+    /**
+     * @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 string only. Prediction runs `enabled()` but cannot run the
+     * invoker, so an action that matches yet bails at `start()` (empty
+     * handle) may still show its cursor — keep `enabled` accurate for
+     * actions that declare one.
+     */
+    cursor?: string;
+    /**
+     * 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?: string;
+}
+/**
+ * @experimental
+ * Closed enum of reasons an action might report itself as disabled. The
+ * consumer (palette, menu, etc.) maps these symbolic values to display
+ * strings via its own label map — see `demo/CommandPalette.tsx` for the
+ * canonical mapping.
+ */
+declare const ActionDisabledReason: {
+    readonly SelectionRequired: "selection-required";
+    readonly SceneEmpty: "scene-empty";
+    readonly NotApplicable: "not-applicable";
+    /** Sentinel: the predicate threw. Surfaced by `evaluateEnabled`'s catch. */
+    readonly PredicateThrew: "predicate-threw";
+};
+type ActionDisabledReason = (typeof ActionDisabledReason)[keyof typeof ActionDisabledReason];
+/**
+ * @experimental
+ * Result of evaluating an Action's `enabled` predicate.
+ */
+interface ActionEnabledResult {
+    enabled: boolean;
+    reason?: ActionDisabledReason;
+}
+declare function evaluateEnabled(action: Action, deps?: ActionDeps): ActionEnabledResult;
+/**
+ * @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 {
+    register(action: Action): () => void;
+    unregister(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.
+     *  Call with `null` to detach. Idempotent. */
+    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. */
+    setDepRegistry(r: DepRegistry | null): void;
+}
+/**
+ * @experimental
+ * Mounts an `ActionsRegistry` for its lifetime. Children call
+ * `useActionsRegistry()` or `useAction()` to participate. Mounts no input
+ * listener of its own — the gesture dispatcher owns input.
+ */
+declare function ActionsProvider({ children }: {
+    children: ReactNode;
+}): ReactElement;
+/**
+ * @experimental
+ * Returns the parent `ActionsRegistry`, or `null` when no provider is in scope.
+ */
+declare function useActionsRegistry(): ActionsRegistry | null;
+/**
+ * @experimental
+ * Register an `Action` for the lifetime of the calling component. No-op when
+ * no `ActionsProvider` is in scope. Re-registers on `action` reference change
+ * (consumers should memoize stable identities to avoid churn).
+ */
+declare function useAction(action: Action): void;
+
+/**
+ * Configurable activation-key descriptor for tools that expose their
+ * keybinding to the host (currently Lasso and Eyedropper). Captures
+ * only the fields meaningful to a caller-supplied tool-select key —
+ * dispatcher-internal fields (`skipInEditable`, `enabled`,
+ * `preventDefault`) live on `KeyBinding` in keyHelpers.ts and are
+ * not part of the configurable surface.
+ */
+interface ToolKeybinding {
+    /** Key or list of keys to match (case-insensitive against `event.key`). */
+    key: string | readonly string[];
+    /** Require Cmd (mac) / Ctrl (others). Default `false`. */
+    mod?: boolean;
+    /** Require Alt. Default `false`. */
+    alt?: boolean;
+    /**
+     * Shift policy. `undefined`/`false` forbids shift, `true` requires
+     * shift, `'optional'` allows either.
+     */
+    shift?: boolean | 'optional';
+}
+interface ToolDef<TScratch = void> {
+    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;
+    /** Declarative held-key trigger (reflection / inspector only). When set,
+     *  signals to the host that this tool can engage via a held key; the host
+     *  must register the activation via the consolidated `tool.offhand` action
+     *  (`makeToolOffhandAction` + `buildToolOffhandBindings`). Built-in tools
+     *  declare held keys in `BUILTIN_OFFHAND_ACTIONS`; configurable-hotkey
+     *  tools rely on the host to wire the binding. Setting this field does NOT
+     *  automatically engage the held-key behavior. */
+    hotkey?: HotkeyTrigger;
+    onActivate?: (ctx: ToolCtx<TScratch>) => void;
+    onDeactivate?: (ctx: ToolCtx<TScratch>) => void;
+    cursor?: string | ((ctx: ToolCtx<TScratch>) => string);
+    /** 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. */
+    overlay?: RenderLayer<unknown>;
+}
+/** 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> = ToolDef<TScratch>;
+
+/**
+ * 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>(def: ToolDef<TScratch>): Tool<TScratch>;
+
+/**
+ * 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>(def: ViewportToolDef<TScratch>): Tool<TScratch>;
+
+/**
+ * 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;
+    /** 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[];
+
+/** 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>[];
+}
+/**
+ * Detect the same-tuple overlaps that are *reachable* — the ones where the
+ * dispatcher really does fall back on declaration order.
+ *
+ * `matchSorted` walks scopes in strict priority (hotkey > active > ambient)
+ * and only sorts by specificity *within* a scope. So a cross-scope tie isn't
+ * a tie at all: an ambient tool losing a tuple to the active tool is the
+ * documented design, not an accident. Likewise two registry tools sharing a
+ * tuple — `rect` and `ellipse` both binding a bare `drag` — can never both be
+ * in the active slot, so they never compete.
+ *
+ * What's left, and what this reports:
+ *  - a single tool colliding with **itself** (possible since bindings became
+ *    an array), which is ambiguous in whichever slot it occupies;
+ *  - two **ambient** tools, all of which are live simultaneously and are
+ *    ordered only by registration;
+ *  - two **hotkey-capable** tools, which can stack.
+ *
+ * Not covered: the actions registry's `defaultBinding`s, which the dispatcher
+ * also folds into ambient/hotkey scope. They're assembled somewhere else
+ * entirely (`ActionsRegistry`, not `useTools`), so catching tool-vs-action
+ * collisions means giving this function a second input it doesn't have yet.
+ */
+declare function findScopedConflicts(scopes: ToolScopes): Conflict[];
+/**
+ * Render a conflict as one line of human-readable text.
+ *
+ * The tuple is printed through {@link formatRoute}, so the message names the
+ * collision in the same grammar the author wrote the binding in — modulo the
+ * phase slot, which prints as a bare `'&'`-channel atom because the bucket key
+ * collapses channel-bearing phase specs (`sel:engaged` and `&:engaged` collide
+ * with each other, and the collapse is what made them collide).
+ */
+declare function formatConflict(conflict: Conflict): string;
+/**
+ * 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[];
+
+declare const index_ChannelRef: typeof ChannelRef;
+type index_Conflict = Conflict;
+declare const index_DescribeRouteOptions: typeof DescribeRouteOptions;
+declare const index_GESTURE_DESCRIPTORS: typeof GESTURE_DESCRIPTORS;
+declare const index_GestureArgSpec: typeof GestureArgSpec;
+declare const index_GestureDescriptor: typeof GestureDescriptor;
+declare const index_GestureName: typeof GestureName;
+declare const index_ModRequirement: typeof ModRequirement;
+declare const index_ModifierKey: typeof ModifierKey;
+declare const index_PREDICATE_TARGET: typeof PREDICATE_TARGET;
+declare const index_ParsedModifiers: typeof ParsedModifiers;
+declare const index_ParsedRoute: typeof ParsedRoute;
+declare const index_PhaseAtom: typeof PhaseAtom;
+declare const index_RESERVED_ID_NAMES: typeof RESERVED_ID_NAMES;
+declare const index_RESERVED_ID_PREFIXES: typeof RESERVED_ID_PREFIXES;
+declare const index_ROUTE_FIELD_DEFINITIONS: typeof ROUTE_FIELD_DEFINITIONS;
+declare const index_ROUTE_TERMS: typeof ROUTE_TERMS;
+type index_RegistryEntry = RegistryEntry;
+declare const index_RouteDescriptionPart: typeof RouteDescriptionPart;
+declare const index_RouteFieldName: typeof RouteFieldName;
+declare const index_RouteTermLabel: typeof RouteTermLabel;
+type index_ToolDef<TScratch = void> = ToolDef<TScratch>;
+type index_ToolKeybinding = ToolKeybinding;
+type index_ToolScopes = ToolScopes;
+type index_ViewportToolDef<TScratch = void> = ViewportToolDef<TScratch>;
+declare const index_buildRouteRegistry: typeof buildRouteRegistry;
+declare const index_canonicalModifiers: typeof canonicalModifiers;
+declare const index_collapseShiftPairs: typeof collapseShiftPairs;
+declare const index_defineTool: typeof defineTool;
+declare const index_defineViewportTool: typeof defineViewportTool;
+declare const index_describeRoute: typeof describeRoute;
+declare const index_describeRouteParts: typeof describeRouteParts;
+declare const index_findConflicts: typeof findConflicts;
+declare const index_findScopedConflicts: typeof findScopedConflicts;
+declare const index_formatConflict: typeof formatConflict;
+declare const index_formatPhaseAtom: typeof formatPhaseAtom;
+declare const index_formatRoute: typeof formatRoute;
+declare const index_getGestureDescriptor: typeof getGestureDescriptor;
+declare const index_isKnownGestureName: typeof isKnownGestureName;
+declare const index_parseRoute: typeof parseRoute;
+declare const index_reportRouteConflicts: typeof reportRouteConflicts;
+declare namespace index {
+  export { index_ChannelRef as ChannelRef, type index_Conflict as Conflict, index_DescribeRouteOptions as DescribeRouteOptions, index_GESTURE_DESCRIPTORS as GESTURE_DESCRIPTORS, index_GestureArgSpec as GestureArgSpec, index_GestureDescriptor as GestureDescriptor, index_GestureName as GestureName, index_ModRequirement as ModRequirement, index_ModifierKey as ModifierKey, index_PREDICATE_TARGET as PREDICATE_TARGET, index_ParsedModifiers as ParsedModifiers, index_ParsedRoute as ParsedRoute, index_PhaseAtom as PhaseAtom, index_RESERVED_ID_NAMES as RESERVED_ID_NAMES, index_RESERVED_ID_PREFIXES as RESERVED_ID_PREFIXES, index_ROUTE_FIELD_DEFINITIONS as ROUTE_FIELD_DEFINITIONS, index_ROUTE_TERMS as ROUTE_TERMS, type index_RegistryEntry as RegistryEntry, index_RouteDescriptionPart as RouteDescriptionPart, index_RouteFieldName as RouteFieldName, index_RouteTermLabel as RouteTermLabel, type index_ToolDef as ToolDef, type index_ToolKeybinding as ToolKeybinding, type index_ToolScopes as ToolScopes, type index_ViewportToolDef as ViewportToolDef, index_buildRouteRegistry as buildRouteRegistry, index_canonicalModifiers as canonicalModifiers, index_collapseShiftPairs as collapseShiftPairs, index_defineTool as defineTool, index_defineViewportTool as defineViewportTool, index_describeRoute as describeRoute, index_describeRouteParts as describeRouteParts, index_findConflicts as findConflicts, index_findScopedConflicts as findScopedConflicts, index_formatConflict as formatConflict, index_formatPhaseAtom as formatPhaseAtom, index_formatRoute as formatRoute, index_getGestureDescriptor as getGestureDescriptor, index_isKnownGestureName as isKnownGestureName, index_parseRoute as parseRoute, index_reportRouteConflicts as reportRouteConflicts };
+}
+
+export { DepRegistryProvider as $, type Action as A, type BooleansAdapter as B, type Condition as C, type Dims as D, ActiveToolContextProvider as E, ActiveToolContextProviderIfRoot as F, type GeometryProjection as G, type HotkeyTrigger as H, type InsertExtras as I, type ActiveToolContextProviderProps as J, type ActiveToolContextValue as K, type AreaSelectDep as L, type BindingOpts as M, type BindingScope as N, type BooleanOp as O, type BooleanOpResult as P, type BoundGesture as Q, type RenderLayer as R, type SliceDep as S, type Tool as T, type UseSelectionOptions as U, type VisibilityRules as V, type BuildRuleCtxArgs as W, type ClipboardIngestCtx as X, type CustomPaintContext as Y, type DepName as Z, type DepRegistry as _, type Rule as a, type ToolScopes as a$, type DispatcherContext as a0, type DragSample as a1, type EditAnchorsDep as a2, type GestureBinding as a3, type ImmediateInvoker as a4, type IngestCtx as a5, type IngestionDep as a6, type InsertDep as a7, type InvocationCtx as a8, type Invoker as a9, type UiOngoingControl as aA, type ViewApi as aB, applyBooleanOp as aC, buildRuleCtx as aD, createDispatcher as aE, describeRule as aF, drawLayers as aG, enterTextEditAction as aH, evaluate as aI, evaluateEnabled as aJ, registerContentHandler as aK, index as aL, sliceAction as aM, specificity as aN, useAction as aO, useActionsRegistry as aP, useActiveToolContext as aQ, useDepRegistry as aR, useDepSource as aS, useOptionalActiveToolContext as aT, useOptionalDepRegistry as aU, usePointerContext as aV, useSelection as aW, type Conflict as aX, PREDICATE_TARGET as aY, type RegistryEntry as aZ, type ToolDef as a_, type LassoSelectDep as aa, type LayoutDep as ab, type MatchResult as ac, NEVER as ad, type NodeAtPointDep as ae, type OngoingHandle as af, type OngoingInvoker as ag, type OngoingOverlay as ah, type Point2 as ai, PointerContextProvider as aj, type PointerContextValue as ak, type PointerWorldPos as al, type ResizePolicy as am, type ResolveAllOptions as an, type ResolveOnlyResult as ao, type ResolvedCandidate as ap, type ScopedBinding as aq, type SelectionExtendKey as ar, type SelectionMode as as, type Selector as at, type SnapDep as au, type SvgUnpacker as av, type TextEditDep as aw, type ToolModifiers as ax, type ToolPresentation as ay, type ToolSlot as az, type RuleCtx as b, type ViewportToolDef as b0, buildRouteRegistry as b1, defineTool as b2, defineViewportTool as b3, findConflicts as b4, findScopedConflicts as b5, formatConflict as b6, reportRouteConflicts as b7, type ChromeCtx as c, type ChromeId as d, type DepSchema as e, type ActionsRegistry as f, type AffordanceHit as g, type Dispatcher as h, type AnyTool as i, type ToolCtx as j, type ToolKeybinding as k, type AffordanceBinding as l, type ChromeState as m, type SelectionApi as n, type ContentHandlerEntry as o, type SvgIngestOptions as p, type ActionsProp as q, type Affordance as r, type AffordanceRegion as s, type CommonAffordanceScratch as t, ALWAYS as u, type ActionDeps as v, ActionDisabledReason as w, type ActionEnabledResult as x, type ActionEntry as y, ActionsProvider as z };