@weasel-js/routing 1.10.0 → 1.11.0

package/dist/{index-Bm2QEV09.d.ts → index-CmfVvwWD.d.ts}

@@ -1,10 +1,14 @@
-import { PoseLinear, View } from '@weasel-js/geom';
-import * as react from 'react';
-import { ReactNode } from 'react';
-import { Emitter } from '@weasel-js/registry';
+import { MenuEntry, Rect, MenuShortcut } from '@weasel-js/menu';
+import { PrefGroup } from '@weasel-js/prefs';
+import { FramedBox, View, Point } from '@weasel-js/geom';
 import { CapabilityTag, ActiveMode, ModeRegistry } from '@weasel-js/modes';
+import { ModifierKey, ClaimableGesture, GestureSpec, IngestItem, BodyTarget, InputEvent, TargetSpec, KeyHeldSpec, TargetPredicate, KeySpec, ParsedModifiers, GestureName } from '@weasel-js/gestures';
+import * as _weasel_js_icons from '@weasel-js/icons';
+import { IconRef } from '@weasel-js/icons';
 import { CursorSpec } from '@weasel-js/cursor';
-import { ClaimableGesture, GestureSpec, IngestItem, InputEvent, TargetSpec, KeyHeldSpec, TargetPredicate, KeySpec, ParsedModifiers, GestureName } from '@weasel-js/gestures';
+import * as react from 'react';
+import { ReactNode } from 'react';
+import { Emitter, QueryMatch } from '@weasel-js/registry';
 import '@weasel-js/select';
 
 /**
@@ -22,20 +26,9 @@ type NodeId = string & {
     readonly __brand: 'NodeId';
 };
 
-/**
- * Axis-aligned rectangle in world space. The optional `rotation` (radians,
- * around the AABB center) and `transform` (inside it, about the same center)
- * let chrome carry the frame a box is drawn in without a parallel type;
- * `poseFrameOf` composes the two.
- */
-interface Bounds {
-    x: number;
-    y: number;
-    width: number;
-    height: number;
-    rotation?: number;
-    transform?: PoseLinear;
-}
+/** Axis-aligned rectangle in world space, with the frame it is drawn in;
+ *  geom's `FramedBox`. */
+type Bounds = FramedBox;
 /** The selection as routing reads and writes it. */
 interface SelectionApi {
     /** Current selection. Re-renders trigger when this reference changes. */
@@ -176,106 +169,6 @@ 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: Emitter;
-}
-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.
- */
-declare function useOptionalActiveToolContext(): ActiveToolContextValue | null;
-/**
- * Mounts an `<ActiveToolContextProvider>` only when no parent provider is in
- * scope; otherwise renders children unwrapped.
- */
-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
@@ -523,6 +416,155 @@ declare function resolveDeviceProfile(detected: DetectedDeviceFacts, overrides?:
  */
 declare const DEFAULT_DEVICE_PROFILE: DeviceProfile;
 
+/**
+ * Modifier roles: the modifiers an ongoing action reads while it runs, named
+ * by what they do rather than which key they are, so a binding or a tuning can
+ * move one to another key without forking the action.
+ */
+
+/** The keys that hold a role: any one of them held holds it. `'mod'` is Cmd
+ *  on a Mac and Ctrl elsewhere. An empty list never holds it. */
+type RoleKeys = readonly ModifierKey[];
+/** One modifier an action reads mid-gesture. */
+interface ModifierRole {
+    label: string;
+    /** The keys that hold it unless a tuning or a binding says otherwise. */
+    keys: RoleKeys;
+}
+/** An action's roles by id, e.g. `'handle.holdAngle'`. */
+type ModifierRoles = Readonly<Record<string, ModifierRole>>;
+/** Keys a tuning or a binding gives some of an action's roles. */
+type RoleRebinds = Readonly<Record<string, RoleKeys>>;
+/** Whether any of `keys` is held. */
+declare function keysHeld(keys: RoleKeys, modifiers: ModifierState, isMac: boolean): boolean;
+/**
+ * A reader for an action's own roles. It answers from `ctx.roles`, which the
+ * dispatcher resolves on every event, and falls back to the role's default
+ * keys where nothing resolved them: an invoker called directly, or a context
+ * a cancel-all built with no event.
+ */
+declare function roleReader<R extends ModifierRoles>(roles: R): (ctx: {
+    roles?: Readonly<Record<string, boolean>>;
+    modifiers: ModifierState;
+}, id: keyof R & string) => boolean;
+
+/** The chrome an in-flight gesture paints beside the scene. */
+
+/**
+ * What a `polyline` overlay is, in a word — the narrowest thing an action can
+ * say about how its run should look without naming a paint.
+ *
+ * The named roles are the kit's; a painter maps each to a style and falls back
+ * to plain chrome for one it does not know, so a package outside core can coin
+ * its own and still be drawn.
+ */
+type OverlayRole = 
+/** Generic in-flight chrome — the marquee/lasso paint. */
+'chrome'
+/** A cut the gesture would make. */
+ | 'cut'
+/** An edge the gesture would author between two points. */
+ | 'connector'
+/** The stretch of a path a soft-selection drag reaches. */
+ | 'falloff'
+/** What a lock holds a dragged point to — a line, a circle. */
+ | 'lock' | (string & {});
+/**
+ * What an in-flight gesture proposes to paint *beside* the scene, returned by
+ * `OngoingHandle.overlay()` — a marquee rect, a lasso trail, the outline of a
+ * shape being dragged out, the line a slice would cut along.
+ *
+ * Every variant is world geometry and nothing else — no `DrawCommand`, no
+ * color, no coordinate space to choose — so a surface rendering the same
+ * gesture some other way can still read it. The painter owns every style
+ * decision.
+ */
+type OngoingOverlay = {
+    kind: 'marquee';
+    start: {
+        x: number;
+        y: number;
+    };
+    current: {
+        x: number;
+        y: number;
+    };
+    shiftHeld: boolean;
+} | {
+    kind: 'lasso';
+    vertices: ReadonlyArray<{
+        x: number;
+        y: number;
+    }>;
+    current: {
+        x: number;
+        y: number;
+    };
+    shiftHeld: boolean;
+} | {
+    /**
+     * An open run of world points the gesture is proposing — a cut line, a
+     * routed connector. `role` is the whole of what an action says about
+     * appearance.
+     */
+    kind: 'polyline';
+    /** At least two points. Anything shorter is dropped in resolution. */
+    points: ReadonlyArray<{
+        x: number;
+        y: number;
+    }>;
+    /** What the run means. Omitted reads as {@link OverlayRole} `'chrome'`. */
+    role?: OverlayRole;
+} | {
+    /**
+     * A round brush dragged through world points: the area it has swept so
+     * far, and its footprint at the last point. The radius is in screen
+     * pixels, so the footprint keeps its size at every zoom.
+     */
+    kind: 'brush';
+    /** The brush's path so far, at least one point; the last is where it is now. */
+    points: ReadonlyArray<{
+        x: number;
+        y: number;
+    }>;
+    radiusPx: number;
+} | {
+    /**
+     * Live insert-drag preview. Pre-commit there is no scene node to ghost
+     * via `previewIds()`/`previewPose()`, so insert paints its preview
+     * through the overlay instead.
+     *
+     * `bounds` is the AABB of the current drag (start/current normalized).
+     * `extras` is the per-kind extras the action already collected; the
+     * overlay renderer narrows on `shape` and casts the field shape it
+     * expects.
+     */
+    kind: 'insertPreview';
+    /** Which preview the dispatcher's overlay draws. The kit's own shape
+     *  kinds are the ones it knows how to render; a consumer-defined kind
+     *  is legal and simply gets no live preview. */
+    shape: string;
+    bounds: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    extras: unknown;
+    /** World-space point to paint a small "anchor" dot at, marking the
+     *  click point — for radial shapes (polygon/star), where no vertex
+     *  sits on it, and for any shape in center mode. */
+    anchorPoint?: {
+        x: number;
+        y: number;
+    };
+    /** World affines the shape will also be drawn under once it lands, by
+     *  the container it is drawn into: the preview is painted under each. */
+    copies?: readonly (readonly [number, number, number, number, number, number])[];
+};
+/** A handle's overlays as a list: empty when it has none. */
+declare function overlaysOf(handle: OngoingHandle): readonly OngoingOverlay[];
+
 /**
  * Invoker — pluggable invocation strategy for an Action.
  *
@@ -531,11 +573,8 @@ declare const DEFAULT_DEVICE_PROFILE: DeviceProfile;
  * driven by the dispatcher (move, resize, pinch-zoom).
  */
 
-/** A 2D point in either world or screen coordinates. */
-interface Point2 {
-    x: number;
-    y: number;
-}
+/** A 2D point in either world or screen coordinates; geom's `Point`. */
+type Point2 = Point;
 /**
  * Which UI affordance was hit at pointerdown. Populated by the dispatcher when
  * the `affordanceAt` thunk is provided to `useGestureDispatcher`.
@@ -543,6 +582,8 @@ interface Point2 {
  * `kind` is a discriminator string:
  *   - `'handle:top-left'` / `'handle:top-right'` / `'handle:bottom-left'` /
  *     `'handle:bottom-right'` — corner resize handles.
+ *   - `'handle:top'` / `'handle:right'` / `'handle:bottom'` / `'handle:left'` —
+ *     edge resize handles.
  *   - `'rotate-handle'` — the rotation affordance.
  *   - `'anchor:N'` — a path anchor at index N.
  */
@@ -565,8 +606,8 @@ interface AffordanceHit {
     };
     /** Which nodes this affordance belongs to. */
     targetIds?: string[];
-    /** Set only when `kind` matches `'handle:*'`: which corner stays fixed
-     *  during a resize. */
+    /** Set only when `kind` matches `'handle:*'`: which corner or edge stays
+     *  fixed during a resize; `'free'` on the axis an edge handle leaves alone. */
     anchor?: ResizeAnchor;
     /** Cursor to show while the pointer hovers this affordance (no gesture in
      *  flight). Unset falls through to action-cursor prediction, then to the
@@ -676,6 +717,12 @@ interface InvocationCtx {
         key: string;
         repeat: boolean;
     };
+    /** What a carry over the surface brings: its payload, as `startCarry` was
+     *  handed it. Present for every event of a `carry` binding's gesture. */
+    carry?: {
+        type: string;
+        value: unknown;
+    };
     /**
      * The view the input landed in, as the surface's view resolver assigned it:
      * a view id, or `null` for the surface's own camera. Absent where no
@@ -689,6 +736,13 @@ interface InvocationCtx {
      * params via `BindingOpts.params` on `start` (the `opts` arg).
      */
     params?: Record<string, unknown>;
+    /**
+     * Which of the action's `modifierRoles` are held for this event, by role
+     * id. The dispatcher fills it on every event of a gesture whose action
+     * declares roles; absent otherwise. Read it through `roleReader`, which
+     * falls back to the roles' default keys where it is absent.
+     */
+    roles?: Readonly<Record<string, boolean>>;
 }
 /** Per-invocation options the dispatcher reads from a `GestureBinding`'s
  *  `opts` field and passes to `OngoingInvoker.start`. */
@@ -723,6 +777,11 @@ interface BindingOpts {
      * binding; this tells the route-conflict check the order is the design.
      */
     yields?: boolean;
+    /**
+     * Keys for some of the action's `modifierRoles` on this binding, by role
+     * id, over the action's defaults and any tuning's.
+     */
+    roles?: RoleRebinds;
 }
 /** Resolve `BindingOpts.params` to a concrete record (calling the thunk if
  *  needed). Returns `undefined` for absent params. */
@@ -734,98 +793,7 @@ declare function resolveParams(params: BindingOpts['params']): Record<string, un
 interface ActionDeps extends Partial<DepSchema> {
     [k: string]: unknown;
 }
-/**
- * What a `polyline` overlay is, in a word — the narrowest thing an action can
- * say about how its run should look without naming a paint.
- *
- * The named roles are the kit's; a painter maps each to a style and falls back
- * to plain chrome for one it does not know, so a package outside core can coin
- * its own and still be drawn.
- */
-type OverlayRole = 
-/** Generic in-flight chrome — the marquee/lasso paint. */
-'chrome'
-/** A cut the gesture would make. */
- | 'cut'
-/** An edge the gesture would author between two points. */
- | 'connector' | (string & {});
-/**
- * What an in-flight gesture proposes to paint *beside* the scene, returned by
- * `OngoingHandle.overlay()` — a marquee rect, a lasso trail, the outline of a
- * shape being dragged out, the line a slice would cut along.
- *
- * Every variant is world geometry and nothing else — no `DrawCommand`, no
- * color, no coordinate space to choose — so a surface rendering the same
- * gesture some other way can still read it. The painter owns every style
- * decision.
- */
-type OngoingOverlay = {
-    kind: 'marquee';
-    start: {
-        x: number;
-        y: number;
-    };
-    current: {
-        x: number;
-        y: number;
-    };
-    shiftHeld: boolean;
-} | {
-    kind: 'lasso';
-    vertices: ReadonlyArray<{
-        x: number;
-        y: number;
-    }>;
-    current: {
-        x: number;
-        y: number;
-    };
-    shiftHeld: boolean;
-} | {
-    /**
-     * An open run of world points the gesture is proposing — a cut line, a
-     * routed connector. `role` is the whole of what an action says about
-     * appearance.
-     */
-    kind: 'polyline';
-    /** At least two points. Anything shorter is dropped in resolution. */
-    points: ReadonlyArray<{
-        x: number;
-        y: number;
-    }>;
-    /** What the run means. Omitted reads as {@link OverlayRole} `'chrome'`. */
-    role?: OverlayRole;
-} | {
-    /**
-     * Live insert-drag preview. Pre-commit there is no scene node to ghost
-     * via `previewIds()`/`previewPose()`, so insert paints its preview
-     * through the overlay instead.
-     *
-     * `bounds` is the AABB of the current drag (start/current normalized).
-     * `extras` is the per-kind extras the action already collected; the
-     * overlay renderer narrows on `shape` and casts the field shape it
-     * expects.
-     */
-    kind: 'insertPreview';
-    /** Which preview the dispatcher's overlay draws. The kit's own shape
-     *  kinds are the ones it knows how to render; a consumer-defined kind
-     *  is legal and simply gets no live preview. */
-    shape: string;
-    bounds: {
-        x: number;
-        y: number;
-        width: number;
-        height: number;
-    };
-    extras: unknown;
-    /** World-space point to paint a small "anchor" dot at, marking the
-     *  click point — for radial shapes (polygon/star), where no vertex
-     *  sits on it, and for any shape in center mode. */
-    anchorPoint?: {
-        x: number;
-        y: number;
-    };
-};
+
 /** Handle returned from an `OngoingInvoker.start`. The dispatcher pumps
  *  `onMove` on subsequent input events of the same gesture and calls
  *  `onEnd` exactly once (with `'commit'` on natural completion or `'cancel'`
@@ -840,6 +808,12 @@ interface OngoingHandle {
      * handle is in flight.
      */
     kind?: string;
+    /**
+     * The cursor this gesture shows now, read after every move. Wins over the
+     * action's `activeCursor`, for a cursor that follows the gesture — the
+     * rotate glyph turning about its pivot. `undefined` defers to the action.
+     */
+    cursor?(): CursorSpec | undefined;
     onMove?(ctx: InvocationCtx): void;
     onEnd?(ctx: InvocationCtx, reason: 'commit' | 'cancel'): void;
     /**
@@ -876,10 +850,19 @@ interface OngoingHandle {
     previewData?(id: string): unknown | null;
     /**
      * Optional chrome surface: a non-ghost visual (marquee rectangle, lasso
-     * polyline) painted while the gesture is in flight. Returning `null`, or
-     * omitting the method, means "no overlay this gesture".
+     * polyline) painted while the gesture is in flight — one, or a list for a
+     * gesture showing several runs at once. Returning `null`, or omitting the
+     * method, means "no overlay this gesture". Read it through
+     * {@link overlaysOf}, which answers a list either way.
+     */
+    overlay?(): OngoingOverlay | readonly OngoingOverlay[] | null;
+    /**
+     * A wheel turned while this gesture is in flight — scrubbing a value the
+     * drag is using, say. Return `true` to claim the wheel, so no wheel binding
+     * (the viewport's zoom or pan) sees it; anything else lets it through.
+     * Omit it and the wheel goes to the bindings as usual.
      */
-    overlay?(): OngoingOverlay | null;
+    onWheel?(ctx: InvocationCtx): boolean | void;
 }
 /** Fire-once invocation. Runs to completion synchronously (or fires off an
  *  async side-effect; the registry doesn't wait). */
@@ -903,8 +886,6 @@ type Invoker = ImmediateInvoker | OngoingInvoker;
  * GestureBinding — connects a GestureSpec to an Action id (with per-binding
  * options). Tools own arrays of these on their `bindings` field; ambient
  * gesture-bindings are registered globally.
- *
- * See `docs/superpowers/specs/2026-05-16-registry-unification-design.md`.
  */
 
 /** An interaction: a gesture spec composed with the id of the action it
@@ -916,7 +897,6 @@ interface GestureBinding {
     opts?: BindingOpts;
 }
 /**
- * @experimental
  * A single entry in `Action.defaultBinding[]`. Either a bare `GestureSpec`
  * (no per-binding opts) or an object form that pairs a spec with
  * `BindingOpts` for parametric actions (e.g. `{ params: { axis: 'x' } }`).
@@ -929,7 +909,6 @@ type BoundGesture = GestureSpec | {
     opts: BindingOpts;
 };
 /**
- * @experimental
  * The whole of an action `actionBindings` reads. Routing needs this much and
  * none of `Action`'s palette fields, so it is the narrowest type the
  * dispatcher's binding walk can be written against.
@@ -946,14 +925,12 @@ interface BindingSource {
     defaultBinding?: GestureSpec | BoundGesture[];
 }
 /**
- * @experimental
  * Flatten an action's `defaultBinding` into `GestureBinding`s. A bare
  * `GestureSpec` has `kind` at top level; the object form has `spec`.
  */
 declare function actionBindings(action: BindingSource): GestureBinding[];
 
 /**
- * @experimental
  * Closed enum of reasons an action might report itself as disabled. The
  * consumer (palette, menu, etc.) maps these symbolic values to display
  * strings via its own label map.
@@ -968,20 +945,23 @@ declare const ActionDisabledReason: {
 /** Why an action is unavailable right now. */
 type ActionDisabledReason = (typeof ActionDisabledReason)[keyof typeof ActionDisabledReason];
 /**
- * @experimental
  * What a palette, menu or toolbar renders for an action. No part of this is
  * read during dispatch.
  */
 interface ActionPresentation {
     label: string;
-    /** Inline-SVG icon for palette / toolbar surfaces. May be a static
-     *  `ReactNode` or a function (rare; useful for state-aware icons like a
-     *  "lock" toggle). */
-    icon?: ReactNode | (() => ReactNode);
+    /** The action's icon, by qualified name: `icon('group')` in the package that draws it. */
+    icon?: IconRef;
     /** Grouping key for palette/menu surfaces. Free-form string; the kit
      *  ships defaults for `'align'` (six edges/centers), `'distribute'`
      *  (two axes), and recommends `'pathfinder'` for boolean ops. */
     group?: string;
+    /** Words the action is also found by and gathered under. Where `group` is
+     *  the one place an action sits, an action carries any number of tags: a
+     *  palette search matches them as it matches the label, and
+     *  `actionsTagged` / `taggedActionItems` gather every action or entry
+     *  carrying one, for a bar or a menu built from a tag. */
+    tags?: readonly string[];
     /** Display override for the keyboard shortcut. When omitted, palette
      *  surfaces derive a label from `defaultBinding` via their own
      *  formatter. */
@@ -994,7 +974,6 @@ interface ActionPresentation {
     variants?: readonly ActionVariant[];
 }
 /**
- * @experimental
  * One entry a parametric action contributes to a bar, menu or palette.
  */
 interface ActionVariant {
@@ -1002,13 +981,14 @@ interface ActionVariant {
     key: string;
     label: string;
     /** Falls back to the action's own `icon`. */
-    icon?: ReactNode | (() => ReactNode);
+    icon?: IconRef;
+    /** Tags this variant carries besides its action's, which it carries too. */
+    tags?: readonly string[];
     /** Passed to `trigger`, and matched against each binding's
      *  `opts.params` to find the variant's shortcuts. */
     params: Readonly<Record<string, unknown>>;
 }
 /**
- * @experimental
  * What routing consults: the bindings that reach the action, the deps its
  * invoker reads, the gates it passes, and the cursors it claims.
  */
@@ -1030,14 +1010,14 @@ interface ActionDispatch extends BindingSource {
      *  shortcuts and global held-key triggers. Default: ambient. */
     scope?: 'hotkey';
     /**
-     * @experimental
      * Optional predicate saying whether the action can run right now. Return
      * `true` when it can, or an `ActionDisabledReason` 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.
+     * to the next binding that matches. `ActionsRegistry.trigger` asks too, but
+     * with no point, so a `run` whose answer depends on `at` should still
+     * self-guard.
      *
      * **Contract:** must be pure (no side effects), fast (< 4ms in dev), and
      * must not throw. A throw is caught and treated as disabled with reason
@@ -1052,8 +1032,10 @@ interface ActionDispatch extends BindingSource {
      * click, a press, a long-press. An action that only applies somewhere
      * (on a path segment, say) refuses other points here, so the dispatcher
      * falls through to the next binding and hover prediction shows the
-     * action's `cursor` only where it would act. Palettes and keystrokes
-     * pass no point; treat absent as "anywhere".
+     * action's `cursor` only where it would act. `trigger` passes the
+     * `worldX`/`worldY` its params carry, so a menu row is run under the
+     * question it was shown enabled for. Palettes and keystrokes pass no
+     * point; treat absent as "anywhere".
      *
      * `carried` is what a drop or a paste being routed brings: its items. For
      * a drag still in flight they hold a MIME and nothing else, since a
@@ -1068,7 +1050,6 @@ interface ActionDispatch extends BindingSource {
         items: readonly IngestItem[];
     }) => 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
@@ -1078,6 +1059,15 @@ interface ActionDispatch extends BindingSource {
      * throw. `deps` is the bag `enabled` is given.
      */
     active?: (deps?: ActionDeps) => boolean;
+    /**
+     * Show what running the action now would do, and change nothing: the
+     * result an operation would make, drawn over the canvas. A toolbar asks
+     * while its button is hovered or focused, through
+     * `ActionsRegistry.preview`, and calls what this returns when that ends.
+     * Asked only while `enabled` says yes, with the deps and params `run`
+     * would get. Omitted = the action has nothing to show.
+     */
+    preview?: (deps: ActionDeps, params?: Record<string, unknown>) => (() => void) | void;
     /**
      * Declarative eligibility rule, evaluated against the current
      * `RuleCtx` by the dispatcher before invoking `start()`. Omitted =
@@ -1100,12 +1090,14 @@ interface ActionDispatch extends BindingSource {
      * resolved earlier in the pump via `AffordanceRegion.cursor` and never
      * reach this field.
      *
-     * Static value only. Prediction runs `enabled()` but cannot run the
-     * invoker, so an action that matches yet bails at `start()` (empty
-     * handle) may still show its cursor — keep `enabled` accurate for
-     * actions that declare one.
+     * A function is asked each time with the params the winning binding would
+     * start the action with, tunings included, so a cursor can follow them — a
+     * brush ring as wide as the brush. Read it through {@link actionCursor}.
+     * Prediction runs `enabled()` but cannot run the invoker, so an action that
+     * matches yet bails at `start()` (empty handle) may still show its cursor —
+     * keep `enabled` accurate for actions that declare one.
      */
-    cursor?: CursorSpec;
+    cursor?: CursorSpec | ((params: Record<string, unknown> | undefined) => CursorSpec | undefined);
     /**
      * CSS cursor shown while THIS action's ongoing handle is in flight —
      * grabbing while panning, `move` while dragging a selection, `crosshair`
@@ -1118,15 +1110,22 @@ interface ActionDispatch extends BindingSource {
      * gesture.
      */
     activeCursor?: CursorSpec;
+    /**
+     * The modifiers an ongoing action reads while it runs, by role: Shift
+     * holding a handle's angle, Alt breaking its mirror. The dispatcher resolves
+     * each into `InvocationCtx.roles` on the press, every move, and the release,
+     * so a binding's `opts.roles` or a tuning's `roles` can move one to another
+     * key. Read them with {@link roleReader}. A binding's own `mods` are matched
+     * once, at the press; these are read throughout.
+     */
+    modifierRoles?: ModifierRoles;
 }
 /**
- * @experimental
  * Single registered action.
  */
 interface Action extends ActionDispatch, ActionPresentation {
 }
 /**
- * @experimental
  * The whole of an actions registry the dispatcher reads. It walks the list
  * once per event to build its actionId lookup and never mutates it, so the
  * routing side depends on this rather than on `ActionsRegistry`, whose
@@ -1135,37 +1134,314 @@ interface Action extends ActionDispatch, ActionPresentation {
 interface ActionSource {
     list(): readonly Action[];
 }
+/** `action`'s hover cursor for an invocation given `params`: its `cursor`,
+ *  asked when it is a function. */
+declare function actionCursor(action: Pick<Action, 'cursor'> | undefined, params?: Record<string, unknown>): CursorSpec | undefined;
+
+/** Which canvas hit a menu answers. Every field given must match. */
+interface MenuWhen {
+    bodyTarget?: BodyTarget | readonly BodyTarget[];
+    bodyKind?: string | readonly string[];
+}
+/** A menu as data: a prefs schema drawn as a menu (`resolveSchemaMenu`).
+ *  A def without `when` is opened only by id, from chrome. */
+interface MenuDef {
+    id: string;
+    when?: MenuWhen;
+    menu: PrefGroup;
+}
+/** What a right-click landed on. */
+interface MenuHit {
+    bodyTarget?: BodyTarget;
+    bodyKind?: string;
+}
+/** A def with who contributed it: a tool id, or `null` for ambient. */
+interface OwnedMenuDef {
+    def: MenuDef;
+    owner: string | null;
+}
+
+/** What resolving reads: the registered actions, each one's deps, how to run
+ *  one, and the values behind the schema's value leaves. */
+interface MenuSources {
+    actions(): readonly Action[];
+    depsFor(action: Action): ActionDeps | undefined;
+    trigger(id: string, params?: Record<string, unknown>): boolean;
+    /** The value at a leaf's dotted path. Booleans, enums, and numbers are left
+     *  out of a menu without both this and `onChange`, colors and strings without
+     *  this, and `showIf`/`enableIf` are checked only with it. */
+    values?(path: string): unknown;
+    onChange?(path: string, value: unknown): void;
+    /** The schema an `alias` leaf's `of` is read in. Default: the menu's own. */
+    over?: PrefGroup;
+}
+/**
+ * Draw a prefs schema as menu entries. Action leaves become items from the
+ * registry (one per variant for a parametric action), an `actions` leaf one
+ * item per action in its group, a boolean a checked item, an enum radio
+ * rows, and a number a row edited in place (all through `src.values`/`src.onChange`);
+ * a color shows as a swatch and a string as a disabled row, both read-only. A group drawn `as` a
+ * `menu`, `page`, `tab`, or `panel` is a submenu, and any other group's rows
+ * sit inline between separators. Paint, field, compound, and app-defined leaves are left out.
+ * `at` is the world point the menu was opened at and reaches `enabled` and
+ * every action's params; `params` go to every action, under its own.
+ */
+declare function resolveSchemaMenu(schema: PrefGroup, src: MenuSources, at?: Point, params?: Record<string, unknown>): MenuEntry[];
+/** Turn a declared menu into model entries; see {@link resolveSchemaMenu}. */
+declare function resolveMenu(def: MenuDef, src: MenuSources, at?: Point, params?: Record<string, unknown>): MenuEntry[];
+
+/** Ask to open a menu: by id (chrome) or by what was hit (canvas). */
+interface MenuOpenRequest {
+    menu?: string;
+    hit?: MenuHit;
+    /** Viewport point the menu is placed at, unless `under` is set. */
+    client: Point;
+    /** Viewport rect of the button the menu hangs from: placed below it, or above when below does not fit. */
+    under?: Rect;
+    /** World point, passed to `enabled` and to every item. */
+    world?: Point;
+    params?: Record<string, unknown>;
+    source?: 'pointer' | 'keyboard';
+}
+/** The menu on screen. `seq` changes on every open, so a renderer remounts. */
+interface OpenMenu {
+    seq: number;
+    entries: readonly MenuEntry[];
+    client: Point;
+    under?: Rect;
+    world?: Point;
+    source: 'pointer' | 'keyboard';
+}
+/** Holds the declared menus and the one open menu. */
+interface MenuHost {
+    /** Declare a menu; `owner` is a tool id, or `null` for always. Returns a release. */
+    define(def: MenuDef, owner?: string | null): () => void;
+    /** Pick, resolve and show. False when nothing matched or nothing resolved. */
+    open(req: MenuOpenRequest): boolean;
+    /** Whether `open(req)` would show anything. Changes no state and notifies no one. */
+    has(req: MenuOpenRequest): boolean;
+    close(): void;
+    current(): OpenMenu | null;
+    subscribe(fn: () => void): () => void;
+}
+/** Creates the host that decides which context menu is open, from the menus registered to it. */
+declare function createMenuHost(src: MenuSources & {
+    activeTool(): string | null;
+}): MenuHost;
+
+/**
+ * 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: Emitter;
+}
+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.
+ */
+declare function useOptionalActiveToolContext(): ActiveToolContextValue | null;
+/**
+ * Mounts an `<ActiveToolContextProvider>` only when no parent provider is in
+ * scope; otherwise renders children unwrapped.
+ */
+declare function ActiveToolContextProviderIfRoot({ children, }: {
+    children: ReactNode;
+}): react.JSX.Element;
+
+/**
+ * Tuning: what a host changes about an action it did not write — the params
+ * every invocation starts from, and bindings added beside the action's own —
+ * without restating the descriptor. `ActionsRegistry.tune` holds tunings and
+ * applies them to whatever descriptor is live for the id.
+ */
+
+/** An action's params, or a thunk read each time the action asks for them. */
+type ActionParams<P = Record<string, unknown>> = Partial<P> | (() => Partial<P>);
+/** A binding added for an action: a gesture alone, or a gesture with the
+ *  options it passes — the {@link BoundGesture} shape, its params typed. */
+type TunedBinding<P = Record<string, unknown>> = GestureSpec | {
+    spec: GestureSpec;
+    opts: Omit<BindingOpts, 'params'> & {
+        params?: ActionParams<P>;
+    };
+};
+/** What a host changes about one action. */
+interface ActionTuning<P = Record<string, unknown>> {
+    /** Params every invocation starts from. What a binding or a `trigger` call
+     *  passes is laid over them, so these fill in what it leaves out. A thunk is
+     *  read on every call, and an ongoing action resolving its `opts.params`
+     *  mid-gesture sees the value as it is then. */
+    params?: ActionParams<P>;
+    /** Bindings added after the action's own `defaultBinding`. */
+    bindings?: readonly TunedBinding<P>[];
+    /** Keys for some of the action's `modifierRoles`, by role id. A binding's
+     *  own `opts.roles` is laid over these. */
+    roles?: RoleRebinds;
+}
+/** `action` with each tuning applied in turn, a later one's params over an
+ *  earlier one's. Applying a tuning to a copy it already tuned changes nothing. */
+declare function tuneAction(action: Action, tunings: readonly ActionTuning[]): Action;
 
 /**
- * @experimental
  * The entries an action contributes to a bar, menu or palette — one per
  * variant, or the action itself when it declares none.
  */
 
-/** @experimental One renderable entry: an action, optionally with params. */
+/** One renderable entry: an action, optionally with params. */
 interface ActionItem {
     /** `action.id`, or `action.id:variant.key` — unique across a registry. */
     key: string;
     action: Action;
     label: string;
-    icon?: ReactNode | (() => ReactNode);
+    icon?: IconRef;
+    /** The action's tags, then the variant's own. */
+    tags: readonly string[];
     /** What to pass to `trigger(action.id, params)`; absent for a plain action. */
     params?: Readonly<Record<string, unknown>>;
 }
-/** @experimental Expand `action` into the entries a surface renders. An
+/** Expand `action` into the entries a surface renders. An
  *  action without an immediate invoker has none: `trigger` cannot start a
  *  drag, so a button for one would do nothing. */
 declare function actionItems(action: Action): ActionItem[];
+/** How a palette titles `item`: a variant reads as its action's
+ *  label and its own ("New: A4"), unless its label already holds the action's
+ *  as whole words ("Zoom In", "Reset Zoom"). */
+declare function actionItemTitle(item: ActionItem): string;
+
+/**
+ * Project an action's keyboard bindings into the shape a shortcut chip
+ * renders from (`formatShortcut` / `formatShortcutParts` in `@weasel-js/ui`).
+ */
+
+/** One keyboard shortcut, flattened for display: the chip a menu row draws
+ *  (`MenuShortcut` in `@weasel-js/menu`, `ShortcutInput` in `@weasel-js/gestures`). */
+type ActionShortcut = MenuShortcut;
+/**
+ * The chip form of a single gesture spec, or `undefined` when the spec has
+ * none.
+ *
+ * - A spec's `key` may list spellings of one keycap (`['[', '{']` — the
+ *   shifted bracket reports as `'{'`). The first is the shortcut's name.
+ * - A modifier declared `'optional'` matches held or unheld, so it isn't
+ *   part of what the user has to press.
+ *
+ * Non-keyboard specs (drag, wheel, click) have no chip form. Neither does a
+ * *required* `ctrl` or `meta`: the display shape carries only `mod`.
+ */
+declare function keySpecShortcut(spec: GestureSpec): ActionShortcut | undefined;
+/**
+ * Every keyboard shortcut an action answers to, in declaration order.
+ * Specs `keySpecShortcut` has no chip for are skipped, and bindings it leaves
+ * identical are emitted once; an action bound only to those returns empty.
+ *
+ * With `params` — an `ActionItem`'s — only the bindings that pass those same
+ * values count, so each variant of `flip` gets its own key.
+ */
+declare function actionShortcuts(action: Action, params?: Readonly<Record<string, unknown>>): readonly ActionShortcut[];
+
+/**
+ * Finding actions by tag: gathering the ones that carry it, and a person's
+ * search matching it as it matches a label.
+ */
+
+/** The actions carrying `tag`, themselves or on any variant, in
+ *  the order given. Drags included, which have no entries to show. */
+declare function actionsTagged(actions: readonly Action[], tag: string): Action[];
+/** The entries carrying `tag`: what a bar or a menu built from
+ *  a tag shows. A variant that does not carry it is left out. */
+declare function taggedActionItems(actions: readonly Action[], tag: string): ActionItem[];
+/** Whether `item` answers a search for `query`, by its palette title or
+ *  by a tag, and which. */
+declare function matchActionItem(item: ActionItem, query: string): QueryMatch | null;
 
 /**
- * @experimental
  * Palette-side evaluation of `Action.enabled`. The dispatcher calls the
  * predicate raw as a gate; this is the surface that also enforces the
  * contract the predicate's JSDoc states — no throwing, under 4ms in dev.
  */
 
 /**
- * @experimental
  * Result of evaluating an Action's `enabled` predicate.
  */
 interface ActionEnabledResult {
@@ -1173,16 +1449,17 @@ interface ActionEnabledResult {
     reason?: ActionDisabledReason;
 }
 /**
- * @experimental
  * Safely evaluate an action's `enabled` predicate. Returns `{enabled: true}`
  * when no predicate is supplied. Catches throws and treats them as disabled
  * with reason `'(predicate threw)'`. In dev mode, warns once per action id
  * when a single call exceeds 4ms (single frame at 240fps — generous; real
  * predicates should be sub-millisecond).
  */
-declare function evaluateEnabled(action: Action, deps?: ActionDeps): ActionEnabledResult;
+declare function evaluateEnabled(action: Action, deps?: ActionDeps, at?: {
+    x: number;
+    y: number;
+}): ActionEnabledResult;
 /**
- * @experimental
  * Safely evaluate an action's `active` predicate. `undefined` for an action
  * with no pressed state; a predicate that throws reads as not active.
  */
@@ -1253,9 +1530,8 @@ type HotkeyTrigger = 'space' | 'alt' | 'ctrl' | 'meta' | 'shift' | (string & {})
 interface ToolPresentation {
     /** Human-readable label, distinct from the `id`. Falls back to `id`. */
     label?: string;
-    /** Inline-SVG icon component output: a static `ReactNode`, or a function
-     *  returning one. */
-    icon?: react.ReactNode | (() => react.ReactNode);
+    /** The tool's icon, by qualified name: `icon('rect')` in the package that draws it. */
+    icon?: _weasel_js_icons.IconRef;
     /** Palette grouping key. Tools sharing a group render contiguously
      *  with separators between groups. Free-form string; the kit
      *  recommends 'select' | 'shape' | 'draw' | 'type' | 'view'. */
@@ -1305,6 +1581,8 @@ interface ContributionRouting {
     eligibility: Eligibility;
     bindings?: GestureBinding[];
     actions?: Action[];
+    /** Menus this entry declares: always, for an ambient entry; while active, for a tool. */
+    menus?: MenuDef[];
     /** Dep sources this entry provides while it is installed. A host installs
      *  them for as long as the entry is registered, whatever its eligibility. */
     deps?: ContributionDeps;
@@ -1617,6 +1895,8 @@ interface ResolveOnlyResult {
     scope: BindingScope;
     /** Tool id owning the winning binding; `null` for ambient action bindings. */
     ownerId: string | null;
+    /** The params the winning binding would start the action with, resolved now. */
+    params?: Record<string, unknown>;
 }
 /**
  * One candidate from `Dispatcher.resolveAll` — a binding that matched the
@@ -1827,6 +2107,7 @@ declare function recordModeSwitch(mode: string, from: string | null, to: string
  *   with no `pointerId` (a synthesized probe, a programmatic drag, most tests)
  *   keys to `pointer-mouse`.
  * - `multitouch`: `multitouch-<fingers>`.
+ * - `carry`: `carry-<pointerId>`, keyed as a pointer is.
  * - any other kind that starts an ongoing invoker: `ongoing-<kind>`.
  */
 
@@ -1874,18 +2155,15 @@ declare function createDispatcher(opts?: {
 }): Dispatcher;
 
 /**
- * @experimental
  * Partial override or full descriptor passed via `<SceneCanvas actions={...}>`.
  * `null` disables a default at this id.
  */
 type ActionEntry = null | Partial<Action> | Action;
 /**
- * @experimental
  * Shape of the `actions` prop on `<SceneCanvas>`. `null` disables all defaults.
  */
 type ActionsProp = null | Record<string, ActionEntry>;
 /**
- * @experimental
  * Imperative API exposed by `useActionsRegistry()`.
  */
 interface ActionsRegistry {
@@ -1902,14 +2180,29 @@ interface ActionsRegistry {
      *  `trigger` nor `begin` will fire it. Returns a release. This is the
      *  "not for me" door — `unregister` is the "should not exist" one. */
     mute(id: string): () => void;
+    /** Tune `id` here and in scopes below: its params and added bindings
+     *  apply to whichever descriptor is live for it, registered before the
+     *  tuning or after. Returns a release. See {@link ActionTuning}. */
+    tune(id: string, tuning: ActionTuning): () => void;
+    /** The params an invocation of `id` from this scope starts with when it
+     *  passes `given`: every tuning's params, `given` laid over them. What a
+     *  tool's chrome reads to show what the action it binds will do. */
+    paramsOf(id: string, given?: Record<string, unknown>): Record<string, unknown>;
     list(): readonly Action[];
     /** 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' })`).
      *  Returns whether it ran one: `false` for an unknown id, for an action
      *  whose `enabled` refuses, and for an ongoing-invoker action, which
-     *  `trigger` cannot reach (see `begin`). `enabled` is asked with no point. */
+     *  `trigger` cannot reach (see `begin`). `enabled` is asked at
+     *  `{ x: params.worldX, y: params.worldY }` when both are numbers, and with
+     *  no point otherwise. */
     trigger(id: string, params?: Record<string, unknown>): boolean;
+    /** Show what firing `id` with `params` would do, by its `Action.preview`,
+     *  and return what takes it down; calling that twice is harmless. Shows
+     *  nothing for an unknown id, one with no preview, and one whose `enabled`
+     *  refuses, asked as `trigger` asks it. */
+    preview(id: string, params?: Record<string, unknown>): () => void;
     /**
      * Subscribe to registry mutations. The callback fires after any
      * `register`/`unregister` that changes the version. Returns an
@@ -1977,7 +2270,11 @@ declare function offhandKeyFor(trigger: HotkeyTrigger): string;
 /** Build the per-tool `BoundGesture` list for the consolidated action's
  *  `defaultBinding`. Each entry pairs a `key-held` spec with
  *  `opts.params.toolId` so the invoker's `start` can pick out which tool
- *  to engage. */
+ *  to engage.
+ *
+ *  An offhand tool engages only between gestures. Swapping the tool out
+ *  mid-drag would cancel the drag, and the key is free for the gesture's own
+ *  tool to use — Space repositions a shape being drawn. */
 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
@@ -2017,7 +2314,7 @@ declare const isSelectedBody: BodyPredicate;
 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. */
+/** Any resize handle: a corner (`handle:top-left`, …) or an edge (`handle:top`, …). */
 declare const isResizeHandle: TargetPredicate & {
     readsAffordance: true;
 };
@@ -2033,10 +2330,28 @@ declare const isAnchor: TargetPredicate & {
 declare const isControlHandle: TargetPredicate & {
     readsAffordance: true;
 };
+/** A corner-shape widget, set inside a corner anchor of the edited path. */
+declare const isCornerWidget: TargetPredicate & {
+    readsAffordance: true;
+};
 /** Any of the three anchor-editing affordances (anchor + both controls). */
 declare const isAnchorOrControl: TargetPredicate & {
     readsAffordance: true;
 };
+/** The outline of the path being edited, between its anchors. */
+declare const isSegment: TargetPredicate & {
+    readsAffordance: true;
+};
+/** The grip midway along a curved segment's balance line, `balance:N`, where
+ *  N is the flat index of the anchor the segment starts at. */
+declare const isBalanceGrip: TargetPredicate & {
+    readsAffordance: true;
+};
+/** Anything path edit puts on the path: an anchor, a control, a segment, a
+ *  segment's balance grip, or a corner widget. */
+declare const isPathEditPart: TargetPredicate & {
+    readsAffordance: true;
+};
 
 /** A press being held toward a long-press. */
 interface PendingLongPress {
@@ -2111,6 +2426,29 @@ interface LongPressOptions {
 /** A store holding the press currently being held, or none. Pass it as `LongPressOptions.state`. */
 declare function createLongPressStore(): LongPressStore;
 
+/**
+ * The `gestures` kit settings area. Declared here rather than in core because
+ * the dispatcher reads it, and routing sits below core.
+ */
+/** Pointer gesture timings and travel; each falls back to its constant in `@weasel-js/gestures`. */
+interface GestureKitSettings {
+    /** Longest gap between the clicks of a double click, in ms. */
+    doubleClickMs: number;
+    /** Farthest apart the clicks of a double click may land, in CSS px. */
+    doubleClickPx: number;
+    /** How long a touch or pen press is held to fire a long-press, in ms. */
+    longPressMs: number;
+    /** Farthest a multitouch tap's fingers may travel, in CSS px. */
+    tapPx: number;
+    /** Travel that makes a press a drag, in CSS px. */
+    dragPx: number;
+}
+declare module '@weasel-js/react' {
+    interface KitSettings {
+        gestures: GestureKitSettings;
+    }
+}
+
 /**
  * The DOM half of a drag: one pointer, held down, from press to release.
  *
@@ -2168,6 +2506,60 @@ interface PointerSession {
  */
 declare function openPointerSession(origin: Element, down: PointerEvent | React.PointerEvent, cb: PointerSessionCallbacks, opts?: PointerSessionOptions): PointerSession;
 
+/**
+ * A press that begins on one element and is carried over another: the in-app
+ * sibling of an OS drag. The source opens the carry; every dispatcher with a
+ * `carry` channel registers its element as a surface, and the one under the
+ * pointer dispatches the carry as `carry` events through its bindings.
+ */
+
+/** What a carry brings. `type` is what a `carry` spec's `types` globs filter. */
+interface CarryPayload {
+    type: string;
+    value: unknown;
+}
+/** The pointer facts a surface reads off each step of a carry. */
+interface CarryPointer {
+    clientX: number;
+    clientY: number;
+    altKey: boolean;
+    ctrlKey: boolean;
+    metaKey: boolean;
+    shiftKey: boolean;
+}
+/** What a carry did on a surface: came over it, moved on it, was released on
+ *  it, or left it — off it, or canceled while over it. */
+type CarryStage = 'enter' | 'move' | 'drop' | 'leave';
+/** What {@link startCarry} reports to its source. Exactly one of `onEnd` /
+ *  `onCancel` fires. */
+interface CarryCallbacks {
+    /** Every move of the carrying pointer. */
+    onMove?: (e: PointerEvent) => void;
+    /** The pointer was released. `taken` is whether a binding on the surface
+     *  under it took the carry. */
+    onEnd?: (result: {
+        taken: boolean;
+        event: PointerEvent;
+    }) => void;
+    /** The carry ended without a release. Any surface it was over has had its leave. */
+    onCancel?: (reason: PointerSessionCancelReason) => void;
+}
+/** A live carry, opened by {@link startCarry}. */
+interface Carry {
+    readonly pointerId: number;
+    readonly active: boolean;
+    /** End the carry now, as a cancel. Idempotent. */
+    cancel(): void;
+}
+/**
+ * Carry `payload` from the press `down` on `origin` until the pointer is
+ * released or the press is canceled. While it moves, the surface under it
+ * hears the carry come over, move, and leave; a release over one is a drop
+ * there. The press is captured to `origin` as any drag is, so nothing the
+ * pointer passes over sees it as a press of its own.
+ */
+declare function startCarry(origin: Element, down: PointerEvent | React.PointerEvent, payload: CarryPayload, cb?: CarryCallbacks): Carry;
+
 /** What the registry knows at dispatch time. */
 interface EligibilityState {
     focusedId: string | null;
@@ -2348,6 +2740,8 @@ interface ToolDef<TOverlay = KernelOverlay> {
      * binding that points at an action id nothing registered.
      */
     actions?: Action[];
+    /** Menus this tool adds while it is active. */
+    menus?: MenuDef[];
     /** Hook name as exported from the kit barrel (e.g. `'useHandTool'`).
      *  Set by built-in hooks for inspector / debugging. Consumer-authored
      *  tools may set this to surface their hook name; omitted is fine.
@@ -2554,8 +2948,7 @@ interface ToolScopes {
 /**
  * Detect reachable route conflicts in an assembled tool set and report each one.
  *
- * Call it once wherever a tool set is assembled, behind a
- * `process.env.NODE_ENV !== 'production'` guard.
+ * Call it once wherever a tool set is assembled, behind an `isDev()` guard.
  *
  * **Warn, never throw.** A conflict between a consumer's tool and a kit tool
  * is sometimes deliberate, since the loser can still take the gesture when
@@ -2573,6 +2966,8 @@ declare function reportRouteConflicts(scopes: ToolScopes, warn?: (message: strin
  *
  * Extracted from the deleted singular `useKeybinding` hook so the remaining
  * consumers don't depend on its disappearance.
+ *
+ * @packageDocumentation
  */
 
 /**
@@ -2618,6 +3013,30 @@ declare function matchesKeyBinding(e: KeyboardEvent, b: KeyBinding): boolean;
  *  React keyboard event as readily as a DOM one. */
 declare function historyKey(e: Pick<KeyboardEvent, 'key' | 'metaKey' | 'ctrlKey' | 'shiftKey' | 'altKey'>): 'undo' | 'redo' | null;
 
+/**
+ * Key chords a major browser or the desktop under it takes before a page can:
+ * reload, devtools, tab and window commands, menu accelerators. A binding on
+ * one never fires for some users, so kit defaults steer clear of them.
+ *
+ * `mod` is Cmd on macOS and Ctrl elsewhere, as in a `KeySpec`. The list is
+ * the union across Chrome, Safari, Firefox and Edge on macOS, Windows and
+ * Linux, and errs toward listing a chord.
+ */
+
+/** One reserved chord, and what takes it. */
+interface ReservedChord {
+    key: string;
+    mod?: boolean;
+    alt?: boolean;
+    shift?: boolean;
+    /** Who takes it, for a message. */
+    use: string;
+}
+/** Every chord the module's header describes, one entry per key. */
+declare const BROWSER_RESERVED_CHORDS: readonly ReservedChord[];
+/** The first reserved chord `spec` can fire on, or `null` when none. */
+declare function browserReservedChord(spec: KeySpec): ReservedChord | null;
+
 /**
  * Typed keys for the gesture/behavior scratch store, `ctx.scratch`.
  * `ScratchKey<T>` carries its payload type at the typing layer; at runtime
@@ -2750,13 +3169,15 @@ declare function dlog(namespace: string, ...args: unknown[]): void;
  *  (e.g. no-op op batches suppressed). */
 declare function dwarn(namespace: string, ...args: unknown[]): void;
 
-/**
- * @weasel-js/routing — binding-to-action routing.
- *
- * The pure half: no React, no DOM. The React seam that pumps browser events
- * into the dispatcher, and the providers that feed it, live behind
- * `@weasel-js/routing/react`.
- */
+/** The menus live now: ambient defs, then the active tool's. Defs that share
+ *  an id become one menu: each contribution's children in turn, with a
+ *  separator between contributions. Children stay at their own keys, so the
+ *  paths their values are read at do not move; a key a previous contribution
+ *  took gets `~n` appended. The first def of an id supplies the schema's
+ *  name and the def's `when`. */
+declare function mergeMenuDefs(defs: readonly OwnedMenuDef[], activeTool: string | null): MenuDef[];
+/** The first def whose `when` matches `hit`. */
+declare function pickMenu(defs: readonly MenuDef[], hit: MenuHit): MenuDef | undefined;
 
 /**
  * The dependency schema — the map of dep name → value type that
@@ -2779,9 +3200,34 @@ declare function dwarn(namespace: string, ...args: unknown[]): void;
 interface DepSchema {
     /** Currently active tool id + hotkey-hold stack. */
     activeTool: ActiveToolContextValue;
+    /** The menu host of the `ActionsProvider` in scope. */
+    menuHost?: MenuHost;
 }
 /** Every dep name declared by anything that has merged into {@link DepSchema}. */
 type DepName = keyof DepSchema;
+/**
+ * The params each action reads, by action id — what types a tuning's
+ * `params` and the params on the bindings it adds. Whoever ships an action
+ * merges its entry in, as with {@link DepSchema}:
+ *
+ * ```ts
+ * declare module '@weasel-js/core' {
+ *   interface ActionParamSchema { simplifyBrush: { radiusPx: number } }
+ * }
+ * ```
+ *
+ * Declare an entry as a type literal, not an interface: an interface has no
+ * index signature, so it is not a `Record<string, unknown>`.
+ */
+interface ActionParamSchema {
+}
+/** Tunings keyed by action id: typed by {@link ActionParamSchema} for an id it
+ *  declares, `Record<string, unknown>` params for any other. */
+type ActionTunings = {
+    readonly [K in keyof ActionParamSchema]?: ActionTuning<ActionParamSchema[K]>;
+} & {
+    readonly [id: string]: ActionTuning | undefined;
+};
 /**
  * What the kernel drawing these tools takes as an overlay. Routing never reads
  * an overlay, so it has no type of its own for one; the kernel merges its type
@@ -2803,4 +3249,4 @@ type KernelOverlay = OverlaySchema extends {
     overlay: infer O;
 } ? O : unknown;
 
-export { type DeviceProfile 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 NodeId as N, type OverlayPosition as O, type Condition as P, type Conflict as Q, type RuleCtx as R, ScopeNode as S, ToolNode as T, type ContributionChrome as U, type ContributionDeps as V, type ContributionRouting as W, DEFAULT_ALLOWED_CAPABILITIES as X, DEFAULT_DEVICE_PROFILE as Y, type DebugSink as Z, type DetectedDeviceFacts as _, type DepName as a, actionBindings as a$, type DispatchRecord as a0, type DispatchRecordInput as a1, type DispatcherContext as a2, type DragSample as a3, type DroppedCandidate as a4, type Eligibility as a5, type EligibilityState as a6, type GestureBinding as a7, type HandleKind as a8, type HitShape as a9, type PointerSessionOptions as aA, type RankedCandidate as aB, type RecordCandidate as aC, type RegistryEntry as aD, type ResizeAnchor as aE, type ResolveAllOptions as aF, type ResolveOnlyResult as aG, type ResolvedCandidate as aH, type Rule as aI, type ScopedBinding as aJ, type ScratchKey as aK, type ScratchStore as aL, type SelectionApi as aM, type Selector as aN, type SpecificityPart as aO, TOOL_OFFHAND_ID as aP, type ToolDef as aQ, type ToolKeybinding as aR, type ToolModifiers as aS, type ToolOffhandBindingSpec as aT, type ToolPresentation as aU, type ToolScopes as aV, type ToolSlot as aW, type TraceLogEntry as aX, type UiOngoingControl as aY, type ViewportGestureKind as aZ, type WalkStep as a_, type HotkeyTrigger as aa, INGEST_STRING_MIMES as ab, type ImmediateInvoker as ac, type InvocationCtx as ad, type Invoker as ae, type KeyBinding 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 OngoingHandle as ao, type OngoingInvoker as ap, type OngoingOverlay as aq, type OverlayRole as ar, type OverlaySchema as as, PREDICATE_TARGET as at, type PendingLongPress as au, type PlacedBy as av, type Point2 as aw, type PointerSession as ax, type PointerSessionCallbacks as ay, type PointerSessionCancelReason as az, type DepSchema as b, validateActionId as b$, actionItems as b0, assembleEntries as b1, buildDepsFromRequires as b2, buildRouteRegistry as b3, buildRuleCtx as b4, buildToolOffhandBindings as b5, clientToCanvas as b6, clientToCanvasRect as b7, createDepRegistry as b8, createDispatcher as b9, itemsFromDataTransfer as bA, itemsFromFiles as bB, liveScope as bC, makeToolOffhandAction as bD, matchBest as bE, matchSorted as bF, matchSortedWithBarred as bG, matchesKeyBinding as bH, mergeContributions as bI, modeShortcutSpec as bJ, modeShortcuts as bK, multiTouchGestureId as bL, offhandKeyFor as bM, openPointerSession as bN, pointerGestureId as bO, recordModeSwitch as bP, reportRouteConflicts as bQ, resolveDeviceProfile as bR, resolveParams as bS, routesForSpec as bT, ruleCanHoldIn as bU, rulesExclusive as bV, scopeBindings as bW, scratchKey as bX, setScratch as bY, targetConsultsAffordance as bZ, validateActionDefaultBinding as b_, createLongPressStore as ba, defineTool as bb, deleteScratch as bc, describeRule as bd, dlog as be, dwarn as bf, evaluate as bg, evaluateActive as bh, evaluateEnabled as bi, findConflicts as bj, getScratch as bk, heldKeySpec as bl, historyKey as bm, isAnchor as bn, isAnchorOrControl as bo, isBody as bp, isControlHandle as bq, isDebugEnabled as br, isEmpty as bs, isResizeHandle as bt, isRotateHandle as bu, isSelectedBody as bv, isTool as bw, isUnselectedBody as bx, itemTypesFromDataTransfer as by, itemsFromClipboardData as bz, type Action as c, DepNode as d, type Tool 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 };
+export { type CarryCallbacks as $, type Action as A, type BoundGesture as B, type Contribution as C, type DepRegistry as D, type ActionSource as E, type ActionTuning as F, type ActionTunings as G, type ActionsProp as H, type AnyTool as I, type AssemblyInputs as J, type KernelOverlay as K, type LongPressOptions as L, type MenuHost as M, type NodeId as N, type OverlayPosition as O, BROWSER_RESERVED_CHORDS as P, type BindingOpts as Q, type RuleCtx as R, ScopeNode as S, ToolNode as T, type BindingScope as U, type BindingSource as V, type BodyPredicate as W, type Bounds as X, type BuildRuleCtxArgs as Y, COARSE_TARGET_SCALE as Z, type Carry as _, type DepName as a, type ResizeAnchor as a$, type CarryPayload as a0, type CarryPointer as a1, type CarryStage as a2, type Condition as a3, type Conflict as a4, type ContributionChrome as a5, type ContributionDeps as a6, type ContributionRouting as a7, DEFAULT_ALLOWED_CAPABILITIES as a8, DEFAULT_DEVICE_PROFILE as a9, type MenuSources as aA, type MenuWhen as aB, type ModeShortcutHandlers as aC, type ModeSwitchLogEntry as aD, type ModifierRole as aE, type ModifierRoles as aF, type ModifierState as aG, NEVER as aH, type OngoingHandle as aI, type OngoingInvoker as aJ, type OngoingOverlay as aK, type OpenMenu as aL, type OverlayRole as aM, type OverlaySchema as aN, type OwnedMenuDef as aO, PREDICATE_TARGET as aP, type PendingLongPress as aQ, type PlacedBy as aR, type Point2 as aS, type PointerSession as aT, type PointerSessionCallbacks as aU, type PointerSessionCancelReason as aV, type PointerSessionOptions as aW, type RankedCandidate as aX, type RecordCandidate as aY, type RegistryEntry as aZ, type ReservedChord as a_, type DebugSink as aa, type DetectedDeviceFacts as ab, type DeviceProfile as ac, type DispatchRecord as ad, type DispatchRecordInput as ae, type DispatcherContext as af, type DragSample as ag, type DroppedCandidate as ah, type Eligibility as ai, type EligibilityState as aj, type GestureBinding as ak, type GestureKitSettings as al, type HandleKind as am, type HitShape as an, type HotkeyTrigger as ao, INGEST_STRING_MIMES as ap, type ImmediateInvoker as aq, type InvocationCtx as ar, type Invoker as as, type KeyBinding as at, type LongPressState as au, type LongPressStore as av, type MatchOutcome as aw, type MatchResult as ax, type MenuHit as ay, type MenuOpenRequest as az, type DepSchema as b, isPathEditPart as b$, type ResolveAllOptions as b0, type ResolveOnlyResult as b1, type ResolvedCandidate as b2, type RoleKeys as b3, type RoleRebinds as b4, type Rule as b5, type ScopedBinding as b6, type ScratchKey as b7, type ScratchStore as b8, type SelectionApi as b9, buildToolOffhandBindings as bA, clientToCanvas as bB, clientToCanvasRect as bC, createDepRegistry as bD, createDispatcher as bE, createLongPressStore as bF, createMenuHost as bG, defineTool as bH, deleteScratch as bI, describeRule as bJ, dlog as bK, dwarn as bL, evaluate as bM, evaluateActive as bN, evaluateEnabled as bO, findConflicts as bP, getScratch as bQ, heldKeySpec as bR, historyKey as bS, isAnchor as bT, isAnchorOrControl as bU, isBalanceGrip as bV, isBody as bW, isControlHandle as bX, isCornerWidget as bY, isDebugEnabled as bZ, isEmpty as b_, type Selector as ba, type SpecificityPart as bb, TOOL_OFFHAND_ID as bc, type ToolDef as bd, type ToolKeybinding as be, type ToolModifiers as bf, type ToolOffhandBindingSpec as bg, type ToolPresentation as bh, type ToolScopes as bi, type ToolSlot as bj, type TraceLogEntry as bk, type TunedBinding as bl, type UiOngoingControl as bm, type ViewportGestureKind as bn, type WalkStep as bo, actionBindings as bp, actionCursor as bq, actionItemTitle as br, actionItems as bs, actionShortcuts as bt, actionsTagged as bu, assembleEntries as bv, browserReservedChord as bw, buildDepsFromRequires as bx, buildRouteRegistry as by, buildRuleCtx as bz, type ActionDeps as c, isResizeHandle as c0, isRotateHandle as c1, isSegment as c2, isSelectedBody as c3, isTool as c4, isUnselectedBody as c5, itemTypesFromDataTransfer as c6, itemsFromClipboardData as c7, itemsFromDataTransfer as c8, itemsFromFiles as c9, routesForSpec as cA, ruleCanHoldIn as cB, rulesExclusive as cC, scopeBindings as cD, scratchKey as cE, setScratch as cF, startCarry as cG, taggedActionItems as cH, targetConsultsAffordance as cI, tuneAction as cJ, validateActionDefaultBinding as cK, validateActionId as cL, keySpecShortcut as ca, keysHeld as cb, liveScope as cc, makeToolOffhandAction as cd, matchActionItem as ce, matchBest as cf, matchSorted as cg, matchSortedWithBarred as ch, matchesKeyBinding as ci, mergeContributions as cj, mergeMenuDefs as ck, modeShortcutSpec as cl, modeShortcuts as cm, multiTouchGestureId as cn, offhandKeyFor as co, openPointerSession as cp, overlaysOf as cq, pickMenu as cr, pointerGestureId as cs, recordModeSwitch as ct, reportRouteConflicts as cu, resolveDeviceProfile as cv, resolveMenu as cw, resolveParams as cx, resolveSchemaMenu as cy, roleReader as cz, type ActionsRegistry as d, ActionDisabledReason as e, type ActionVariant as f, type MenuDef as g, DepNode as h, type Tool as i, ActiveToolContextProvider as j, ActiveToolContextProviderIfRoot as k, type ActiveToolContextProviderProps as l, type ActiveToolContextValue as m, useOptionalActiveToolContext as n, type Dispatcher as o, type AffordanceHit as p, ALWAYS as q, type ActionDispatch as r, type ActionEnabledResult as s, type ActionEntry as t, useActiveToolContext as u, type ActionItem as v, type ActionParamSchema as w, type ActionParams as x, type ActionPresentation as y, type ActionShortcut as z };