@weasel-js/routing 1.9.3 → 1.9.4

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

@@ -1,8 +1,9 @@
-import { CapabilityTag, ActiveMode, ModeRegistry } from '@weasel-js/modes';
+import { View } from '@weasel-js/geom';
 import * as react from 'react';
 import { ReactNode } from 'react';
+import { CapabilityTag, ActiveMode, ModeRegistry } from '@weasel-js/modes';
 import { CursorSpec } from '@weasel-js/cursor';
-import { ClaimableGesture, GestureSpec, InputEvent, TargetSpec, KeySpec, ParsedModifiers, GestureName, IngestItem } from '@weasel-js/gestures';
+import { ClaimableGesture, GestureSpec, InputEvent, TargetSpec, KeyHeldSpec, TargetPredicate, KeySpec, ParsedModifiers, GestureName, IngestItem } from '@weasel-js/gestures';
 import { Op } from '@weasel-js/history';
 import '@weasel-js/select';
 
@@ -29,22 +30,7 @@ import '@weasel-js/select';
 type NodeId = string & {
     readonly __brand: 'NodeId';
 };
-/**
- * Viewport state. `(view.x, view.y)` is the world point currently rendered at
- * the canvas top-left; `view.scale.x` / `view.scale.y` is pixels per world
- * unit on each axis.
- *
- * The one outright 2D dead end in the routing surface: a `View` names no
- * orientation, so a kernel with a camera cannot express its viewport as one.
- */
-interface View {
-    x: number;
-    y: number;
-    scale: {
-        x: number;
-        y: number;
-    };
-}
+
 /**
  * Axis-aligned rectangle in world space. The optional `rotation` (radians,
  * around the AABB center) lets chrome attach an orientation to an otherwise
@@ -196,6 +182,108 @@ type ResizeAnchor = {
     y: 'min' | 'max' | 'free';
 };
 
+/**
+ * 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.
+ */
+/** 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>;
+}
+
+/** Which tool is active, plus the stack of tools temporarily held active by a
+ *  hotkey (space-for-hand and the like). The dispatcher reads this to decide
+ *  whose bindings are in scope. */
+interface ActiveToolContextValue {
+    /** The focused tool's id, or `null` when no tool holds the active slot —
+     *  a canvas can run on ambient bindings alone. */
+    active: string | null;
+    hotkeyStack: string[];
+    setActive(id: string | null): void;
+    pushHotkey(id: string): void;
+    /**
+     * Disengage a hotkey-held tool. With `id`, removes that tool's own entry
+     * wherever it now sits — holds do not have to come up in the order they went
+     * down, and popping the top would disengage a tool whose key is still held.
+     * With no id, pops the top.
+     */
+    popHotkey(id?: string): void;
+}
+/**
+ * One node of the tool tree. A node that `owns` a tool holds its state; one
+ * that does not — a scope inside a yoke — reads and writes its yoke's.
+ */
+declare class ToolNode extends ScopeNode<ToolNode> {
+    private state;
+    private value;
+    constructor(parent: ToolNode | null, descends: boolean, owns: boolean, initialActive: string | null);
+    /** The node whose tool a read here resolves to. */
+    owner(): ToolNode;
+    private update;
+    /** A stable value per owner and state, for `useSyncExternalStore`. */
+    snapshot(): ActiveToolContextValue;
+    subscribe: (listener: () => void) => (() => void);
+}
+/** Props for `<ActiveToolContextProvider>`. */
+interface ActiveToolContextProviderProps {
+    children: ReactNode;
+    /** Seeds the active slot, and wins over the first `useTools` call's
+     *  `active`. Omitted, the slot starts empty and that call seeds it. */
+    initialActive?: string | null;
+}
+/** Provides root active-tool state. Every canvas below has a tool of its own;
+ *  reads and writes here reach the one last used. */
+declare function ActiveToolContextProvider({ children, initialActive, }: ActiveToolContextProviderProps): react.JSX.Element;
+/** The active-tool state in scope. Throws outside a provider; use
+ *  `useOptionalActiveToolContext` where one is not guaranteed. */
+declare function useActiveToolContext(): ActiveToolContextValue;
+/**
+ * Like `useActiveToolContext`, but returns `null` when no
+ * `<ActiveToolContextProvider>` is in scope instead of throwing. Used by
+ * `useStandardActions` to preserve its silent-no-op contract when no provider
+ * is present.
+ */
+declare function useOptionalActiveToolContext(): ActiveToolContextValue | null;
+/**
+ * Conditional `<ActiveToolContextProvider>` wrapper. Mounts a provider only
+ * when no parent provider is in scope — otherwise renders children unwrapped
+ * so `<WeaselProvider>` defers to the host's existing scope.
+ */
+declare function ActiveToolContextProviderIfRoot({ children, }: {
+    children: ReactNode;
+}): react.JSX.Element;
+
 /**
  * Live state read by rule evaluation. Built once per frame on the consuming
  * surface — chrome-caps, the affordance pipeline, the dispatcher's
@@ -1035,12 +1123,13 @@ interface ActionDispatch extends BindingSource {
     scope?: 'hotkey';
     /**
      * @experimental
-     * Optional predicate the command palette consults when rendering. Return
-     * `true` when the action is currently triggerable. Return a reason string
-     * (e.g. `'Selection required'`) when disabled — the palette greys out
-     * the row, skips it in keyboard nav, ignores clicks, and shows the
-     * reason next to the label. Keystroke dispatch (the registered binding)
-     * is unaffected; the action's own `run` should self-guard.
+     * Optional predicate saying whether the action can run right now. Return
+     * `true` when it can, or a reason string (e.g. `'Selection required'`)
+     * when it cannot. The command palette greys out a disabled row, skips it
+     * in keyboard nav, ignores clicks, and shows the reason next to the label.
+     * The dispatcher skips a disabled action too, on a key as on a pointer, and
+     * falls through to the next binding that matches. `ActionsRegistry.trigger`
+     * does not ask, so the action's own `run` should still self-guard.
      *
      * **Contract:** must be pure (no side effects), fast (< 4ms in dev), and
      * must not throw. If a call throws or exceeds the budget in dev mode,
@@ -1071,6 +1160,17 @@ interface ActionDispatch extends BindingSource {
         x: number;
         y: number;
     }) => true | ActionDisabledReason;
+    /**
+     * @experimental
+     * Whether the action reads as held down right now: bold on the selected
+     * text, snapping switched on. A toolbar button draws it as pressed.
+     * Omitted = the action has no pressed state, which is not the same as
+     * one that is off. Never read during dispatch.
+     *
+     * Under the same contract as `enabled`: pure, fast, and it must not
+     * throw. `deps` is the bag `enabled` is given.
+     */
+    active?: (deps?: ActionDeps) => boolean;
     /**
      * Declarative eligibility rule, evaluated against the current
      * `RuleCtx` by the dispatcher before invoking `start()`. Omitted =
@@ -1182,48 +1282,12 @@ interface ActionEnabledResult {
  * predicates should be sub-millisecond).
  */
 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.
+ * @experimental
+ * Safely evaluate an action's `active` predicate. `undefined` for an action
+ * with no pressed state; a predicate that throws reads as not active.
  */
-/** 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>;
-}
+declare function evaluateActive(action: Action, deps?: ActionDeps): boolean | undefined;
 
 /**
  * Dep registry for registry unification.
@@ -1248,6 +1312,15 @@ declare class ScopeNode<N extends ScopeNode<N>> {
 interface DepRegistry {
     register<K extends DepName>(name: K, source: () => DepSchema[K]): () => void;
     get<K extends DepName>(name: K): DepSchema[K] | undefined;
+    /** Hear that what the registry answers may have changed: a source was
+     *  registered or released anywhere in its tree, or an owner called
+     *  {@link DepRegistry.changed}. Returns the unsubscribe. A hand-built
+     *  registry whose answers never change leaves this and `changed` out. */
+    subscribe?(listener: () => void): () => void;
+    /** Say that a source's value changed. A source is a thunk read on demand,
+     *  so its owner is the only one who knows; chrome showing an action's
+     *  `enabled` or `active` state re-reads on this. */
+    changed?(): 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
@@ -1408,9 +1481,8 @@ interface MatchResult {
  * `bodyTarget` / `bodyKind` and never see it — which is why chrome floating
  * over empty canvas used to read as empty canvas.
  *
- * A predicate carrying `readsAffordance: false` says the same about itself;
- * the kit's own body predicates do. Shape stays the fallback for predicates
- * that declare nothing.
+ * A predicate declares which it is with `readsAffordance`; one that declares
+ * nothing, which only untyped code can write, counts as not reading the hit.
  */
 declare function targetConsultsAffordance(specTarget: TargetSpec | undefined): boolean;
 /**
@@ -1609,86 +1681,11 @@ interface RankedCandidate {
 }
 
 /**
- * Dispatcher orchestrator — pure module, no React, no DOM.
- *
- * Assembles `ScopedBinding[]` from the actions registry, active tool, and
- * hotkey stack; matches input events via `matchSorted`; gates each candidate
- * on `enabled()`; then invokes `immediate` or `ongoing` invokers and tracks
- * in-flight handles.
- *
- * ## 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
- * binding (e.g. drag-on-empty → areaSelect) that gracefully falls through
- * to a lower-specificity ambient binding (e.g. drag → viewport.dragPan)
- * when its required deps aren't wired.
- *
- * ## gestureId scheme
- * - `key-held` ongoing actions: `key-held-<key>` (e.g. `key-held- ` for Space).
- *   Chosen because key-held gestures are identified by the held key alone.
- * - `pointerdown` / drag ongoing actions: `pointer-<pointerId>`, taken from
- *   the originating DOM `PointerEvent`. Each physical pointer — mouse, each
- *   touch, the stylus — gets its own handle slot. Events with no
- *   `pointerId` (synthesized probes, programmatic drags, most tests) key to
- *   `pointer-mouse`, so a single synthetic pointer behaves as it always has.
- * - `multitouch` ongoing actions: `multitouch-<fingers>`.
- * - Fallback for any other kind that triggers an ongoing invoker: `ongoing-<kind>`.
- *
- * ## Action-lookup miss behavior
- * When `matchBest` resolves a binding whose `actionId` has no entry in
- * `ctx.actions.list()`, the dispatcher emits `console.warn` and returns
- * `'unhandled'`. The user's input gesture falls through as if unmatched.
- * This preserves input flow (nothing is swallowed silently) while flagging
- * the misconfiguration at dev time.
+ * The dispatcher's contract: what a host hands it per input
+ * (`DispatcherContext`) and what it answers with (`Dispatcher`).
+ * `createDispatcher` in `dispatcher.ts` implements it.
  */
 
-/**
- * The in-flight handle slot a pointer's gestures key into.
- *
- * Exported because the React seam (`useGestureDispatcher`) has to name the
- * same slot when it asks `dispatcher.inFlight()` whether a given pointer is
- * mid-drag. That used to be the string literal `'pointer-mouse'` on both
- * sides, which was correct only because `gestureIdFor` ignored the pointer id
- * entirely — the two lies cancelled out.
- *
- * @param pointerId - `PointerEvent.pointerId`, or `undefined` for a
- *   synthesized event with no originating DOM pointer.
- */
-declare function pointerGestureId(pointerId: number | undefined): string;
-/** One entry per "mode change" — a kit state transition that isn't a
- *  dispatched input event but is load-bearing for understanding why an
- *  input was (or wasn't) handled later. Pushed via `recordModeSwitch()`;
- *  consumers include the editAnchors dep (editingId changes), and
- *  could expand to active-tool / hotkey-stack / focus changes. */
-interface ModeSwitchLogEntry {
-    kind: 'mode';
-    ts: number;
-    /** Logical mode name, e.g. `'editAnchors.editingId'`. */
-    mode: string;
-    from: string | null;
-    to: string | null;
-    /** Optional free-form context — `'enterPathEdit'`, `'exitPathEdit'`,
-     *  `'selection-dropped target'`, etc. */
-    detail?: string;
-}
-/** 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;
 /** Everything the dispatcher must consult to route one input event: the
  *  registered actions and their deps, which tool is active, which hotkeys are
  *  held, and — optionally — the chrome state that action eligibility rules are
@@ -1732,9 +1729,13 @@ interface DispatcherContext {
  *    calls the handle's `onMove`. Safe to call many times.
  *  - `end(reason)` calls `onEnd(ctx, reason)` once and removes the handle
  *    from the in-flight map. Idempotent — further calls are no-ops.
+ *  - `active` is false once the handle has ended, whether through `end` or
+ *    by the dispatcher (`cancelAll`, or a later `beginUiOngoing` for the same
+ *    action). `update` and `end` do nothing from then on.
  */
 interface UiOngoingControl {
     readonly gestureId: string;
+    readonly active: boolean;
     update(params?: Record<string, unknown>): void;
     end(reason: 'commit' | 'cancel'): void;
 }
@@ -1880,12 +1881,12 @@ interface Dispatcher {
      */
     inFlight(): ReadonlyMap<string, OngoingHandle>;
     /**
-     * CSS cursor for the gesture currently in flight, or `null` when nothing
+     * Cursor for the gesture currently in flight, as declared, or `null` when nothing
      * is. Reads `Action.activeCursor` (falling back to `Action.cursor`) off the
      * action whose handle is open — the hover pump applies this instead of its
      * prediction once a gesture starts, which is how `grab` becomes `grabbing`.
      */
-    inFlightCursor(): string | null;
+    inFlightCursor(): CursorSpec | null;
     /**
      * Read-only iterator over currently in-flight `OngoingHandle` instances.
      *
@@ -1899,7 +1900,9 @@ interface Dispatcher {
      * Subscribe to in-flight state changes. The callback fires after every
      * mutation that affects what the preview-ghost / dispatcher-overlay
      * layers read — handle start, every `onMove` pump, end, cancel,
-     * cancel-all. Consumers re-read `getInFlightHandles()` and re-render.
+     * cancel-all — and after any other input handled while a gesture is in
+     * flight. Input that arrives with nothing in flight and starts nothing
+     * does not fire it. Consumers re-read `getInFlightHandles()` and re-render.
      *
      * Returns an unsubscribe function.
      */
@@ -1911,9 +1914,9 @@ interface Dispatcher {
      * a `useReducer` force-rerender.
      *
      * Starts at 0 and only ever increases. Two reads returning the same number
-     * mean nothing pumped in between; it does **not** guarantee that a bump
-     * changed anything observable (a pump that matched no binding still
-     * counts — see `subscribe`).
+     * mean no gesture was in flight in between; it does **not** guarantee that
+     * a bump changed anything observable (input that matched no binding still
+     * counts while a gesture is in flight — see `subscribe`).
      */
     getVersion(): number;
     /**
@@ -1959,6 +1962,96 @@ interface Dispatcher {
      */
     beginUiOngoing(actionId: string, deps: ActionDeps, params?: Record<string, unknown>): UiOngoingControl | null;
 }
+
+/**
+ * Dev-only trace of what the dispatcher did: one record per resolved input and
+ * one per mode switch, in a rolling buffer the dev tools read.
+ */
+
+/** One entry per "mode change" — a kit state transition that isn't a
+ *  dispatched input event but is load-bearing for understanding why an
+ *  input was (or wasn't) handled later. Pushed via `recordModeSwitch()`;
+ *  consumers include the editAnchors dep (editingId changes), and
+ *  could expand to active-tool / hotkey-stack / focus changes. */
+interface ModeSwitchLogEntry {
+    kind: 'mode';
+    ts: number;
+    /** Logical mode name, e.g. `'editAnchors.editingId'`. */
+    mode: string;
+    from: string | null;
+    to: string | null;
+    /** Optional free-form context — `'enterPathEdit'`, `'exitPathEdit'`,
+     *  `'selection-dropped target'`, etc. */
+    detail?: string;
+}
+/** 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;
+
+/**
+ * Dispatcher orchestrator — pure module, no React, no DOM.
+ *
+ * Assembles `ScopedBinding[]` from the actions registry, active tool, and
+ * hotkey stack; matches input events via `matchSorted`; gates each candidate
+ * on `enabled()`; then invokes `immediate` or `ongoing` invokers and tracks
+ * in-flight handles.
+ *
+ * ## 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
+ * binding (e.g. drag-on-empty → areaSelect) that gracefully falls through
+ * to a lower-specificity ambient binding (e.g. drag → viewport.dragPan)
+ * when its required deps aren't wired.
+ *
+ * ## gestureId scheme
+ * - `key-held` ongoing actions: `key-held-<code>` (`key-held-Space`), so two
+ *   keys that share a `key`, such as the two Shifts, hold separately. An event
+ *   with no code keys by `key`.
+ *   Chosen because key-held gestures are identified by the held key alone.
+ * - `pointerdown` / drag ongoing actions: `pointer-<pointerId>`, taken from
+ *   the originating DOM `PointerEvent`. Each physical pointer — mouse, each
+ *   touch, the stylus — gets its own handle slot. Events with no
+ *   `pointerId` (synthesized probes, programmatic drags, most tests) key to
+ *   `pointer-mouse`, so a single synthetic pointer behaves as it always has.
+ * - `multitouch` ongoing actions: `multitouch-<fingers>`.
+ * - Fallback for any other kind that triggers an ongoing invoker: `ongoing-<kind>`.
+ *
+ * ## Action-lookup miss behavior
+ * When the walk reaches a binding whose `actionId` has no entry in
+ * `ctx.actions.list()`, the dispatcher emits `console.warn` and returns
+ * `'unhandled'`. The user's input gesture falls through as if unmatched.
+ * This preserves input flow (nothing is swallowed silently) while flagging
+ * the misconfiguration at dev time.
+ */
+
+/**
+ * The in-flight handle slot a pointer's gestures key into.
+ *
+ * Exported because the React seam (`useGestureDispatcher`) has to name the
+ * same slot when it asks `dispatcher.inFlight()` whether a given pointer is
+ * mid-drag. That used to be the string literal `'pointer-mouse'` on both
+ * sides, which was correct only because `gestureIdFor` ignored the pointer id
+ * entirely — the two lies cancelled out.
+ *
+ * @param pointerId - `PointerEvent.pointerId`, or `undefined` for a
+ *   synthesized event with no originating DOM pointer.
+ */
+declare function pointerGestureId(pointerId: number | undefined): string;
 /** Build a dispatcher. `getAction` overrides how action ids are resolved;
  *  by default the `DispatcherContext`'s registry is used. */
 declare function createDispatcher(opts?: {
@@ -1998,7 +2091,9 @@ interface ActionsRegistry {
     /** Fire an immediate-invoker action by id. The optional `params` arg is
      *  forwarded to `ImmediateInvoker.run` as its second argument — use it for
      *  parametric actions (e.g. `trigger('tool.activate', { toolId: 'rect' })`).
-     *  Ongoing-invoker actions are not reachable from `trigger`. */
+     *  Returns whether it ran one: `false` for an unknown id, and for an
+     *  ongoing-invoker action, which `trigger` cannot reach (see `begin`). It
+     *  does not ask `enabled`. */
     trigger(id: string, params?: Record<string, unknown>): boolean;
     /**
      * Subscribe to registry mutations. The callback fires after any
@@ -2023,13 +2118,22 @@ interface ActionsRegistry {
      *  Returns a release that takes out only this dispatcher; a `null` wires
      *  nothing. */
     setDispatcher(d: Dispatcher | 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. */
+    /** Make this registry's scope the one chrome above it reaches, and the one
+     *  keys go to: `trigger`, `begin` and `list` on any ancestor then answer from
+     *  here. A dispatcher calls it on the pointerdown and wheel that land in its
+     *  scope; moving DOM focus alone does not. */
     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. */
+    /** Whether a lookup made from the root of this registry's tree starts here.
+     *  A dispatcher with no canvas to press in asks this before handling a
+     *  keystroke. */
     isActive(): boolean;
+    /** Whether this registry's scope is the one last activated on the page, in
+     *  any tree: the question a canvas's dispatcher asks before handling a key
+     *  or a paste that reached the page. No scope holds the keys before the
+     *  first activation. */
+    holdsKeys(): boolean;
+    /** Let go of the keys if this scope holds them, as its canvas unmounts. */
+    dropKeys(): void;
 }
 /** Validate that `id` is usable as an action id in the route grammar.
  *  Rejects ids that start with a reserved sigil (would shadow future
@@ -2060,6 +2164,12 @@ declare function offhandKeyFor(trigger: HotkeyTrigger): string;
  *  `opts.params.toolId` so the invoker's `start` can pick out which tool
  *  to engage. */
 declare function buildToolOffhandBindings(specs: readonly ToolOffhandBindingSpec[]): BoundGesture[];
+/** The `key-held` spec for holding `key` (a `KeyboardEvent.key`, or several).
+ *  A modifier key gets every modifier optional, since its own keydown reports
+ *  its flag set. Any other key engages with Shift or Alt already down and not
+ *  with Cmd or Ctrl, so a letter trigger leaves its browser chord alone.
+ *  Every hold-a-key binding builds its spec here, so that rule has one home. */
+declare function heldKeySpec(key: string | string[]): KeyHeldSpec;
 /** Build the consolidated `tool.offhand` action — "hold a key to engage a
  *  secondary tool" (e.g. Space-for-hand). `bindings` enumerates one
  *  `{ spec: keyHeld, opts: { params: { toolId } } }` per tool; the invoker
@@ -2070,7 +2180,7 @@ declare function makeToolOffhandAction(bindings: BoundGesture[]): Action;
 
 /**
  * Named predicates for `defaultBinding.target.kindOf`. Each matches the
- * existing `kindOf` signature `(target: unknown, bodyTarget?: string) => boolean`
+ * `TargetPredicate` shape, declaring whether it reads the hit,
  * so they drop into action descriptors without a wrapper:
  *
  *     target: { kindOf: isAnchor }
@@ -2079,10 +2189,9 @@ declare function makeToolOffhandAction(bindings: BoundGesture[]): Action;
  * a new predicate here is what enables every action that needs the same
  * shape to read it. Drift prevention.
  */
-/** A predicate that resolves from `bodyTarget` alone. The exclusive-claim
- *  filter reads `readsAffordance`: without it a body predicate looks like it
- *  consults the hit, and survives a claim that should have barred it. */
-type BodyPredicate = ((target: unknown, bodyTarget?: string) => boolean) & {
+
+/** A predicate that resolves from `bodyTarget` alone. */
+type BodyPredicate = TargetPredicate & {
     readsAffordance: false;
 };
 /** Matches any body hit — selected or unselected node body. */
@@ -2094,15 +2203,25 @@ declare const isUnselectedBody: BodyPredicate;
 /** Empty-canvas hit — no node beneath cursor. */
 declare const isEmpty: BodyPredicate;
 /** Any corner resize handle — top-left/top-right/bottom-left/bottom-right. */
-declare const isResizeHandle: (target: unknown) => boolean;
+declare const isResizeHandle: TargetPredicate & {
+    readsAffordance: true;
+};
 /** The rotate-around-center handle above the bounding box. */
-declare const isRotateHandle: (target: unknown) => boolean;
+declare const isRotateHandle: TargetPredicate & {
+    readsAffordance: true;
+};
 /** Any path anchor (the on-curve dot). */
-declare const isAnchor: (target: unknown) => boolean;
+declare const isAnchor: TargetPredicate & {
+    readsAffordance: true;
+};
 /** Either control handle (controlIn or controlOut). */
-declare const isControlHandle: (target: unknown) => boolean;
+declare const isControlHandle: TargetPredicate & {
+    readsAffordance: true;
+};
 /** Any of the three anchor-editing affordances (anchor + both controls). */
-declare const isAnchorOrControl: (target: unknown) => boolean;
+declare const isAnchorOrControl: TargetPredicate & {
+    readsAffordance: true;
+};
 
 /**
  * The long-press the gesture dispatcher is timing, as observable state: where
@@ -2181,6 +2300,7 @@ interface LongPressOptions {
      */
     haptics?: boolean;
 }
+/** A store holding the press currently being held, or none. Pass it as `LongPressOptions.state`. */
 declare function createLongPressStore(): LongPressStore;
 
 /**
@@ -2265,6 +2385,29 @@ declare function liveScope(id: string, eligibility: Eligibility, state: Eligibil
  * of two same-specificity bindings in one tier wins.
  */
 declare function scopeBindings(entries: Iterable<Contribution<unknown>>, state: EligibilityState): ScopedBinding[];
+/** What decides which entries are live, and in what order they are walked. */
+interface AssemblyInputs {
+    focusedId: string | null;
+    /** Ids held by a hotkey, oldest first, as the active-tool context keeps them. */
+    hotkeyStack: readonly string[];
+    /** The capability tags the active mode allows. Omitted: no mode system, so
+     *  every entry is allowed. */
+    allowedCapabilities?: ReadonlySet<CapabilityTag>;
+}
+/**
+ * The entry set as routing walks it, with the state that tiers it. The
+ * dispatcher's bindings and a canvas's tool overlays both come from here, so a
+ * tool the dispatcher would not route to is never drawn, and two held tools
+ * stack in one order.
+ *
+ * Held entries lead, newest hold first: the top of the stack is the one every
+ * reader treats as engaged, so it wins a tie within the hotkey tier. A tagged
+ * entry is live only while the mode allows every one of its tags.
+ */
+declare function assembleEntries<T extends Contribution<unknown>>(entries: Iterable<T>, inputs: AssemblyInputs): {
+    ordered: T[];
+    state: EligibilityState;
+};
 
 /**
  * Concatenate contribution bundles into one registry, preserving order —
@@ -2315,9 +2458,8 @@ declare function modeShortcutSpec(shortcut: string): KeySpec;
 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 —
+ * A tool's activation key, as `ToolDef.keybinding` declares it. Captures
+ * only the fields meaningful to a tool-select key —
  * dispatcher-internal fields (`skipInEditable`, `enabled`,
  * `preventDefault`) live on `KeyBinding` in keyHelpers.ts and are
  * not part of the configurable surface.
@@ -2388,13 +2530,10 @@ type ToolBounds = Bounds;
  * 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). */
+    /** The key that activates this tool. `useKeybindings` appends a binding
+     *  entry for it to the consolidated `tool.activate` action (with
+     *  `opts.params.toolId` set so the invoker knows which tool to switch to).
+     *  A tool with none has no activation key. */
     keybinding?: ToolKeybinding;
     initScratch?: () => TScratch;
     cursor?: CursorSpec | ((ctx: ToolCtx<TScratch>) => CursorSpec);
@@ -2637,8 +2776,10 @@ interface Conflict {
  *  - Broad vs. narrow targets (e.g. an untargeted `click` alongside
  *    `click` on `empty`) — the dispatcher's specificity ordering resolves
  *    those cleanly, and the broad one is usually the intended fallback.
- *  - Different modifier requirements on the same target — they fire on
- *    different inputs.
+ *  - Modifier requirements no one press satisfies at equal rank: Shift
+ *    required against Alt required fire on different inputs, and Shift
+ *    required outranks Shift optional. An optional modifier against a
+ *    forbidden one is flagged, since both take the bare press.
  *  - A binding whose action declines via `enabled()` so a lower-priority
  *    one can take the gesture. Detecting that intent would mean evaluating
  *    the action; consumers can suppress known-intentional compositions in
@@ -2657,7 +2798,7 @@ interface Conflict {
  *    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}.
+ *    ranked in any one view. See `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
@@ -2665,7 +2806,7 @@ interface Conflict {
  *
  *  This is the raw same-tuple detector. Feeding it a whole tool *registry*
  *  over-reports, because registry tools take turns in the active slot and
- *  can't collide with each other — see {@link findScopedConflicts}.
+ *  can't collide with each other — see `findScopedConflicts`.
  */
 declare function findConflicts(entries: readonly Contribution<unknown>[]): Conflict[];
 /**
@@ -2872,9 +3013,41 @@ declare function clientToCanvasRect(rect: {
     top: number;
 }, clientX: number, clientY: number): [number, number];
 
+/**
+ * Namespaced, opt-in console tracing for the kit.
+ *
+ * Enable in the browser:
+ *
+ *   localStorage.setItem('weasel.debug', '*')                 // all namespaces
+ *   localStorage.setItem('weasel.debug', 'tools,dispatch')    // specific ones
+ *   localStorage.setItem('weasel.debug', '1')                 // legacy "all"
+ *
+ * Each call site picks a stable namespace string. Off by default; the flag
+ * is read once and cached per page session — reload to pick up a change.
+ *
+ * The one definition: `@weasel-js/core` and `@weasel-js/ui` pass these on, so
+ * every package reads the flag from one cache.
+ *
+ * Known kit namespaces:
+ *   - tools           — active-tool + hotkey transitions (useTools)
+ *   - dispatch        — gesture start / end / cancel (dispatcher)
+ *   - drag-rect       — useDragRect lifecycle
+ *   - drag-radial     — useDragRadial lifecycle
+ *   - scene           — restored-op replay gaps (history persistence)
+ *   - scene-canvas    — SceneCanvas mount / unmount; adapter paste-translation warnings
+ *   - history         — applyOps push, no-op suppression, serialize/restore
+ *   - clipboard       — OS clipboard write/read failures, malformed payloads
+ */
+/** True when `namespace` (or `*`) is enabled. Pass no argument to test
+ *  whether *any* namespace is on (legacy global-flag semantics). */
+declare function isDebugEnabled(namespace?: string): boolean;
 /** Conditional `console.debug` — no-op unless `namespace` (or `*`) is enabled.
  *  Each call is prefixed with `[namespace]` so the source is searchable. */
 declare function dlog(namespace: string, ...args: unknown[]): void;
+/** Conditional `console.warn` — like `dlog` but at warn level. Use for
+ *  diagnostics that indicate something worth surfacing during debugging
+ *  (e.g. no-op op batches suppressed). */
+declare function dwarn(namespace: string, ...args: unknown[]): void;
 
 /**
  * @weasel-js/routing — binding-to-action routing.
@@ -2889,10 +3062,11 @@ declare function dlog(namespace: string, ...args: unknown[]): void;
  * `Action.requires`, `DepRegistry.register`/`get` and `useDepSource` are all
  * keyed on.
  *
- * It is declared **empty** here on purpose. Routing knows that an action names
- * its dependencies and that the registry resolves them at invocation time; it
- * does not know what a selection, a scene or a viewport is. Whoever supplies
- * those merges them in:
+ * It declares one entry, `activeTool`, because the value and the action that
+ * requires it (`tool.offhand`) are both routing's. Routing knows that an
+ * action names its dependencies and that the registry resolves them at
+ * invocation time; it does not know what a selection, a scene, or a viewport
+ * is. Whoever supplies those merges them in:
  *
  * ```ts
  * declare module '@weasel-js/routing' {
@@ -2900,7 +3074,7 @@ declare function dlog(namespace: string, ...args: unknown[]): void;
  * }
  * ```
  *
- * `@weasel-js/core` merges the kit's own 24 deps this way and re-exports
+ * `@weasel-js/core` merges the kit's own deps this way and re-exports
  * `DepSchema`, so a consumer adds its own against `'@weasel-js/core'` and
  * never has to know this module exists. The merge carries through the
  * re-export in both directions — `scripts/smoke-consumer-bundle.mjs` asserts
@@ -2909,6 +3083,8 @@ declare function dlog(namespace: string, ...args: unknown[]): void;
  * both files into one chunk.
  */
 interface DepSchema {
+    /** Currently active tool id + hotkey-hold stack. */
+    activeTool: ActiveToolContextValue;
 }
 /** Every dep name declared by anything that has merged into {@link DepSchema}. */
 type DepName = keyof DepSchema;
@@ -2933,4 +3109,4 @@ type KernelOverlay = OverlaySchema extends {
     overlay: infer O;
 } ? O : unknown;
 
-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, buildDepsFromRequires 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 Selector as aG, type SpecificityPart as aH, TOOL_OFFHAND_ID as aI, type Tool as aJ, type ToolBounds as aK, type ToolCtx as aL, type ToolDef as aM, type ToolKeybinding as aN, type ToolLifecycleCtx as aO, type ToolModifiers as aP, type ToolOffhandBindingSpec as aQ, type ToolPresentation as aR, type ToolSlot as aS, type TraceLogEntry as aT, type UiOngoingControl as aU, type View as aV, type ViewportGestureKind as aW, type WalkStep as aX, actionBindings as aY, actionItems as aZ, activatesFocusedControl 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, buildRouteRegistry as b0, buildRuleCtx as b1, buildToolOffhandBindings as b2, clientToCanvas as b3, clientToCanvasRect as b4, createDepRegistry as b5, createDispatcher as b6, createLongPressStore as b7, defineTool as b8, deleteScratch 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, describeRule as ba, dlog as bb, evaluate as bc, evaluateEnabled as bd, findConflicts as be, getScratch as bf, historyKey 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 };
+export { type DispatchRecord as $, type ActionsRegistry as A, type BindingOpts as B, type Contribution as C, type DepRegistry as D, type BindingScope as E, type BindingSource as F, type BodyPredicate as G, type BoundGesture as H, type Bounds as I, type BuildRuleCtxArgs as J, type KernelOverlay as K, type LongPressOptions as L, COARSE_TARGET_SCALE as M, type Condition as N, type OverlayPosition as O, type Conflict as P, type ContributionChrome as Q, type RuleCtx as R, ScopeNode as S, ToolNode as T, type ContributionDeps as U, type ContributionRouting as V, DEFAULT_ALLOWED_CAPABILITIES as W, DEFAULT_DEVICE_PROFILE as X, type DebugSink as Y, type DetectedDeviceFacts as Z, type DeviceProfile as _, type DepName as a, type TraceLogEntry as a$, type DispatchRecordInput as a0, type DispatcherContext as a1, type DragSample as a2, type DroppedCandidate as a3, type Eligibility as a4, type EligibilityState as a5, type GestureBinding as a6, type HandleKind as a7, type HitShape as a8, type HotkeyTrigger as a9, type PointerSessionCancelReason as aA, type PointerSessionOptions as aB, type RankedCandidate as aC, type RecordCandidate as aD, type RegistryEntry as aE, type ResizeAnchor as aF, type ResolveAllOptions as aG, type ResolveOnlyResult as aH, type ResolvedCandidate as aI, type Rule as aJ, type ScopedBinding as aK, type ScratchKey as aL, type ScratchStore as aM, type SelectionApi as aN, type Selector as aO, type SpecificityPart as aP, TOOL_OFFHAND_ID as aQ, type Tool as aR, type ToolBounds as aS, type ToolCtx as aT, type ToolDef as aU, type ToolKeybinding as aV, type ToolLifecycleCtx as aW, type ToolModifiers as aX, type ToolOffhandBindingSpec as aY, type ToolPresentation as aZ, type ToolSlot as a_, INGEST_STRING_MIMES as aa, type ImmediateInvoker as ab, type InvocationCtx as ac, type Invoker as ad, type KeyBinding as ae, LONG_PRESS_MS as af, type LongPressState as ag, type LongPressStore as ah, type MatchOutcome as ai, type MatchResult as aj, type ModeShortcutHandlers as ak, type ModeSwitchLogEntry as al, type ModifierState as am, NEVER as an, type NodeId as ao, type OngoingHandle as ap, type OngoingInvoker as aq, type OngoingOverlay as ar, type OverlayRole as as, type OverlaySchema as at, PREDICATE_TARGET as au, type PendingLongPress as av, type PlacedBy as aw, type Point2 as ax, type PointerSession as ay, type PointerSessionCallbacks as az, type DepSchema as b, scratchKey as b$, type UiOngoingControl as b0, type ViewportGestureKind as b1, type WalkStep as b2, actionBindings as b3, actionItems as b4, activatesFocusedControl as b5, assembleEntries as b6, buildDepsFromRequires as b7, buildRouteRegistry as b8, buildRuleCtx as b9, isRotateHandle as bA, isSelectedBody as bB, isTool as bC, isUnselectedBody as bD, itemsFromClipboardData as bE, itemsFromDataTransfer as bF, itemsFromFiles as bG, liveScope as bH, makeToolOffhandAction as bI, matchBest as bJ, matchSorted as bK, matchSortedWithBarred as bL, matchesKeyBinding as bM, mergeContributions as bN, modeShortcutSpec as bO, modeShortcuts as bP, offhandKeyFor as bQ, openPointerSession as bR, pointerGestureId as bS, recordModeSwitch as bT, reportRouteConflicts as bU, resolveDeviceProfile as bV, resolveParams as bW, routesForSpec as bX, ruleCanHoldIn as bY, rulesExclusive as bZ, scopeBindings as b_, buildToolOffhandBindings as ba, clientToCanvas as bb, clientToCanvasRect as bc, createDepRegistry as bd, createDispatcher as be, createLongPressStore as bf, defineTool as bg, deleteScratch as bh, describeRule as bi, dlog as bj, dwarn as bk, evaluate as bl, evaluateActive as bm, evaluateEnabled as bn, findConflicts as bo, getScratch as bp, heldKeySpec as bq, historyKey as br, isAnchor as bs, isAnchorOrControl as bt, isBody as bu, isControlHandle as bv, isDebugEnabled as bw, isEditableTarget as bx, isEmpty as by, isResizeHandle as bz, type Action as c, setScratch as c0, targetConsultsAffordance as c1, validateActionDefaultBinding as c2, validateActionId as c3, DepNode as d, type AnyToolOf as e, ActiveToolContextProvider as f, ActiveToolContextProviderIfRoot as g, type ActiveToolContextProviderProps as h, type ActiveToolContextValue as i, useOptionalActiveToolContext as j, type Dispatcher as k, type AffordanceHit as l, ALWAYS as m, type ActionDeps as n, ActionDisabledReason as o, type ActionDispatch as p, type ActionEnabledResult as q, type ActionEntry as r, type ActionItem as s, type ActionPresentation as t, useActiveToolContext as u, type ActionSource as v, type ActionVariant as w, type ActionsProp as x, type AnyTool as y, type AssemblyInputs as z };