@weasel-js/routing 1.6.1 → 1.7.1

package/dist/{index-CKmbNpwl.d.ts → index-BV53gfyB.d.ts}

@@ -1,8 +1,8 @@
-import { CapabilityTag } from '@weasel-js/modes';
+import { CapabilityTag, ActiveMode, ModeRegistry } from '@weasel-js/modes';
 import * as react from 'react';
 import { ReactNode } from 'react';
 import { CursorSpec } from '@weasel-js/cursor';
-import { ClaimableGesture, GestureSpec, InputEvent, TargetSpec, ParsedModifiers, GestureName, IngestItem } from '@weasel-js/gestures';
+import { ClaimableGesture, GestureSpec, InputEvent, TargetSpec, KeySpec, ParsedModifiers, GestureName, IngestItem } from '@weasel-js/gestures';
 import { Op } from '@weasel-js/history';
 
 /**
@@ -126,10 +126,21 @@ type HitShape = {
     cx: number;
     cy: number;
     r: number;
+}
+/** A world-space polygon — for a region that is a turned square on screen,
+ *  which under non-uniform zoom is no rotated rect in world. */
+ | {
+    kind: 'polygon';
+    points: readonly {
+        x: number;
+        y: number;
+    }[];
 } | {
     kind: 'path';
     d: Path2D;
 };
+/** 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.
@@ -155,6 +166,16 @@ interface DebugSink {
         y: number;
     }, accepted: boolean): void;
     recordLayer(id: string, label: string, space: 'world' | 'screen', index: number): void;
+    /**
+     * A viewport change a gesture made: the view it started from, the view it
+     * produced, and the world point it held fixed — a pan's grab point, a zoom's
+     * focal point — when it had one. Survives `beginFrame`; the next record
+     * replaces it.
+     */
+    recordViewport(kind: ViewportGestureKind, from: View, to: View, anchor?: {
+        x: number;
+        y: number;
+    }): void;
     /** Clears every non-snap array. Called at the start of each Canvas render. */
     beginFrame(): void;
     /** Clears the snap array. Called at gesture end. */
@@ -382,6 +403,24 @@ interface Condition {
     orNot(other: Condition | Rule): Condition;
 }
 
+/**
+ * Whether two rules can never hold at once — no `RuleCtx` passes both.
+ *
+ * Conservative: `true` is a proof, `false` means "may overlap". It reasons
+ * about the selector values themselves (two different `mode`s, an empty
+ * selection against a non-empty one, `focused: true` against `false`) and
+ * through `all` / `any` / `not`; a `when` closure is opaque, so it overlaps
+ * everything. The route-conflict check uses it to stay quiet about bindings
+ * that share a tuple but are never eligible together.
+ */
+declare function rulesExclusive(a: Rule, b: Rule): boolean;
+/**
+ * Whether `rule` can hold while `mode` is active. Only its `mode` and
+ * `capability` tests are settled by the mode; every other test could go either
+ * way, so `false` is a proof and `true` means "may hold".
+ */
+declare function ruleCanHoldIn(rule: Rule, mode: ActiveMode): boolean;
+
 /** The detected half of a profile — everything except the derived scale. */
 type DetectedDeviceFacts = Omit<DeviceProfile, 'targetScale'>;
 /**
@@ -1079,7 +1118,7 @@ interface ActionDispatch extends BindingSource {
      * gesture.
      *
      * This is where mid-gesture cursors live now. They used to come from the
-     * tool side — `ViewportToolDef.engaged.cursor` for a phase-gated string,
+     * 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
@@ -1150,6 +1189,65 @@ interface ActionEnabledResult {
  */
 declare function evaluateEnabled(action: Action, deps?: ActionDeps): ActionEnabledResult;
 
+/**
+ * The tree both input registries hang on. A provider is a root; every canvas
+ * mounts a scope under the registry in scope; a yoke sits between the two. A
+ * 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.
+ *
+ * Design: docs/proposals/2026-09-27-input-scopes.md.
+ */
+/** What every node of one tree shares: a version and the listeners to it. */
+interface ScopeTree {
+    version: number;
+    readonly listeners: Set<() => void>;
+}
+declare class ScopeNode<N extends ScopeNode<N>> {
+    readonly parent: N | null;
+    readonly descends: boolean;
+    readonly tree: ScopeTree;
+    private readonly children;
+    private activeChild;
+    /** `descends`: whether reads made here answer from the active child down —
+     *  true for a root or a yoke, which chrome reads through; false for a scope,
+     *  which answers for itself even with a scope nested inside it. */
+    constructor(parent: N | null, descends: boolean);
+    /** Bump the tree's version and tell every listener in it. */
+    changed(): void;
+    /** Join the parent's children, newest last; returns the leave. */
+    mount(): () => void;
+    /** Make this node the one its ancestors resolve through. */
+    activate(): void;
+    /** The node a lookup made here starts from: down the active children, or the
+     *  newest where nothing has been activated yet. A yoke with no members yet
+     *  is passed over — there is no canvas behind it to answer. */
+    leaf(): N;
+    private newestMember;
+    /** Where a read made through this node starts. */
+    start(): N;
+    /** Whether this node is on the path a read from the root takes. */
+    isActive(): boolean;
+    /** This node, then each ancestor up to the root. */
+    chain(): Generator<N>;
+}
+
+/**
+ * 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.
+ */
+
 /** Holds the live sources an action's declared dependencies resolve to.
  *  Sources are thunks, read at invocation time, so an action never captures
  *  stale state. */
@@ -1157,23 +1255,20 @@ interface DepRegistry {
     register<K extends DepName>(name: K, source: () => DepSchema[K]): () => void;
     get<K extends DepName>(name: K): DepSchema[K] | undefined;
 }
-/** Provides the dep registry for a canvas. `<SceneCanvas>` mounts one; a
- *  consumer registering its own dep sources must be inside it. */
-declare function DepRegistryProvider({ children }: {
-    children: ReactNode;
-}): react.JSX.Element;
-/** The dep registry in scope. Throws outside a `<DepRegistryProvider>`. */
-declare function useDepRegistry(): DepRegistry;
-/**
- * Like `useDepRegistry`, but returns `null` when no `<DepRegistryProvider>` is
- * in scope instead of throwing. Used by `useStandardActions` to preserve its
- * silent-no-op contract when neither provider is present.
- */
-declare function useOptionalDepRegistry(): DepRegistry | null;
-/** Register a live source for `name` for the lifetime of the calling
- *  component. The `source` thunk is called at dispatch time and should
- *  return the latest value. */
-declare function useDepSource<K extends DepName>(name: K, source: () => DepSchema[K]): void;
+/** One node of the dep tree: the sources registered at it, over its parent's.
+ *  Each name holds a stack of sources, newest live, so a displaced source is
+ *  restored when the one above it leaves. */
+declare class DepNode extends ScopeNode<DepNode> {
+    private readonly sources;
+    readonly registry: DepRegistry;
+    constructor(parent: DepNode | null, descends: boolean);
+}
+/**
+ * A stock dep registry with no parent: what `<DepRegistryProvider>` mounts,
+ * for a dispatcher driven without React. Sources registered under one name
+ * stack, newest live, and releasing one restores the one beneath it.
+ */
+declare function createDepRegistry(): DepRegistry;
 
 /**
  * Shared dep-bag builder — the single implementation behind both the gesture
@@ -1187,9 +1282,13 @@ declare function useDepSource<K extends DepName>(name: K, source: () => DepSchem
 declare function buildDepsFromRequires(action: Action, depRegistry: DepRegistry): ActionDeps;
 
 /** Hotkey-slot trigger key. The slot is engaged while this key is held —
- *  hence "hotkey": active as long as the key is hot. `null` (or omitted)
- *  means the tool is not eligible for the hotkey slot. */
-type HotkeyTrigger = 'space' | 'alt' | 'ctrl' | 'meta' | 'shift';
+ *  hence "hotkey": active as long as the key is hot. Omitted means the tool
+ *  is not eligible for the hotkey slot.
+ *
+ *  The named keys map to their DOM names (`'space'` is `' '`, `'ctrl'` is
+ *  `'Control'`). Anything else is a `KeyboardEvent.key` value, matched
+ *  case-insensitively as every key spec is — so `'o'` holds on O. */
+type HotkeyTrigger = 'space' | 'alt' | 'ctrl' | 'meta' | 'shift' | (string & {});
 /** Presentation metadata for tool palettes / menus. Optional on every
  *  tool — consumers that render a palette (`<ToolPalette>`) read these
  *  fields to display the tool; consumers that don't can ignore them.
@@ -1209,6 +1308,10 @@ interface ToolPresentation<TScratch = unknown> {
     /** Display override for the keyboard shortcut. When omitted the palette
      *  derives one from `Tool.keybinding` via its own formatter. */
     shortcut?: string;
+    /** Keep the tool off palettes — for a tool that is only ever held, like a
+     *  scrub engaged by its `hotkey`. It stays registered and selectable by
+     *  id; only the palette leaves it out. */
+    hide?: boolean;
 }
 /**
  * When an entry's bindings are live. A set, not one value: the hand tool is
@@ -1255,7 +1358,7 @@ interface ContributionRouting {
  * What an entry draws and how a palette shows it. None of it reaches the
  * dispatcher.
  */
-interface ContributionChrome<TOverlay = unknown> {
+interface ContributionChrome<TOverlay = KernelOverlay> {
     /** One layer, or several composed in the given order.
      *
      *  Routing never reads a layer — it collects the live ones and hands them
@@ -1271,117 +1374,11 @@ interface ContributionChrome<TOverlay = unknown> {
  * is optional and independent — an entry that only routes input declares only
  * `bindings` and `actions`.
  */
-interface Contribution<TOverlay = unknown> extends ContributionRouting, ContributionChrome<TOverlay> {
+interface Contribution<TOverlay = KernelOverlay> extends ContributionRouting, ContributionChrome<TOverlay> {
     /** Reflection escape hatch — the authored form, when there was one. */
     def?: unknown;
 }
 
-/**
- * Configurable activation-key descriptor for tools that expose their
- * keybinding to the host (currently Lasso and Eyedropper). Captures
- * only the fields meaningful to a caller-supplied tool-select key —
- * dispatcher-internal fields (`skipInEditable`, `enabled`,
- * `preventDefault`) live on `KeyBinding` in keyHelpers.ts and are
- * not part of the configurable surface.
- */
-interface ToolKeybinding {
-    /** Key or list of keys to match (case-insensitive against `event.key`). */
-    key: string | readonly string[];
-    /** Require Cmd (mac) / Ctrl (others). Default `false`. */
-    mod?: boolean;
-    /** Require Alt. Default `false`. */
-    alt?: boolean;
-    /**
-     * Shift policy. `undefined`/`false` forbids shift, `true` requires
-     * shift, `'optional'` allows either.
-     */
-    shift?: boolean | 'optional';
-}
-/** Modifier-key snapshot at event dispatch time. */
-type ToolModifiers = ModifierState;
-/** Per-event context passed to every channel handler. `scratch` is typed
- *  via the tool's `TScratch` parameter; it survives across a single
- *  gesture (pointer-down through end/cancel) and is replaced on next
- *  gesture start by `initScratch()`. */
-interface ToolCtx<TScratch = unknown> {
-    worldX: number;
-    worldY: number;
-    modifiers: ToolModifiers;
-    selection: SelectionApi;
-    /** Adapter/scene access — opaque at this layer; tools that need it
-     *  cast to a known shape. This layer doesn't constrain it. */
-    adapter: unknown;
-    applyOps: (ops: Op[], label: string) => void;
-    /** Current viewport. Reflects camera-position semantics — see
-     *  `View` JSDoc. */
-    view: View;
-    /** Mutate the viewport. In controlled mode this calls the consumer's
-     *  `onViewChange`; in uncontrolled mode it updates Canvas's internal
-     *  state. View changes are not undoable. */
-    setView: (next: View) => void;
-    /** Bounding rect of the canvas element in viewport coords. Used by
-     *  zoom/pan tools to convert event clientX/clientY to canvas-relative
-     *  anchors. */
-    canvasRect: DOMRect;
-    /** Optional debug sink. When `<Canvas debug={...}>` is enabled, Canvas
-     *  threads its sink here so tool-internal hit math (handle hitboxes,
-     *  rotation handle, etc.) lands in the same overlay as Canvas's own
-     *  bounds/origin records. Tools should call this conditionally with `?.`. */
-    debug?: DebugSink;
-    scratch: TScratch;
-}
-/** World-space AABB shape used by `previewBounds`. Alias of the kit-wide
- *  `Bounds` type — the optional `rotation` field carries through so a tool
- *  can report an oriented preview rect (e.g. mid-rotate). */
-type ToolBounds = Bounds;
-/**
- * The focus-declaring case of a `Contribution`: a mode the user switches
- * into, plus the hooks that only make sense for one (`initScratch`,
- * activate/deactivate, live preview, `cursor`). Everything else — bindings,
- * actions, overlay, presentation — is inherited.
- */
-interface Tool<TScratch = unknown, TOverlay = unknown> extends Contribution<TOverlay> {
-    /** Optional caller-supplied key. Most built-in tools have their activation
-     *  key declared in `BUILTIN_SELECT_KEYS` in `useKeybindings.ts`; this field
-     *  is for tools that want their activation key to be configurable by the
-     *  host (currently Lasso and Eyedropper). The dynamic loop in
-     *  `useKeybindings.ts` picks this up and appends a binding entry to the
-     *  consolidated `tool.activate` action (with `opts.params.toolId` set so
-     *  the invoker knows which tool to switch to). */
-    keybinding?: ToolKeybinding;
-    initScratch?: () => TScratch;
-    cursor?: CursorSpec | ((ctx: ToolCtx<TScratch>) => CursorSpec);
-    onActivate?: (ctx: ToolCtx<TScratch>) => void;
-    onDeactivate?: (ctx: ToolCtx<TScratch>) => void;
-    /** Returns the in-flight preview pose for `id` if this tool is mid-gesture
-     *  on it; otherwise `null`. Lets `Canvas.helpersRef.getEffectivePose`
-     *  reflect live gesture state without reaching into hook internals. The
-     *  return type is `unknown` here because the Tool interface is pose-agnostic;
-     *  callers that know the pose shape (e.g. Canvas typed by `TPose`) cast at
-     *  the use site. */
-    previewPose?: (id: string) => unknown;
-    /** Returns the in-flight preview bounds for `id` if this tool is mid-gesture
-     *  on it; otherwise `null`. Optional companion to `previewPose` for tools that
-     *  can compute bounds without round-tripping through a geometry adapter. */
-    previewBounds?: (id: string) => ToolBounds | null;
-    /** Returns ids whose committed scene-render should be suppressed while this
-     *  tool is mid-gesture (e.g. cascade move's dragged + descendant ids whose
-     *  preview ghosts replace the committed pose). The standard scene slot
-     *  consults this alongside `previewPose` to avoid double-rendering. Returns
-     *  `null` when no gesture is in flight. */
-    previewIds?: () => Iterable<string> | null;
-}
-/** Internal — which slot a tool occupies in the dispatch order. */
-type ToolSlot = 'hotkey' | 'active' | 'ambient';
-/** Internal alias for "a Tool of any scratch type" — used in registries and
- *  dispatchers that hold tools of heterogeneous scratch shapes. `any` is
- *  intentional: `Tool<TScratch>` is invariant in TScratch, so `Tool<unknown>`
- *  is too strict for containers that accept any concrete `Tool<T>`. */
-type AnyTool = Tool<any, any>;
-/** "A tool of any scratch type that draws `TOverlay`" — the container form for
- *  registries that hold heterogeneous scratch shapes but one overlay type. */
-type AnyToolOf<TOverlay> = Tool<any, TOverlay>;
-
 /**
  * Pure matcher primitives live in `@weasel-js/gestures`. This file
  * re-exports them for kit-internal consumers and layers the actions-layer
@@ -1396,18 +1393,18 @@ type BindingScope = 'ambient' | 'active' | 'hotkey';
 interface ScopedBinding {
     binding: GestureBinding;
     scope: BindingScope;
-    /** Tool id that owns this binding — `'&'`-channel phase atoms resolve
-     *  to this. `null` for ambient bindings that came from a registered
-     *  Action with no owning tool. */
-    ownerToolId: string | null;
+    /** Id of the tool or contribution that declared this binding —
+     *  `'&'`-channel phase atoms resolve to it. `null` for a registered
+     *  action's own binding. */
+    ownerId: string | null;
 }
 /** The binding that won a match. */
 interface MatchResult {
     binding: GestureBinding;
     scope: BindingScope;
-    /** Tool id that owns the binding — propagated from `ScopedBinding`
-     *  so the dispatcher can record it as the handle owner. */
-    ownerToolId: string | null;
+    /** Id of the entry that declared the binding — propagated from
+     *  `ScopedBinding` so the dispatcher can record it as the handle owner. */
+    ownerId: string | null;
 }
 /**
  * True when a spec's target actually consults the affordance hit rather than
@@ -1422,19 +1419,6 @@ interface MatchResult {
  * that declare nothing.
  */
 declare function targetConsultsAffordance(specTarget: TargetSpec | undefined): boolean;
-/** CSS-style specificity tuple for a GestureSpec. Higher tuple wins under
- *  lexicographic compare. Dimensions, in order of precedence:
- *
- *    [0] target — how much the spec's target narrows; see `targetRank`.
- *    [1] mods   — count of required modifier keys (shift/alt/ctrl/meta/mod).
- *                 `'optional'` does NOT count.
- *    [2] phase  — how much the spec's `phase` narrows; see `phaseRank`.
- *    [3] exact  — per-kind tiebreak: 2 for a drop/paste spec with a
- *                 non-empty `types` MIME filter, else 1.
- *
- *  Identical tuples fall back to registration order in the matcher's
- *  stable sort, preserving the pre-specificity tiebreaker. */
-declare function specificity(spec: GestureSpec): readonly [number, number, number, number];
 /**
  * Find the best-matching binding across all scopes.
  *
@@ -1463,6 +1447,172 @@ declare function matchBest(e: InputEvent, bindings: readonly ScopedBinding[], is
  * action's `start()` returns an empty handle), the next match is tried.
  */
 declare function matchSorted(e: InputEvent, bindings: readonly ScopedBinding[], isMac: boolean, engagedChannels?: ReadonlySet<string>, warn?: (message: string) => void): MatchResult[];
+/** {@link matchSorted}, plus what an exclusive claim on the event barred. */
+interface MatchOutcome {
+    matches: MatchResult[];
+    /** Bindings whose spec matched the event but which the claim barred, in
+     *  the same order `matches` uses. Filled only when `collectBarred` is set. */
+    barred: MatchResult[];
+    /** Owner of the exclusive claim, when one applied. */
+    claimOwner?: string;
+}
+/**
+ * {@link matchSorted} that can also report the bindings an exclusive claim
+ * kept out. Collecting them costs a spec match per barred binding, so it is
+ * opt-in — the dispatcher asks only when it is recording.
+ */
+declare function matchSortedWithBarred(e: InputEvent, bindings: readonly ScopedBinding[], isMac: boolean, engagedChannels?: ReadonlySet<string>, opts?: {
+    collectBarred?: boolean;
+    warn?: (message: string) => void;
+}): MatchOutcome;
+
+/**
+ * How one input was resolved: every binding that matched it, what each filter
+ * dropped, the order the rest were ranked in and why, and what the walk down
+ * that order did. The dispatcher fills one per input in dev builds, and
+ * `Dispatcher.explain` fills one on request without invoking anything.
+ *
+ * Plain data — no functions, no live objects — so it can be kept in a trace
+ * buffer, serialized, or built by hand as a fixture.
+ */
+interface DispatchRecord {
+    kind: 'dispatch';
+    ts: number;
+    input: DispatchRecordInput;
+    /** Every binding whose spec matched the input, in matcher order, including
+     *  those a filter then dropped. */
+    matched: readonly RecordCandidate[];
+    dropped: readonly DroppedCandidate[];
+    /** The candidates that survived both filters, best first. */
+    ranked: readonly RankedCandidate[];
+    /** True when nothing was invoked: the record answers "what would happen". */
+    predicted: boolean;
+    /** Action id of the candidate that fired (or would), else `null`. */
+    fired: string | null;
+    outcome: 'handled' | 'unhandled';
+}
+/** The input a {@link DispatchRecord} describes, reduced to plain data. */
+interface DispatchRecordInput {
+    /** `InputEvent.kind`: `'key'`, `'pointerdown'`, `'wheel'`, … */
+    eventKind: string;
+    /** For `key` / `key-held` events, the key id (`'Escape'`, `' '`, `'a'`). */
+    key?: string;
+    modifiers: {
+        alt: boolean;
+        ctrl: boolean;
+        meta: boolean;
+        shift: boolean;
+    };
+    /** The view the input was routed to; `null` for the surface's own camera. */
+    viewId: string | null;
+    /** World point, for events that carry one. */
+    world?: {
+        x: number;
+        y: number;
+    };
+    /** Active mode id, when the host supplies a rule context. */
+    mode?: string;
+}
+/** One matched binding. */
+interface RecordCandidate {
+    actionId: string;
+    /** The binding's spec in route grammar — one per arg alternative. */
+    routes: readonly string[];
+    scope: BindingScope;
+    /** The tool or contribution that declared the binding; `null` for an action's own binding. */
+    ownerId: string | null;
+    /** Whether the binding's `views` names the routed view. */
+    namesView: boolean;
+    /** `specificity(spec)`: target, modifiers, phase, exact. */
+    specificity: readonly [number, number, number, number];
+    /** The action's `eligible` rule as text, when it declares one. */
+    eligible?: string;
+}
+/** A matched candidate a filter removed before ranking, and which filter. */
+type DroppedCandidate = 
+/** An exclusive claim on the input barred bindings that do not read the
+ *  claim's affordance. */
+{
+    candidate: RecordCandidate;
+    filter: 'claim';
+    owner?: string;
+}
+/** The action's `eligible` rule does not hold. */
+ | {
+    candidate: RecordCandidate;
+    filter: 'ineligible';
+    rule: string;
+};
+/** One field of the `specificity` tuple, in the order it is compared. */
+type SpecificityPart = 'target' | 'mods' | 'phase' | 'exact';
+/** The ranking step that put a candidate below the one before it. */
+type PlacedBy = {
+    step: 'first';
+}
+/** The one above names the routed view; this one does not. */
+ | {
+    step: 'view';
+}
+/** The one above sits in a higher scope tier. */
+ | {
+    step: 'tier';
+}
+/** Same tier; the one above is more specific in `part`. */
+ | {
+    step: 'specificity';
+    part: SpecificityPart;
+}
+/** Tied; the one above is gated by an `eligible` rule that holds. */
+ | {
+    step: 'context';
+}
+/** Tied on everything; registration order. */
+ | {
+    step: 'order';
+};
+/** What the walk did with one ranked candidate. */
+type WalkStep = {
+    kind: 'fired';
+}
+/** Predicted records only: this candidate would fire. Nothing was started,
+ *  so an ongoing action here may still bail at `start()` for real. */
+ | {
+    kind: 'would-fire';
+}
+/** `enabled()` returned this reason. */
+ | {
+    kind: 'declined';
+    reason: string;
+}
+/** An ongoing action's `start()` returned an empty handle. */
+ | {
+    kind: 'empty-handle';
+}
+/** An ongoing action bound to a press-time `pointerDown` spec; refused. */
+ | {
+    kind: 'misbound';
+}
+/** Its action was already tried higher up; each runs at most once. */
+ | {
+    kind: 'duplicate';
+} | {
+    kind: 'no-such-action';
+}
+/** Below the winner; never asked. */
+ | {
+    kind: 'not-asked';
+}
+/** Below the winner, asked anyway (`evaluateShadowed`), and it passed. */
+ | {
+    kind: 'outranked';
+};
+/** A candidate that survived the filters: why it sits where it does, and
+ *  what the walk did with it. */
+interface RankedCandidate {
+    candidate: RecordCandidate;
+    placedBy: PlacedBy;
+    walk: WalkStep;
+}
 
 /**
  * Dispatcher orchestrator — pure module, no React, no DOM.
@@ -1472,10 +1622,19 @@ declare function matchSorted(e: InputEvent, bindings: readonly ScopedBinding[],
  * on `enabled()`; then invokes `immediate` or `ongoing` invokers and tracks
  * in-flight handles.
  *
- * ## Specificity-ordered fall-through
- * `matchSorted` returns every matching binding in precedence order
- * (hotkey > active > ambient, first-declared within scope). The dispatcher
- * walks that list and fires the first action whose `enabled()` returns
+ * ## Precedence and fall-through
+ * An exclusive affordance claim first bars every binding that does not
+ * consult the affordance. The rest are ranked, best first, by:
+ *   1. bindings naming the routed view ahead of every other
+ *      (`preferViewScoped`);
+ *   2. scope tier: hotkey > active > ambient;
+ *   3. specificity within a tier (`specificity()` in `matcher.ts`);
+ *   4. an action gated by an `eligible` rule that holds now ahead of one with
+ *      no rule (`preferContextual`) — Escape while editing a path exits the
+ *      edit rather than resetting the tool;
+ *   5. registration order.
+ * 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
@@ -1515,23 +1674,6 @@ declare function matchSorted(e: InputEvent, bindings: readonly ScopedBinding[],
  *   synthesized event with no originating DOM pointer.
  */
 declare function pointerGestureId(pointerId: number | undefined): string;
-/** One entry per `handleInput` call. */
-interface DispatchLogEntry {
-    kind: 'dispatch';
-    ts: number;
-    eventKind: string;
-    /** For `key` / `key-held` events, the key id (`'Escape'`, `' '`, `'a'`).
-     *  Lives on the event side of the entry — `fired` should describe
-     *  what dispatched, not which key triggered it. */
-    key?: string;
-    candidates: Array<{
-        actionId: string;
-        scope: BindingScope;
-        enabledResult: boolean | string;
-    }>;
-    fired: string | null;
-    outcome: 'handled' | 'unhandled';
-}
 /** One entry per "mode change" — a kit state transition that isn't a
  *  dispatched input event but is load-bearing for understanding why an
  *  input was (or wasn't) handled later. Pushed via `recordModeSwitch()`;
@@ -1548,7 +1690,8 @@ interface ModeSwitchLogEntry {
      *  `'selection-dropped target'`, etc. */
     detail?: string;
 }
-type TraceLogEntry = DispatchLogEntry | ModeSwitchLogEntry;
+/** A trace entry: one {@link DispatchRecord} per resolved input, or a mode switch. */
+type TraceLogEntry = DispatchRecord | ModeSwitchLogEntry;
 /** Push a mode-switch record into the trace log. Safe to call from
  *  anywhere; no-ops outside DEV. */
 declare function recordModeSwitch(mode: string, from: string | null, to: string | null, detail?: string): void;
@@ -1562,12 +1705,12 @@ interface DispatcherContext {
     actions: ActionSource;
     /** Dep sources keyed by name. */
     depRegistry: DepRegistry;
-    /** Active tool's id (from ActiveToolContext). */
-    activeToolId: string;
+    /** Active tool's id (from ActiveToolContext); `null` when none is. */
+    activeToolId: string | null;
     /** Held-hotkey stack, top of stack last. */
     hotkeyStack: readonly string[];
-    /** Lookup for tool definitions. */
-    toolsById: ReadonlyMap<string, Tool>;
+    /** Every registered entry, tools and ambient contributions alike, by id. */
+    entriesById: ReadonlyMap<string, Contribution<unknown>>;
     /** Platform flag for `mod` shorthand resolution. */
     isMac: boolean;
     /**
@@ -1587,18 +1730,6 @@ interface DispatcherContext {
      */
     viewId?: string | null;
 }
-/**
- * Filter `matches` to only those whose backing action has no `eligible`
- * rule, or whose rule evaluates true against `ruleCtx`. Exported for
- * unit testing.
- *
- * @internal
- */
-declare function filterEligible<M extends {
-    binding: {
-        actionId: string;
-    };
-}>(matches: readonly M[], actionLookup: (id: string) => Action | undefined, ruleCtx: RuleCtx): M[];
 /**
  * Handle returned by `Dispatcher.beginUiOngoing()` for driving an
  * ongoing invoker from a UI control (color picker, slider).
@@ -1624,7 +1755,7 @@ interface ResolveOnlyResult {
     action: Action;
     scope: BindingScope;
     /** Tool id owning the winning binding; `null` for ambient action bindings. */
-    ownerToolId: string | null;
+    ownerId: string | null;
 }
 /**
  * One candidate from `Dispatcher.resolveAll` — a binding that matched the
@@ -1648,7 +1779,7 @@ interface ResolvedCandidate {
     action: Action;
     binding: GestureBinding;
     scope: BindingScope;
-    ownerToolId: string | null;
+    ownerId: string | null;
     /** The tuple from `specificity(binding.spec)`, surfaced so a reader can see
      *  why one candidate outranks another rather than inferring it. */
     specificity: readonly [number, number, number, number];
@@ -1736,6 +1867,14 @@ interface Dispatcher {
      * {@link ResolveAllOptions.evaluateShadowed}.
      */
     resolveAll(event: InputEvent, ctx: DispatcherContext, opts?: ResolveAllOptions): ResolvedCandidate[];
+    /**
+     * The full {@link DispatchRecord} for `event` — what matched, what each
+     * filter dropped, how the rest ranked and why, and the walk — without
+     * invoking anything, so `predicted` is true and the winner is `would-fire`.
+     * It is the same computation `handleInput` and `resolveAll` run. Costs more
+     * than `resolveOnly`: it renders every candidate's routes and rule.
+     */
+    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).
@@ -1856,10 +1995,9 @@ interface ActionsRegistry {
     /** Drop every registrant of `id`. This is the "this action should not exist"
      *  door, not a release — for that, call what `register` returned. */
     unregister(id: string): void;
-    /** Declare `id` not for this scope: it stays registered, and every other
-     *  scope over the same store still resolves it, but here it lists as absent
-     *  and neither `trigger` nor `begin` will fire it. Returns a release; an
-     *  `<ActionsScope>` drops what it muted when it unmounts. This is the
+    /** Declare `id` not for this scope: it stays registered wherever it was,
+     *  but here — and in scopes below — it lists as absent and neither
+     *  `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;
     list(): readonly Action[];
@@ -1888,18 +2026,16 @@ interface ActionsRegistry {
      */
     begin(id: string, params?: Record<string, unknown>): UiOngoingControl | null;
     /** Wire a dispatcher into the registry so `begin()` can delegate to it.
-     *  Returns a release that clears the slot only while this dispatcher still
-     *  holds it: a canvas displaced by a later one must not take input away from
-     *  the canvas now on screen. Call with `null` to detach unconditionally. */
+     *  Returns a release that takes out only this dispatcher; a `null` wires
+     *  nothing. */
     setDispatcher(d: Dispatcher | null): () => void;
-    /** Wire a `DepRegistry` into the registry so `trigger()` / `begin()` can
-     *  resolve action deps even when this provider is mounted ABOVE the dep
-     *  registry (e.g. a consumer's root `<ActionsProvider>` reused by
-     *  SceneCanvas's `ActionsProviderIfRoot`). Takes precedence over the dep
-     *  registry read from context at the provider's own level. Call with
-     *  `null` to detach unconditionally; the returned release clears the slot
-     *  only while this registry still holds it. */
-    setDepRegistry(r: DepRegistry | null): () => void;
+    /** Make this registry's scope the one chrome above it reaches: `trigger`,
+     *  `begin` and `list` on any ancestor then answer from here. A dispatcher
+     *  calls it on the pointerdown and focus that land in its scope. */
+    activate(): void;
+    /** Whether a lookup made from the root of this registry's tree starts here —
+     *  the question a dispatcher asks before handling a keystroke. */
+    isActive(): boolean;
 }
 /** Validate that `id` is usable as an action id in the route grammar.
  *  Rejects ids that start with a reserved sigil (would shadow future
@@ -1922,8 +2058,8 @@ interface ToolOffhandBindingSpec {
     toolId: string;
     key: string | string[];
 }
-/** `KeyboardEvent.key` for a declared `Eligibility.offhand` trigger. Only
- *  `space` is exercised today; the modifier arms follow the DOM's names. */
+/** `KeyboardEvent.key` for a declared `Eligibility.offhand` trigger. The
+ *  named keys become their DOM names; any other trigger already is one. */
 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
@@ -1974,6 +2110,85 @@ declare const isControlHandle: (target: unknown) => boolean;
 /** Any of the three anchor-editing affordances (anchor + both controls). */
 declare const isAnchorOrControl: (target: unknown) => boolean;
 
+/**
+ * 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;
+    /** Long-press is synthesized for these two only; a mouse never arms one. */
+    pointerType: 'touch' | 'pen';
+    /** Where the press landed, in client coordinates. */
+    client: {
+        x: number;
+        y: number;
+    };
+    /** The same point in CSS pixels from the canvas element's top-left — what a
+     *  `space: 'screen'` layer draws in. */
+    local: {
+        x: number;
+        y: number;
+    };
+    /** The same point in the routed view's world coordinates. */
+    world: {
+        x: number;
+        y: number;
+    };
+    /** The view the press routed to; `null` is the root view. */
+    viewId: string | null;
+    /** `performance.now()` when the hold started. */
+    startedAt: number;
+    /** How long the hold must last before the long-press fires, in ms. */
+    duration: number;
+    /**
+     * Whether holding to the end would fire anything — a `longPress` binding,
+     * or a `contextMenu` binding through the fallback. Resolved at press time.
+     * Feedback shows only when this is true: a press that will do nothing must
+     * not promise that it will.
+     */
+    armed: boolean;
+}
+/** Read side of the pending long-press. Published as the `longPress` dep. */
+interface LongPressState {
+    /** The press being held, or `null` when none is. Cleared when the
+     *  long-press fires, and when movement, release, cancel or a second
+     *  pointer abandons it. */
+    get(): PendingLongPress | null;
+    /** How far through the hold the pending press is, 0→1, at `now`
+     *  (`performance.now()` by default). 0 when nothing is pending. */
+    progress(now?: number): number;
+    /** Called whenever {@link get} changes. Progress is derived from the
+     *  clock, so it does not notify — a loop drawing it asks for frames. */
+    subscribe(fn: () => void): () => void;
+}
+/** The dispatcher's writable half of {@link 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}. */
+    duration?: number;
+    /**
+     * Where the press being held is published: position, start time, progress,
+     * and whether any binding would fire on it. `<SceneCanvas>` passes one and
+     * republishes it as the `longPress` dep, which its default press ring
+     * reads. Omit it and nothing is published.
+     */
+    state?: LongPressStore;
+    /**
+     * Default true. A long-press some binding handled pulses `navigator.vibrate`
+     * briefly, for touch and pen pointers, where the API exists.
+     */
+    haptics?: boolean;
+}
+declare function createLongPressStore(): LongPressStore;
+
 /**
  * The DOM half of a drag: one pointer, held down, from press to release.
  *
@@ -1993,6 +2208,7 @@ type PointerSessionCancelReason =
  | 'aborted'
 /** A new press arrived on this pointer, so the tracked one had ended. */
  | 'superseded';
+/** What {@link openPointerSession} reports. Exactly one of `onEnd` / `onCancel` fires when the session ends. */
 interface PointerSessionCallbacks {
     /** Every move belonging to this pointer, while it is still held. */
     onMove?: (e: PointerEvent) => void;
@@ -2001,13 +2217,16 @@ interface PointerSessionCallbacks {
     /** The session ended without a release. Fires once. */
     onCancel?: (reason: PointerSessionCancelReason) => void;
 }
+/** Options for {@link openPointerSession}. */
 interface PointerSessionOptions {
     /** Ask the origin element to capture the pointer. Default `true`. Capture
      *  keeps hover and click off everything the drag passes over; the session
      *  does not depend on it to keep receiving events. */
     capture?: boolean;
 }
+/** A live drag opened by {@link openPointerSession}. */
 interface PointerSession {
+    /** The pointer this session follows, taken from the press. */
     readonly pointerId: number;
     /** False once the session has ended, by any route. */
     readonly active: boolean;
@@ -2051,7 +2270,7 @@ declare function liveScope(id: string, eligibility: Eligibility, state: Eligibil
  * breaks ties by declaration order, so the caller's entry order decides which
  * of two same-specificity bindings in one tier wins.
  */
-declare function scopeBindings(entries: Iterable<Contribution>, state: EligibilityState): ScopedBinding[];
+declare function scopeBindings(entries: Iterable<Contribution<unknown>>, state: EligibilityState): ScopedBinding[];
 
 /**
  * Concatenate contribution bundles into one registry, preserving order —
@@ -2064,6 +2283,165 @@ declare function scopeBindings(entries: Iterable<Contribution>, state: Eligibili
  */
 declare function mergeContributions<T extends Contribution<unknown>>(...bundles: readonly (readonly T[])[]): T[];
 
+/**
+ * What each mode shortcut does. A role left out binds nothing, so its key
+ * falls through to whatever else the dispatcher has on it.
+ */
+interface ModeShortcutHandlers {
+    /** Enter mode `id` — the `entry` shortcut. */
+    enter?: (id: string) => void;
+    /** Whether mode `id` can be entered now. A mode that needs a target it
+     *  doesn't have answers no, and its entry key falls through. Default yes. */
+    canEnter?: (id: string) => boolean;
+    /** Leave the active soft mode, keeping its session to resume. */
+    exit?: () => void;
+    /** Leave the active soft mode and throw its session away. */
+    discard?: () => void;
+    /** Commit the active strict mode's transaction. */
+    commit?: () => void;
+    /** Abandon the active strict mode's transaction. */
+    cancel?: () => void;
+}
+/**
+ * A `ModeDefinition` shortcut chord — `'Escape'`, `'Meta+T'` — as a key spec.
+ * Modifier names are case-insensitive; the last segment is the key.
+ */
+declare function modeShortcutSpec(shortcut: string): KeySpec;
+/**
+ * The registry's declared mode shortcuts as an always-on contribution: one
+ * action per shortcut, bound to its chord and gated on the mode it acts on —
+ * `exit` / `discard` / `commit` / `cancel` while that mode is active, `entry`
+ * while it is not. Install it with `<SceneCanvas ambient>`.
+ *
+ * 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
+ * typed into an editable element never reach them.
+ */
+declare function modeShortcuts(registry: ModeRegistry, handlers: ModeShortcutHandlers): Contribution<never>;
+
+/**
+ * Configurable activation-key descriptor for tools that expose their
+ * keybinding to the host (currently Lasso and Eyedropper). Captures
+ * only the fields meaningful to a caller-supplied tool-select key —
+ * dispatcher-internal fields (`skipInEditable`, `enabled`,
+ * `preventDefault`) live on `KeyBinding` in keyHelpers.ts and are
+ * not part of the configurable surface.
+ */
+interface ToolKeybinding {
+    /** Key or list of keys to match (case-insensitive against `event.key`). */
+    key: string | readonly string[];
+    /** Require Cmd (mac) / Ctrl (others). Default `false`. */
+    mod?: boolean;
+    /** Require Alt. Default `false`. */
+    alt?: boolean;
+    /**
+     * Shift policy. `undefined`/`false` forbids shift, `true` requires
+     * shift, `'optional'` allows either.
+     */
+    shift?: boolean | 'optional';
+}
+/** Modifier-key snapshot at event dispatch time. */
+type ToolModifiers = ModifierState;
+/** Per-event context passed to every channel handler. `scratch` is typed
+ *  via the tool's `TScratch` parameter; it survives across a single
+ *  gesture (pointer-down through end/cancel) and is replaced on next
+ *  gesture start by `initScratch()`. */
+interface ToolCtx<TScratch = unknown> {
+    worldX: number;
+    worldY: number;
+    modifiers: ToolModifiers;
+    selection: SelectionApi;
+    /** Adapter/scene access — opaque at this layer; tools that need it
+     *  cast to a known shape. This layer doesn't constrain it. */
+    adapter: unknown;
+    applyOps: (ops: Op[], label: string) => void;
+    /** Current viewport. Reflects camera-position semantics — see
+     *  `View` JSDoc. */
+    view: View;
+    /** Mutate the viewport. In controlled mode this calls the consumer's
+     *  `onViewChange`; in uncontrolled mode it updates Canvas's internal
+     *  state. View changes are not undoable. */
+    setView: (next: View) => void;
+    /** Bounding rect of the canvas element in viewport coords. Used by
+     *  zoom/pan tools to convert event clientX/clientY to canvas-relative
+     *  anchors. */
+    canvasRect: DOMRect;
+    /** 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.
+ */
+interface Tool<TScratch = unknown, TOverlay = KernelOverlay> extends Contribution<TOverlay> {
+    /** Optional caller-supplied key. Most built-in tools have their activation
+     *  key declared in `BUILTIN_SELECT_KEYS` in `useKeybindings.ts`; this field
+     *  is for tools that want their activation key to be configurable by the
+     *  host (currently Lasso and Eyedropper). The dynamic loop in
+     *  `useKeybindings.ts` picks this up and appends a binding entry to the
+     *  consolidated `tool.activate` action (with `opts.params.toolId` set so
+     *  the invoker knows which tool to switch to). */
+    keybinding?: ToolKeybinding;
+    initScratch?: () => TScratch;
+    cursor?: CursorSpec | ((ctx: ToolCtx<TScratch>) => CursorSpec);
+    /** The tool became live: it took the active slot, or its `hotkey` went
+     *  down, while it held neither. */
+    onActivate?: (ctx: ToolLifecycleCtx<TScratch>) => 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;
+}
+/** 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>;
+/** 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>;
+
 /**
  * What a tool declares.
  *
@@ -2073,7 +2451,7 @@ declare function mergeContributions<T extends Contribution<unknown>>(...bundles:
  * definition is mostly `bindings`, plus presentation and any actions the tool
  * itself introduces.
  */
-interface ToolDef<TScratch = void, TOverlay = unknown> {
+interface ToolDef<TScratch = void, TOverlay = KernelOverlay> {
     id: string;
     /** Capability tags for modality eligibility. `defineTool` forwards these
      *  onto `Tool.eligibility.capabilities`, which is where every gate reads
@@ -2085,14 +2463,9 @@ interface ToolDef<TScratch = void, TOverlay = unknown> {
      * reference by id.
      *
      * Declared here rather than registered by the hook with `useAction`,
-     * because tool hooks run wherever the consumer calls them — for
-     * `<SceneCanvas>` that is ABOVE `<ActionsProviderIfRoot>`, where
-     * `useActionsRegistry()` returns null and `useAction` silently no-ops. The
-     * result was a binding pointing at an action id nothing had registered, so
-     * the gesture fell through to whatever matched next (polygon's
-     * wheel/arrow-key side adjustment did nothing and `nudge.*` moved the
-     * selection instead). `<ToolActionsMounter>` registers these from inside
-     * the provider.
+     * because tool hooks run wherever the consumer calls them, which may be
+     * outside any registry — and there `useAction` silently no-ops, leaving a
+     * binding that points at an action id nothing registered.
      */
     actions?: Action[];
     /** Hook name as exported from the kit barrel (e.g. `'useHandTool'`).
@@ -2111,12 +2484,17 @@ interface ToolDef<TScratch = void, TOverlay = unknown> {
      *  set so the invoker knows which tool to switch to). */
     keybinding?: ToolKeybinding;
     /** Held-key trigger: this tool engages while the key is down and
-     *  disengages on release. Carried onto `Tool.eligibility.offhand`, which
+     *  disengages on release — a modifier, `'space'`, or any other key
+     *  (`'o'`), never while typing in a text field. Carried onto
+     *  `Tool.eligibility.offhand`, which
      *  assembly reads to register the consolidated `tool.offhand` action — the
      *  declaration is the wiring, with nothing for the host to do. */
     hotkey?: HotkeyTrigger;
-    onActivate?: (ctx: ToolCtx<TScratch>) => void;
-    onDeactivate?: (ctx: ToolCtx<TScratch>) => void;
+    /** Fires as the tool becomes live in the active or hotkey slot. See
+     *  `Tool.onActivate`. */
+    onActivate?: (ctx: ToolLifecycleCtx<TScratch>) => 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
@@ -2146,10 +2524,6 @@ interface ToolDef<TScratch = void, TOverlay = unknown> {
      *  `'top'`, above everything. */
     overlayPosition?: OverlayPosition;
 }
-/** Viewport-tool spec. Once phase tables went away this stopped differing
- *  from `ToolDef` in any structural way; `defineViewportTool` survives as the
- *  authoring signal that a tool pans/zooms the view rather than the scene. */
-type ViewportToolDef<TScratch = void, TOverlay = unknown> = ToolDef<TScratch, TOverlay>;
 
 /**
  * Build a `Tool<TScratch>` from a declarative `ToolDef<TScratch>`.
@@ -2165,22 +2539,7 @@ type ViewportToolDef<TScratch = void, TOverlay = unknown> = ToolDef<TScratch, TO
  * and the `initScratch` / `cursor` defaults are worth applying uniformly, and
  * because `Tool.def` gives reflection a handle on the authored form.
  */
-declare function defineTool<TScratch = void, TOverlay = unknown>(def: ToolDef<TScratch, TOverlay>): Tool<TScratch, TOverlay>;
-
-/**
- * Define a tool that acts on the viewport rather than the scene.
- *
- * This used to do real work: `ViewportPhaseDef` was a narrowed `PhaseDef`
- * (no click routes, drag restricted to the function form), and the factory
- * lifted it back to the permissive shape before handing it to `defineTool`.
- * With phase tables gone there is no shape left to narrow — a viewport tool
- * declares `bindings` like any other, pointing at `viewport.*` actions.
- *
- * It survives as an authoring signal. `defineViewportTool` at the top of a
- * hook says "this tool moves the camera, not the drawing", which is worth
- * more than the type gymnastics it replaced.
- */
-declare function defineViewportTool<TScratch = void, TOverlay = unknown>(def: ViewportToolDef<TScratch, TOverlay>): Tool<TScratch, TOverlay>;
+declare function defineTool<TScratch = void, TOverlay = KernelOverlay>(def: ToolDef<TScratch, TOverlay>): Tool<TScratch, TOverlay>;
 
 /**
  * One row in the route registry — a single `GestureBinding` on one tool,
@@ -2191,7 +2550,8 @@ declare function defineViewportTool<TScratch = void, TOverlay = unknown>(def: Vi
  * declare them; consumers walk the list and group client-side.
  */
 interface RegistryEntry {
-    toolId: string;
+    /** The id of the entry that declared the binding: a tool, or a contribution. */
+    ownerId: string;
     /** Which phase the binding's `phase` spec restricts it to. `'any'` when it
      *  declares none, declares `'*'`, or declares an atom list whose atoms
      *  don't agree on one phase — such a binding fires in either phase, and
@@ -2224,6 +2584,9 @@ interface RegistryEntry {
      *  specificity tuple, a `kindOf` predicate identity — read it here rather
      *  than re-walking `Tool.bindings`. */
     spec: GestureSpec;
+    /** The binding's `opts.views`: the views it is live in. Absent when it is
+     *  live in every view. */
+    views?: readonly (string | null)[];
 }
 /**
  * Stand-in target for a `{ kindOf }` predicate spec.
@@ -2246,10 +2609,7 @@ declare const PREDICATE_TARGET = "predicate";
  * Registry, and reading `buildActionRegistry` next to `ActionsRegistry`
  * suggested otherwise.
  */
-declare function buildRouteRegistry(tools: readonly Tool<unknown>[]): RegistryEntry[];
-/** The route-grammar gesture a `GestureSpec.kind` routes as, or `undefined`
- *  for kinds the grammar has no name for. */
-declare function routeGestureForSpecKind(kind: GestureSpec['kind']): GestureName | undefined;
+declare function buildRouteRegistry(entries: readonly Contribution<unknown>[]): RegistryEntry[];
 /**
  * Every route string one `GestureSpec` declares, in route-grammar notation.
  *
@@ -2273,9 +2633,9 @@ interface Conflict {
     arg: string | undefined;
     target: string | undefined;
     modifiers: ParsedModifiers;
-    /** All tool ids that registered the same tuple. At least 2 by
-     *  construction. Order matches the input tools[] order. */
-    toolIds: string[];
+    /** The ids of every entry that declared the same tuple. At least 2 by
+     *  construction, in input order. */
+    ownerIds: string[];
 }
 /** Detect exact-tuple overlaps across a tool registration set.
  *
@@ -2299,6 +2659,12 @@ interface Conflict {
  *    right way to be wrong here: this check has to be silent when nothing is
  *    wrong or nobody will keep it on.
  *
+ *  - 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 {@link viewsTie}.
+ *
  *  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.
@@ -2307,19 +2673,23 @@ interface Conflict {
  *  over-reports, because registry tools take turns in the active slot and
  *  can't collide with each other — see {@link findScopedConflicts}.
  */
-declare function findConflicts(tools: readonly Tool<unknown>[]): Conflict[];
+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.
  */
 interface ToolScopes {
     /** Tools eligible for the active slot, keyed by id or as a flat list. */
-    registry: readonly Tool<unknown>[] | Readonly<Record<string, Tool<unknown>>>;
-    /** Always-on tools. Every one of these is live at once. */
-    ambient?: readonly Tool<unknown>[];
+    registry: readonly Contribution<unknown>[] | Readonly<Record<string, Contribution<unknown>>>;
+    /** Always-on entries. Every one of these is live at once. */
+    ambient?: readonly Contribution<unknown>[];
     /** Registered actions. Their `defaultBinding`s assemble at ambient scope
      *  (hotkey scope when `Action.scope` says so), alongside the tools above. */
     actions?: readonly Action[];
+    /** Every mode the canvas can be in (`activeModeOf` builds one from a
+     *  definition). Two gated actions conflict only when some mode lets both
+     *  rules hold. Default: the kit's `DEFAULT_MODES`. */
+    modes?: readonly ActiveMode[];
 }
 /**
  * Detect reachable route conflicts in an assembled tool set and report each one.
@@ -2349,9 +2719,11 @@ declare function reportRouteConflicts(scopes: ToolScopes, warn?: (message: strin
  * consumers don't depend on its disappearance.
  */
 /**
- * @internal — runtime shape consumed by `matchesKeyBinding`. Public tool authors
- * should use `ToolKeybinding` from `@weasel-js/core` for declaring
- * configurable activation keys.
+ * A key plus a modifier policy, as {@link matchesKeyBinding} tests it against a
+ * `KeyboardEvent`. Every modifier left unset is forbidden, so `{ key: 'a' }`
+ * does not fire on Cmd+A. The matcher ignores `skipInEditable`, `enabled` and
+ * `preventDefault`; those are for whatever attaches the listener. Tools
+ * declaring an activation key use `ToolKeybinding` instead.
  */
 interface KeyBinding {
     /**
@@ -2536,5 +2908,25 @@ interface DepSchema {
 }
 /** Every dep name declared by anything that has merged into {@link DepSchema}. */
 type DepName = keyof DepSchema;
+/**
+ * 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
+ * in, the same way and for the same reason as {@link DepSchema}:
+ *
+ * ```ts
+ * declare module '@weasel-js/routing' {
+ *   interface OverlaySchema { overlay: RenderLayer<unknown> }
+ * }
+ * ```
+ *
+ * `defineTool` defaults its overlay type to it, so a
+ * tool it builds fits the kernel's `tools` without naming the parameter.
+ */
+interface OverlaySchema {
+}
+/** The overlay type merged into {@link OverlaySchema}; `unknown` when none is. */
+type KernelOverlay = OverlaySchema extends {
+    overlay: infer O;
+} ? O : unknown;
 
-export { type HandleKind as $, type ActionsRegistry as A, type BindingOpts as B, type Contribution as C, type Dispatcher as D, type BuildRuleCtxArgs as E, COARSE_TARGET_SCALE as F, type Condition as G, type Conflict as H, type ContributionChrome as I, type ContributionDeps as J, type ContributionRouting as K, DEFAULT_ALLOWED_CAPABILITIES as L, DEFAULT_DEVICE_PROFILE as M, type DebugSink as N, type OverlayPosition as O, type DepName as P, type DetectedDeviceFacts as Q, type RuleCtx as R, type ScopedBinding as S, type Tool as T, type DeviceProfile as U, type DispatchLogEntry as V, type DispatcherContext as W, type DragSample as X, type Eligibility as Y, type EligibilityState as Z, type GestureBinding as _, type AffordanceHit as a, filterEligible as a$, type HitShape as a0, type HotkeyTrigger as a1, INGEST_STRING_MIMES as a2, type ImmediateInvoker as a3, type InvocationCtx as a4, type Invoker as a5, type KeyBinding as a6, type MatchResult as a7, type ModeSwitchLogEntry as a8, type ModifierState as a9, type ToolCtx as aA, type ToolDef as aB, type ToolKeybinding as aC, type ToolModifiers as aD, type ToolOffhandBindingSpec as aE, type ToolPresentation as aF, type ToolSlot as aG, type TraceLogEntry as aH, type UiOngoingControl as aI, type View as aJ, type ViewportToolDef as aK, actionBindings as aL, actionItems as aM, buildDepsFromRequires as aN, buildRouteRegistry as aO, buildRuleCtx as aP, buildToolOffhandBindings as aQ, clientToCanvas as aR, clientToCanvasRect as aS, createDispatcher as aT, defineTool as aU, defineViewportTool as aV, deleteScratch as aW, describeRule as aX, dlog as aY, evaluate as aZ, evaluateEnabled as a_, NEVER as aa, type NodeId as ab, type OngoingHandle as ac, type OngoingInvoker as ad, type OngoingOverlay as ae, type OverlayRole as af, PREDICATE_TARGET as ag, type Point2 as ah, type PointerSession as ai, type PointerSessionCallbacks as aj, type PointerSessionCancelReason as ak, type PointerSessionOptions as al, type RegistryEntry as am, type ResizeAnchor as an, type ResolveAllOptions as ao, type ResolveOnlyResult as ap, type ResolvedCandidate as aq, type Rule as ar, type ScratchKey as as, type ScratchStore as at, type SelectionApi as au, type SelectionExtendKey as av, type SelectionMode as aw, type Selector as ax, TOOL_OFFHAND_ID as ay, type ToolBounds as az, type DepSchema as b, findConflicts as b0, getScratch as b1, isAnchor as b2, isAnchorOrControl as b3, isBody as b4, isControlHandle as b5, isEditableTarget as b6, isEmpty as b7, isResizeHandle as b8, isRotateHandle as b9, validateActionId as bA, isSelectedBody as ba, isUnselectedBody as bb, itemsFromClipboardData as bc, itemsFromDataTransfer as bd, itemsFromFiles as be, liveScope as bf, makeToolOffhandAction as bg, matchBest as bh, matchSorted as bi, matchesKeyBinding as bj, mergeContributions as bk, offhandKeyFor as bl, openPointerSession as bm, pointerGestureId as bn, recordModeSwitch as bo, reportRouteConflicts as bp, resolveDeviceProfile as bq, resolveParams as br, routeGestureForSpecKind as bs, routesForSpec as bt, scopeBindings as bu, scratchKey as bv, setScratch as bw, specificity as bx, targetConsultsAffordance as by, validateActionDefaultBinding as bz, type Action as c, type AnyToolOf as d, type DepRegistry as e, DepRegistryProvider as f, useDepSource as g, useOptionalDepRegistry as h, ALWAYS as i, type ActionDeps as j, ActionDisabledReason as k, type ActionDispatch as l, type ActionEnabledResult as m, type ActionEntry as n, type ActionItem as o, type ActionPresentation as p, type ActionSource as q, type ActionVariant as r, type ActionsProp as s, type AnyTool as t, useDepRegistry as u, type BindingScope as v, type BindingSource as w, type BodyPredicate as x, type BoundGesture as y, type Bounds as z };
+export { type GestureBinding as $, type ActionsRegistry as A, type BindingOpts as B, type Contribution as C, type DepRegistry as D, COARSE_TARGET_SCALE as E, type Condition as F, type Conflict as G, type ContributionChrome as H, type ContributionDeps as I, type ContributionRouting as J, type KernelOverlay as K, type LongPressOptions as L, DEFAULT_ALLOWED_CAPABILITIES as M, DEFAULT_DEVICE_PROFILE as N, type OverlayPosition as O, type DebugSink as P, type DetectedDeviceFacts as Q, type RuleCtx as R, ScopeNode as S, type DeviceProfile as T, type DispatchRecord as U, type DispatchRecordInput as V, type DispatcherContext as W, type DragSample as X, type DroppedCandidate as Y, type Eligibility as Z, type EligibilityState as _, type DepName as a, actionItems as a$, type HandleKind as a0, type HitShape as a1, type HotkeyTrigger as a2, INGEST_STRING_MIMES as a3, type ImmediateInvoker as a4, type InvocationCtx as a5, type Invoker as a6, type KeyBinding as a7, LONG_PRESS_MS as a8, type LongPressState as a9, type ResolveOnlyResult as aA, type ResolvedCandidate as aB, type Rule as aC, type ScratchKey as aD, type ScratchStore as aE, type SelectionApi as aF, type SelectionExtendKey as aG, type SelectionMode as aH, type Selector as aI, type SpecificityPart as aJ, TOOL_OFFHAND_ID as aK, type Tool as aL, type ToolBounds as aM, type ToolCtx as aN, type ToolDef as aO, type ToolKeybinding as aP, type ToolLifecycleCtx as aQ, type ToolModifiers as aR, type ToolOffhandBindingSpec as aS, type ToolPresentation as aT, type ToolSlot as aU, type TraceLogEntry as aV, type UiOngoingControl as aW, type View as aX, type ViewportGestureKind as aY, type WalkStep as aZ, actionBindings as a_, type LongPressStore as aa, type MatchOutcome as ab, type MatchResult as ac, type ModeShortcutHandlers as ad, type ModeSwitchLogEntry as ae, type ModifierState as af, NEVER as ag, type NodeId as ah, type OngoingHandle as ai, type OngoingInvoker as aj, type OngoingOverlay as ak, type OverlayRole as al, type OverlaySchema as am, PREDICATE_TARGET as an, type PendingLongPress as ao, type PlacedBy as ap, type Point2 as aq, type PointerSession as ar, type PointerSessionCallbacks as as, type PointerSessionCancelReason as at, type PointerSessionOptions as au, type RankedCandidate as av, type RecordCandidate as aw, type RegistryEntry as ax, type ResizeAnchor as ay, type ResolveAllOptions as az, type DepSchema as b, buildDepsFromRequires as b0, buildRouteRegistry as b1, buildRuleCtx as b2, buildToolOffhandBindings as b3, clientToCanvas as b4, clientToCanvasRect as b5, createDepRegistry as b6, createDispatcher as b7, createLongPressStore as b8, defineTool as b9, matchesKeyBinding as bA, mergeContributions as bB, modeShortcutSpec as bC, modeShortcuts as bD, offhandKeyFor as bE, openPointerSession as bF, pointerGestureId as bG, recordModeSwitch as bH, reportRouteConflicts as bI, resolveDeviceProfile as bJ, resolveParams as bK, routesForSpec as bL, ruleCanHoldIn as bM, rulesExclusive as bN, scopeBindings as bO, scratchKey as bP, setScratch as bQ, targetConsultsAffordance as bR, validateActionDefaultBinding as bS, validateActionId as bT, deleteScratch as ba, describeRule as bb, dlog as bc, evaluate as bd, evaluateEnabled as be, findConflicts as bf, getScratch as bg, isAnchor as bh, isAnchorOrControl as bi, isBody as bj, isControlHandle as bk, isEditableTarget as bl, isEmpty as bm, isResizeHandle as bn, isRotateHandle as bo, isSelectedBody as bp, isTool as bq, isUnselectedBody as br, itemsFromClipboardData as bs, itemsFromDataTransfer as bt, itemsFromFiles as bu, liveScope as bv, makeToolOffhandAction as bw, matchBest as bx, matchSorted as by, matchSortedWithBarred as bz, type Action as c, DepNode as d, type AnyToolOf as e, type ScopedBinding as f, type Dispatcher as g, type AffordanceHit as h, ALWAYS as i, type ActionDeps as j, ActionDisabledReason as k, type ActionDispatch as l, type ActionEnabledResult as m, type ActionEntry as n, type ActionItem as o, type ActionPresentation as p, type ActionSource as q, type ActionVariant as r, type ActionsProp as s, type AnyTool as t, type BindingScope as u, type BindingSource as v, type BodyPredicate as w, type BoundGesture as x, type Bounds as y, type BuildRuleCtxArgs as z };