@weasel-js/labkit 0.7.2 → 1.0.0

package/dist/passthrough/weasel-canvas.d.ts

@@ -1,6 +1,6 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import { Ref } from 'react';
-import { N as Node, V as View, D as DrawCommand, S as Scene, B as Bounds, a as ViewportDims, P as PathDrawCommand } from '../_dts/DrawCommand-CEvS5AdV.js';
+import { N as Node, V as View, D as DrawCommand, S as Scene, B as Bounds, a as ViewportDims, P as PathDrawCommand } from '../_dts/DrawCommand-BwRCZYuo.js';
 
 /**
  * `renderSceneToCanvas` — substrate for detached, read-only scene views

package/dist/passthrough/weasel-canvas.js

@@ -1,3 +1,3 @@
-export { FALLBACK_FIT_VIEW, MinimapCanvas, SceneViewCanvas, buildSceneViewCommands, computeFitView2 as computeFitView, computeIndicatorCommand, renderSceneToCanvas } from '../chunk-5XDFILHZ.js';
+export { FALLBACK_FIT_VIEW, MinimapCanvas, SceneViewCanvas, buildSceneViewCommands, computeFitView2 as computeFitView, computeIndicatorCommand, renderSceneToCanvas } from '../chunk-XVBXYKFJ.js';
 //# sourceMappingURL=weasel-canvas.js.map
 //# sourceMappingURL=weasel-canvas.js.map

package/dist/passthrough/weasel-ui.d.ts

@@ -1,7 +1,7 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import * as react from 'react';
 import { ReactNode, CSSProperties, ButtonHTMLAttributes, ReactElement, MutableRefObject, PointerEvent as PointerEvent$1, KeyboardEvent, RefCallback } from 'react';
-import { O as Op, V as View, D as DrawCommand, b as NodeId, c as Path, S as Scene, H as History, d as PoseComposition, B as Bounds } from '../_dts/DrawCommand-CEvS5AdV.js';
+import { V as View, D as DrawCommand, O as Op, b as NodeId, c as Path, S as Scene, H as History, B as Bounds } from '../_dts/DrawCommand-BwRCZYuo.js';
 import { TextFieldProps, ValidationResult, CheckboxProps as CheckboxProps$1, SwitchProps as SwitchProps$1, TabProps as TabProps$1, TabListProps as TabListProps$1, TabPanelProps as TabPanelProps$1, TabsProps as TabsProps$1, RadioProps as RadioProps$1, RadioGroupProps as RadioGroupProps$1, NumberFieldProps as NumberFieldProps$1, SelectProps as SelectProps$1, ListBoxItemProps, ComboBoxProps as ComboBoxProps$1, SliderProps as SliderProps$1, ModalOverlayProps, DialogProps as DialogProps$1 } from 'react-aria-components';
 
 /**
@@ -1124,6 +1124,181 @@ interface PowerlineProps {
 }
 declare function Powerline({ segments, startCap, size, variant, depth, gap, className, ...rest }: PowerlineProps): react_jsx_runtime.JSX.Element;
 
+/**
+ * Snapshot of modifier-key state at gesture dispatch.
+ *
+ * Lives in core rather than beside the gesture types that produce it because
+ * `core/selection/chromeState.ts` reads it, and core may not import from
+ * `interactions/`. Re-exported from `interactions/gestures/types.ts`, which
+ * is still where gesture code names it.
+ */
+interface ModifierState {
+    alt: boolean;
+    shift: boolean;
+    meta: boolean;
+    ctrl: boolean;
+}
+
+/**
+ * @experimental
+ * Result of an affordance hit — what the region computed about itself.
+ *
+ * `initialScratch` is the payload: what the region already knows (which
+ * corner, which target id) so the action that picks up the drag doesn't
+ * re-derive it. `<SceneCanvas>` reads it out of the layer hit-test and packs
+ * it into `AffordanceHit`, which flows to the matching action through
+ * `InvocationCtx.drag.affordance`.
+ *
+ * This used to also carry a `drag: DragChannel` naming the handlers the
+ * tool-routing dispatcher should wire up. Every implementation supplied a
+ * no-op stub that claimed, because the real routing had already moved to
+ * bindings; the field went with that dispatcher.
+ */
+interface AffordanceBinding<TScratch = unknown> {
+    initialScratch?: TScratch;
+}
+/**
+ * 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
+ * canvas edges (e.g. the debug overlay's layer-list panel). The GL backend
+ * supplies it explicitly so layers don't have to know about DPR.
+ */
+interface Dims {
+    width: number;
+    height: number;
+}
+/**
+ * A single named render sub-layer within a canvas renderer.
+ *
+ * @template TData - The data object passed to each draw call.
+ */
+interface RenderLayer<TData> {
+    /** Unique identifier used in visibility maps and ordering arrays. */
+    id: string;
+    /** Human-readable name for UI toggles. */
+    label: string;
+    /**
+     * Emit a DrawCommand tree for the GL backend to dispatch.
+     *
+     * For world-space layers (the default), emit commands in WORLD COORDS —
+     * `drawLayers` automatically wraps them in `{ kind: 'group', transform:
+     * viewToMat3(view), ... }` before handing them to the renderer. Do NOT
+     * apply the view transform yourself.
+     *
+     * For screen-space layers (`space: 'screen'`), emit commands in CSS-pixel
+     * coords directly; `drawLayers` passes them through unchanged. If part
+     * of a screen-space layer's output needs to track the view, wrap that
+     * subset manually with `viewToMat3(view)`.
+     */
+    draw: (data: TData, view: View, dims: Dims) => DrawCommand[];
+    /**
+     * Whether the layer is shown when no explicit visibility entry exists.
+     * Defaults to `true` when absent.
+     */
+    defaultVisible?: boolean;
+    /**
+     * When true, the layer is always drawn regardless of the visibility map.
+     * Useful for layers that must never be hidden (e.g. base grid).
+     */
+    alwaysOn?: boolean;
+    /**
+     * Coordinate space the layer draws in.
+     *
+     * - `'world'` (default): the layer's `draw` returns world-space commands;
+     *   `drawLayers` wraps them in a `kind: 'group'` with `viewToMat3(view)`
+     *   automatically.
+     * - `'screen'`: the layer's `draw` returns screen-space (CSS-pixel)
+     *   commands; `drawLayers` passes them through unchanged. World-anchored
+     *   chrome inside a screen-space layer must call `worldToScreen` or wrap
+     *   the relevant subset with `viewToMat3(view)` manually.
+     */
+    space?: 'world' | 'screen';
+    /**
+     * Optional hit-test for **consumer-attached** layers.
+     *
+     * Only layers registered through `CanvasExtensionApi.registerLayer` are
+     * hit-tested: `hitTestExtras` walks them last-registered-first on
+     * pointerdown, and `<SceneCanvas>` folds the result into its `affordanceAt`
+     * thunk ahead of the kit's own selection chrome. First non-null result
+     * wins; null means "I don't claim this hit, try the next layer."
+     *
+     * Layers that reach the draw stack some other way — a `Tool.overlay`, an
+     * entry in the `layers` map — are painted but never hit-tested, so defining
+     * `hitTest` on one has no effect. (The kit's own chrome doesn't need it: it
+     * goes through `buildAffordanceAt`.)
+     *
+     * Coordinates are world-space. The `data` arg is the layer's
+     * configured data slot (same as `draw`); `view` and `dims` mirror
+     * `draw`'s arguments.
+     */
+    hitTest?: (worldX: number, worldY: number, data: TData, view: View, dims: Dims, 
+    /** 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) => LayerHit | null;
+    /**
+     * Called on every pointermove when no gesture is currently captured.
+     * Lets layers (e.g. HUD widgets) track hover state without participating
+     * in the drag pipeline. Coords are world-space; the layer is responsible
+     * for any further conversion (e.g. world→screen for screen-space layers)
+     * and for its own throttling.
+     */
+    onUncapturedMove?: (worldX: number, worldY: number, evt: PointerEvent, view: View, dims: Dims) => void;
+    /**
+     * Called when the cursor leaves the canvas element. Lets layers clear
+     * any hover state they're holding.
+     */
+    onUncapturedLeave?: () => void;
+}
+
+/**
+ * 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;
+}
+
 type ContainerBounds = {
     x: number;
     y: number;
@@ -1309,13 +1484,6 @@ interface InsertAdapter<TNode extends {
     getSelection(): string[];
 }
 
-/** Snapshot of modifier-key state at gesture dispatch. */
-interface ModifierState {
-    alt: boolean;
-    shift: boolean;
-    meta: boolean;
-    ctrl: boolean;
-}
 /** Pointer position in both world and client coords. */
 interface PointerState {
     worldX: number;
@@ -1430,118 +1598,6 @@ interface PointSnapBehavior<TPose extends ResizePose> {
     onMove(ctx: PointSnapContext<TPose>): PointSnapResult | null | undefined;
 }
 
-/**
- * @experimental
- * Result of an affordance hit — what the region computed about itself.
- *
- * `initialScratch` is the payload: what the region already knows (which
- * corner, which target id) so the action that picks up the drag doesn't
- * re-derive it. `<SceneCanvas>` reads it out of the layer hit-test and packs
- * it into `AffordanceHit`, which flows to the matching action through
- * `InvocationCtx.drag.affordance`.
- *
- * This used to also carry a `drag: DragChannel` naming the handlers the
- * tool-routing dispatcher should wire up. Every implementation supplied a
- * no-op stub that claimed, because the real routing had already moved to
- * bindings; the field went with that dispatcher.
- */
-interface AffordanceBinding<TScratch = unknown> {
-    initialScratch?: TScratch;
-}
-
-/**
- * Canvas size in CSS pixels — passed to `draw` for layers that anchor to
- * canvas edges (e.g. the debug overlay's layer-list panel). The GL backend
- * supplies it explicitly so layers don't have to know about DPR.
- */
-interface Dims {
-    width: number;
-    height: number;
-}
-/**
- * A single named render sub-layer within a canvas renderer.
- *
- * @template TData - The data object passed to each draw call.
- */
-interface RenderLayer<TData> {
-    /** Unique identifier used in visibility maps and ordering arrays. */
-    id: string;
-    /** Human-readable name for UI toggles. */
-    label: string;
-    /**
-     * Emit a DrawCommand tree for the GL backend to dispatch.
-     *
-     * For world-space layers (the default), emit commands in WORLD COORDS —
-     * `drawLayers` automatically wraps them in `{ kind: 'group', transform:
-     * viewToMat3(view), ... }` before handing them to the renderer. Do NOT
-     * apply the view transform yourself.
-     *
-     * For screen-space layers (`space: 'screen'`), emit commands in CSS-pixel
-     * coords directly; `drawLayers` passes them through unchanged. If part
-     * of a screen-space layer's output needs to track the view, wrap that
-     * subset manually with `viewToMat3(view)`.
-     */
-    draw: (data: TData, view: View, dims: Dims) => DrawCommand[];
-    /**
-     * Whether the layer is shown when no explicit visibility entry exists.
-     * Defaults to `true` when absent.
-     */
-    defaultVisible?: boolean;
-    /**
-     * When true, the layer is always drawn regardless of the visibility map.
-     * Useful for layers that must never be hidden (e.g. base grid).
-     */
-    alwaysOn?: boolean;
-    /**
-     * Coordinate space the layer draws in.
-     *
-     * - `'world'` (default): the layer's `draw` returns world-space commands;
-     *   `drawLayers` wraps them in a `kind: 'group'` with `viewToMat3(view)`
-     *   automatically.
-     * - `'screen'`: the layer's `draw` returns screen-space (CSS-pixel)
-     *   commands; `drawLayers` passes them through unchanged. World-anchored
-     *   chrome inside a screen-space layer must call `worldToScreen` or wrap
-     *   the relevant subset with `viewToMat3(view)` manually.
-     */
-    space?: 'world' | 'screen';
-    /**
-     * Optional hit-test for **consumer-attached** layers.
-     *
-     * Only layers registered through `CanvasExtensionApi.registerLayer` are
-     * hit-tested: `hitTestExtras` walks them last-registered-first on
-     * pointerdown, and `<SceneCanvas>` folds the result into its `affordanceAt`
-     * thunk ahead of the kit's own selection chrome. First non-null result
-     * wins; null means "I don't claim this hit, try the next layer."
-     *
-     * Layers that reach the draw stack some other way — a `Tool.overlay`, an
-     * entry in the `layers` map — are painted but never hit-tested, so defining
-     * `hitTest` on one has no effect. (The kit's own chrome doesn't need it: it
-     * goes through `buildAffordanceAt`.)
-     *
-     * Coordinates are world-space. The `data` arg is the layer's
-     * configured data slot (same as `draw`); `view` and `dims` mirror
-     * `draw`'s arguments.
-     */
-    hitTest?: (worldX: number, worldY: number, data: TData, view: View, dims: Dims, 
-    /** 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;
-    /**
-     * Called on every pointermove when no gesture is currently captured.
-     * Lets layers (e.g. HUD widgets) track hover state without participating
-     * in the drag pipeline. Coords are world-space; the layer is responsible
-     * for any further conversion (e.g. world→screen for screen-space layers)
-     * and for its own throttling.
-     */
-    onUncapturedMove?: (worldX: number, worldY: number, evt: PointerEvent, view: View, dims: Dims) => void;
-    /**
-     * Called when the cursor leaves the canvas element. Lets layers clear
-     * any hover state they're holding.
-     */
-    onUncapturedLeave?: () => void;
-}
-
 /** The full vocabulary of capability tags shipped in the default preset.
  *  Apps and other consumers can add their own tags; this list is what
  *  `weasel-modes` itself uses. */
@@ -1625,6 +1681,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;
 }
 
 /**
@@ -1661,6 +1724,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
@@ -1836,6 +1905,7 @@ interface KeyHeldSpec {
 interface WheelSpec {
     kind: 'wheel';
     direction?: 'up' | 'down' | '*';
+    target?: TargetSpec;
     mods?: ModSpec;
     phase?: PhaseSpec;
 }
@@ -1893,6 +1963,24 @@ interface PointerDownSpec {
     mods?: ModSpec;
     phase?: PhaseSpec;
 }
+/**
+ * Press held past the long-press threshold without crossing the drag
+ * threshold. Synthesized by `useGestureDispatcher` from the pointer stream.
+ *
+ * Fires for `touch` and `pen` pointers only. A mouse held still for half a
+ * second is an ordinary slow click, and firing on it would produce a context
+ * menu nobody asked for.
+ *
+ * When a long-press matches no binding, the dispatcher re-dispatches it as a
+ * `contextmenu` event — so `contextMenu` bindings work under a finger with no
+ * consumer changes, while `longPress` stays independently bindable.
+ */
+interface LongPressSpec {
+    kind: 'longPress';
+    target?: TargetSpec;
+    mods?: ModSpec;
+    phase?: PhaseSpec;
+}
 /** Multi-touch gesture. `fingers` is the required touch count. */
 interface MultiTouchSpec {
     kind: 'multiTouch';
@@ -1927,9 +2015,9 @@ interface PasteSpec {
     phase?: PhaseSpec;
 }
 /** The full union of supported gesture spec kinds. New invocation forms
- *  (long-press, two-stage, modal-dialog) extend this union without touching
+ *  (two-stage, modal-dialog) extend this union without touching
  *  the `Action` type. */
-type GestureSpec = KeySpec | KeyHeldSpec | WheelSpec | ClickSpec | DoubleClickSpec | ContextMenuSpec | DragSpec | PointerDownSpec | MultiTouchSpec | MultiTouchTapSpec | DropSpec | PasteSpec;
+type GestureSpec = KeySpec | KeyHeldSpec | WheelSpec | ClickSpec | DoubleClickSpec | ContextMenuSpec | DragSpec | PointerDownSpec | LongPressSpec | MultiTouchSpec | MultiTouchTapSpec | DropSpec | PasteSpec;
 
 /** A 2D point in either world or screen coordinates. */
 interface Point2 {
@@ -1960,6 +2048,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;
@@ -2287,6 +2384,50 @@ 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. */
+
+/** 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;
+}
+
 /** Boolean op identifiers — five Pathfinder primaries plus Crop. */
 type BooleanOp = 'union' | 'intersect' | 'subtract' | 'exclude' | 'divide' | 'crop';
 /**
@@ -2576,6 +2717,20 @@ interface SliceDep {
     commit(a: Point2, b: Point2): void;
 }
 
+/**
+ * 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;
+}
+
 /**
  * Bridges arbitrary `TPose` shapes into the resize hook's bounds-driven math.
  * The hook reads bounds via `getBounds`, runs anchor-relative math on those
@@ -3147,6 +3302,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
@@ -3196,20 +3360,6 @@ interface DepSchema {
  */
 type DepName = keyof DepSchema;
 
-/**
- * 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;
-}
-
 type HandleKind = 'corner' | 'rotation' | 'anchor';
 type HitShape = {
     kind: 'rect';
@@ -3254,6 +3404,38 @@ interface DebugSink {
     clearSnap(): void;
 }
 
+/**
+ * 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 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
  *  because tools commonly use space as a hotkey-slot trigger and may
  *  also want to read it as a flag mid-gesture. */
@@ -3303,6 +3485,10 @@ interface ToolCtx<TScratch = unknown> {
     debug?: DebugSink;
     scratch: TScratch;
 }
+/** Hotkey-slot trigger key. The slot is engaged while this key is held —
+ *  hence "hotkey": active as long as the key is hot. `null` (or omitted)
+ *  means the tool is not eligible for the hotkey slot. */
+type HotkeyTrigger = 'space' | 'alt' | 'ctrl' | 'meta' | 'shift';
 /** World-space AABB shape used by `previewBounds`. Alias of the kit-wide
  *  `Bounds` type — the optional `rotation` field carries through so a tool
  *  can report an oriented preview rect (e.g. mid-rotate). */
@@ -3311,8 +3497,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;
@@ -3327,34 +3513,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
@@ -3364,11 +3529,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
@@ -3386,26 +3549,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 alias for "a Tool of any scratch type" — used in registries and
  *  dispatchers that hold tools of heterogeneous scratch shapes. `any` is