@weasel-js/routing 1.9.4 → 1.10.1

package/dist/{index-gArM2tbt.d.ts → index-DkOqUxow.d.ts}

@@ -1,29 +1,20 @@
-import { View } from '@weasel-js/geom';
+import { PoseLinear, View } from '@weasel-js/geom';
 import * as react from 'react';
 import { ReactNode } from 'react';
+import { Emitter } from '@weasel-js/registry';
+import { ClaimableGesture, GestureSpec, IngestItem, InputEvent, TargetSpec, KeyHeldSpec, TargetPredicate, KeySpec, ParsedModifiers, GestureName } from '@weasel-js/gestures';
 import { CapabilityTag, ActiveMode, ModeRegistry } from '@weasel-js/modes';
 import { CursorSpec } from '@weasel-js/cursor';
-import { ClaimableGesture, GestureSpec, InputEvent, TargetSpec, KeyHeldSpec, TargetPredicate, KeySpec, ParsedModifiers, GestureName, IngestItem } from '@weasel-js/gestures';
-import { Op } from '@weasel-js/history';
 import '@weasel-js/select';
 
 /**
  * The primitives the routing surface is typed in.
  *
- * Routing decides which action a gesture runs. To do that it has to name a
- * viewport, a rect, a node id and a selection — but it never constructs,
- * projects or renders any of them. So they are declared here as structural
- * interfaces with no dependencies, and `@weasel-js/core` re-exports each from
- * the path its own call sites have always used. Same arrangement as `Op`,
- * which is declared in `@weasel-js/history` and re-exported by
- * `core/ops/types`. The selection click policy's own vocabulary comes from
- * `@weasel-js/select`, where the rules that read it live.
- *
- * Authority for the *behavior* behind each of these stays in core: `View` is
- * what `core/viewport` maintains, `SelectionApi` is what `useSelection`
- * returns, `DeviceProfile` is what `resolveDeviceProfile` detects. Changing
- * one of these shapes is a change to core's contract that happens to be
- * spelled here.
+ * Routing has to name a viewport, a rect, a node id, and a selection, but it
+ * never constructs, projects, or renders any of them. So they are declared
+ * here as structural interfaces with no dependencies, and `@weasel-js/core`
+ * re-exports each. The behavior behind them stays in core: changing one of
+ * these shapes is a change to core's contract that happens to be spelled here.
  */
 
 /** An opaque scene-node identifier. Branded so a bare string cannot stand in. */
@@ -33,8 +24,9 @@ type NodeId = string & {
 
 /**
  * Axis-aligned rectangle in world space. The optional `rotation` (radians,
- * around the AABB center) lets chrome attach an orientation to an otherwise
- * axis-aligned rect without a parallel type.
+ * around the AABB center) and `transform` (inside it, about the same center)
+ * let chrome carry the frame a box is drawn in without a parallel type;
+ * `poseFrameOf` composes the two.
  */
 interface Bounds {
     x: number;
@@ -42,6 +34,7 @@ interface Bounds {
     width: number;
     height: number;
     rotation?: number;
+    transform?: PoseLinear;
 }
 /** The selection as routing reads and writes it. */
 interface SelectionApi {
@@ -65,6 +58,7 @@ interface SelectionApi {
      * 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;
+     *   with the range key held, selects from the last pressed id through `id`;
      *   otherwise replaces with `[id]`.
      */
     applyClick(id: NodeId, modifiers: {
@@ -126,8 +120,8 @@ type HitShape = {
 /** What a recorded viewport change was: a translation or a scale change. */
 type ViewportGestureKind = 'pan' | 'zoom';
 /**
- * Where a tool reports its internal hit math so the debug overlay can draw it.
- * Routing threads a sink through `ToolCtx` and never calls one.
+ * Where an action reports its hit math so the debug overlay can draw it. An
+ * action reaches the canvas's sink as its `debug` dep; routing never calls one.
  */
 interface DebugSink {
     recordHitbox(id: string, kind: 'body' | 'handle' | 'rotation' | 'anchor', shape: HitShape): void;
@@ -188,10 +182,11 @@ type ResizeAnchor = {
  * registration lives in the node it was made in, and a lookup starts at a leaf
  * and walks up, so one canvas never answers for another.
  */
+
 /** What every node of one tree shares: a version and the listeners to it. */
 interface ScopeTree {
     version: number;
-    readonly listeners: Set<() => void>;
+    readonly listeners: Emitter;
 }
 declare class ScopeNode<N extends ScopeNode<N>> {
     readonly parent: N | null;
@@ -270,15 +265,12 @@ declare function ActiveToolContextProvider({ children, initialActive, }: ActiveT
 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.
+ * `<ActiveToolContextProvider>` is in scope instead of throwing.
  */
 declare function useOptionalActiveToolContext(): ActiveToolContextValue | null;
 /**
- * Conditional `<ActiveToolContextProvider>` wrapper. Mounts a provider only
- * when no parent provider is in scope — otherwise renders children unwrapped
- * so `<WeaselProvider>` defers to the host's existing scope.
+ * Mounts an `<ActiveToolContextProvider>` only when no parent provider is in
+ * scope; otherwise renders children unwrapped.
  */
 declare function ActiveToolContextProviderIfRoot({ children, }: {
     children: ReactNode;
@@ -456,25 +448,20 @@ declare const NEVER: Rule;
  * { 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 `{}`.
+ * Never throws and always terminates.
  */
 declare function describeRule(rule: Rule): string;
 /** Evaluate a rule against a context. Pure, and cheap enough to run per
  *  frame for every piece of chrome. */
 declare function evaluate(rule: Rule, ctx: RuleCtx): boolean;
 /**
- * Composable eligibility predicate with a fluent surface. Carries its
- * underlying `Rule` tree at `.rule` so the dispatcher's eligibility filter and
- * the chrome resolver can introspect and share trees.
- *
- * Callable form `cond(ctx)` evaluates the tree against ctx. The fluent methods
- * return new Conditions wrapping new trees.
+ * Composable eligibility predicate with a fluent surface. `cond(ctx)`
+ * evaluates its `Rule` tree, carried at `.rule`; 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(...)`.
+ * `(a && b) || c`; `a.or(b).and(c)` is `(a || b) && c`. For grouped
+ * disjunction, name the subexpression or use the top-level `or(...)`.
  */
 interface Condition {
     (ctx: RuleCtx): boolean;
@@ -542,9 +529,6 @@ declare const DEFAULT_DEVICE_PROFILE: DeviceProfile;
  * An Action's `invoker` field describes how it's run. `immediate` invokers
  * fire once (delete, align, undo). `ongoing` invokers open a phase machine
  * driven by the dispatcher (move, resize, pinch-zoom).
- *
- * See `docs/superpowers/specs/2026-05-16-registry-unification-design.md`
- * § "Types" for the full design.
  */
 
 /** A 2D point in either world or screen coordinates. */
@@ -553,31 +537,20 @@ interface Point2 {
     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.
+ * Which UI affordance was hit at pointerdown. Populated by the dispatcher when
+ * the `affordanceAt` thunk is provided to `useGestureDispatcher`.
  *
  * `kind` is a discriminator string:
  *   - `'handle:top-left'` / `'handle:top-right'` / `'handle:bottom-left'` /
  *     `'handle:bottom-right'` — corner resize handles.
  *   - `'rotate-handle'` — the rotation affordance.
  *   - `'anchor:N'` — a path anchor at index N.
- *
- * `fixedPoint` is the world-space point that should remain stationary during
- * the gesture. For resize handles this is the opposite (diagonally fixed)
- * corner; for rotate it is the pivot.
- *
- * `targetIds` are the node ids this affordance belongs to.
  */
 interface AffordanceHit {
     /** Discriminator string, e.g. `'handle:bottom-right'`. */
     kind: string;
     /** Id of whatever produced this hit — a kit affordance's `id`, or the
-     *  registered layer's id. Read only by the dispatcher's dead-claim warning today. */
+     *  registered layer's id. */
     owner?: string;
     /** `'exclusive'` means no binding may act on this point unless its target
      *  consults the affordance. `'shared'` (the default) competes on scope and
@@ -592,25 +565,18 @@ interface AffordanceHit {
     };
     /** 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. */
+    /** Set only when `kind` matches `'handle:*'`: which corner stays fixed
+     *  during a resize. */
     anchor?: ResizeAnchor;
-    /** Cursor to show while the pointer hovers this affordance (no
-     *  gesture in flight). Consumed by the hover-cursor pump in
-     *  `useGestureDispatcher`; unset = the pump falls through to
-     *  action-cursor prediction, then to the active tool's cursor. */
+    /** Cursor to show while the pointer hovers this affordance (no gesture in
+     *  flight). Unset falls through to action-cursor prediction, then to the
+     *  active tool's cursor. */
     cursor?: CursorSpec;
     /**
      * Free-form payload from whatever produced the hit, carried through to the
-     * matching action untouched.
-     *
-     * Kit affordances describe themselves fully in the fields above and leave
-     * this unset. It exists for affordances the kit doesn't know the shape of —
+     * matching action untouched. Kit affordances leave it unset; it exists for
      * 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.
+     * *which* of its pieces was hit.
      */
     payload?: unknown;
 }
@@ -619,9 +585,7 @@ interface AffordanceHit {
  * 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/StrokeAndFillDemo.tsx`.
+ * them, and for synthetic events.
  */
 interface DragSample extends Point2 {
     /** 0..1. Mouse/touch report 0.5 while a button is held, per the spec. */
@@ -659,23 +623,19 @@ interface InvocationCtx {
          * 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.
+         * Absent when the underlying pointer events carried no
+         * `clientX`/`clientY`.
          */
         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`).
          *
          * During `onMove` this is the dispatcher's live accumulator, and it grows
          * under you — read it, don't retain it. On `onEnd` it is a snapshot, so
          * that is where an action that keeps the trail should take it.
-         * Used by `lassoSelectAction` to build its polygon vertex list and by
-         * `insertAction`'s pencil kind to carry the freehand stroke.
          */
         points?: DragSample[];
     };
@@ -697,12 +657,13 @@ interface InvocationCtx {
         centroid: Point2;
         /** Distance between the two primary pointers, in CSS pixels. */
         spread: number;
+        /** Degrees the line between the two primary pointers has turned since
+         *  the gesture began, clockwise positive. It keeps counting past a half
+         *  turn. Zero where the events carry no `MultiTouchEvent.angle`. */
         rotation: number;
         /**
-         * Pinch-zoom geometry. Populated by the dispatcher when a multitouch
-         * handle is in flight and a pointermove-pump fires.
+         * Pinch-zoom geometry, populated while a multitouch handle is in flight.
          * `startSpread` is the spread at the moment the gesture began.
-         * `currentSpread` is the spread at the current frame.
          */
         pinch?: {
             startSpread: number;
@@ -723,33 +684,27 @@ interface InvocationCtx {
     viewId?: string | null;
     /**
      * 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).
+     * UI-driven ongoing actions (color picker, opacity slider). 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. */
+ *  `opts` field and passes to `OngoingInvoker.start`. */
 interface BindingOpts {
     /** Gesture behaviors the action's own invoker runs. Routing carries the
      *  array to the action and never reads an element, so the element type is
-     *  open here; `@weasel-js/core` narrows it to `ActionBehavior<unknown,
-     *  unknown, unknown>[]`, which is what a behavior is authored against. */
+     *  open here; `@weasel-js/core` narrows it. */
     behaviors?: unknown[];
-    /** Per-binding action parameters. The action's invoker reads
-     *  these via the second arg to `run` (or via InvocationCtx for ongoing
-     *  invokers, when needed). Loose typing (Record<string, unknown>) for
-     *  now; consider per-action typing later via BindingOpts<A>.
+    /** Per-binding action parameters, which an immediate invoker reads via the
+     *  second arg to `run`.
      *
-     *  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)`. */
+     *  May also be a thunk evaluated each time the value is needed, so a tool
+     *  can close over refs that mutate during a gesture (e.g. polygon `sides`
+     *  adjusted mid-drag via ArrowUp). An ongoing invoker that wants the latest
+     *  values at commit re-calls it inside `onEnd` via
+     *  `resolveParams(opts?.params)`. */
     params?: Record<string, unknown> | (() => Record<string, unknown>);
     /**
      * The views this binding is live in, by id, where `null` is the surface's
@@ -761,6 +716,13 @@ interface BindingOpts {
      * drag bound inside a minimap view loses to the active tool's marquee.
      */
     views?: readonly (string | null)[];
+    /**
+     * Says this binding is declared ahead of another on the same input on
+     * purpose: its action declines through `enabled()` when the input is not its
+     * to take, and the next binding fires. The dispatcher does that for any
+     * binding; this tells the route-conflict check the order is the design.
+     */
+    yields?: boolean;
 }
 /** Resolve `BindingOpts.params` to a concrete record (calling the thunk if
  *  needed). Returns `undefined` for absent params. */
@@ -792,12 +754,10 @@ type OverlayRole =
  * `OngoingHandle.overlay()` — a marquee rect, a lasso trail, the outline of a
  * shape being dragged out, the line a slice would cut along.
  *
- * Every variant is world geometry and nothing else. No `DrawCommand`, no
- * color, no coordinate space to choose: an action that reached for any of
- * those would be publishing core's own 2D vocabulary, and a surface rendering
- * the same gesture some other way could not read it. `resolveOverlays`
- * normalizes this into `ResolvedOverlay`, which is what a painter consumes —
- * `useDispatcherOverlayLayer` is core's, and it owns every style decision.
+ * Every variant is world geometry and nothing else — no `DrawCommand`, no
+ * color, no coordinate space to choose — so a surface rendering the same
+ * gesture some other way can still read it. The painter owns every style
+ * decision.
  */
 type OngoingOverlay = {
     kind: 'marquee';
@@ -823,13 +783,9 @@ type OngoingOverlay = {
     shiftHeld: boolean;
 } | {
     /**
-     * An open run of world points the gesture is proposing — the slice
-     * action's cut line, `@weasel-js/diagram`'s routed connector.
-     *
-     * Geometry only, like every other variant: `role` is the whole of what
-     * an action says about appearance, and the painting surface is what
-     * turns it into a stroke. An action that picked its own color would be
-     * unpaintable by any renderer but the one it had in mind.
+     * An open run of world points the gesture is proposing — a cut line, a
+     * routed connector. `role` is the whole of what an action says about
+     * appearance.
      */
     kind: 'polyline';
     /** At least two points. Anything shorter is dropped in resolution. */
@@ -841,19 +797,14 @@ type OngoingOverlay = {
     role?: OverlayRole;
 } | {
     /**
-     * Live insert-drag preview — dispatched by `insertAction` while the
-     * user is dragging out a new shape. Pre-commit there is no scene node
-     * to ghost via `previewIds()`/`previewPose()`, so insert paints its
-     * preview through the dispatcher overlay layer instead.
+     * Live insert-drag preview. Pre-commit there is no scene node to ghost
+     * via `previewIds()`/`previewPose()`, so insert paints its preview
+     * through the overlay 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.
+     * `bounds` is the AABB of the current drag (start/current normalized).
+     * `extras` is the per-kind extras the action already collected; the
+     * overlay renderer narrows on `shape` and casts the field shape it
+     * expects.
      */
     kind: 'insertPreview';
     /** Which preview the dispatcher's overlay draws. The kit's own shape
@@ -867,15 +818,16 @@ type OngoingOverlay = {
         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. */
+    /** World-space point to paint a small "anchor" dot at, marking the
+     *  click point — for radial shapes (polygon/star), where no vertex
+     *  sits on it, and for any shape in center mode. */
     anchorPoint?: {
         x: number;
         y: number;
     };
+    /** World affines the shape will also be drawn under once it lands, by
+     *  the container it is drawn into: the preview is painted under each. */
+    copies?: readonly (readonly [number, number, number, number, number, number])[];
 };
 /** Handle returned from an `OngoingInvoker.start`. The dispatcher pumps
  *  `onMove` on subsequent input events of the same gesture and calls
@@ -884,42 +836,29 @@ type OngoingOverlay = {
 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.
+     * dispatcher exposes via `getActiveAction()`, e.g. `'marquee'`, `'move'`,
+     * `'resize'`, `'pan'`.
      *
-     * 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.
+     * When omitted, `getActiveAction().kind` reports `null` even though a
+     * handle is in flight.
      */
     kind?: string;
+    /**
+     * The cursor this gesture shows now, read after every move. Wins over the
+     * action's `activeCursor`, for a cursor that follows the gesture — the
+     * rotate glyph turning about its pivot. `undefined` defers to the action.
+     */
+    cursor?(): CursorSpec | undefined;
     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.
+     * Optional preview surface: the in-flight state the canvas's preview-ghost
+     * layer renders 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()` enumerates the displaced node ids; `previewPose(id)`
+     * returns the interim pose for one of them (shape opaque — the canvas
+     * casts to its `TPose` parameter). Returning `null`, or omitting the
+     * method, means "no preview this gesture".
      */
     previewIds?(): Iterable<string> | null;
     previewPose?(id: string): unknown | null;
@@ -932,40 +871,22 @@ interface OngoingHandle {
      */
     previewOpaqueIds?(): Iterable<string> | null;
     /**
-     * When `false`, the preview-ghost layer paints the ghost AND the
-     * source node stays visible at its committed pose. Defaults to
-     * `true` (move/resize/rotate semantics: ghost replaces the source
-     * during the gesture). Clone overrides to `false` so the original
-     * stays put and the ghost appears at the drag target.
+     * When `false`, the preview-ghost layer paints the ghost AND the source
+     * node stays visible at its committed pose, as a clone wants. Defaults to
+     * `true`: the ghost replaces the source during the gesture.
      */
     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).
+     * Optional per-id preview *data*, for a gesture that mutates `node.data`
+     * (e.g. anchor-edit on nodes that store the polygon on `data.path`) rather
+     * than, or in addition to, the pose. Falls back to the committed
+     * `node.data` when null/absent.
      */
     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.
+     * Optional chrome surface: a non-ghost visual (marquee rectangle, lasso
+     * polyline) painted while the gesture is in flight. Returning `null`, or
+     * omitting the method, means "no overlay this gesture".
      */
     overlay?(): OngoingOverlay | null;
 }
@@ -984,17 +905,13 @@ 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. */
+/** Pluggable invocation strategy for an Action. */
 type Invoker = ImmediateInvoker | OngoingInvoker;
 
 /**
  * GestureBinding — connects a GestureSpec to an Action id (with per-binding
  * options). Tools own arrays of these on their `bindings` field; ambient
  * gesture-bindings are registered globally.
- *
- * See `docs/superpowers/specs/2026-05-16-registry-unification-design.md`.
  */
 
 /** An interaction: a gesture spec composed with the id of the action it
@@ -1006,7 +923,6 @@ interface GestureBinding {
     opts?: BindingOpts;
 }
 /**
- * @experimental
  * A single entry in `Action.defaultBinding[]`. Either a bare `GestureSpec`
  * (no per-binding opts) or an object form that pairs a spec with
  * `BindingOpts` for parametric actions (e.g. `{ params: { axis: 'x' } }`).
@@ -1064,11 +980,9 @@ type ActionDisabledReason = (typeof ActionDisabledReason)[keyof typeof ActionDis
  */
 interface ActionPresentation {
     label: string;
-    /** Inline-SVG icon for palette / toolbar surfaces. Mirrors
-     *  `ToolPresentation.icon` so a generic `<ActionBar>` can render from
-     *  action metadata the same way `<ToolPalette>` renders from tool
-     *  metadata. May be a static `ReactNode` or a function (rare; useful
-     *  for state-aware icons like a "lock" toggle). */
+    /** Inline-SVG icon for palette / toolbar surfaces. 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'`
@@ -1124,30 +1038,21 @@ interface ActionDispatch extends BindingSource {
     /**
      * @experimental
      * Optional predicate saying whether the action can run right now. Return
-     * `true` when it can, or a reason string (e.g. `'Selection required'`)
-     * when it cannot. The command palette greys out a disabled row, skips it
-     * in keyboard nav, ignores clicks, and shows the reason next to the label.
-     * The dispatcher skips a disabled action too, on a key as on a pointer, and
-     * falls through to the next binding that matches. `ActionsRegistry.trigger`
-     * does not ask, so the action's own `run` should still self-guard.
+     * `true` when it can, or an `ActionDisabledReason` when it cannot. The
+     * command palette greys out a disabled row, skips it in keyboard nav,
+     * ignores clicks, and shows the reason next to the label. The dispatcher
+     * skips a disabled action too, on a key as on a pointer, and falls through
+     * to the next binding that matches. `ActionsRegistry.trigger` does not ask,
+     * so the action's own `run` should still 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)'`.
+     * must not throw. A throw is caught and treated as disabled with reason
+     * `ActionDisabledReason.PredicateThrew`.
      *
-     * 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 palette evaluates `enabled` once when opened and does NOT re-evaluate
+     * on selection changes while open.
      *
-     * 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.
+     * `deps` is the same bag passed to `ImmediateInvoker.run`.
      *
      * `at` is the world point of the event being routed, when it has one — a
      * click, a press, a long-press. An action that only applies somewhere
@@ -1155,10 +1060,18 @@ interface ActionDispatch extends BindingSource {
      * falls through to the next binding and hover prediction shows the
      * action's `cursor` only where it would act. Palettes and keystrokes
      * pass no point; treat absent as "anywhere".
+     *
+     * `carried` is what a drop or a paste being routed brings: its items. For
+     * a drag still in flight they hold a MIME and nothing else, since a
+     * browser withholds contents until the drop. An action that takes only
+     * some content refuses the rest here, so a drag it would not take is not
+     * accepted and a paste it would not take stays the page's.
      */
     enabled?: (deps?: ActionDeps, at?: {
         x: number;
         y: number;
+    }, carried?: {
+        items: readonly IngestItem[];
     }) => true | ActionDisabledReason;
     /**
      * @experimental
@@ -1187,12 +1100,11 @@ interface ActionDispatch extends BindingSource {
     /**
      * CSS cursor shown while the pointer hovers a spot where this action
      * would win the drag — or, when the drag's winner declares no cursor,
-     * the click. The hover-cursor pump (in `useGestureDispatcher`) runs
-     * `Dispatcher.resolveOnly` on each idle pointermove — the same match
-     * walk a real press takes — and applies the winning action's `cursor`,
-     * so the hint and the actual 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.
+     * the click. The hover-cursor pump runs the same match walk a real press
+     * takes, so the hint and the actual target stay in sync. Omitted = no
+     * override (the active tool's `Tool.cursor` shows). Affordance hits are
+     * resolved earlier in the pump via `AffordanceRegion.cursor` and never
+     * reach this field.
      *
      * Static value only. Prediction runs `enabled()` but cannot run the
      * invoker, so an action that matches yet bails at `start()` (empty
@@ -1210,19 +1122,12 @@ interface ActionDispatch extends BindingSource {
      * ("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 — an `engaged` phase entry's cursor,
-     * or a function-form `Tool.cursor` reading the gesture scratch out of the
-     * tool-routing dispatcher. Both belonged to a pipeline whose whole job was
-     * being taken over by bindings, and neither could describe a cursor for an
-     * action a tool doesn't own.
      */
     activeCursor?: CursorSpec;
 }
 /**
  * @experimental
- * Single registered action. v1: one binding per action.
+ * Single registered action.
  */
 interface Action extends ActionDispatch, ActionPresentation {
 }
@@ -1237,6 +1142,37 @@ interface ActionSource {
     list(): readonly Action[];
 }
 
+/**
+ * Tuning: what a host changes about an action it did not write — the params
+ * every invocation starts from, and bindings added beside the action's own —
+ * without restating the descriptor. `ActionsRegistry.tune` holds tunings and
+ * applies them to whatever descriptor is live for the id.
+ */
+
+/** An action's params, or a thunk read each time the action asks for them. */
+type ActionParams<P = Record<string, unknown>> = Partial<P> | (() => Partial<P>);
+/** A binding added for an action: a gesture alone, or a gesture with the
+ *  options it passes — the {@link BoundGesture} shape, its params typed. */
+type TunedBinding<P = Record<string, unknown>> = GestureSpec | {
+    spec: GestureSpec;
+    opts: Omit<BindingOpts, 'params'> & {
+        params?: ActionParams<P>;
+    };
+};
+/** What a host changes about one action. */
+interface ActionTuning<P = Record<string, unknown>> {
+    /** Params every invocation starts from. What a binding or a `trigger` call
+     *  passes is laid over them, so these fill in what it leaves out. A thunk is
+     *  read on every call, and an ongoing action resolving its `opts.params`
+     *  mid-gesture sees the value as it is then. */
+    params?: ActionParams<P>;
+    /** Bindings added after the action's own `defaultBinding`. */
+    bindings?: readonly TunedBinding<P>[];
+}
+/** `action` with each tuning applied in turn, a later one's params over an
+ *  earlier one's. Applying a tuning to a copy it already tuned changes nothing. */
+declare function tuneAction(action: Action, tunings: readonly ActionTuning[]): Action;
+
 /**
  * @experimental
  * The entries an action contributes to a bar, menu or palette — one per
@@ -1290,20 +1226,9 @@ declare function evaluateEnabled(action: Action, deps?: ActionDeps): ActionEnabl
 declare function evaluateActive(action: Action, deps?: ActionDeps): boolean | undefined;
 
 /**
- * Dep registry for registry unification.
- *
- * Holds named "live source" thunks. Actions declare `requires: ['selection']`;
- * the dispatcher calls `registry.get('selection')` at invocation time to
- * build a typed Deps bag.
- *
- * `DepSchema` — the map of dep name → value type — is the single source of
- * truth for what `requires`/`register`/`get` accept. Its concrete fields live
- * in `./depSchema` (co-located with the dep value types). It is declared there
- * as a plain `export interface` rather than via a cross-module
- * `declare module './depRegistry'` augmentation: that augmentation does NOT
- * merge once rollup-plugin-dts flattens both files into one `.d.ts` chunk,
- * which silently emptied `DepSchema` for consumers. Consumers still extend it
- * via `declare module '@weasel-js/core'` augmentation.
+ * The dep registry: named "live source" thunks. Actions declare
+ * `requires: ['selection']`; the dispatcher calls `registry.get('selection')`
+ * at invocation time to build a typed Deps bag.
  */
 
 /** Holds the live sources an action's declared dependencies resolve to.
@@ -1362,12 +1287,12 @@ type HotkeyTrigger = 'space' | 'alt' | 'ctrl' | 'meta' | 'shift' | (string & {})
  *
  *  Note: cursor is NOT here. `Tool.cursor` (inherited from `Contribution`)
  *  is already plumbed through `<Canvas>` to `style.cursor` on the host. */
-interface ToolPresentation<TScratch = unknown> {
+interface ToolPresentation {
     /** 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);
+    /** Inline-SVG icon component output: a static `ReactNode`, or a function
+     *  returning one. */
+    icon?: react.ReactNode | (() => 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'. */
@@ -1447,9 +1372,8 @@ interface Contribution<TOverlay = KernelOverlay> extends ContributionRouting, Co
 }
 
 /**
- * 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.
+ * Re-exports the pure matcher primitives from `@weasel-js/gestures` and layers
+ * the actions-layer binding-scope / matchBest logic on top.
  */
 
 /** Where a binding came from, which is also its priority: a held hotkey beats
@@ -1478,25 +1402,13 @@ interface MatchResult {
  * only the body classification. `kindOf` predicates are handed the hit;
  * `affordance:<k>` matches on its `kind`. The body-class strings (`'empty'`,
  * `'selected-body'`, `'unselected-body'`) and the `kind:` forms resolve from
- * `bodyTarget` / `bodyKind` and never see it — which is why chrome floating
- * over empty canvas used to read as empty canvas.
+ * `bodyTarget` / `bodyKind` and never see it.
  *
  * A predicate declares which it is with `readsAffordance`; one that declares
  * nothing, which only untyped code can write, counts as not reading the hit.
  */
 declare function targetConsultsAffordance(specTarget: TargetSpec | undefined): boolean;
-/**
- * Find the best-matching binding across all scopes.
- *
- * Precedence: hotkey > active > ambient.
- * Within a scope, more-specific bindings win; same-specificity bindings keep
- * registration order (see `matchSorted`).
- * Returns null when nothing matches.
- *
- * Note: this returns only the single best match. The dispatcher uses
- * `matchSorted` so it can fall through to lower-specificity matches when a
- * higher-specificity match's `enabled()` reports disabled.
- */
+/** The first of {@link matchSorted}'s matches, or null when nothing matches. */
 declare function matchBest(e: InputEvent, bindings: readonly ScopedBinding[], isMac: boolean, engagedChannels?: ReadonlySet<string>): MatchResult | null;
 /**
  * Find every binding that matches the event, sorted by precedence
@@ -1505,12 +1417,7 @@ declare function matchBest(e: InputEvent, bindings: readonly ScopedBinding[], is
  *   - Scopes by priority: hotkey > active > ambient.
  *   - Within a scope, more-specific bindings beat less-specific (see
  *     `specificity()`).
- *   - Among same-specificity bindings, first-declared wins (stable sort
- *     preserves registration order — same tiebreaker as pre-specificity).
- *
- * Used by the dispatcher to implement specificity-ordered fall-through:
- * when the top match's `enabled()` returns a disabled reason (or the
- * action's `start()` returns an empty handle), the next match is tried.
+ *   - Among same-specificity bindings, first-declared wins.
  */
 declare function matchSorted(e: InputEvent, bindings: readonly ScopedBinding[], isMac: boolean, engagedChannels?: ReadonlySet<string>, warn?: (message: string) => void): MatchResult[];
 /** {@link matchSorted}, plus what an exclusive claim on the event barred. */
@@ -1686,11 +1593,9 @@ interface RankedCandidate {
  * `createDispatcher` in `dispatcher.ts` implements it.
  */
 
-/** Everything the dispatcher must consult to route one input event: the
- *  registered actions and their deps, which tool is active, which hotkeys are
- *  held, and — optionally — the chrome state that action eligibility rules are
- *  evaluated against. Rebuilt per event rather than held, so the dispatcher
- *  itself stays stateless apart from in-flight gestures. */
+/** Everything the dispatcher must consult to route one input event. Rebuilt
+ *  per event rather than held, so the dispatcher itself stays stateless apart
+ *  from in-flight gestures. */
 interface DispatcherContext {
     /** All registered actions; the dispatcher walks `.defaultBinding` for ambient bindings. */
     actions: ActionSource;
@@ -1741,9 +1646,7 @@ interface UiOngoingControl {
 }
 /**
  * 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.
+ * would fire if `event` were dispatched for real.
  */
 interface ResolveOnlyResult {
     actionId: string;
@@ -1796,14 +1699,12 @@ 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.
+     * Off by default: 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.
+     * With it on, `shadowed` narrows to its precise meaning: this candidate
+     * would have fired, but something above it did.
      */
     evaluateShadowed?: boolean;
 }
@@ -1825,12 +1726,10 @@ interface Dispatcher {
      */
     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.
+     * Predict which action `event` would route to WITHOUT invoking it: the
+     * first candidate `handleInput`'s walk 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
@@ -1841,25 +1740,15 @@ interface Dispatcher {
     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.
+     * with a verdict explaining whether it would fire. Nothing is dropped:
+     * candidates that `resolveOnly`'s walk would filter out are kept here and
+     * labeled `ineligible` instead. Pure query, and it shares `resolveOnly`'s
+     * known divergence from a real dispatch.
      *
      * `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}.
+     * By default everything below the winner is `shadowed` without being asked
+     * — see {@link ResolveAllOptions.evaluateShadowed}.
      */
     resolveAll(event: InputEvent, ctx: DispatcherContext, opts?: ResolveAllOptions): ResolvedCandidate[];
     /**
@@ -1872,7 +1761,6 @@ interface Dispatcher {
     explain(event: InputEvent, ctx: DispatcherContext, opts?: ResolveAllOptions): DispatchRecord;
     /**
      * Synthesize an end-of-gesture for every in-flight ongoing handle.
-     * Used by tool-switch cancellation (Q2 decision).
      */
     cancelAll(reason: 'commit' | 'cancel'): void;
     /**
@@ -1888,41 +1776,31 @@ interface Dispatcher {
      */
     inFlightCursor(): CursorSpec | 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.
+     * Read-only iterator over currently in-flight `OngoingHandle` instances,
+     * for a preview layer to walk each handle's `previewIds()` /
+     * `previewPose(id)`.
      */
     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 — and after any other input handled while a gesture is in
-     * flight. Input that arrives with nothing in flight and starts nothing
-     * does not fire it. Consumers re-read `getInFlightHandles()` and re-render.
+     * Subscribe to in-flight state changes. The callback fires after handle
+     * start, every `onMove` pump, end, cancel, and cancel-all, and after any
+     * other input handled while a gesture is in flight. Input that arrives
+     * with nothing in flight and starts nothing does not fire it.
      *
      * 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.
+     * on: the snapshot half of the `useSyncExternalStore` contract.
      *
-     * Starts at 0 and only ever increases. Two reads returning the same number
-     * mean no gesture was in flight in between; it does **not** guarantee that
-     * a bump changed anything observable (input that matched no binding still
-     * counts while a gesture is in flight — see `subscribe`).
+     * A bump does **not** guarantee that anything observable changed (input
+     * that matched no binding still counts while a gesture is in flight — 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."
+     * Snapshot of the currently active action.
      *
      * - `kind` — the `OngoingHandle.kind` reported by the in-flight
      *   handle (e.g. `'marquee'`, `'move'`). `null` when no action is
@@ -1933,26 +1811,15 @@ interface Dispatcher {
      *
      * 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.
+     * handle wins.
      */
     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`.
+     * Start an ongoing action driven by UI (not a gesture), and register its
+     * handle in the in-flight map so `getInFlightHandles()` reports it.
      *
      * Returns `null` if `actionId` is unknown, the action's invoker is not
      * ongoing, or `start` returned an empty handle.
@@ -1969,10 +1836,8 @@ interface Dispatcher {
  */
 
 /** One entry per "mode change" — a kit state transition that isn't a
- *  dispatched input event but is load-bearing for understanding why an
- *  input was (or wasn't) handled later. Pushed via `recordModeSwitch()`;
- *  consumers include the editAnchors dep (editingId changes), and
- *  could expand to active-tool / hotkey-stack / focus changes. */
+ *  dispatched input event but explains why an input was (or wasn't) handled
+ *  later. Pushed via `recordModeSwitch()`. */
 interface ModeSwitchLogEntry {
     kind: 'mode';
     ts: number;
@@ -1991,12 +1856,31 @@ type TraceLogEntry = DispatchRecord | ModeSwitchLogEntry;
 declare function recordModeSwitch(mode: string, from: string | null, to: string | null, detail?: string): void;
 
 /**
- * Dispatcher orchestrator — pure module, no React, no DOM.
+ * The slot an in-flight ongoing handle is keyed by:
+ * - `key-held`: `key-held-<code>` (`key-held-Space`), so two keys that share a
+ *   `key`, such as the two Shifts, hold separately. An event with no code keys
+ *   by `key`.
+ * - `pointerdown` and the drag that follows: `pointer-<pointerId>`. An event
+ *   with no `pointerId` (a synthesized probe, a programmatic drag, most tests)
+ *   keys to `pointer-mouse`.
+ * - `multitouch`: `multitouch-<fingers>`.
+ * - any other kind that starts an ongoing invoker: `ongoing-<kind>`.
+ */
+
+/**
+ * The in-flight handle slot a pointer's gestures key into. Exported because
+ * the React seam (`useGestureDispatcher`) has to name the same slot when it
+ * asks `dispatcher.inFlight()` whether a given pointer is mid-drag.
  *
- * 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.
+ * @param pointerId - `PointerEvent.pointerId`, or `undefined` for a
+ *   synthesized event with no originating DOM pointer.
+ */
+declare function pointerGestureId(pointerId: number | undefined): string;
+/** The in-flight handle slot a multitouch gesture of `fingers` fingers keys into. */
+declare function multiTouchGestureId(fingers: number): string;
+
+/**
+ * Dispatcher orchestrator — pure module, no React, no DOM.
  *
  * ## Precedence and fall-through
  * An exclusive affordance claim first bars every binding that does not
@@ -2012,46 +1896,14 @@ declare function recordModeSwitch(mode: string, from: string | null, to: string
  * Candidates whose `eligible` rule is false are dropped first. The dispatcher
  * walks the rest 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-<code>` (`key-held-Space`), so two
- *   keys that share a `key`, such as the two Shifts, hold separately. An event
- *   with no code keys by `key`.
- *   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>`.
+ * event is unhandled.
  *
  * ## Action-lookup miss behavior
  * When the walk reaches 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.
+ * `'unhandled'`, so the gesture falls through as if unmatched.
  */
 
-/**
- * The in-flight handle slot a pointer's gestures key into.
- *
- * Exported because the React seam (`useGestureDispatcher`) has to name the
- * same slot when it asks `dispatcher.inFlight()` whether a given pointer is
- * mid-drag. That used to be the string literal `'pointer-mouse'` on both
- * sides, which was correct only because `gestureIdFor` ignored the pointer id
- * entirely — the two lies cancelled out.
- *
- * @param pointerId - `PointerEvent.pointerId`, or `undefined` for a
- *   synthesized event with no originating DOM pointer.
- */
-declare function pointerGestureId(pointerId: number | undefined): string;
 /** Build a dispatcher. `getAction` overrides how action ids are resolved;
  *  by default the `DispatcherContext`'s registry is used. */
 declare function createDispatcher(opts?: {
@@ -2087,13 +1939,17 @@ interface ActionsRegistry {
      *  `trigger` nor `begin` will fire it. Returns a release. This is the
      *  "not for me" door — `unregister` is the "should not exist" one. */
     mute(id: string): () => void;
+    /** Tune `id` here and in scopes below: its params and added bindings
+     *  apply to whichever descriptor is live for it, registered before the
+     *  tuning or after. Returns a release. See {@link ActionTuning}. */
+    tune(id: string, tuning: ActionTuning): () => 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' })`).
-     *  Returns whether it ran one: `false` for an unknown id, and for an
-     *  ongoing-invoker action, which `trigger` cannot reach (see `begin`). It
-     *  does not ask `enabled`. */
+     *  Returns whether it ran one: `false` for an unknown id, for an action
+     *  whose `enabled` refuses, and for an ongoing-invoker action, which
+     *  `trigger` cannot reach (see `begin`). `enabled` is asked with no point. */
     trigger(id: string, params?: Record<string, unknown>): boolean;
     /**
      * Subscribe to registry mutations. The callback fires after any
@@ -2162,7 +2018,11 @@ declare function offhandKeyFor(trigger: HotkeyTrigger): string;
 /** Build the per-tool `BoundGesture` list for the consolidated action's
  *  `defaultBinding`. Each entry pairs a `key-held` spec with
  *  `opts.params.toolId` so the invoker's `start` can pick out which tool
- *  to engage. */
+ *  to engage.
+ *
+ *  An offhand tool engages only between gestures. Swapping the tool out
+ *  mid-drag would cancel the drag, and the key is free for the gesture's own
+ *  tool to use — Space repositions a shape being drawn. */
 declare function buildToolOffhandBindings(specs: readonly ToolOffhandBindingSpec[]): BoundGesture[];
 /** The `key-held` spec for holding `key` (a `KeyboardEvent.key`, or several).
  *  A modifier key gets every modifier optional, since its own keydown reports
@@ -2222,13 +2082,15 @@ declare const isControlHandle: TargetPredicate & {
 declare const isAnchorOrControl: TargetPredicate & {
     readsAffordance: true;
 };
+/** The outline of the path being edited, between its anchors. */
+declare const isSegment: TargetPredicate & {
+    readsAffordance: true;
+};
+/** Anything path edit puts on the path: an anchor, a control, or a segment. */
+declare const isPathEditPart: TargetPredicate & {
+    readsAffordance: true;
+};
 
-/**
- * The long-press the gesture dispatcher is timing, as observable state: where
- * the press landed, when the hold started, how far through it is, and whether
- * any binding would fire on it. Feedback — a filling ring, a haptic — reads
- * this; nothing here decides what the feedback looks like.
- */
 /** A press being held toward a long-press. */
 interface PendingLongPress {
     pointerId: number;
@@ -2281,8 +2143,7 @@ interface LongPressState {
 interface LongPressStore extends LongPressState {
     set(next: PendingLongPress | null): void;
 }
-/** How long a touch or pen press is held before it fires `longPress`, in ms. */
-declare const LONG_PRESS_MS = 500;
+
 /** How `useGestureDispatcher` times, publishes and signals a long-press. */
 interface LongPressOptions {
     /** Hold time in ms. Default {@link LONG_PRESS_MS}. */
@@ -2450,6 +2311,10 @@ declare function modeShortcutSpec(shortcut: string): KeySpec;
  * `exit` / `discard` / `commit` / `cancel` while that mode is active, `entry`
  * while it is not. Install it with `<SceneCanvas ambient>`.
  *
+ * An entry key one mode shares with another mode's leaving key is reported as
+ * a route conflict unless `canEnter` is given: that is what keeps the entry
+ * key from firing inside the other mode.
+ *
  * The bindings ride the hotkey tier, so leaving a mode outranks what the same
  * key does otherwise (Escape clearing the selection), and they yield while a
  * gesture is in flight, so Escape mid-drag still cancels the drag first. Keys
@@ -2479,101 +2344,36 @@ interface ToolKeybinding {
 }
 /** Modifier-key snapshot at event dispatch time. */
 type ToolModifiers = ModifierState;
-/** Per-event context passed to every channel handler. `scratch` is typed
- *  via the tool's `TScratch` parameter; it survives across a single
- *  gesture (pointer-down through end/cancel) and is replaced on next
- *  gesture start by `initScratch()`. */
-interface ToolCtx<TScratch = unknown> {
-    worldX: number;
-    worldY: number;
-    modifiers: ToolModifiers;
-    selection: SelectionApi;
-    /** Adapter/scene access — opaque at this layer; tools that need it
-     *  cast to a known shape. This layer doesn't constrain it. */
-    adapter: unknown;
-    applyOps: (ops: Op[], label: string) => void;
-    /** Current viewport. Reflects camera-position semantics — see
-     *  `View` JSDoc. */
-    view: View;
-    /** Mutate the viewport. In controlled mode this calls the consumer's
-     *  `onViewChange`; in uncontrolled mode it updates Canvas's internal
-     *  state. View changes are not undoable. */
-    setView: (next: View) => void;
-    /** Bounding rect of the canvas element in viewport coords. Used by
-     *  zoom/pan tools to convert event clientX/clientY to canvas-relative
-     *  anchors. */
-    canvasRect: DOMRect;
-    /** 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;
-}
-/**
- * What `onActivate` / `onDeactivate` receive: the tool's scratch, from
- * `initScratch()`. A lifecycle moment has no pointer, hit or modifier state to
- * report, so nothing else is populated; a callback needing the selection or
- * the scene closes over it, as the tool's actions do.
- */
-interface ToolLifecycleCtx<TScratch = unknown> {
-    scratch: TScratch;
-}
-/** World-space AABB shape used by `previewBounds`. Alias of the kit-wide
- *  `Bounds` type — the optional `rotation` field carries through so a tool
- *  can report an oriented preview rect (e.g. mid-rotate). */
-type ToolBounds = Bounds;
 /**
  * The focus-declaring case of a `Contribution`: a mode the user switches
- * into, plus the hooks that only make sense for one (`initScratch`,
- * activate/deactivate, live preview, `cursor`). Everything else — bindings,
- * actions, overlay, presentation — is inherited.
+ * into, plus the hooks that only make sense for one (activate/deactivate,
+ * `cursor`). Everything else — bindings, actions, overlay, presentation — is
+ * inherited.
  */
-interface Tool<TScratch = unknown, TOverlay = KernelOverlay> extends Contribution<TOverlay> {
+interface Tool<TOverlay = KernelOverlay> extends Contribution<TOverlay> {
     /** The key that activates this tool. `useKeybindings` appends a binding
      *  entry for it to the consolidated `tool.activate` action (with
      *  `opts.params.toolId` set so the invoker knows which tool to switch to).
      *  A tool with none has no activation key. */
     keybinding?: ToolKeybinding;
-    initScratch?: () => TScratch;
-    cursor?: CursorSpec | ((ctx: ToolCtx<TScratch>) => CursorSpec);
+    cursor?: CursorSpec | (() => CursorSpec);
     /** The tool became live: it took the active slot, or its `hotkey` went
-     *  down, while it held neither. */
-    onActivate?: (ctx: ToolLifecycleCtx<TScratch>) => void;
+     *  down, while it held neither. A lifecycle moment has no pointer, hit or
+     *  modifier state to report; a callback needing the selection or the scene
+     *  closes over it, as the tool's actions do. */
+    onActivate?: () => void;
     /** The tool stopped being live in both slots, or its canvas unmounted. */
-    onDeactivate?: (ctx: ToolLifecycleCtx<TScratch>) => void;
-    /** Returns the in-flight preview pose for `id` if this tool is mid-gesture
-     *  on it; otherwise `null`. Lets `Canvas.helpersRef.getEffectivePose`
-     *  reflect live gesture state without reaching into hook internals. The
-     *  return type is `unknown` here because the Tool interface is pose-agnostic;
-     *  callers that know the pose shape (e.g. Canvas typed by `TPose`) cast at
-     *  the use site. */
-    previewPose?: (id: string) => unknown;
-    /** Returns the in-flight preview bounds for `id` if this tool is mid-gesture
-     *  on it; otherwise `null`. Optional companion to `previewPose` for tools that
-     *  can compute bounds without round-tripping through a geometry adapter. */
-    previewBounds?: (id: string) => ToolBounds | null;
-    /** Returns ids whose committed scene-render should be suppressed while this
-     *  tool is mid-gesture (e.g. cascade move's dragged + descendant ids whose
-     *  preview ghosts replace the committed pose). The standard scene slot
-     *  consults this alongside `previewPose` to avoid double-rendering. Returns
-     *  `null` when no gesture is in flight. */
-    previewIds?: () => Iterable<string> | null;
+    onDeactivate?: () => void;
 }
 /** Whether `entry` is a tool: a contribution that can hold focus, chosen from
- *  a palette or held on a key. Only a tool's focus hooks (`initScratch`,
- *  `cursor`, `onActivate`, the previews) ever run. */
-declare function isTool<TOverlay>(entry: Contribution<TOverlay>): entry is Tool<unknown, TOverlay>;
+ *  a palette or held on a key. Only a tool's focus hooks (`cursor`,
+ *  `onActivate`, `onDeactivate`) ever run. */
+declare function isTool<TOverlay>(entry: Contribution<TOverlay>): entry is Tool<TOverlay>;
 /** Internal — which slot a tool occupies in the dispatch order. */
 type ToolSlot = 'hotkey' | 'active' | 'ambient';
-/** Internal alias for "a Tool of any scratch type" — used in registries and
- *  dispatchers that hold tools of heterogeneous scratch shapes. `any` is
- *  intentional: `Tool<TScratch>` is invariant in TScratch, so `Tool<unknown>`
- *  is too strict for containers that accept any concrete `Tool<T>`. */
-type AnyTool = Tool<any, any>;
-/** "A tool of any scratch type that draws `TOverlay`" — the container form for
- *  registries that hold heterogeneous scratch shapes but one overlay type. */
-type AnyToolOf<TOverlay> = Tool<any, TOverlay>;
+/** A tool drawing any overlay type — the element type for registries and
+ *  dispatchers that never read the overlay. */
+type AnyTool = Tool<any>;
 
 /**
  * What a tool declares.
@@ -2584,7 +2384,7 @@ type AnyToolOf<TOverlay> = Tool<any, TOverlay>;
  * definition is mostly `bindings`, plus presentation and any actions the tool
  * itself introduces.
  */
-interface ToolDef<TScratch = void, TOverlay = KernelOverlay> {
+interface ToolDef<TOverlay = KernelOverlay> {
     id: string;
     /** Capability tags for modality eligibility. `defineTool` forwards these
      *  onto `Tool.eligibility.capabilities`, which is where every gate reads
@@ -2607,7 +2407,7 @@ interface ToolDef<TScratch = void, TOverlay = KernelOverlay> {
      *  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>;
+    presentation?: ToolPresentation;
     /** 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
@@ -2625,17 +2425,10 @@ interface ToolDef<TScratch = void, TOverlay = KernelOverlay> {
     hotkey?: HotkeyTrigger;
     /** Fires as the tool becomes live in the active or hotkey slot. See
      *  `Tool.onActivate`. */
-    onActivate?: (ctx: ToolLifecycleCtx<TScratch>) => void;
+    onActivate?: () => void;
     /** Fires as the tool stops being live in either slot. */
-    onDeactivate?: (ctx: ToolLifecycleCtx<TScratch>) => void;
-    cursor?: CursorSpec | ((ctx: ToolCtx<TScratch>) => CursorSpec);
-    /** Override the default scratch initializer. Default is `() => null`
-     *  cast to `TScratch`, which works for tools whose scratch is fresh
-     *  every gesture. Tools that need scratch identity to survive across
-     *  gesture boundaries (e.g. the pen tool's multi-click subpath state)
-     *  pass a stable-ref-returning thunk here. The factory forwards this
-     *  onto the returned `Tool.initScratch`. */
-    initScratch?: () => TScratch;
+    onDeactivate?: () => void;
+    cursor?: CursorSpec | (() => CursorSpec);
     /** 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
@@ -2648,7 +2441,7 @@ interface ToolDef<TScratch = void, TOverlay = KernelOverlay> {
      *
      *  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
+     *  `if (!state.something) return []` — rather than expecting the kit to
      *  swap layers as the gesture progresses.
      *
      *  Pass an array to contribute several layers; they render in order. */
@@ -2659,20 +2452,10 @@ interface ToolDef<TScratch = void, TOverlay = KernelOverlay> {
 }
 
 /**
- * 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.
+ * Build a `Tool` from a declarative `ToolDef`: validates the id, applies the
+ * `cursor` default, and keeps the authored form on `Tool.def` for reflection.
  */
-declare function defineTool<TScratch = void, TOverlay = KernelOverlay>(def: ToolDef<TScratch, TOverlay>): Tool<TScratch, TOverlay>;
+declare function defineTool<TOverlay = KernelOverlay>(def: ToolDef<TOverlay>): Tool<TOverlay>;
 
 /**
  * One row in the route registry — a single `GestureBinding` on one tool,
@@ -2720,6 +2503,10 @@ interface RegistryEntry {
     /** The binding's `opts.views`: the views it is live in. Absent when it is
      *  live in every view. */
     views?: readonly (string | null)[];
+    /** The binding's `opts.params`, as declared: a thunk is not called. */
+    params?: unknown;
+    /** The binding's `opts.yields`, when it is set. */
+    yields?: true;
 }
 /**
  * Stand-in target for a `{ kindOf }` predicate spec.
@@ -2756,10 +2543,8 @@ declare function buildRouteRegistry(entries: readonly Contribution<unknown>[]):
  */
 declare function routesForSpec(spec: GestureSpec): readonly string[];
 
-/** Two or more tools declare the same exact (phase, gesture, arg, target,
- *  modifiers) tuple — the dispatcher's slot precedence picks one
- *  arbitrarily (well, deterministically by slot order, but the author
- *  probably didn't intend the duplication). */
+/** Two or more bindings declare the same exact (phase, gesture, arg, target,
+ *  modifiers) tuple, so slot order alone picks one. */
 interface Conflict {
     phase: 'initial' | 'engaged' | 'any';
     gesture: GestureName;
@@ -2780,39 +2565,32 @@ interface Conflict {
  *    required against Alt required fire on different inputs, and Shift
  *    required outranks Shift optional. An optional modifier against a
  *    forbidden one is flagged, since both take the bare press.
- *  - 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.
- *
+ *  - Two `{ kindOf }` predicate targets, unless they are the same function.
+ *    Predicates bucket by identity, so two separately written but
+ *    equivalent ones go unflagged.
  *  - Two actions whose `eligible` rules can never hold together — each
  *    mode's own Escape exit, say. See {@link rulesExclusive}.
- *
  *  - Two bindings whose `opts.views` keep them from being live and equally
- *    ranked in any one view. See `viewsTie`.
+ *    ranked in any one view.
+ *  - Two bindings of one action with equal params that tie on one platform
+ *    only: `mod` against `ctrl`, which are one key off a Mac and two on it.
+ *    The same pair tying on both platforms is a plain duplicate and is flagged.
+ *
+ *  A binding whose action declines via `enabled()` so a lower-priority one
+ *  takes the gesture is flagged all the same, since seeing that intent would
+ *  mean evaluating the action, unless it says so with `opts.yields`. A pair
+ *  whose earlier binding yields is not a conflict; one whose later binding
+ *  yields still is, as the earlier one decides alone.
  *
- *  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.
+ *  Two bindings on the same tool can share a tuple, 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 `findScopedConflicts`.
+ *  Feeding this a whole tool *registry* over-reports, because registry tools
+ *  take turns in the active slot and can't collide with each other — see
+ *  `findScopedConflicts`.
  */
 declare function findConflicts(entries: readonly Contribution<unknown>[]): Conflict[];
-/**
- * The tool scopes as the dispatcher sees them — which is what decides whether
- * two same-tuple bindings can actually collide.
- */
+/** The tool scopes as the dispatcher sees them. */
 interface ToolScopes {
     /** Tools eligible for the active slot, keyed by id or as a flat list. */
     registry: readonly Contribution<unknown>[] | Readonly<Record<string, Contribution<unknown>>>;
@@ -2829,17 +2607,13 @@ interface ToolScopes {
 /**
  * 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.
+ * Call it once wherever a tool set is assembled, 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.
+ * is sometimes deliberate, since the loser can still take the gesture when
+ * the winner declines through `enabled()`. A binding ordered that way on
+ * purpose says so with `opts.yields`, and is not reported.
  *
  * @returns The conflicts found, so callers can dedupe repeat reports.
  */
@@ -2852,7 +2626,10 @@ declare function reportRouteConflicts(scopes: ToolScopes, warn?: (message: strin
  *
  * Extracted from the deleted singular `useKeybinding` hook so the remaining
  * consumers don't depend on its disappearance.
+ *
+ * @packageDocumentation
  */
+
 /**
  * A key plus a modifier policy, as {@link matchesKeyBinding} tests it against a
  * `KeyboardEvent`. Every modifier left unset is forbidden, so `{ key: 'a' }`
@@ -2885,14 +2662,6 @@ interface KeyBinding {
     /** Call `preventDefault` before the handler. Default `true`. */
     preventDefault?: boolean;
 }
-/** Returns true when the target is an input, textarea, or contenteditable element. */
-declare function isEditableTarget(target: EventTarget | null): boolean;
-/**
- * True when `e` is Space or Enter on a focused control those keys activate — a
- * button, a link, a checkbox. The key is that control's, so a page-level
- * listener that claims it cancels the control's own activation.
- */
-declare function activatesFocusedControl(e: KeyboardEvent): boolean;
 /**
  * Pure matcher for `KeyBinding` against a `KeyboardEvent`. Only checks key +
  * modifier policy — does NOT apply the editable-target skip or
@@ -2900,38 +2669,21 @@ declare function activatesFocusedControl(e: KeyboardEvent): boolean;
  * gesture dispatcher so the rules can't drift.
  */
 declare function matchesKeyBinding(e: KeyboardEvent, b: KeyBinding): boolean;
-type ModifierKeys = Pick<KeyboardEvent, 'key' | 'metaKey' | 'ctrlKey' | 'shiftKey' | 'altKey'>;
 /** Which history step `e` asks for: Mod+Z undoes, Shift+Mod+Z and Mod+Y redo. `null` for anything else. Takes a
  *  React keyboard event as readily as a DOM one. */
-declare function historyKey(e: ModifierKeys): 'undo' | 'redo' | null;
+declare function historyKey(e: Pick<KeyboardEvent, 'key' | 'metaKey' | 'ctrlKey' | 'shiftKey' | 'altKey'>): 'undo' | 'redo' | null;
 
 /**
- * Typed keys for the gesture/behavior scratch store.
- *
- * Gestures expose `ctx.scratch: Record<string, unknown>` as a per-gesture
- * mutable bag that behaviors use to stash state across `onDown` / `onMove`
- * / `onEnd` calls. The store is `unknown`-valued because behaviors are
- * tool-agnostic — a single behavior may run under different tools with
- * different scratch shapes. Without a typing convention every read site
- * has to `(ctx.scratch as <some shape>)[KEY]`, and a writer changing the
- * shape can silently break readers with no compile-time signal.
- *
- * `ScratchKey<T>` is a phantom-typed string that carries its payload type
- * via a branded interface. `getScratch` and `setScratch` use the brand to
- * narrow / constrain at the typing layer; at runtime the key is just its
- * underlying string and the store remains a plain `Record`.
+ * Typed keys for the gesture/behavior scratch store, `ctx.scratch`.
+ * `ScratchKey<T>` carries its payload type at the typing layer; at runtime
+ * the key is just its underlying string and the store remains a plain `Record`.
  *
  * @example
  * ```ts
- * // Module-level (or behavior-level) constant, shared by writer + reader:
+ * // Module-level constant, shared by writer + reader:
  * const LASSO_VERTICES = scratchKey<readonly { x: number; y: number }[]>('lasso.vertices');
- *
- * // Writer (a tool's onMove):
  * setScratch(ctx.scratch, LASSO_VERTICES, vertices);
- *
- * // Reader (a behavior's onEnd):
  * const vertices = getScratch(ctx.scratch, LASSO_VERTICES) ?? [];
- * //    ^?  readonly { x: number; y: number }[] | undefined
  * ```
  */
 /** Phantom-typed key for a scratch slot. The `__scratchKeyPayload` phantom
@@ -2946,13 +2698,9 @@ interface ScratchKey<T> {
  *  field already satisfies this; consumers don't need to construct one. */
 type ScratchStore = Record<string, unknown>;
 /**
- * Make a typed scratch key. Use module-level constants so the same key
- * is shared by writer and reader.
- *
- * Namespace the name by behavior or feature to avoid collisions
- * (`'behavior.field'` is a good convention). Two keys with the same
- * `name` refer to the same slot at runtime — the type parameter is a
- * compile-time contract, not a uniqueness guarantee.
+ * Make a typed scratch key. Two keys with the same `name` refer to the same
+ * slot at runtime — the type parameter is a compile-time contract, not a
+ * uniqueness guarantee — so namespace the name (`'behavior.field'`).
  */
 declare function scratchKey<T>(name: string): ScratchKey<T>;
 /** Read a typed slot from the scratch store. Returns `undefined` if
@@ -2993,6 +2741,14 @@ declare function itemsFromFiles(files: File[]): IngestItem[];
 /** Materialize a drop's `DataTransfer`. MUST be called during the `drop`
  *  event dispatch (see module doc). */
 declare function itemsFromDataTransfer(dt: DataTransfer): Promise<IngestItem[]>;
+/**
+ * What a drag still in flight says it carries: one item per flavor, MIME
+ * only. A browser withholds contents until the drop, so nothing may read
+ * `file` or `text` off these; they exist to ask which bindings would match.
+ * A file the browser does not name yet (Firefox reports
+ * `application/x-moz-file`, others only a `Files` type) is `UNKNOWN_MIME`.
+ */
+declare function itemTypesFromDataTransfer(dt: DataTransfer): readonly IngestItem[];
 /** Materialize a paste's `clipboardData`. Fully synchronous. */
 declare function itemsFromClipboardData(cd: DataTransfer): IngestItem[];
 
@@ -3055,6 +2811,8 @@ declare function dwarn(namespace: string, ...args: unknown[]): void;
  * The pure half: no React, no DOM. The React seam that pumps browser events
  * into the dispatcher, and the providers that feed it, live behind
  * `@weasel-js/routing/react`.
+ *
+ * @packageDocumentation
  */
 
 /**
@@ -3063,10 +2821,8 @@ declare function dwarn(namespace: string, ...args: unknown[]): void;
  * keyed on.
  *
  * It declares one entry, `activeTool`, because the value and the action that
- * requires it (`tool.offhand`) are both routing's. Routing knows that an
- * action names its dependencies and that the registry resolves them at
- * invocation time; it does not know what a selection, a scene, or a viewport
- * is. Whoever supplies those merges them in:
+ * requires it (`tool.offhand`) are both routing's. Whoever supplies the rest
+ * merges them in:
  *
  * ```ts
  * declare module '@weasel-js/routing' {
@@ -3075,12 +2831,7 @@ declare function dwarn(namespace: string, ...args: unknown[]): void;
  * ```
  *
  * `@weasel-js/core` merges the kit's own deps this way and re-exports
- * `DepSchema`, so a consumer adds its own against `'@weasel-js/core'` and
- * never has to know this module exists. The merge carries through the
- * re-export in both directions — `scripts/smoke-consumer-bundle.mjs` asserts
- * it against the published `.d.ts`, which is where it once broke: a
- * cross-module augmentation stops merging when `rollup-plugin-dts` flattens
- * both files into one chunk.
+ * `DepSchema`, so a consumer adds its own against `'@weasel-js/core'`.
  */
 interface DepSchema {
     /** Currently active tool id + hotkey-hold stack. */
@@ -3088,6 +2839,29 @@ interface DepSchema {
 }
 /** Every dep name declared by anything that has merged into {@link DepSchema}. */
 type DepName = keyof DepSchema;
+/**
+ * The params each action reads, by action id — what types a tuning's
+ * `params` and the params on the bindings it adds. Whoever ships an action
+ * merges its entry in, as with {@link DepSchema}:
+ *
+ * ```ts
+ * declare module '@weasel-js/core' {
+ *   interface ActionParamSchema { brushDeleteAnchors: { radiusPx: number } }
+ * }
+ * ```
+ *
+ * Declare an entry as a type literal, not an interface: an interface has no
+ * index signature, so it is not a `Record<string, unknown>`.
+ */
+interface ActionParamSchema {
+}
+/** Tunings keyed by action id: typed by {@link ActionParamSchema} for an id it
+ *  declares, `Record<string, unknown>` params for any other. */
+type ActionTunings = {
+    readonly [K in keyof ActionParamSchema]?: ActionTuning<ActionParamSchema[K]>;
+} & {
+    readonly [id: string]: ActionTuning | undefined;
+};
 /**
  * What the kernel drawing these tools takes as an overlay. Routing never reads
  * an overlay, so it has no type of its own for one; the kernel merges its type
@@ -3109,4 +2883,4 @@ type KernelOverlay = OverlaySchema extends {
     overlay: infer O;
 } ? O : unknown;
 
-export { type DispatchRecord as $, type ActionsRegistry as A, type BindingOpts as B, type Contribution as C, type DepRegistry as D, type BindingScope as E, type BindingSource as F, type BodyPredicate as G, type BoundGesture as H, type Bounds as I, type BuildRuleCtxArgs as J, type KernelOverlay as K, type LongPressOptions as L, COARSE_TARGET_SCALE as M, type Condition as N, type OverlayPosition as O, type Conflict as P, type ContributionChrome as Q, type RuleCtx as R, ScopeNode as S, ToolNode as T, type ContributionDeps as U, type ContributionRouting as V, DEFAULT_ALLOWED_CAPABILITIES as W, DEFAULT_DEVICE_PROFILE as X, type DebugSink as Y, type DetectedDeviceFacts as Z, type DeviceProfile as _, type DepName as a, type TraceLogEntry as a$, type DispatchRecordInput as a0, type DispatcherContext as a1, type DragSample as a2, type DroppedCandidate as a3, type Eligibility as a4, type EligibilityState as a5, type GestureBinding as a6, type HandleKind as a7, type HitShape as a8, type HotkeyTrigger as a9, type PointerSessionCancelReason as aA, type PointerSessionOptions as aB, type RankedCandidate as aC, type RecordCandidate as aD, type RegistryEntry as aE, type ResizeAnchor as aF, type ResolveAllOptions as aG, type ResolveOnlyResult as aH, type ResolvedCandidate as aI, type Rule as aJ, type ScopedBinding as aK, type ScratchKey as aL, type ScratchStore as aM, type SelectionApi as aN, type Selector as aO, type SpecificityPart as aP, TOOL_OFFHAND_ID as aQ, type Tool as aR, type ToolBounds as aS, type ToolCtx as aT, type ToolDef as aU, type ToolKeybinding as aV, type ToolLifecycleCtx as aW, type ToolModifiers as aX, type ToolOffhandBindingSpec as aY, type ToolPresentation as aZ, type ToolSlot as a_, INGEST_STRING_MIMES as aa, type ImmediateInvoker as ab, type InvocationCtx as ac, type Invoker as ad, type KeyBinding as ae, LONG_PRESS_MS as af, type LongPressState as ag, type LongPressStore as ah, type MatchOutcome as ai, type MatchResult as aj, type ModeShortcutHandlers as ak, type ModeSwitchLogEntry as al, type ModifierState as am, NEVER as an, type NodeId as ao, type OngoingHandle as ap, type OngoingInvoker as aq, type OngoingOverlay as ar, type OverlayRole as as, type OverlaySchema as at, PREDICATE_TARGET as au, type PendingLongPress as av, type PlacedBy as aw, type Point2 as ax, type PointerSession as ay, type PointerSessionCallbacks as az, type DepSchema as b, scratchKey as b$, type UiOngoingControl as b0, type ViewportGestureKind as b1, type WalkStep as b2, actionBindings as b3, actionItems as b4, activatesFocusedControl as b5, assembleEntries as b6, buildDepsFromRequires as b7, buildRouteRegistry as b8, buildRuleCtx as b9, isRotateHandle as bA, isSelectedBody as bB, isTool as bC, isUnselectedBody as bD, itemsFromClipboardData as bE, itemsFromDataTransfer as bF, itemsFromFiles as bG, liveScope as bH, makeToolOffhandAction as bI, matchBest as bJ, matchSorted as bK, matchSortedWithBarred as bL, matchesKeyBinding as bM, mergeContributions as bN, modeShortcutSpec as bO, modeShortcuts as bP, offhandKeyFor as bQ, openPointerSession as bR, pointerGestureId as bS, recordModeSwitch as bT, reportRouteConflicts as bU, resolveDeviceProfile as bV, resolveParams as bW, routesForSpec as bX, ruleCanHoldIn as bY, rulesExclusive as bZ, scopeBindings as b_, buildToolOffhandBindings as ba, clientToCanvas as bb, clientToCanvasRect as bc, createDepRegistry as bd, createDispatcher as be, createLongPressStore as bf, defineTool as bg, deleteScratch as bh, describeRule as bi, dlog as bj, dwarn as bk, evaluate as bl, evaluateActive as bm, evaluateEnabled as bn, findConflicts as bo, getScratch as bp, heldKeySpec as bq, historyKey as br, isAnchor as bs, isAnchorOrControl as bt, isBody as bu, isControlHandle as bv, isDebugEnabled as bw, isEditableTarget as bx, isEmpty as by, isResizeHandle as bz, type Action as c, setScratch as c0, targetConsultsAffordance as c1, validateActionDefaultBinding as c2, validateActionId as c3, DepNode as d, type AnyToolOf as e, ActiveToolContextProvider as f, ActiveToolContextProviderIfRoot as g, type ActiveToolContextProviderProps as h, type ActiveToolContextValue as i, useOptionalActiveToolContext as j, type Dispatcher as k, type AffordanceHit as l, ALWAYS as m, type ActionDeps as n, ActionDisabledReason as o, type ActionDispatch as p, type ActionEnabledResult as q, type ActionEntry as r, type ActionItem as s, type ActionPresentation as t, useActiveToolContext as u, type ActionSource as v, type ActionVariant as w, type ActionsProp as x, type AnyTool as y, type AssemblyInputs as z };
+export { DEFAULT_ALLOWED_CAPABILITIES as $, type ActionsRegistry as A, type ActionVariant as B, type Contribution as C, type DepRegistry as D, type ActionsProp as E, type AnyTool as F, type AssemblyInputs as G, type BindingOpts as H, type BindingScope as I, type BindingSource as J, type KernelOverlay as K, type LongPressOptions as L, type BodyPredicate as M, type NodeId as N, type OverlayPosition as O, type BoundGesture as P, type Bounds as Q, type RuleCtx as R, ScopeNode as S, ToolNode as T, type BuildRuleCtxArgs as U, COARSE_TARGET_SCALE as V, type Condition as W, type Conflict as X, type ContributionChrome as Y, type ContributionDeps as Z, type ContributionRouting as _, type DepName as a, type TraceLogEntry as a$, DEFAULT_DEVICE_PROFILE as a0, type DebugSink as a1, type DetectedDeviceFacts as a2, type DeviceProfile as a3, type DispatchRecord as a4, type DispatchRecordInput as a5, type DispatcherContext as a6, type DragSample as a7, type DroppedCandidate as a8, type Eligibility as a9, type Point2 as aA, type PointerSession as aB, type PointerSessionCallbacks as aC, type PointerSessionCancelReason as aD, type PointerSessionOptions as aE, type RankedCandidate as aF, type RecordCandidate as aG, type RegistryEntry as aH, type ResizeAnchor as aI, type ResolveAllOptions as aJ, type ResolveOnlyResult as aK, type ResolvedCandidate as aL, type Rule as aM, type ScopedBinding as aN, type ScratchKey as aO, type ScratchStore as aP, type SelectionApi as aQ, type Selector as aR, type SpecificityPart as aS, TOOL_OFFHAND_ID as aT, type ToolDef as aU, type ToolKeybinding as aV, type ToolModifiers as aW, type ToolOffhandBindingSpec as aX, type ToolPresentation as aY, type ToolScopes as aZ, type ToolSlot as a_, type EligibilityState as aa, type GestureBinding as ab, type HandleKind as ac, type HitShape as ad, type HotkeyTrigger as ae, INGEST_STRING_MIMES as af, type ImmediateInvoker as ag, type InvocationCtx as ah, type Invoker as ai, type KeyBinding as aj, type LongPressState as ak, type LongPressStore as al, type MatchOutcome as am, type MatchResult as an, type ModeShortcutHandlers as ao, type ModeSwitchLogEntry as ap, type ModifierState as aq, NEVER as ar, type OngoingHandle as as, type OngoingInvoker as at, type OngoingOverlay as au, type OverlayRole as av, type OverlaySchema as aw, PREDICATE_TARGET as ax, type PendingLongPress as ay, type PlacedBy as az, type DepSchema as b, ruleCanHoldIn as b$, type TunedBinding as b0, type UiOngoingControl as b1, type ViewportGestureKind as b2, type WalkStep as b3, actionBindings as b4, actionItems as b5, assembleEntries as b6, buildDepsFromRequires as b7, buildRouteRegistry as b8, buildRuleCtx as b9, isRotateHandle as bA, isSegment as bB, isSelectedBody as bC, isTool as bD, isUnselectedBody as bE, itemTypesFromDataTransfer as bF, itemsFromClipboardData as bG, itemsFromDataTransfer as bH, itemsFromFiles as bI, liveScope as bJ, makeToolOffhandAction as bK, matchBest as bL, matchSorted as bM, matchSortedWithBarred as bN, matchesKeyBinding as bO, mergeContributions as bP, modeShortcutSpec as bQ, modeShortcuts as bR, multiTouchGestureId as bS, offhandKeyFor as bT, openPointerSession as bU, pointerGestureId as bV, recordModeSwitch as bW, reportRouteConflicts as bX, resolveDeviceProfile as bY, resolveParams as bZ, routesForSpec as b_, buildToolOffhandBindings as ba, clientToCanvas as bb, clientToCanvasRect as bc, createDepRegistry as bd, createDispatcher as be, createLongPressStore as bf, defineTool as bg, deleteScratch as bh, describeRule as bi, dlog as bj, dwarn as bk, evaluate as bl, evaluateActive as bm, evaluateEnabled as bn, findConflicts as bo, getScratch as bp, heldKeySpec as bq, historyKey as br, isAnchor as bs, isAnchorOrControl as bt, isBody as bu, isControlHandle as bv, isDebugEnabled as bw, isEmpty as bx, isPathEditPart as by, isResizeHandle as bz, type Action as c, rulesExclusive as c0, scopeBindings as c1, scratchKey as c2, setScratch as c3, targetConsultsAffordance as c4, tuneAction as c5, validateActionDefaultBinding as c6, validateActionId as c7, DepNode as d, type Tool as e, ActiveToolContextProvider as f, ActiveToolContextProviderIfRoot as g, type ActiveToolContextProviderProps as h, type ActiveToolContextValue as i, useOptionalActiveToolContext as j, type Dispatcher as k, type AffordanceHit as l, ALWAYS as m, type ActionDeps as n, ActionDisabledReason as o, type ActionDispatch as p, type ActionEnabledResult as q, type ActionEntry as r, type ActionItem as s, type ActionParamSchema as t, useActiveToolContext as u, type ActionParams as v, type ActionPresentation as w, type ActionSource as x, type ActionTuning as y, type ActionTunings as z };