@weasel-js/routing 1.9.3 → 1.10.0

package/dist/react.d.ts

@@ -1,13 +1,26 @@
-export { D as DispatcherChannels, U as UseGestureDispatcherOptions, u as useGestureDispatcher } from './internal-B1B6gfOS.js';
+import { U as UseGestureDispatcherOptions } from './internal-D0rDmi7t.js';
+export { D as DispatcherChannels } from './internal-D0rDmi7t.js';
 import * as react from 'react';
 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-CrbDNXT_.js';
+import { D as DepRegistry, a as DepName, b as DepSchema, S as ScopeNode, A as ActionsRegistry, c as Action, d as DepNode, T as ToolNode, N as NodeId, K as KernelOverlay, C as Contribution, e as Tool, O as OverlayPosition } from './index-Bm2QEV09.js';
+export { f as ActiveToolContextProvider, g as ActiveToolContextProviderIfRoot, h as ActiveToolContextProviderProps, i as ActiveToolContextValue, u as useActiveToolContext, j as useOptionalActiveToolContext } from './index-Bm2QEV09.js';
 import { ModeRegistry } from '@weasel-js/modes';
 import '@weasel-js/gestures';
 import '@weasel-js/cursor';
-import '@weasel-js/history';
+import '@weasel-js/geom';
+import '@weasel-js/registry';
 import '@weasel-js/select';
 
+/**
+ * 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.
+ *
+ * The active tool and the dep registry come from context, so it must be
+ * mounted inside `<SceneCanvas>`'s providers.
+ */
+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 }: {
@@ -71,72 +84,9 @@ declare function useActionsRegistry(): ActionsRegistry | null;
  */
 declare function useAction(action: Action): void;
 
-/** 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;
-
 /**
  * @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>`. */
@@ -155,7 +105,9 @@ interface InputScopeProps {
  *
  * 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.
+ * pointerdown or wheel — or the newest where none has been. Keys are stricter:
+ * one that reaches the page goes to the canvas last pressed or scrolled in,
+ * across every root on the page, and to none before the first.
  */
 declare function InputScope({ yoke, children }: InputScopeProps): ReactElement;
 /**
@@ -172,11 +124,10 @@ interface YokeProps {
 /**
  * @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.
+ * flight, history, and yoke-wide actions. Made once with `useYoke()`, 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.
  */
 interface Yoke {
     /** @internal */
@@ -206,6 +157,10 @@ declare function Yoke({ value, children }: YokeProps): ReactElement;
  *   on its own — a click on a swatch, a switch of paint kind.
  * - `cancel()` ends an open edit without keeping it.
  *
+ * An edit the dispatcher ended first — a tool switch, Escape, another control
+ * committing the same action — counts as not open: the next `input` opens a
+ * new one.
+ *
  * All three are no-ops when no action is reachable, so a control renders the
  * same with or without a canvas in scope.
  */
@@ -223,6 +178,101 @@ interface OngoingAction {
  */
 declare function useOngoingAction(actionId: string): OngoingAction;
 
+/** @experimental World-space pointer position and the view it is over — a
+ *  view id, or `null` for a surface's own camera. `null` as a whole when the
+ *  pointer is over no publishing surface. */
+type PointerWorldPos = {
+    worldX: number;
+    worldY: number;
+    viewId: string | null;
+} | null;
+/** @experimental */
+interface PointerContextValue {
+    /** The latest position. */
+    get(): PointerWorldPos;
+    /** Publish a position. Subscribers hear only a changed value. */
+    set(next: PointerWorldPos): void;
+    /** Called after every change; returns the unsubscribe. */
+    subscribe(fn: () => void): () => void;
+    /** Bumps on every change. */
+    getVersion(): number;
+    /** `get()` as a stable thunk, for hooks taking a drop-point option. */
+    readonly getDropPoint: () => PointerWorldPos;
+}
+/** @experimental A pointer store with no provider around it. */
+declare function createPointerStore(): PointerContextValue;
+/**
+ * @experimental
+ * Wrap the part of the React tree that should share one pointer.
+ * `<SceneCanvas>` mounts one when none is in scope, so mount it yourself only
+ * when two surfaces should share a pointer. Pass `store` to publish into one
+ * you hold elsewhere (`createPointerStore()`).
+ */
+declare function PointerContextProvider({ children, store }: {
+    children: ReactNode;
+    store?: PointerContextValue;
+}): ReactNode;
+/** @experimental The surrounding pointer store, or `null` when no provider is
+ *  in scope. */
+declare function usePointerContext(): PointerContextValue | null;
+/** @experimental The pointer, re-rendering the caller whenever it changes.
+ *  `null` outside a provider. */
+declare function usePointerPosition(): PointerWorldPos;
+
+/**
+ * @experimental
+ * SelectionContext — an ambient context that publishes "what's currently
+ * selected" so non-canvas UI (command palette, status bar) can read it without
+ * threading a selection prop through the tree.
+ *
+ * **Single slot:** the context holds one selection array. Whichever publisher
+ * calls `publishSelection` most recently owns it, so a multi-canvas page gets
+ * last-writer-wins. `<SceneCanvas>` publishes automatically.
+ */
+
+/** @experimental */
+interface SelectionContextValue {
+    /** The most-recently-published selection. Empty array when no canvas
+     *  has published or when the active canvas's selection is empty. */
+    readonly selection: readonly NodeId[];
+    /** Optional per-id kind label, parallel to `selection` (e.g. `'rectangle'`,
+     *  `'path'`, `'group'`). Sparse entries (`undefined`) are allowed; treat it
+     *  as best-effort. */
+    readonly kinds?: readonly (string | undefined)[];
+    /** Publish the calling canvas's selection. Calling with the same content
+     *  does not re-render the consumer tree. */
+    publishSelection(ids: readonly NodeId[], kinds?: readonly (string | undefined)[]): void;
+}
+/**
+ * @experimental
+ * Wrap the part of the React tree that should share a selection context.
+ * Usually placed at the demo / app root, alongside `<ActionsProvider>`.
+ */
+declare function SelectionContextProvider({ children }: {
+    children: ReactNode;
+}): ReactNode;
+/**
+ * @experimental
+ * The current selection-context value, or `null` when no
+ * `<SelectionContextProvider>` is in scope.
+ */
+declare function useSelectionContext(): SelectionContextValue | null;
+/**
+ * @experimental
+ * Mounts a `<SelectionContextProvider>` only when no parent provider is in
+ * scope; otherwise renders children unwrapped.
+ */
+declare function SelectionContextProviderIfRoot({ children, }: {
+    children: ReactNode;
+}): ReactNode;
+/**
+ * @experimental
+ * Publishes `ids` into the surrounding `<SelectionContextProvider>` whenever
+ * their content changes, and clears the slot on unmount unless another
+ * publisher has written it since. No-op when there's no provider in scope.
+ */
+declare function usePublishSelection(ids: readonly NodeId[], kinds?: readonly (string | undefined)[]): void;
+
 /** Options for `useTools`: which tools exist, which one starts active, and
  *  which run continuously regardless of the active one. */
 interface UseToolsOptions<TOverlay = KernelOverlay> {
@@ -232,7 +282,7 @@ interface UseToolsOptions<TOverlay = KernelOverlay> {
     /** 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>>;
+    registry: Record<string, Tool<TOverlay>>;
     /** Always-on entries — tools or other contributions, live regardless of
      *  the active slot. */
     ambient?: readonly Contribution<TOverlay>[];
@@ -248,8 +298,7 @@ interface ToolsApi<TOverlay = KernelOverlay> {
     /** 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. */
+    /** Currently hotkey-engaged tool id (or `null`): the top of the hotkey stack. */
     hotkeyEngaged: string | null;
     /** Engage a hotkey-slot tool by id. */
     engageHotkey: (id: string) => void;
@@ -258,31 +307,24 @@ interface ToolsApi<TOverlay = KernelOverlay> {
     /** 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>>>;
+    registry: Readonly<Record<string, Tool<TOverlay>>>;
     /** Returns true if a tool with the given id is in the registry or ambient list. */
     has(id: string): boolean;
-    /** All overlay layers from currently-engaged tools (active slot, hotkey
-     *  slot if engaged, all ambient slot tools) that declare `position`.
-     *  Filters out tools with no `overlay` field. Order: active, then hotkey
-     *  (if engaged), then ambient (registration order). */
+    /** Overlay layers from currently-engaged tools that declare `position`.
+     *  Order: active, then hotkey (if engaged), then ambient (registration order). */
     getActiveOverlays(position?: OverlayPosition): TOverlay[];
 }
 /**
- * Manages the active tool and hotkey slot.
- *
- * A thin shim over {@link useContributions}: the `registry` / `ambient`
- * arguments are restated as declared eligibility (`focus` / `always`), and
- * assembly happens in one place for tools and non-tool contributions alike.
+ * Manages the active tool and hotkey slot; a thin shim over
+ * {@link useContributions}.
  *
  * Requires `<ActiveToolContextProvider>` (or `<WeaselProvider>` /
  * `<SceneCanvas>`, which mount one internally) in scope: active/hotkey state
- * lives in the context so the gesture dispatcher and any sibling
- * `useTools` calls all read the same source of truth.
+ * lives in the context.
  *
- * **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).
+ * **First mount wins**: if the context's slot is unseeded on first mount,
+ * `useTools` pushes `opts.active` to the context. Subsequent mounts respect
+ * whatever the context currently holds.
  */
 declare function useTools<TOverlay = KernelOverlay>(opts: UseToolsOptions<TOverlay>): ToolsApi<TOverlay>;
 
@@ -294,9 +336,10 @@ interface UseContributionsOptions<TOverlay = KernelOverlay> {
     /** 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`. */
+    /** The modes the canvas can be in. The active one decides which tagged
+     *  entries draw their overlays, and the dev-time route-conflict check reads
+     *  them all to decide whether two gated actions can ever compete; without a
+     *  registry nothing is barred and the check uses the kit's `DEFAULT_MODES`. */
     modes?: ModeRegistry;
 }
 /** The assembled registry {@link useContributions} returns. */
@@ -308,10 +351,9 @@ interface ContributionsApi<TOverlay = KernelOverlay> {
     /** 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
-     *  hotkey, then ambient. */
+     *  hotkey, then ambient. Live is what the dispatcher routes to: an entry the
+     *  active mode bars draws nothing. */
     overlays(position?: OverlayPosition): TOverlay[];
 }
 /**
@@ -334,4 +376,4 @@ declare function useContributions<TOverlay = KernelOverlay>(opts: UseContributio
  */
 declare function useOffhandAction(entries: readonly Contribution<unknown>[]): void;
 
-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 };
+export { ActionsProvider, type ContributionsApi, DepRegistry, DepRegistryProvider, InputScope, type InputScopeProps, type OngoingAction, PointerContextProvider, type PointerContextValue, type PointerWorldPos, SelectionContextProvider, SelectionContextProviderIfRoot, type SelectionContextValue, type ToolsApi, type UseContributionsOptions, UseGestureDispatcherOptions, type UseToolsOptions, Yoke, type YokeProps, createPointerStore, useAction, useActionsRegistry, useContributions, useDepRegistry, useDepSource, useGestureDispatcher, useOffhandAction, useOngoingAction, useOptionalDepRegistry, usePointerContext, usePointerPosition, usePublishSelection, useSelectionContext, useTools, useYoke };