@weasel-js/routing 1.6.0 → 1.7.0

package/dist/{index-B_KvoXww.d.ts → index-Bmq4lSHY.d.ts}

@@ -1,9 +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 * as react_jsx_runtime from 'react/jsx-runtime';
+import { ClaimableGesture, GestureSpec, InputEvent, TargetSpec, KeySpec, ParsedModifiers, GestureName, IngestItem } from '@weasel-js/gestures';
 import { Op } from '@weasel-js/history';
 
 /**
@@ -235,6 +234,10 @@ interface RuleCtx {
      *  density 1. That is what the kit assumed before this field existed, so
      *  an absent profile is behavior-preserving by construction. */
     readonly device?: DeviceProfile;
+    /** The view the input being dispatched landed in — a view id, or `null`
+     *  for the surface's own camera. The dispatcher fills it; absent anywhere
+     *  else a rule is evaluated. */
+    readonly viewId?: string | null;
 }
 /** The live state a `RuleCtx` is assembled from — the chrome context plus
  *  what the active mode allows. */
@@ -379,6 +382,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'>;
 /**
@@ -587,6 +608,12 @@ interface InvocationCtx {
         key: string;
         repeat: boolean;
     };
+    /**
+     * The view the input landed in, as the surface's view resolver assigned it:
+     * a view id, or `null` for the surface's own camera. Absent where no
+     * surface routed the input — a UI-driven trigger, a bare dispatcher.
+     */
+    viewId?: string | null;
     /**
      * Per-invocation parameters. Populated by `ActionsRegistry.begin()` for
      * UI-driven ongoing actions (color picker, opacity slider) so handles can
@@ -617,6 +644,16 @@ interface BindingOpts {
      *  values at commit, the invoker can re-call the thunk 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
+     * own camera. Omitted means every view.
+     *
+     * A binding that names the view an input landed in outranks every binding
+     * that does not, whatever their scope tiers: naming a view is the most
+     * specific thing a binding can say about where it applies. Without that, a
+     * drag bound inside a minimap view loses to the active tool's marquee.
+     */
+    views?: readonly (string | null)[];
 }
 /** Resolve `BindingOpts.params` to a concrete record (calling the thunk if
  *  needed). Returns `undefined` for absent params. */
@@ -1060,7 +1097,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
@@ -1131,6 +1168,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. */
@@ -1138,23 +1234,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_runtime.JSX.Element;
-/** The dep registry in scope. Throws outside a `<DepRegistryProvider>`. */
-declare function useDepRegistry(): DepRegistry;
-/**
- * Like `useDepRegistry`, but returns `null` when no `<DepRegistryProvider>` is
- * in scope instead of throwing. Used by `useStandardActions` to preserve its
- * silent-no-op contract when neither provider is present.
- */
-declare function useOptionalDepRegistry(): DepRegistry | null;
-/** Register a live source for `name` for the lifetime of the calling
- *  component. The `source` thunk is called at dispatch time and should
- *  return the latest value. */
-declare function useDepSource<K extends DepName>(name: K, source: () => DepSchema[K]): void;
+/** 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
@@ -1168,9 +1261,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.
@@ -1190,6 +1287,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
@@ -1215,21 +1316,28 @@ interface Eligibility {
  * all three collapse to `'top'`.
  */
 type OverlayPosition = 'top' | 'before-selection' | 'after-selection';
+/** Dep sources an entry provides while it is installed, by dep name. */
+type ContributionDeps = {
+    [K in DepName]?: () => DepSchema[K];
+};
 /**
  * What routing reads off an entry: when its bindings are live, which they
- * are, and the actions they name.
+ * are, the actions they name, and the deps those actions read.
  */
 interface ContributionRouting {
     id: string;
     eligibility: Eligibility;
     bindings?: GestureBinding[];
     actions?: Action[];
+    /** Dep sources this entry provides while it is installed. A host installs
+     *  them for as long as the entry is registered, whatever its eligibility. */
+    deps?: ContributionDeps;
 }
 /**
  * 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
@@ -1245,117 +1353,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
@@ -1370,18 +1372,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
@@ -1396,19 +1398,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.
  *
@@ -1437,6 +1426,167 @@ 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';
+}
+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;
+}
+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;
+};
+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';
+};
+interface RankedCandidate {
+    candidate: RecordCandidate;
+    placedBy: PlacedBy;
+    walk: WalkStep;
+}
 
 /**
  * Dispatcher orchestrator — pure module, no React, no DOM.
@@ -1446,10 +1596,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
@@ -1489,23 +1648,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()`;
@@ -1522,7 +1664,17 @@ 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;
+/**
+ * Dev only: offer the record for what a press at the pointer would do, as a
+ * thunk on `window.__weaselDispatchLive__`. The hover pump offers one per move
+ * and a reader builds the record only when it looks, so no record is built
+ * while nothing is watching. `null` withdraws it when the pointer leaves.
+ *
+ * @internal
+ */
+declare function publishLiveDispatch(explain: (() => DispatchRecord) | null): void;
 /** 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;
@@ -1536,12 +1688,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;
     /**
@@ -1552,6 +1704,14 @@ interface DispatcherContext {
      * no eligibility filtering.
      */
     getRuleCtx?: () => RuleCtx | undefined;
+    /**
+     * The view this input landed in — a view id, or `null` for the surface's
+     * own camera. Bindings whose `opts.views` omit it are not live, those naming
+     * it outrank the rest, and it reaches the invoker as `InvocationCtx.viewId`
+     * and rules as `RuleCtx.viewId`. Absent means the host routes no views, which
+     * reads as the root.
+     */
+    viewId?: string | null;
 }
 /**
  * Filter `matches` to only those whose backing action has no `eligible`
@@ -1565,6 +1725,23 @@ declare function filterEligible<M extends {
         actionId: string;
     };
 }>(matches: readonly M[], actionLookup: (id: string) => Action | undefined, ruleCtx: RuleCtx): M[];
+/**
+ * Among matches tied on scope and specificity, put those whose action is
+ * gated by an `eligible` rule that holds now ahead of those with no rule: a
+ * binding that applies only in the current context — Escape while editing a
+ * path — outranks one that applies everywhere. Otherwise stable.
+ *
+ * @internal
+ */
+declare function preferContextual<M extends {
+    binding: GestureBinding;
+    scope: string;
+}>(matches: readonly M[], actionLookup: (id: string) => Action | undefined, 
+/** Whether a gated action's rule holds; skip re-asking where the matches
+ *  were already filtered by it. */
+holds: (action: Action) => boolean, 
+/** The routed view: a binding naming it is never tied with one that does not. */
+view: string | null): M[];
 /**
  * Handle returned by `Dispatcher.beginUiOngoing()` for driving an
  * ongoing invoker from a UI control (color picker, slider).
@@ -1590,7 +1767,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
@@ -1614,7 +1791,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];
@@ -1702,6 +1879,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).
@@ -1822,10 +2007,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[];
@@ -1854,18 +2038,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
@@ -1888,8 +2070,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
@@ -2017,17 +2199,177 @@ 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 —
  * entry order decides which of two same-specificity bindings in one scope
  * tier wins, so it is part of the result, not an accident of it.
  *
- * Throws on a duplicate id rather than dropping one: a feature silently
- * losing its bindings is the failure this registry exists to make loud.
+ * Throws on a duplicate id or dep name rather than dropping one: a feature
+ * silently losing its bindings, or reading another feature's dep, is the
+ * failure this registry exists to make loud.
+ */
+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 mergeContributions(...bundles: readonly Contribution[][]): Contribution[];
+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.
@@ -2038,7 +2380,7 @@ declare function mergeContributions(...bundles: readonly Contribution[][]): Cont
  * 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
@@ -2050,14 +2392,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'`).
@@ -2076,12 +2413,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
@@ -2111,10 +2453,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>`.
@@ -2130,22 +2468,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,
@@ -2156,7 +2479,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
@@ -2189,6 +2513,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.
@@ -2211,10 +2538,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.
  *
@@ -2238,9 +2562,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.
  *
@@ -2264,6 +2588,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.
@@ -2272,19 +2602,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.
@@ -2501,5 +2835,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 HitShape 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 ContributionRouting as J, DEFAULT_ALLOWED_CAPABILITIES as K, DEFAULT_DEVICE_PROFILE as L, type DebugSink as M, type DepName as N, type OverlayPosition as O, type DetectedDeviceFacts as P, type DeviceProfile as Q, type RuleCtx as R, type ScopedBinding as S, type Tool as T, type DispatchLogEntry as U, type DispatcherContext as V, type DragSample as W, type Eligibility as X, type EligibilityState as Y, type GestureBinding as Z, type HandleKind as _, type AffordanceHit as a, findConflicts as a$, type HotkeyTrigger as a0, INGEST_STRING_MIMES as a1, type ImmediateInvoker as a2, type InvocationCtx as a3, type Invoker as a4, type KeyBinding as a5, type MatchResult as a6, type ModeSwitchLogEntry as a7, type ModifierState as a8, NEVER as a9, type ToolDef as aA, type ToolKeybinding as aB, type ToolModifiers as aC, type ToolOffhandBindingSpec as aD, type ToolPresentation as aE, type ToolSlot as aF, type TraceLogEntry as aG, type UiOngoingControl as aH, type View as aI, type ViewportToolDef as aJ, actionBindings as aK, actionItems as aL, buildDepsFromRequires as aM, buildRouteRegistry as aN, buildRuleCtx as aO, buildToolOffhandBindings as aP, clientToCanvas as aQ, clientToCanvasRect as aR, createDispatcher as aS, defineTool as aT, defineViewportTool as aU, deleteScratch as aV, describeRule as aW, dlog as aX, evaluate as aY, evaluateEnabled as aZ, filterEligible as a_, type NodeId as aa, type OngoingHandle as ab, type OngoingInvoker as ac, type OngoingOverlay as ad, type OverlayRole as ae, PREDICATE_TARGET as af, type Point2 as ag, type PointerSession as ah, type PointerSessionCallbacks as ai, type PointerSessionCancelReason as aj, type PointerSessionOptions as ak, type RegistryEntry as al, type ResizeAnchor as am, type ResolveAllOptions as an, type ResolveOnlyResult as ao, type ResolvedCandidate as ap, type Rule as aq, type ScratchKey as ar, type ScratchStore as as, type SelectionApi as at, type SelectionExtendKey as au, type SelectionMode as av, type Selector as aw, TOOL_OFFHAND_ID as ax, type ToolBounds as ay, type ToolCtx as az, type DepSchema as b, getScratch as b0, isAnchor as b1, isAnchorOrControl as b2, isBody as b3, isControlHandle as b4, isEditableTarget as b5, isEmpty as b6, isResizeHandle as b7, isRotateHandle as b8, isSelectedBody as b9, isUnselectedBody as ba, itemsFromClipboardData as bb, itemsFromDataTransfer as bc, itemsFromFiles as bd, liveScope as be, makeToolOffhandAction as bf, matchBest as bg, matchSorted as bh, matchesKeyBinding as bi, mergeContributions as bj, offhandKeyFor as bk, openPointerSession as bl, pointerGestureId as bm, recordModeSwitch as bn, reportRouteConflicts as bo, resolveDeviceProfile as bp, resolveParams as bq, routeGestureForSpecKind as br, routesForSpec as bs, scopeBindings as bt, scratchKey as bu, setScratch as bv, specificity as bw, targetConsultsAffordance as bx, validateActionDefaultBinding as by, validateActionId 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 HandleKind as $, type ActionsRegistry as A, type BindingOpts as B, type Contribution as C, type Dispatcher 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, DEFAULT_ALLOWED_CAPABILITIES as L, DEFAULT_DEVICE_PROFILE as M, type DebugSink as N, type OverlayPosition as O, type DetectedDeviceFacts as P, type DeviceProfile as Q, type RuleCtx as R, ScopeNode as S, type DispatchRecord as T, type DispatchRecordInput as U, type DispatcherContext as V, type DragSample as W, type DroppedCandidate as X, type Eligibility as Y, type EligibilityState as Z, type GestureBinding as _, type AffordanceHit as a, clientToCanvasRect 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 MatchOutcome as a7, type MatchResult as a8, type ModeShortcutHandlers as a9, type SelectionApi as aA, type SelectionExtendKey as aB, type SelectionMode as aC, type Selector as aD, type SpecificityPart as aE, TOOL_OFFHAND_ID as aF, type Tool as aG, type ToolBounds as aH, type ToolCtx as aI, type ToolDef as aJ, type ToolKeybinding as aK, type ToolLifecycleCtx as aL, type ToolModifiers as aM, type ToolOffhandBindingSpec as aN, type ToolPresentation as aO, type ToolSlot as aP, type TraceLogEntry as aQ, type UiOngoingControl as aR, type View as aS, type WalkStep as aT, actionBindings as aU, actionItems as aV, buildDepsFromRequires as aW, buildRouteRegistry as aX, buildRuleCtx as aY, buildToolOffhandBindings as aZ, clientToCanvas as a_, type ModeSwitchLogEntry as aa, type ModifierState as ab, NEVER as ac, type NodeId as ad, type OngoingHandle as ae, type OngoingInvoker as af, type OngoingOverlay as ag, type OverlayRole as ah, type OverlaySchema as ai, PREDICATE_TARGET as aj, type PlacedBy as ak, type Point2 as al, type PointerSession as am, type PointerSessionCallbacks as an, type PointerSessionCancelReason as ao, type PointerSessionOptions as ap, type RankedCandidate as aq, type RecordCandidate as ar, type RegistryEntry as as, type ResizeAnchor as at, type ResolveAllOptions as au, type ResolveOnlyResult as av, type ResolvedCandidate as aw, type Rule as ax, type ScratchKey as ay, type ScratchStore as az, type DepSchema as b, createDepRegistry as b0, createDispatcher as b1, defineTool as b2, deleteScratch as b3, describeRule as b4, dlog as b5, evaluate as b6, evaluateEnabled as b7, filterEligible as b8, findConflicts as b9, pointerGestureId as bA, preferContextual as bB, publishLiveDispatch as bC, recordModeSwitch as bD, reportRouteConflicts as bE, resolveDeviceProfile as bF, resolveParams as bG, routesForSpec as bH, ruleCanHoldIn as bI, rulesExclusive as bJ, scopeBindings as bK, scratchKey as bL, setScratch as bM, targetConsultsAffordance as bN, validateActionDefaultBinding as bO, validateActionId as bP, getScratch as ba, isAnchor as bb, isAnchorOrControl as bc, isBody as bd, isControlHandle as be, isEditableTarget as bf, isEmpty as bg, isResizeHandle as bh, isRotateHandle as bi, isSelectedBody as bj, isTool as bk, isUnselectedBody as bl, itemsFromClipboardData as bm, itemsFromDataTransfer as bn, itemsFromFiles as bo, liveScope as bp, makeToolOffhandAction as bq, matchBest as br, matchSorted as bs, matchSortedWithBarred as bt, matchesKeyBinding as bu, mergeContributions as bv, modeShortcutSpec as bw, modeShortcuts as bx, offhandKeyFor as by, openPointerSession as bz, type DepRegistry as c, type DepName as d, type Action as e, DepNode as f, type AnyToolOf as g, type ScopedBinding 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 };