@weasel-js/routing 1.6.1 → 1.7.0

package/dist/react.d.ts

@@ -1,10 +1,9 @@
-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';
+import { D as Dispatcher, A as ActionsRegistry, C as Contribution, a as AffordanceHit, R as RuleCtx, b as DepSchema, c as DepRegistry, d as DepName, S as ScopeNode, e as Action, f as DepNode, K as KernelOverlay, g as AnyToolOf, O as OverlayPosition, h as ScopedBinding } from './index-Bmq4lSHY.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 { ModeRegistry } from '@weasel-js/modes';
 import '@weasel-js/history';
 
 /**
@@ -90,7 +89,7 @@ interface UseGestureDispatcherOptions {
     /** Action registry (ActionsRegistry from registry.tsx). */
     actions: ActionsRegistry;
     /** Tool definitions keyed by id. Typically passes an empty Map. */
-    toolsById: ReadonlyMap<string, Tool>;
+    entriesById: ReadonlyMap<string, Contribution<unknown>>;
     /** Default true. Set false to opt out of dispatcher wiring (e.g. demos that disable it). */
     enabled?: boolean;
     /**
@@ -116,8 +115,14 @@ interface UseGestureDispatcherOptions {
      * 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.
+     *
+     * Every dispatcher hears keys on `window`, and a keystroke one of them
+     * claims — or anything else calls `preventDefault` on — is not dispatched by
+     * the rest. `'first'` listens in the capture phase, so this dispatcher gets
+     * the keystroke ahead of every dispatcher listening normally, whatever the
+     * mount order: the shape for chrome that owns a key only when it can act.
      */
-    keyboard?: boolean;
+    keyboard?: boolean | 'first';
     /**
      * Optional affordance classifier. Called with the **world** coordinates of
      * the pointer — this hook applies the routed view's `clientToWorld` before
@@ -268,29 +273,59 @@ interface UseGestureDispatcherOptions {
  */
 declare function useGestureDispatcher(opts: UseGestureDispatcherOptions): void;
 
+/** 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;
 /**
- * @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`.
+ * 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 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 +336,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 +354,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 +392,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 +520,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 +544,33 @@ 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> {
+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> {
+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 +587,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, type DispatcherChannels, type DispatcherViewTarget, InputScope, type InputScopeProps, type OngoingAction, type ToolsApi, type UseContributionsOptions, type UseGestureDispatcherOptions, type UseToolsOptions, type ViewIdResolver, Yoke, type YokeProps, useAction, useActionsRegistry, useActiveToolContext, useContributions, useDepRegistry, useDepSource, useGestureDispatcher, useOffhandAction, useOngoingAction, useOptionalActiveToolContext, useOptionalDepRegistry, useTools, useYoke };