@weasel-js/routing 1.6.1 → 1.7.1

package/dist/react.d.ts

@@ -1,296 +1,65 @@
-import { D as Dispatcher, A as ActionsRegistry, T as Tool, a as AffordanceHit, R as RuleCtx, b as DepSchema, c as Action, d as AnyToolOf, O as OverlayPosition, C as Contribution, S as ScopedBinding } from './index-CKmbNpwl.js';
-export { e as DepRegistry, f as DepRegistryProvider, u as useDepRegistry, g as useDepSource, h as useOptionalDepRegistry } from './index-CKmbNpwl.js';
+export { D as DispatcherChannels, U as UseGestureDispatcherOptions, u as useGestureDispatcher } from './internal--mYnGecm.js';
 import * as react from 'react';
-import { RefObject, ReactNode, ReactElement } from 'react';
-import { BodyClassification } from '@weasel-js/gestures';
-import { PaintedCursorState } from '@weasel-js/cursor';
-import '@weasel-js/modes';
+import { ReactNode, ReactElement } from 'react';
+import { D as DepRegistry, a as DepName, b as DepSchema, S as ScopeNode, A as ActionsRegistry, c as Action, d as DepNode, K as KernelOverlay, C as Contribution, e as AnyToolOf, O as OverlayPosition, f as ScopedBinding } from './index-BV53gfyB.js';
+import { ModeRegistry } from '@weasel-js/modes';
+import '@weasel-js/gestures';
+import '@weasel-js/cursor';
 import '@weasel-js/history';
 
+/** Provides the dep registry for a canvas. `<SceneCanvas>` mounts one; a
+ *  consumer registering its own dep sources must be inside it. */
+declare function DepRegistryProvider({ children }: {
+    children: ReactNode;
+}): react.JSX.Element;
+/** The dep registry in scope. Throws outside a `<DepRegistryProvider>`. */
+declare function useDepRegistry(): DepRegistry;
 /**
- * Everything about handling an input event that depends on *which view* it
- * landed in: the dispatcher that runs it, and the three lookups that resolve
- * a client point against that view's camera.
- *
- * @internal One per view. The hook builds the `id: null` one from its flat
- *   options; `views` supplies the rest, and the hook chooses between them per
- *   event, so that it — and its listener set — still mounts exactly once.
- */
-interface DispatcherViewTarget {
-    /** `null` is the root view — the whole canvas. Matches `ViewTarget.id`. */
-    id: string | null;
-    dispatcher: Dispatcher;
-    affordanceAt: UseGestureDispatcherOptions['affordanceAt'];
-    classifyTarget: UseGestureDispatcherOptions['classifyTarget'];
-    clientToWorld: UseGestureDispatcherOptions['clientToWorld'];
-    /**
-     * The deps this view answers for itself — its camera, its selection, and
-     * whatever else is per-view rather than per-canvas. Read per event; every
-     * name it does not carry still resolves through the canvas registry.
-     *
-     * This is why a view does not get a `DepRegistryProvider` of its own. The
-     * registry is where a consumer registers *sources*, and one per view would
-     * fragment that: a consumer overriding `insert` would have to know how many
-     * views exist and override each. An overlay keeps one place to register and
-     * one authority per dep, with the view claiming only what is genuinely its.
-     *
-     * Without this a gesture inside a panel pans the whole canvas and selects
-     * into the canvas's selection — correct coordinates alone do not make
-     * routing correct.
-     */
-    deps?: () => Partial<DepSchema>;
-    /**
-     * This view's chrome-caps rule context, for the eligibility filter. The rule
-     * table is the surface's, but a rule keyed on selection or the in-flight
-     * action answers per view — so an action hidden in one panel must not
-     * decline a gesture in another. `undefined` means "nothing gates here", the
-     * same answer a surface with no mode registry gives.
-     */
-    getRuleCtx?: () => RuleCtx | undefined;
-}
-/**
- * The part of `features/viewports`' `ViewResolver` the dispatcher needs: which
- * view a client point belongs to, pinned to the view a gesture began in.
- *
- * @internal Structural on purpose — a `ViewResolver` satisfies it, and the
- *   dispatcher stays free of the viewport module.
- */
-interface ViewIdResolver {
-    begin(pointerId: number, clientX: number, clientY: number): {
-        id: string | null;
-    };
-    at(pointerId: number | null, clientX: number, clientY: number): {
-        id: string | null;
-    };
-    end(pointerId: number): void;
-}
-/** Per-channel switches for the listeners `useGestureDispatcher` attaches to
- *  the canvas element. Omitted or `true` attaches the channel. */
-interface DispatcherChannels {
-    /** `pointerdown`, hover `pointermove`, `pointerleave` — press, drag, click,
-     *  long-press, multi-touch and the hover-cursor pump. */
-    pointer?: boolean;
-    /** `wheel`. */
-    wheel?: boolean;
-    /** WebKit's `gesturestart` / `gesturechange` / `gestureend` — Safari's
-     *  trackpad pinch, dispatched as `pinch` events. */
-    pinch?: boolean;
-    /** `contextmenu`. Off leaves the browser's native menu in place. */
-    contextMenu?: boolean;
-    /** OS drop on the element plus `paste` on the window. Off leaves the
-     *  element a non-drop-target and stops `weasel-dropover` being applied. */
-    ingest?: boolean;
-}
-/** Options for `useGestureDispatcher`: the element to listen on, the actions
- *  and tools in play, and the hooks that turn raw DOM events into the world
- *  coordinates and hit targets bindings match against. */
-interface UseGestureDispatcherOptions {
-    /** Ref to the canvas element. Pointer/wheel/multitouch listeners attach here. */
-    canvasRef: RefObject<HTMLElement | null>;
-    /** Action registry (ActionsRegistry from registry.tsx). */
-    actions: ActionsRegistry;
-    /** Tool definitions keyed by id. Typically passes an empty Map. */
-    toolsById: ReadonlyMap<string, Tool>;
-    /** Default true. Set false to opt out of dispatcher wiring (e.g. demos that disable it). */
-    enabled?: boolean;
-    /**
-     * Observer fired whenever the dispatcher synthesizes a double click, in
-     * world coordinates. Runs BEFORE the event is dispatched and independently
-     * of which binding (if any) handles it.
-     *
-     * This is deliberately not an Action. `<SceneCanvas onDoubleClick>` is a
-     * notification — "the user double-clicked, here's what they hit" — and a
-     * notification must not compete with behavior for the gesture. As a binding
-     * it would lose to `enterPathEdit` on any body hit and silently never fire.
-     * Routing it here keeps a single definition of "double click" (the point of
-     * consolidating the kit's three detectors) without giving it
-     * first-match-wins semantics it shouldn't have.
-     */
-    onDoubleClick?: (world: {
-        x: number;
-        y: number;
-    }) => void;
-    /**
-     * Default true. Set false to leave the window `keydown`/`keyup` listeners
-     * unattached so keyboard-bound actions never dispatch — pointer, wheel, and
-     * contextmenu channels stay live. `<SceneCanvas>` wires this to
-     * `enableKeybindings`, so opting out of keybindings disables the modern
-     * dispatcher key path as well as the legacy `useKeybindings` hook.
-     */
-    keyboard?: boolean;
-    /**
-     * Optional affordance classifier. Called with the **world** coordinates of
-     * the pointer — this hook applies the routed view's `clientToWorld` before
-     * calling it, the same conversion that produces `InputEvent.x`/`y`, so a
-     * consumer hit-tests in one space. Returns an `AffordanceHit` when the
-     * pointer lands on a known affordance (resize handle, rotate handle, etc.)
-     * or `null` when the pointer hit open canvas.
-     *
-     * The hit is packed into `InputEvent.pointerdown.affordance` and flows
-     * through into `InvocationCtx.drag.affordance`. Action invokers that require
-     * a specific affordance (e.g. `resizeAction` requires `handle:*`) use this
-     * field as a guard in their `start` body.
-     *
-     * When omitted, `affordance` is always `undefined` — meaning only consumers
-     * that explicitly wire a classifier get affordance-gated behavior.
-     * `<SceneCanvas>` wires the full chrome→dispatcher bridge.
-     */
-    affordanceAt?: (worldPoint: {
-        x: number;
-        y: number;
-    }) => AffordanceHit | null;
-    /**
-     * Optional body classifier. Called on every pointerdown with the world-space
-     * coordinates of the pointer. Its result is packed onto the event as
-     * `bodyTarget` + `bodyKind`, which `matchTarget` reads to resolve the
-     * string-form `TargetSpec` values in `Tool.bindings`.
-     *
-     * `body` is `'empty'` when nothing is under the pointer, `'selected-body'`
-     * when the topmost hit belongs to the current selection, or
-     * `'unselected-body'` when it belongs to a node that isn't selected. `kind`
-     * is the hit node's semantic kind, when the scene can name it.
-     *
-     * When omitted, every body-derived target form (`'empty'`,
-     * `'selected-body'`, `'unselected-body'`, `kind:<k>`, `kind:<k>:selected`)
-     * never matches — bindings using those specs are silently skipped.
-     * `<SceneCanvas>` wires this.
-     *
-     * World coordinates, on every path, for the same reason as `affordanceAt`.
-     */
-    classifyTarget?: (worldPoint: {
-        x: number;
-        y: number;
-    }) => BodyClassification;
-    /**
-     * Optional pre-created `Dispatcher`. When provided, this hook pumps events
-     * into the supplied instance instead of creating its own. Lets a parent
-     * scope (e.g. `<SceneCanvas>`) share one dispatcher between the gesture
-     * mounter and other consumers (the preview-ghost layer).
-     */
-    dispatcher?: Dispatcher;
-    /**
-     * Converts a client-space pointer position (e.g. `e.clientX`, `e.clientY`)
-     * to world-space coordinates. When supplied, every pointer/wheel event's
-     * `x`/`y` is converted before the dispatcher builds `InvocationCtx.world`.
-     *
-     * Without this, `ctx.world` is populated with the raw client coords, which
-     * silently breaks any action whose overlay/output uses absolute world
-     * positions (marquee, lasso polyline, world-space affordances). Actions
-     * that only read `drag.delta` are unaffected because client→world deltas
-     * are equal at scale 1, but as soon as a consumer pans/zooms the view the
-     * deltas diverge too.
-     *
-     * `<SceneCanvas>` always wires this via its canvas rect + current view.
-     * Tests / harnesses without a view can omit it and continue passing raw
-     * coordinates as before.
-     */
-    clientToWorld?: (clientX: number, clientY: number) => {
-        x: number;
-        y: number;
-    };
-    /**
-     * Invoked once per pump event (`pointermove`, `pointerup`, `pointercancel`,
-     * `key-held` up-phase, `multitouch` move) when a dispatcher-side handle is
-     * in flight. Lets the host canvas schedule a redraw so dispatcher-only
-     * overlays (marquee, lasso, preview-ghost) repaint on each frame.
-     *
-     * Required because dispatcher actions don't go through the legacy
-     * `tools.dispatcher.onGestureChange` redraw bump that ambient tool drags
-     * relied on. Without it, the overlay layer's `draw` never runs between
-     * pointerdown and pointerup, and the chrome flashes once at gesture start
-     * and then sits frozen until the gesture ends.
-     *
-     * `<SceneCanvas>` wires this to the canvas's `requestRedraw`. Test
-     * harnesses can omit it; their dispatchers won't paint between events but
-     * that's already the test contract.
-     */
-    requestRedraw?: () => void;
-    /**
-     * The surface's painted-cursor channel, read live because the canvas handle
-     * it lives on arrives a render after this hook runs.
-     *
-     * Given one, a cursor the CSS tier cannot express — sized in world units, or
-     * past the size the browser drops the image at — is published here and drawn
-     * by the painted-cursor layer instead. Without one, such a cursor resolves to
-     * `none` and the pointer shows nothing.
-     */
-    paintedCursor?: () => PaintedCursorState | undefined;
-    /**
-     * Thunk returning the live `RuleCtx` for the current frame. When supplied,
-     * the dispatcher filters matched candidates by their declared
-     * `Action.eligible` rule (omitted => always eligible). `<SceneCanvas>`
-     * wires this; tests / harnesses without chrome-caps state can omit it.
-     */
-    getRuleCtx?: () => RuleCtx | undefined;
-    /**
-     * Which of the canvas element's input channels to attach. Every one
-     * defaults to `true`; naming a channel `false` leaves its listeners
-     * unattached, so the element behaves as if the dispatcher were not there.
-     *
-     * A mount that binds two gestures should not also have to take the rest of
-     * the pipeline's side effects: `contextMenu` suppresses the native menu
-     * unconditionally, and `ingest` makes the element a valid drop target and
-     * styles it while an OS drag hovers. `@weasel-js/labkit`'s loupe mounts on
-     * a lab's own canvas host for a wheel and a held key, and turning the other
-     * three off is what keeps right-click and file drops working there.
-     *
-     * The window keyboard channel is `keyboard` instead of an entry here,
-     * because `<SceneCanvas enableKeybindings>` drives it.
-     */
-    channels?: DispatcherChannels;
-    /**
-     * Routing for a canvas hosting more than one view: the non-root dispatch
-     * records to choose between, read fresh per event, and the resolver that
-     * chooses. Omit for a single view — then every event runs on the record the
-     * flat options above describe, which is what they are: view zero.
-     *
-     * A resolved id with no live record falls back to the root, so a view that
-     * unmounts mid-gesture degrades instead of dropping the event.
-     *
-     * Keyboard and paste have no coordinates to resolve; they run on the view
-     * the last coordinate-bearing event resolved to.
-     *
-     * @internal
-     */
-    views?: {
-        targets: () => readonly DispatcherViewTarget[];
-        resolver: ViewIdResolver;
-    };
-}
-/**
- * Attach the input pipeline to a canvas: DOM pointer, wheel, keyboard and
- * multitouch listeners in, normalized input events out, routed through the
- * dispatcher to whichever action a binding names.
- *
- * Everything it needs beyond its options — the active tool, the dep registry —
- * comes from context, so it must be mounted inside `<SceneCanvas>`'s
- * providers.
+ * 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 useGestureDispatcher(opts: UseGestureDispatcherOptions): void;
+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;
 
 /**
- * @experimental
- * The React half of the actions registry: the context, the provider that owns
- * the id → descriptor stack, the mute scope, and the two hooks. The store
- * contract it implements is in `registry.tsx`.
+ * One node of the actions tree: the actions registered at it, over its
+ * parent's. Each id holds a stack of registrants, newest live, so a displaced
+ * registrant is restored when the one above it leaves. Every read the registry
+ * answers — `list`, `trigger`, `begin` — starts at the node's leaf.
  */
-
+declare class ActionsNode extends ScopeNode<ActionsNode> {
+    private readonly contextDeps;
+    private readonly actions;
+    private readonly muted;
+    private readonly dispatchers;
+    private cache;
+    /** Called on `activate`, so a scope's dep and tool nodes move with it. */
+    readonly onActivate: (() => void)[];
+    constructor(parent: ActionsNode | null, descends: boolean, contextDeps: () => DepRegistry | null);
+    private resolve;
+    private snapshot;
+    private deps;
+    private dispatcher;
+    activate(): void;
+    readonly registry: ActionsRegistry;
+}
 /**
  * @experimental
- * A view of the registry in scope that can declare ids not for itself. Wrap
- * anything that should be able to opt out of an action — a second
- * `<SceneCanvas>` sharing the host's `<ActionsProvider>` mounts one — and its
- * `mute` calls stay inside it. Renders nothing of its own.
- *
- * Not a `BindingScope`: that names the tier a binding matches at (hotkey /
- * active / ambient), which this has nothing to do with.
+ * Mounts a root `ActionsRegistry` for its lifetime. Children call
+ * `useActionsRegistry()` or `useAction()` to participate. Mounts no input
+ * listener of its own — the gesture dispatcher owns input.
  */
-declare function ActionsScope({ children }: {
-    children: ReactNode;
-}): ReactElement;
 declare function ActionsProvider({ children }: {
     children: ReactNode;
 }): ReactElement;
+/**
+ * @experimental
+ * Returns the `ActionsRegistry` in scope, or `null` when there is none.
+ */
 declare function useActionsRegistry(): ActionsRegistry | null;
 /**
  * @experimental
@@ -301,42 +70,15 @@ declare function useActionsRegistry(): ActionsRegistry | null;
  */
 declare function useAction(action: Action): void;
 
-/**
- * One UI control's hold on an ongoing action — the handle a color picker, a
- * slider or a swatch drives the action through, the way a drag drives one
- * through a gesture.
- *
- * - `input(params)` opens the action on the first call and moves it on every
- *   later one: the live preview.
- * - `commit(params?)` moves it to `params`, if given, and ends it as one
- *   undoable edit. With nothing open, a commit carrying params is a whole edit
- *   on its own — a click on a swatch, a switch of paint kind.
- * - `cancel()` ends an open edit without keeping it.
- *
- * All three are no-ops when no action is reachable, so a control renders the
- * same with or without a canvas in scope.
- */
-interface OngoingAction {
-    input(params: Record<string, unknown>): void;
-    commit(params?: Record<string, unknown>): void;
-    cancel(): void;
-}
-/**
- * Drive the ongoing action `actionId` from a UI control: {@link OngoingAction}.
- *
- * An edit left open when the control unmounts, or when `actionId` changes, is
- * committed — it is what the user was looking at when the control went away.
- * The returned object is stable for the life of the component.
- */
-declare function useOngoingAction(actionId: string): OngoingAction;
-
 /** 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 {
-    active: string;
+    /** 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): void;
+    setActive(id: string | null): void;
     pushHotkey(id: string): void;
     /**
      * Disengage a hotkey-held tool. With `id`, removes that tool's own entry
@@ -346,15 +88,33 @@ interface ActiveToolContextValue {
      */
     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;
-    initialActive?: string;
+    /** 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 active-tool state for a canvas. `<SceneCanvas>` mounts one. */
+/** 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
- *  `useActiveToolContextOptional` where one is not guaranteed. */
+ *  `useOptionalActiveToolContext` where one is not guaranteed. */
 declare function useActiveToolContext(): ActiveToolContextValue;
 /**
  * Like `useActiveToolContext`, but returns `null` when no
@@ -366,33 +126,127 @@ declare function useOptionalActiveToolContext(): ActiveToolContextValue | null;
 /**
  * Conditional `<ActiveToolContextProvider>` wrapper. Mounts a provider only
  * when no parent provider is in scope — otherwise renders children unwrapped
- * so callers (e.g. `<WeaselProvider>`, `<SceneCanvas>`) defer to the host's
- * existing scope. Mirrors `ActionsProviderIfRoot` / `DepRegistryProviderIfRoot`.
+ * so `<WeaselProvider>` defers to the host's existing scope.
  */
 declare function ActiveToolContextProviderIfRoot({ children, }: {
     children: ReactNode;
 }): react.JSX.Element;
 
+/**
+ * @experimental
+ * Input scopes and yokes: the tiers between a root registry and a canvas.
+ * Design: docs/proposals/2026-09-27-input-scopes.md.
+ */
+
+/** Props for `<InputScope>`. */
+interface InputScopeProps {
+    /** The yoke this scope joins. Omitted, it sits under the registries in
+     *  scope and keeps a tool of its own. */
+    yoke?: Yoke;
+    children: ReactNode;
+}
+/**
+ * @experimental
+ * One canvas's input: actions, deps and a tool of its own, under whichever
+ * registries are in scope (or its yoke's). What the canvas registers stays
+ * here; what it looks up is answered here first, then by the tiers above.
+ * With nothing in scope it is a root.
+ *
+ * Chrome above calls `trigger` / `begin` / `useActiveToolContext` on its own
+ * registries, and those reach the active scope: the one last activated — by a
+ * pointerdown or wheel — or the newest where none has been.
+ */
+declare function InputScope({ yoke, children }: InputScopeProps): ReactElement;
+/**
+ * @experimental
+ * Make a yoke for canvases to join, under the registries in scope where it is
+ * called. It lives as long as the calling component.
+ */
+declare function useYoke(): Yoke;
+/** Props for `<Yoke>`. */
+interface YokeProps {
+    value: Yoke;
+    children: ReactNode;
+}
+/**
+ * @experimental
+ * Canvases that share input on purpose: the active tool, the gesture in
+ * flight, history and yoke-wide actions. Made once with `useYoke()` where the
+ * sharing is decided, and passed to each canvas that joins it (`yoke={yoke}`)
+ * and to `<Yoke value={yoke}>` around anything else that should reach it — a
+ * toolbar, say. The members can sit anywhere in the tree: the handle, not the
+ * tree, says who shares.
+ */
+interface Yoke {
+    /** @internal */
+    readonly actions: ActionsNode;
+    /** @internal */
+    readonly deps: DepNode;
+    /** @internal */
+    readonly tools: ToolNode;
+}
+/**
+ * @experimental
+ * Put `value` in scope for what is not a canvas — a toolbar, a status bar — so
+ * its actions, deps and tool reads reach the yoke and, through it, the member
+ * canvas last used.
+ */
+declare function Yoke({ value, children }: YokeProps): ReactElement;
+
+/**
+ * One UI control's hold on an ongoing action — the handle a color picker, a
+ * slider or a swatch drives the action through, the way a drag drives one
+ * through a gesture.
+ *
+ * - `input(params)` opens the action on the first call and moves it on every
+ *   later one: the live preview.
+ * - `commit(params?)` moves it to `params`, if given, and ends it as one
+ *   undoable edit. With nothing open, a commit carrying params is a whole edit
+ *   on its own — a click on a swatch, a switch of paint kind.
+ * - `cancel()` ends an open edit without keeping it.
+ *
+ * All three are no-ops when no action is reachable, so a control renders the
+ * same with or without a canvas in scope.
+ */
+interface OngoingAction {
+    input(params: Record<string, unknown>): void;
+    commit(params?: Record<string, unknown>): void;
+    cancel(): void;
+}
+/**
+ * Drive the ongoing action `actionId` from a UI control: {@link OngoingAction}.
+ *
+ * An edit left open when the control unmounts, or when `actionId` changes, is
+ * committed — it is what the user was looking at when the control went away.
+ * The returned object is stable for the life of the component.
+ */
+declare function useOngoingAction(actionId: string): OngoingAction;
+
 /** Options for `useTools`: which tools exist, which one starts active, and
  *  which run continuously regardless of the active one. */
-interface UseToolsOptions<TOverlay = unknown> {
-    /** Initial active-slot tool id. Must exist in `registry`. */
-    active: string;
+interface UseToolsOptions<TOverlay = KernelOverlay> {
+    /** Initial active-slot tool id, which must exist in `registry`. Omit, or
+     *  pass `null`, for no active tool: only hotkey and ambient bindings run. */
+    active?: string | null;
     /** Tools eligible for the active slot or hotkey slot. The keys are the
      *  tool ids; the values are the tool records. A tool with `hotkey` set
      *  is wired into the hotkey slot whenever the engagement state matches. */
     registry: Record<string, AnyToolOf<TOverlay>>;
-    /** Always-on tools — listen continuously regardless of active slot. */
-    ambient?: AnyToolOf<TOverlay>[];
+    /** Always-on entries — tools or other contributions, live regardless of
+     *  the active slot. */
+    ambient?: readonly Contribution<TOverlay>[];
+    /** The modes the canvas can be in, read by the dev-time route-conflict
+     *  check; without a registry it checks against the kit's `DEFAULT_MODES`. */
+    modes?: ModeRegistry;
 }
 /** The tool registry's runtime surface: which tool is active, which is
  *  temporarily held by a hotkey, and how to change either. */
-interface ToolsApi<TOverlay = unknown> {
-    /** Current active-slot tool id. */
-    active: string;
-    /** Set the active-slot tool. The gesture dispatcher watches the active
-     *  tool and cancels any in-flight handle itself. */
-    setActive: (id: string) => void;
+interface ToolsApi<TOverlay = KernelOverlay> {
+    /** Current active-slot tool id, or `null` when no tool is active. */
+    active: string | null;
+    /** Set the active-slot tool, or `null` to clear it. The gesture dispatcher
+     *  watches the active tool and cancels any in-flight handle itself. */
+    setActive: (id: string | null) => void;
     /** Currently hotkey-engaged tool id (or `null`). Derived as the top of
      *  the hotkey stack for backwards compat with the pre-stack API. */
     hotkeyEngaged: string | null;
@@ -400,8 +254,8 @@ interface ToolsApi<TOverlay = unknown> {
     engageHotkey: (id: string) => void;
     /** Disengage the hotkey-slot tool, if any. */
     disengageHotkey: () => void;
-    /** All always-on tools, in registration order. */
-    ambient: readonly AnyToolOf<TOverlay>[];
+    /** All always-on entries, in registration order. */
+    ambient: readonly Contribution<TOverlay>[];
     /** Full registry — for userland UI (palette buttons, etc.). */
     registry: Readonly<Record<string, AnyToolOf<TOverlay>>>;
     /** Returns true if a tool with the given id is in the registry or ambient list. */
@@ -424,28 +278,35 @@ interface ToolsApi<TOverlay = unknown> {
  * lives in the context so the gesture dispatcher and any sibling
  * `useTools` calls all read the same source of truth.
  *
- * **First-mount-wins semantics**: if `opts.active` differs from the context
- * default (`'select'`) on first mount, `useTools` pushes `opts.active` to
- * the context. Subsequent mounts respect whatever the context currently
- * holds (the first caller wins).
+ * **First-mount-wins semantics**: if the context's slot is unseeded (no
+ * `initialActive`, nothing set yet) on first mount, `useTools` pushes
+ * `opts.active` to the context. Subsequent mounts respect whatever the
+ * context currently holds (the first caller wins).
  */
-declare function useTools<TOverlay = unknown>(opts: UseToolsOptions<TOverlay>): ToolsApi<TOverlay>;
+declare function useTools<TOverlay = KernelOverlay>(opts: UseToolsOptions<TOverlay>): ToolsApi<TOverlay>;
 
-interface UseContributionsOptions<TOverlay = unknown> {
+/** Options for {@link useContributions}. */
+interface UseContributionsOptions<TOverlay = KernelOverlay> {
     /** Every registry entry, in declaration order. Order decides which of two
      *  same-specificity bindings in one scope tier wins. */
     entries: readonly Contribution<TOverlay>[];
-    /** Desired focused entry id. First-mount-wins against the shared
-     *  `ActiveToolContext` — see `useTools` for the full semantics. */
-    focused: string;
+    /** Desired focused entry id, or `null` for none. First-mount-wins against
+     *  the shared `ActiveToolContext` — see `useTools` for the full semantics. */
+    focused: string | null;
+    /** The modes the canvas can be in. The dev-time route-conflict check reads
+     *  them to decide whether two gated actions can ever compete; without a
+     *  registry it checks against the kit's `DEFAULT_MODES`. */
+    modes?: ModeRegistry;
 }
-interface ContributionsApi<TOverlay = unknown> {
+/** The assembled registry {@link useContributions} returns. */
+interface ContributionsApi<TOverlay = KernelOverlay> {
     /** Every entry, as passed in. */
     entries: readonly Contribution<TOverlay>[];
-    /** Currently focused entry id. */
-    focused: string;
-    /** Focus an entry. Writes through to the shared `ActiveToolContext`. */
-    setFocused: (id: string) => void;
+    /** Currently focused entry id, or `null` when nothing is focused. */
+    focused: string | null;
+    /** Focus an entry, or pass `null` to focus none. Writes through to the
+     *  shared `ActiveToolContext`. */
+    setFocused: (id: string | null) => void;
     /** Every live binding, tiered by the declaring entry's eligibility. */
     scopedBindings(): ScopedBinding[];
     /** Overlays of every live entry declaring `position`, ordered active, then
@@ -462,6 +323,14 @@ interface ContributionsApi<TOverlay = unknown> {
  * in the context so the gesture dispatcher and every sibling caller read the
  * same source of truth.
  */
-declare function useContributions<TOverlay = unknown>(opts: UseContributionsOptions<TOverlay>): ContributionsApi<TOverlay>;
+declare function useContributions<TOverlay = KernelOverlay>(opts: UseContributionsOptions<TOverlay>): ContributionsApi<TOverlay>;
+/**
+ * Registers the consolidated `tool.offhand` action for every entry declaring
+ * an `offhand` trigger, into the nearest `<ActionsProvider>`; its invoker
+ * reads `params.toolId` off the matched binding. `useContributions` calls it,
+ * and so does any host that assembles its entries above its own provider —
+ * `<SceneCanvas>` does — since a null registry here registers nothing.
+ */
+declare function useOffhandAction(entries: readonly Contribution<unknown>[]): void;
 
-export { ActionsProvider, ActionsScope, ActiveToolContextProvider, ActiveToolContextProviderIfRoot, type ActiveToolContextProviderProps, type ActiveToolContextValue, type ContributionsApi, type DispatcherChannels, type DispatcherViewTarget, type OngoingAction, type ToolsApi, type UseContributionsOptions, type UseGestureDispatcherOptions, type UseToolsOptions, type ViewIdResolver, useAction, useActionsRegistry, useActiveToolContext, useContributions, useGestureDispatcher, useOngoingAction, useOptionalActiveToolContext, useTools };
+export { ActionsProvider, ActiveToolContextProvider, ActiveToolContextProviderIfRoot, type ActiveToolContextProviderProps, type ActiveToolContextValue, type ContributionsApi, DepRegistry, DepRegistryProvider, InputScope, type InputScopeProps, type OngoingAction, type ToolsApi, type UseContributionsOptions, type UseToolsOptions, Yoke, type YokeProps, useAction, useActionsRegistry, useActiveToolContext, useContributions, useDepRegistry, useDepSource, useOffhandAction, useOngoingAction, useOptionalActiveToolContext, useOptionalDepRegistry, useTools, useYoke };