@weasel-js/core 0.7.2 → 1.0.0

package/dist/{index-DOYRTfP0.d.ts → index-ChM3ZJ2v.d.ts}

@@ -1,16 +1,17 @@
-import { N as NodeId, S as Scene, P as PoseComposition } from './types-Cpb4hii1.js';
-import { M as ModifierState, A as ActionBehavior, c as ResizeAnchor, R as ResizePose, B as BoundsConstraint, P as PointSnapBehavior } from './types-Dcaa0tPq.js';
+import { N as NodeId, R as RectPose, S as Scene } from './types-DUpI7Apc.js';
+import { M as ModifierState, A as ActionBehavior, c as ResizeAnchor, R as ResizePose, B as BoundsConstraint, P as PointSnapBehavior } from './types-BhJJ2OCM.js';
 import { V as View } from './view-DSQgxBJB.js';
 import { CapabilityTag } from '@weasel-js/modes';
 import * as React from 'react';
 import { MutableRefObject, ReactNode, ReactElement } from 'react';
-import { IngestItem, GestureSpec, InputEvent, ParsedModifiers, GestureName, ChannelRef, DescribeRouteOptions, GESTURE_DESCRIPTORS, GestureArgSpec, GestureDescriptor, ModRequirement, ModifierKey, ParsedRoute, PhaseAtom, RESERVED_ID_NAMES, RESERVED_ID_PREFIXES, ROUTE_FIELD_DEFINITIONS, ROUTE_TERMS, RouteDescriptionPart, RouteFieldName, RouteTermLabel, canonicalModifiers, collapseShiftPairs, describeRoute, describeRouteParts, formatPhaseAtom, formatRoute, getGestureDescriptor, isKnownGestureName, parseRoute } from '@weasel-js/gestures';
-import { F as FillStyle, a as Stroke, D as DrawCommand } from './DrawCommand-CJtqqt8H.js';
+import { GestureSpec, IngestItem, InputEvent, ParsedModifiers, GestureName, ChannelRef, DescribeRouteOptions, GESTURE_DESCRIPTORS, GestureArgSpec, GestureDescriptor, ModRequirement, ModifierKey, ParsedRoute, PhaseAtom, RESERVED_ID_NAMES, RESERVED_ID_PREFIXES, ROUTE_FIELD_DEFINITIONS, ROUTE_TERMS, RouteDescriptionPart, RouteFieldName, RouteTermLabel, canonicalModifiers, collapseShiftPairs, describeRoute, describeRouteParts, formatPhaseAtom, formatRoute, getGestureDescriptor, isKnownGestureName, parseRoute } from '@weasel-js/gestures';
+import { B as Bounds, P as PoseProjection } from './geometry-DVeZ2i-c.js';
+import { F as FillStyle, S as Stroke } from './paint-types-CnLIzqq1.js';
+import { D as DrawCommand } from './DrawCommand-DCmiNkBj.js';
 import * as react_jsx_runtime from 'react/jsx-runtime';
-import { P as Path } from './types-B6MMiodD.js';
+import { P as Path } from './path-B6MMiodD.js';
 import { Op, History } from '@weasel-js/history';
 import { L as LayoutStrategy, I as InsertAdapter } from './types-B_-khFM0.js';
-import { B as Bounds, P as PoseProjection } from './geometry-D9BDMiQi.js';
 import { Mat3 } from '@weasel-js/geom';
 import { D as DebugSink } from './types-BJ8_cyT7.js';
 
@@ -239,6 +240,31 @@ interface CommonAffordanceScratch {
         y: number;
     };
 }
+/**
+ * What a **registered layer's** `hitTest` returns. Extends `AffordanceBinding`
+ * so existing implementations keep typechecking; the added fields are how a
+ * consumer's own chrome says the things kit chrome says through
+ * `AffordanceRegion` — which cursor to show, and whether it owns the point
+ * outright.
+ */
+interface LayerHit<TScratch = unknown> extends AffordanceBinding<TScratch> {
+    /** CSS cursor while the pointer is over this hit. Reaches the hover-cursor
+     *  pump as `AffordanceHit.cursor`, the same path kit chrome uses. */
+    cursor?: string;
+    /** `'exclusive'` bars every binding whose target doesn't consult the
+     *  affordance. Omitted means `'shared'` — today's behavior. Same name and
+     *  meaning as `AffordanceHit.strength`, which it becomes. */
+    strength?: 'exclusive' | 'shared';
+    /** Which gestures an exclusive claim bars. Omitted bars all of them. */
+    claimedKinds?: readonly ClaimableGesture[];
+}
+/**
+ * Gesture kinds an affordance claim can bar, in the spec vocabulary bindings
+ * are written in. `'pointer'` is one token because `pointerDown` / `click` /
+ * `drag` are a single press protocol — at the event level the first two are
+ * the same `kind: 'pointerdown'`, told apart only by `stage`.
+ */
+type ClaimableGesture = 'pointer' | 'doubleClick' | 'contextMenu' | 'longPress' | 'wheel';
 
 /**
  * Canvas size in CSS pixels — passed to `draw` for layers that anchor to
@@ -317,7 +343,7 @@ interface RenderLayer<TData> {
     /** Chrome-caps visibility predicate. When supplied, the layer must
      *  not return a hit from any chrome element whose id reports
      *  `false`. Absent → every element is hittable. */
-    isVisible?: (id: string) => boolean) => AffordanceBinding | null;
+    isVisible?: (id: string) => boolean) => LayerHit | null;
     /**
      * Called on every pointermove when no gesture is currently captured.
      * Lets layers (e.g. HUD widgets) track hover state without participating
@@ -348,6 +374,31 @@ interface RenderLayer<TData> {
  */
 declare function drawLayers<TData>(layers: RenderLayer<TData>[], data: TData, visibility: Record<string, boolean>, order: string[] | undefined, view: View | undefined, dims: Dims): DrawCommand[];
 
+/**
+ * Facts about the device the canvas is running on.
+ *
+ * One object, recomputed when the underlying media queries change, read by
+ * two consumers: the chrome-caps rule layer (via `RuleCtx.device`) and the
+ * handle-sizing constants (via `targetScale`).
+ *
+ * Deliberately NOT a form-factor concept. There is no `isPhone` here and
+ * there should never be one: chrome layout is the consuming app's decision.
+ * The kit's job is to stop assuming a mouse.
+ */
+interface DeviceProfile {
+    /** `matchMedia('(pointer: coarse)')` — the primary pointer is imprecise. */
+    readonly coarsePointer: boolean;
+    /** `matchMedia('(hover: hover)')` — the primary pointer can hover. */
+    readonly canHover: boolean;
+    /** Live device pixel ratio. */
+    readonly dpr: number;
+    /** Multiplier for handle sizes and hit radii. Derived from
+     *  `coarsePointer` unless explicitly overridden. */
+    readonly targetScale: number;
+}
+/** The detected half of a profile — everything except the derived scale. */
+type DetectedDeviceFacts = Omit<DeviceProfile, 'targetScale'>;
+
 /**
  * Live state read by rule evaluation. Built once per frame on the consuming
  * surface — chrome-caps, the affordance pipeline, the dispatcher's
@@ -389,6 +440,13 @@ interface RuleCtx {
      *  with nothing being edited should draw no anchors. Absent is treated
      *  as false. */
     readonly editingAnchors?: boolean;
+    /** Device facts — pointer coarseness, hover capability, density.
+     *
+     *  Absent (legacy ctx builders) is treated as
+     *  {@link DEFAULT_DEVICE_PROFILE}: a fine pointer that can hover, at
+     *  density 1. That is what the kit assumed before this field existed, so
+     *  an absent profile is behavior-preserving by construction. */
+    readonly device?: DeviceProfile;
 }
 interface BuildRuleCtxArgs {
     focused: boolean;
@@ -407,6 +465,8 @@ interface BuildRuleCtxArgs {
     selectionResizable?: boolean;
     /** Optional — omitted means "no path is being anchor-edited". */
     editingAnchors?: boolean;
+    /** Optional — omitted means {@link DEFAULT_DEVICE_PROFILE}. */
+    device?: DeviceProfile;
 }
 declare function buildRuleCtx(args: BuildRuleCtxArgs): RuleCtx;
 
@@ -444,6 +504,12 @@ interface Selector {
      *  (resizable), so `{ resizable: true }` passes for legacy ctx builders
      *  that don't compute it. */
     resizable?: boolean;
+    /** Matches `ctx.device.coarsePointer` — the primary pointer is imprecise
+     *  (touch, most styluses). Absent device is treated as `false`. */
+    coarsePointer?: boolean;
+    /** Matches `ctx.device.canHover` — the primary pointer can hover. Absent
+     *  device is treated as `true`. */
+    canHover?: boolean;
 }
 /**
  * Composable visibility/eligibility rule. Trees of `all`/`any`/`not` nodes
@@ -583,6 +649,15 @@ interface Point2 {
 interface AffordanceHit {
     /** Discriminator string, e.g. `'handle:bottom-right'`. */
     kind: string;
+    /** Id of whatever produced this hit — a kit affordance's `id`, or the
+     *  registered layer's id. Read only by the dispatcher's dead-claim warning today. */
+    owner?: string;
+    /** `'exclusive'` means no binding may act on this point unless its target
+     *  consults the affordance. `'shared'` (the default) competes on scope and
+     *  specificity as bindings always have. */
+    strength?: 'exclusive' | 'shared';
+    /** Which gestures an exclusive claim bars. Omitted bars all of them. */
+    claimedKinds?: readonly ClaimableGesture[];
     /** World-space fixed/pivot point. For resize: opposite corner. For rotate: pivot. */
     fixedPoint?: {
         x: number;
@@ -910,6 +985,114 @@ interface OngoingInvoker {
  *  the `Action` type. */
 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`.
+ */
+
+interface GestureBinding {
+    spec: GestureSpec;
+    actionId: string;
+    opts?: BindingOpts;
+}
+
+/**
+ * Pose composition for hierarchical scene graphs.
+ *
+ * As of the nesting change, `getPose(id)` on adapters returns the
+ * **local** pose — relative to the object's direct parent. Anything in the
+ * kit that needs to draw, hit-test, snap, or otherwise reason about world
+ * coordinates routes through `composeWorldPose`, which walks the parent
+ * chain and folds local poses together via a consumer-supplied `compose`.
+ *
+ * Pose shape is generic, so the compose strategy is too. For the common
+ * `{x, y, width, height}` axis-aligned rect, use `composeRectPose` —
+ * translation only, child dimensions preserved. Custom pose shapes (paths,
+ * matrix transforms) supply their own.
+ *
+ * The inverse — `rebaseLocalPose` — converts a world-space pose into a
+ * local pose under a target parent. Used when reparenting so the visual
+ * world position of a child is preserved across the parent change.
+ */
+/** Re-exported; the declaration lives in `core/scene/types.ts`, which names
+ *  it and may not import from features. */
+
+/** Minimal adapter needed by `composeWorldPose` and friends — pose lookup plus parent walk. */
+interface PoseAdapter<TPose> {
+    getPose(id: string): TPose;
+    getParent(id: string): string | null;
+}
+/** Consumer's pose-composition strategy for hierarchical scenes. `compose`
+ *  folds a child's pose (in parent's frame) up to the next frame; `decompose`
+ *  is its inverse. Default is IDENTITY — an absolute-pose scene where every
+ *  node already stores world coords (parent is grouping-only, no transform). */
+interface PoseComposition<TPose> {
+    compose: (parent: TPose, child: TPose) => TPose;
+    decompose: (parent: TPose, world: TPose) => TPose;
+}
+/** Default pose-composition strategy: IDENTITY. Both `compose` and
+ *  `decompose` return the child/world pose unchanged, modeling an
+ *  absolute-pose scene where every node stores world coords and parents are
+ *  grouping-only (no transform). With this strategy `composeWorldPose`
+ *  returns a node's own raw pose and `rebaseLocalPose` is a no-op. */
+declare const IDENTITY_POSE_COMPOSITION: PoseComposition<unknown>;
+/**
+ * Walk `id`'s parent chain (root first to id last) and fold local poses into
+ * a world pose via `compose`. Returns the world pose for `id`. Cycle-safe:
+ * a visited-set guard breaks if the chain ever loops back to itself.
+ *
+ * `compose(parent, child)` interprets `child` as expressed *in `parent`'s
+ * local frame* and returns the equivalent pose in the next frame up. For a
+ * standard translation-only rect: `world = { x: p.x + c.x, y: p.y + c.y,
+ * width: c.width, height: c.height }`.
+ */
+declare function composeWorldPose<TPose>(adapter: PoseAdapter<TPose>, id: string, compose: (parent: TPose, child: TPose) => TPose): TPose;
+/**
+ * Default `compose` for axis-aligned rectangles. Adds translation; preserves
+ * child width/height. Treat as the canonical compose for any
+ * `{x, y, width, height}` pose under a translation-only hierarchy.
+ *
+ * Generic over the concrete pose type so callers with a wider pose
+ * (e.g. `RectPose & { rotation }`) can pass it through; the extra fields
+ * are taken from the child unchanged.
+ */
+declare function composeRectPose<TPose extends RectPose>(parent: TPose, child: TPose): TPose;
+/**
+ * Translate a `RectPose`-shaped pose by `(dx, dy)`. Suitable as the default
+ * `translatePose` for `useMove` when poses carry top-level `x`/`y`. Other
+ * fields (width/height, plus any extra props on `TPose`) are preserved.
+ */
+declare function translateRectPose<TPose extends RectPose>(pose: TPose, dx: number, dy: number): TPose;
+/**
+ * Convert `worldPose` into a local pose expressed under `newParentId`'s
+ * frame. Used when reparenting so the child's visual world position is
+ * preserved despite the change of frame. Inverse of one `compose` step.
+ *
+ * `decompose(parent, world)` returns the local pose `child` such that
+ * `compose(parent, child) === world`. For axis-aligned rects:
+ * `child = { ...world, x: world.x - parent.x, y: world.y - parent.y }`.
+ *
+ * Pass `newParentId === null` for the root frame; the function returns
+ * `worldPose` unchanged.
+ */
+declare function rebaseLocalPose<TPose>(adapter: PoseAdapter<TPose>, worldPose: TPose, newParentId: string | null, compose: (parent: TPose, child: TPose) => TPose, decompose: (parent: TPose, world: TPose) => TPose): TPose;
+/** Inverse of `composeRectPose` — subtracts parent translation. */
+declare function decomposeRectPose<TPose extends RectPose>(parent: TPose, world: TPose): TPose;
+/**
+ * Build a `(id) => world pose | null` callback over a `PoseAdapter`.
+ * Convenience for RenderLayers that take a `getPose` callback (selection
+ * overlays, debug layers, etc.) so consumers don't hand-write a
+ * `composeWorldPose` call per layer.
+ *
+ * Returns `null` when `adapter.getPose` or `adapter.getParent` throws — the
+ * common case is an id removed mid-render between selection state and the
+ * next paint. Layers should treat `null` as "skip this id."
+ */
+declare function worldPoseLookup<TPose>(adapter: PoseAdapter<TPose>, compose: (parent: TPose, child: TPose) => TPose): (id: string) => TPose | null;
+
 /** Boolean op identifiers — five Pathfinder primaries plus Crop. */
 type BooleanOp = 'union' | 'intersect' | 'subtract' | 'exclude' | 'divide' | 'crop';
 /**
@@ -1320,6 +1503,35 @@ declare const sliceAction: Action & {
     requires: string[];
 };
 
+/**
+ * Clipboard dep — the imperative surface `useClipboardOps` returns.
+ *
+ * Consumers publish their live clipboard through `useDepSource('clipboard',
+ * …)` from inside the `<DepRegistryProvider>` (i.e. under `<SceneCanvas>`).
+ * The kit deliberately does not build one for them: `useClipboardOps` needs
+ * an adapter and a selection reader that only the consumer can supply.
+ */
+interface ClipboardDep {
+    copy(): void;
+    paste(): void;
+    isEmpty(): boolean;
+}
+/**
+ * @experimental
+ * Static descriptor for the `clipboard.copy` Action (Cmd/Ctrl+C).
+ */
+declare const clipboardCopyAction: Action & {
+    requires: string[];
+};
+/**
+ * @experimental
+ * Static descriptor for the `clipboard.cut` Action (Cmd/Ctrl+X) — copy, then
+ * the same batched delete `deleteAction` performs, as one undo entry.
+ */
+declare const clipboardCutAction: Action & {
+    requires: string[];
+};
+
 /** Optional consumer seam: given a node and the affine `m` that a pose-transform
  *  action applied to the node's POSE, return updated `data` with the node's
  *  data-held geometry transformed by `m`, or `null` if this node has no
@@ -1832,6 +2044,15 @@ interface DepSchema {
      * Optional: when absent, `sliceAction` is a no-op.
      */
     slice?: SliceDep;
+    /**
+     * Clipboard dep — the imperative surface `useClipboardOps` returns.
+     *
+     * Published by the consumer (`useDepSource('clipboard', …)` from under
+     * `<SceneCanvas>`), because `useClipboardOps` needs an adapter and a
+     * selection reader only the consumer has. Feeds `clipboard.copy` /
+     * `clipboard.cut`; both no-op when the dep is absent.
+     */
+    clipboard?: ClipboardDep;
     /**
      * Optional consumer commit hook. When present, `moveAction` (and other
      * default actions) submit their committed ops through it instead of
@@ -1901,17 +2122,35 @@ declare function useOptionalDepRegistry(): DepRegistry | null;
 declare function useDepSource<K extends DepName>(name: K, source: () => DepSchema[K]): void;
 
 /**
- * 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`.
+ * When an entry's bindings are live. A set, not one value: the hand tool is
+ * palette-selectable AND engaged by holding space, and both hold at once.
+ */
+interface Eligibility {
+    /** Selectable as the focused entry — exclusive, one at a time. */
+    focus?: boolean;
+    /** Also live while this key is held. */
+    offhand?: HotkeyTrigger;
+    /** Live regardless of what is focused. */
+    always?: boolean;
+    /** Live only for input this entry's own affordances produced. */
+    claimed?: boolean;
+    /** Modality filter, applied wherever it would otherwise be live. */
+    capabilities?: CapabilityTag[];
+}
+/**
+ * A registry entry: what it contributes, and when it is eligible. Every role
+ * is optional and independent — an entry that only routes input declares only
+ * `bindings` and `actions`.
  */
-
-interface GestureBinding {
-    spec: GestureSpec;
-    actionId: string;
-    opts?: BindingOpts;
+interface Contribution {
+    id: string;
+    eligibility: Eligibility;
+    bindings?: GestureBinding[];
+    actions?: Action[];
+    overlay?: RenderLayer<unknown>;
+    presentation?: ToolPresentation;
+    /** Reflection escape hatch — the authored form, when there was one. */
+    def?: unknown;
 }
 
 /** Modifier-key snapshot at event dispatch time. `space` is included
@@ -1975,8 +2214,8 @@ type ToolBounds = Bounds;
  *  tool — consumers that render a palette (`<ToolPalette>`) read these
  *  fields to display the tool; consumers that don't can ignore them.
  *
- *  Note: cursor is NOT here. The top-level `Tool.cursor` field below is
- *  already plumbed through `<Canvas>` to `style.cursor` on the host. */
+ *  Note: cursor is NOT here. `Tool.cursor` (inherited from `Contribution`)
+ *  is already plumbed through `<Canvas>` to `style.cursor` on the host. */
 interface ToolPresentation<TScratch = unknown> {
     /** Human-readable label, distinct from the `id`. Falls back to `id`. */
     label?: string;
@@ -1991,34 +2230,13 @@ interface ToolPresentation<TScratch = unknown> {
      *  derives one from `Tool.keybinding` via its own formatter. */
     shortcut?: string;
 }
-/** Full Tool record. */
-interface Tool<TScratch = unknown> {
-    id: string;
-    /**
-     * App-level capability tags for modality. The `weasel-modes` package's
-     * `eligibleForMode(mode, capabilities)` predicate consumes these to decide
-     * whether the tool is usable in the active mode. Tags are extensible
-     * strings — apps can define their own. Untagged tools are treated as
-     * ineligible by all modes except those whose `allows` list includes
-     * every implicit-or-declared tag (i.e. `normal` in the default preset).
-     */
-    capabilities?: CapabilityTag[];
-    /**
-     * Actions this tool owns and needs registered while it is in the tools
-     * registry — e.g. polygon's `polygon.adjustSides`, which its own bindings
-     * reference by id.
-     *
-     * Declared here rather than registered by the hook with `useAction`,
-     * because tool hooks run wherever the consumer calls them — for
-     * `<SceneCanvas>` that is ABOVE `<ActionsProviderIfRoot>`, where
-     * `useActionsRegistry()` returns null and `useAction` silently no-ops. The
-     * result was a binding pointing at an action id nothing had registered, so
-     * the gesture fell through to whatever matched next (polygon's
-     * wheel/arrow-key side adjustment did nothing and `nudge.*` moved the
-     * selection instead). `<ToolActionsMounter>` registers these from inside
-     * the provider.
-     */
-    actions?: Action[];
+/**
+ * The focus-declaring case of a `Contribution`: a mode the user switches
+ * into, plus the hooks that only make sense for one (`initScratch`,
+ * activate/deactivate, live preview, `cursor`). Everything else — bindings,
+ * actions, overlay, presentation — is inherited.
+ */
+interface Tool<TScratch = unknown> extends Contribution {
     /** Optional caller-supplied key. Most built-in tools have their activation
      *  key declared in `BUILTIN_SELECT_KEYS` in `useKeybindings.ts`; this field
      *  is for tools that want their activation key to be configurable by the
@@ -2028,11 +2246,9 @@ interface Tool<TScratch = unknown> {
      *  the invoker knows which tool to switch to). */
     keybinding?: ToolKeybinding;
     initScratch?: () => TScratch;
+    cursor?: string | ((ctx: ToolCtx<TScratch>) => string);
     onActivate?: (ctx: ToolCtx<TScratch>) => void;
     onDeactivate?: (ctx: ToolCtx<TScratch>) => void;
-    cursor?: string | ((ctx: ToolCtx<TScratch>) => string);
-    /** Presentation metadata for tool palettes. See `ToolPresentation`. */
-    presentation?: ToolPresentation<TScratch>;
     /** Returns the in-flight preview pose for `id` if this tool is mid-gesture
      *  on it; otherwise `null`. Lets `Canvas.helpersRef.getEffectivePose`
      *  reflect live gesture state without reaching into hook internals. The
@@ -2050,26 +2266,6 @@ interface Tool<TScratch = unknown> {
      *  consults this alongside `previewPose` to avoid double-rendering. Returns
      *  `null` when no gesture is in flight. */
     previewIds?: () => Iterable<string> | null;
-    /** Optional overlay layer rendered on top of the scene/chrome whenever
-     *  this tool is in any active slot (active, hotkey, or ambient).
-     *  The layer's `draw` function reads from this tool's scratch via React
-     *  closure (re-evaluated each render). Return early from `draw` to render
-     *  nothing — typically gated on a scratch field like
-     *  `if (!scratch.overlay) return`. */
-    overlay?: RenderLayer<unknown>;
-    /** Declarative gesture bindings — the tool's entire input surface. The
-     *  gesture dispatcher consults these at active scope while this tool is
-     *  active, and at hotkey scope while it is held. See
-     *  `docs/superpowers/specs/2026-05-16-registry-unification-design.md`. */
-    bindings?: GestureBinding[];
-    /** Reflection escape hatch: when this `Tool` was produced by `defineTool`,
-     *  the source `ToolDef` is attached here so introspection consumers
-     *  (`buildRouteRegistry`, `findConflicts`, the toolkit-builder UI, the
-     *  reflection demo) can read the authored form — `hookName` in particular,
-     *  which the runtime `Tool` doesn't carry. Tools constructed without
-     *  `defineTool` may leave this undefined. Typed as `unknown` to keep this
-     *  file from importing the routing types — consumers cast at the use site. */
-    def?: unknown;
 }
 /** Internal — which slot a tool occupies in the dispatch order. */
 type ToolSlot = 'hotkey' | 'active' | 'ambient';
@@ -2162,17 +2358,6 @@ interface DispatcherContext {
     activeToolId: string;
     /** Held-hotkey stack, top of stack last. */
     hotkeyStack: readonly string[];
-    /**
-     * Ids of always-on tools. Their bindings are assembled at AMBIENT scope, so
-     * they lose to the active tool on a tie — which is what "always listening,
-     * never in the way" needs. Chrome that floats over the scene lives here:
-     * `@weasel-js/hud`'s tool is the worked example.
-     *
-     * Without this an ambient tool's `bindings` were assembled nowhere at all:
-     * the walk covered hotkey and active tools plus actions' `defaultBinding`,
-     * and an ambient tool is in neither set.
-     */
-    ambientToolIds?: readonly string[];
     /** Lookup for tool definitions. */
     toolsById: ReadonlyMap<string, Tool>;
     /** Platform flag for `mod` shorthand resolution. */
@@ -2700,13 +2885,10 @@ interface ToolDef<TScratch = void> {
      *  to the consolidated `tool.activate` action (with `opts.params.toolId`
      *  set so the invoker knows which tool to switch to). */
     keybinding?: ToolKeybinding;
-    /** Declarative held-key trigger (reflection / inspector only). When set,
-     *  signals to the host that this tool can engage via a held key; the host
-     *  must register the activation via the consolidated `tool.offhand` action
-     *  (`makeToolOffhandAction` + `buildToolOffhandBindings`). Built-in tools
-     *  declare held keys in `BUILTIN_OFFHAND_ACTIONS`; configurable-hotkey
-     *  tools rely on the host to wire the binding. Setting this field does NOT
-     *  automatically engage the held-key behavior. */
+    /** Held-key trigger: this tool engages while the key is down and
+     *  disengages on release. Carried onto `Tool.eligibility.offhand`, which
+     *  assembly reads to register the consolidated `tool.offhand` action — the
+     *  declaration is the wiring, with nothing for the host to do. */
     hotkey?: HotkeyTrigger;
     onActivate?: (ctx: ToolCtx<TScratch>) => void;
     onDeactivate?: (ctx: ToolCtx<TScratch>) => void;
@@ -2884,6 +3066,9 @@ interface ToolScopes {
     registry: readonly Tool<unknown>[] | Readonly<Record<string, Tool<unknown>>>;
     /** Always-on tools. Every one of these is live at once. */
     ambient?: readonly Tool<unknown>[];
+    /** Registered actions. Their `defaultBinding`s assemble at ambient scope
+     *  (hotkey scope when `Action.scope` says so), alongside the tools above. */
+    actions?: readonly Action[];
 }
 /**
  * Detect the same-tuple overlaps that are *reachable* — the ones where the
@@ -2903,10 +3088,10 @@ interface ToolScopes {
  *    ordered only by registration;
  *  - two **hotkey-capable** tools, which can stack.
  *
- * Not covered: the actions registry's `defaultBinding`s, which the dispatcher
- * also folds into ambient/hotkey scope. They're assembled somewhere else
- * entirely (`ActionsRegistry`, not `useTools`), so catching tool-vs-action
- * collisions means giving this function a second input it doesn't have yet.
+ * Registered actions join the same two buckets: their `defaultBinding`s
+ * assemble at ambient scope (hotkey scope when `Action.scope` says so), so an
+ * ambient tool and an action claiming one tuple really do fall back on
+ * declaration order.
  */
 declare function findScopedConflicts(scopes: ToolScopes): Conflict[];
 /**
@@ -2983,4 +3168,4 @@ declare namespace index {
   export { index_ChannelRef as ChannelRef, type index_Conflict as Conflict, index_DescribeRouteOptions as DescribeRouteOptions, index_GESTURE_DESCRIPTORS as GESTURE_DESCRIPTORS, index_GestureArgSpec as GestureArgSpec, index_GestureDescriptor as GestureDescriptor, index_GestureName as GestureName, index_ModRequirement as ModRequirement, index_ModifierKey as ModifierKey, index_PREDICATE_TARGET as PREDICATE_TARGET, index_ParsedModifiers as ParsedModifiers, index_ParsedRoute as ParsedRoute, index_PhaseAtom as PhaseAtom, index_RESERVED_ID_NAMES as RESERVED_ID_NAMES, index_RESERVED_ID_PREFIXES as RESERVED_ID_PREFIXES, index_ROUTE_FIELD_DEFINITIONS as ROUTE_FIELD_DEFINITIONS, index_ROUTE_TERMS as ROUTE_TERMS, type index_RegistryEntry as RegistryEntry, index_RouteDescriptionPart as RouteDescriptionPart, index_RouteFieldName as RouteFieldName, index_RouteTermLabel as RouteTermLabel, type index_ToolDef as ToolDef, type index_ToolKeybinding as ToolKeybinding, type index_ToolScopes as ToolScopes, type index_ViewportToolDef as ViewportToolDef, index_buildRouteRegistry as buildRouteRegistry, index_canonicalModifiers as canonicalModifiers, index_collapseShiftPairs as collapseShiftPairs, index_defineTool as defineTool, index_defineViewportTool as defineViewportTool, index_describeRoute as describeRoute, index_describeRouteParts as describeRouteParts, index_findConflicts as findConflicts, index_findScopedConflicts as findScopedConflicts, index_formatConflict as formatConflict, index_formatPhaseAtom as formatPhaseAtom, index_formatRoute as formatRoute, index_getGestureDescriptor as getGestureDescriptor, index_isKnownGestureName as isKnownGestureName, index_parseRoute as parseRoute, index_reportRouteConflicts as reportRouteConflicts };
 }
 
-export { DepRegistryProvider as $, type Action as A, type BooleansAdapter as B, type Condition as C, type Dims as D, ActiveToolContextProvider as E, ActiveToolContextProviderIfRoot as F, type GeometryProjection as G, type HotkeyTrigger as H, type InsertExtras as I, type ActiveToolContextProviderProps as J, type ActiveToolContextValue as K, type AreaSelectDep as L, type BindingOpts as M, type BindingScope as N, type BooleanOp as O, type BooleanOpResult as P, type BoundGesture as Q, type RenderLayer as R, type SliceDep as S, type Tool as T, type UseSelectionOptions as U, type VisibilityRules as V, type BuildRuleCtxArgs as W, type ClipboardIngestCtx as X, type CustomPaintContext as Y, type DepName as Z, type DepRegistry as _, type Rule as a, type ToolScopes as a$, type DispatcherContext as a0, type DragSample as a1, type EditAnchorsDep as a2, type GestureBinding as a3, type ImmediateInvoker as a4, type IngestCtx as a5, type IngestionDep as a6, type InsertDep as a7, type InvocationCtx as a8, type Invoker as a9, type UiOngoingControl as aA, type ViewApi as aB, applyBooleanOp as aC, buildRuleCtx as aD, createDispatcher as aE, describeRule as aF, drawLayers as aG, enterTextEditAction as aH, evaluate as aI, evaluateEnabled as aJ, registerContentHandler as aK, index as aL, sliceAction as aM, specificity as aN, useAction as aO, useActionsRegistry as aP, useActiveToolContext as aQ, useDepRegistry as aR, useDepSource as aS, useOptionalActiveToolContext as aT, useOptionalDepRegistry as aU, usePointerContext as aV, useSelection as aW, type Conflict as aX, PREDICATE_TARGET as aY, type RegistryEntry as aZ, type ToolDef as a_, type LassoSelectDep as aa, type LayoutDep as ab, type MatchResult as ac, NEVER as ad, type NodeAtPointDep as ae, type OngoingHandle as af, type OngoingInvoker as ag, type OngoingOverlay as ah, type Point2 as ai, PointerContextProvider as aj, type PointerContextValue as ak, type PointerWorldPos as al, type ResizePolicy as am, type ResolveAllOptions as an, type ResolveOnlyResult as ao, type ResolvedCandidate as ap, type ScopedBinding as aq, type SelectionExtendKey as ar, type SelectionMode as as, type Selector as at, type SnapDep as au, type SvgUnpacker as av, type TextEditDep as aw, type ToolModifiers as ax, type ToolPresentation as ay, type ToolSlot as az, type RuleCtx as b, type ViewportToolDef as b0, buildRouteRegistry as b1, defineTool as b2, defineViewportTool as b3, findConflicts as b4, findScopedConflicts as b5, formatConflict as b6, reportRouteConflicts as b7, type ChromeCtx as c, type ChromeId as d, type DepSchema as e, type ActionsRegistry as f, type AffordanceHit as g, type Dispatcher as h, type AnyTool as i, type ToolCtx as j, type ToolKeybinding as k, type AffordanceBinding as l, type ChromeState as m, type SelectionApi as n, type ContentHandlerEntry as o, type SvgIngestOptions as p, type ActionsProp as q, type Affordance as r, type AffordanceRegion as s, type CommonAffordanceScratch as t, ALWAYS as u, type ActionDeps as v, ActionDisabledReason as w, type ActionEnabledResult as x, type ActionEntry as y, ActionsProvider as z };
+export { type BoundGesture as $, type Action as A, type BooleansAdapter as B, type Condition as C, type Dims as D, type Eligibility as E, type ActionDeps as F, type GeometryProjection as G, type HotkeyTrigger as H, type InsertExtras as I, ActionDisabledReason as J, type ActionEnabledResult as K, type LayerHit as L, type ActionEntry as M, ActionsProvider as N, ActiveToolContextProvider as O, ActiveToolContextProviderIfRoot as P, type ActiveToolContextProviderProps as Q, type RenderLayer as R, type SliceDep as S, type Tool as T, type UseSelectionOptions as U, type VisibilityRules as V, type ActiveToolContextValue as W, type AreaSelectDep as X, type BindingOpts as Y, type BooleanOp as Z, type BooleanOpResult as _, type DeviceProfile as a, index as a$, type BuildRuleCtxArgs as a0, type ClaimableGesture as a1, type ClipboardDep as a2, type ClipboardIngestCtx as a3, type CustomPaintContext as a4, type DepName as a5, type DepRegistry as a6, DepRegistryProvider as a7, type DispatcherContext as a8, type DragSample as a9, type ResolvedCandidate as aA, type SelectionExtendKey as aB, type SelectionMode as aC, type Selector as aD, type SnapDep as aE, type SvgUnpacker as aF, type TextEditDep as aG, type ToolModifiers as aH, type ToolPresentation as aI, type ToolSlot as aJ, type UiOngoingControl as aK, type ViewApi as aL, applyBooleanOp as aM, buildRuleCtx as aN, clipboardCopyAction as aO, clipboardCutAction as aP, composeRectPose as aQ, composeWorldPose as aR, createDispatcher as aS, decomposeRectPose as aT, describeRule as aU, drawLayers as aV, enterTextEditAction as aW, evaluate as aX, evaluateEnabled as aY, rebaseLocalPose as aZ, registerContentHandler as a_, type EditAnchorsDep as aa, type GestureBinding as ab, IDENTITY_POSE_COMPOSITION as ac, type ImmediateInvoker as ad, type IngestCtx as ae, type IngestionDep as af, type InsertDep as ag, type InvocationCtx as ah, type Invoker as ai, type LassoSelectDep as aj, type LayoutDep as ak, type MatchResult as al, NEVER as am, type NodeAtPointDep as an, type OngoingHandle as ao, type OngoingInvoker as ap, type OngoingOverlay as aq, type Point2 as ar, PointerContextProvider as as, type PointerContextValue as at, type PointerWorldPos as au, type PoseAdapter as av, type PoseComposition as aw, type ResizePolicy as ax, type ResolveAllOptions as ay, type ResolveOnlyResult as az, type DetectedDeviceFacts as b, sliceAction as b0, specificity as b1, translateRectPose as b2, useAction as b3, useActionsRegistry as b4, useActiveToolContext as b5, useDepRegistry as b6, useDepSource as b7, useOptionalActiveToolContext as b8, useOptionalDepRegistry as b9, usePointerContext as ba, useSelection as bb, worldPoseLookup as bc, type Conflict as bd, PREDICATE_TARGET as be, type RegistryEntry as bf, type ToolDef as bg, type ToolScopes as bh, type ViewportToolDef as bi, buildRouteRegistry as bj, defineTool as bk, defineViewportTool as bl, findConflicts as bm, findScopedConflicts as bn, formatConflict as bo, reportRouteConflicts as bp, type Rule as c, type RuleCtx as d, type ChromeCtx as e, type ChromeId as f, type DepSchema as g, type ActionsRegistry as h, type AffordanceHit as i, type Dispatcher as j, type AnyTool as k, type ToolCtx as l, type ToolKeybinding as m, type ChromeState as n, type SelectionApi as o, type ContentHandlerEntry as p, type SvgIngestOptions as q, type ActionsProp as r, type Affordance as s, type AffordanceBinding as t, type AffordanceRegion as u, type CommonAffordanceScratch as v, type BindingScope as w, type Contribution as x, type ScopedBinding as y, ALWAYS as z };