@weasel-js/routing 1.11.0 → 1.11.1

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

@@ -1,11 +1,11 @@
+import { ModifierKey, ClaimableGesture, GestureSpec, InputEvent, TargetSpec, IngestItem, BodyTarget, KeyHeldSpec, TargetPredicate, KeySpec, ParsedModifiers, GestureName } from '@weasel-js/gestures';
+import { FramedBox, View, Point } from '@weasel-js/geom';
+import { CursorSpec } from '@weasel-js/cursor';
 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 * as react from 'react';
 import { ReactNode } from 'react';
 import { Emitter, QueryMatch } from '@weasel-js/registry';
@@ -169,489 +169,246 @@ type ResizeAnchor = {
     y: 'min' | 'max' | 'free';
 };
 
+/** The chrome an in-flight gesture paints beside the scene. */
+
 /**
- * Live state read by rule evaluation. Built once per frame on the consuming
- * surface — chrome-caps, the affordance pipeline, the dispatcher's
- * eligibility filter — and discarded.
+ * 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.
  *
- * Adding a new field is additive: existing rules don't change, new
- * selector atoms can read it.
+ * 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.
  */
-interface RuleCtx {
-    readonly focused: boolean;
-    readonly selection: readonly NodeId[];
-    readonly multiActive: boolean;
-    readonly modifiers: ModifierState;
-    readonly action: {
-        readonly kind: string | null;
-        readonly id: string | null;
+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'
+/** Where a dragged item would land: a reorder's insertion bar. */
+ | 'insert'
+/** Where a dragged item is over and cannot land. */
+ | 'refused' | (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;
     };
-    readonly hover: NodeId | null;
+    current: {
+        x: number;
+        y: number;
+    };
+    shiftHeld: boolean;
+} | {
+    kind: 'lasso';
+    vertices: ReadonlyArray<{
+        x: number;
+        y: number;
+    }>;
+    current: {
+        x: number;
+        y: number;
+    };
+    shiftHeld: boolean;
+} | {
     /**
-     * How far the viewport is zoomed in, as one number — `1` at native scale.
-     *
-     * A scalar rather than the `View` this used to carry, because `zoomAtLeast`
-     * is the only selector that ever read one and a number is all it needs. A
-     * host whose viewport is a camera has no `View` to hand over and would
-     * otherwise have to invent one to use eligibility at all; it omits this
-     * instead, and `zoomAtLeast` declines rather than matching on a fiction.
+     * 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.
      */
-    readonly zoom?: number;
-    /** Active mode id. `'normal'` when no non-default mode is engaged. */
-    readonly mode: string;
-    /** Capability tags allowed by the active mode (the union of
-     *  `ModeDefinition.allows` plus implicit tags). The `capability:`
-     *  selector reads this to determine whether a tag is permitted. */
-    readonly allowedCapabilities: ReadonlySet<CapabilityTag>;
-    /** Whether the current selection may be resized. `<SceneCanvas>` folds
-     *  `selectTool.resize.resizable` over the selection (true only when every
-     *  selected node is resizable). Read by the `resizable:` selector to gate
-     *  `selection.resize-handles`. Absent (legacy ctx builders) is treated as
-     *  resizable — back-compat: handles show unless a consumer opts a node out. */
-    readonly selectionResizable?: boolean;
-    /** Whether a path is currently in anchor-edit mode. Read by the
-     *  `editingAnchors:` selector, which gates the path-edit chrome.
-     *
-     *  This is deliberately a fact about state, not about permission: the
-     *  anchor overlay and the anchor hit-test must agree, and the thing they
-     *  must agree on is "is there an edited path right now", which no
-     *  capability or mode id answers. A mode that allows `edits-anchors`
-     *  with nothing being edited should draw no anchors. Absent is treated
-     *  as false. */
-    readonly editingAnchors?: boolean;
-    /** Device facts — pointer coarseness, hover capability, density.
+    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.
      *
-     *  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;
-    /** The view the input being dispatched landed in — a view id, or `null`
-     *  for the surface's own camera. The dispatcher fills it; absent anywhere
-     *  else a rule is evaluated. */
-    readonly viewId?: string | null;
-}
-/** The live state a `RuleCtx` is assembled from — the chrome context plus
- *  what the active mode allows. */
-interface BuildRuleCtxArgs {
-    focused: boolean;
-    selection: readonly NodeId[];
-    multiActive: boolean;
-    modifiers: ModifierState;
-    action: {
-        kind: string | null;
-        id: string | null;
+     * `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;
     };
-    hover: NodeId | null;
-    /** See {@link RuleCtx.zoom}. */
-    zoom?: number;
-    mode: string;
-    allowedCapabilities: ReadonlySet<CapabilityTag>;
-    /** Optional — omitted means "resizable" (handles show). See {@link RuleCtx}. */
-    selectionResizable?: boolean;
-    /** Optional — omitted means "no path is being anchor-edited". */
-    editingAnchors?: boolean;
-    /** Optional — omitted means {@link DEFAULT_DEVICE_PROFILE}. */
-    device?: DeviceProfile;
+    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[];
+
+/**
+ * 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;
 /**
- * Capability set to assume when no mode registry is wired.
+ * 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;
+
+/**
+ * Invoker — pluggable invocation strategy for an Action.
  *
- * "No modes configured" means *everything the default mode permits*, not
- * *nothing permitted*. The empty set is the wrong default: it makes every
- * `capability:` rule evaluate false, so a kit default written the
- * recommended way (capability rules outlive new modes; mode rules have to
- * be edited) would silently hide its chrome for every consumer that hasn't
- * opted into modality. `NORMAL.allows` plus the implicit tags is what a
- * mode-less canvas actually behaves like.
+ * An Action's `invoker` field describes how it's run. `immediate` invokers
+ * fire once (delete, align, undo). `ongoing` invokers open a phase machine
+ * driven by the dispatcher (move, resize, pinch-zoom).
  */
-declare const DEFAULT_ALLOWED_CAPABILITIES: ReadonlySet<CapabilityTag>;
-/** Gather the current canvas and mode state into the context that action
- *  eligibility and chrome-visibility rules are evaluated against. */
-declare function buildRuleCtx(args: BuildRuleCtxArgs): RuleCtx;
 
+/** A 2D point in either world or screen coordinates; geom's `Point`. */
+type Point2 = Point;
 /**
- * A selector is a conjunction of key/value tests. Multiple keys at the same
- * level AND together. Each key maps to a selector primitive in the evaluator.
+ * Which UI affordance was hit at pointerdown. Populated by the dispatcher when
+ * the `affordanceAt` thunk is provided to `useGestureDispatcher`.
+ *
+ * `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.
  */
-interface Selector {
-    selection?: {
-        is?: number;
-        atLeast?: number;
-        empty?: boolean;
-    };
-    mode?: string | {
-        not: string;
-    } | {
-        in: readonly string[];
-    };
-    capability?: CapabilityTag | readonly CapabilityTag[] | {
-        in: readonly CapabilityTag[];
-    } | {
-        not: CapabilityTag;
+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. */
+    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;
+        y: number;
     };
-    gesturing?: boolean;
-    actionIs?: string;
-    modifierHeld?: keyof ModifierState;
-    focused?: boolean;
-    hovering?: boolean;
-    hoveringSelected?: boolean;
-    zoomAtLeast?: number;
-    /** Matches `ctx.editingAnchors` — true while a path is in anchor-edit
-     *  mode. Absent flag is treated as `false`. */
-    editingAnchors?: boolean;
-    /** Matches `ctx.selectionResizable`. Absent flag is treated as `true`
-     *  (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
- * over `Selector` leaves. `when` is the escape hatch — its closure is
- * opaque to introspection and should be avoided when a declarative form
- * exists. Empty `all` is true; empty `any` is false.
- */
-type Rule = Selector | {
-    all: readonly Rule[];
-} | {
-    any: readonly Rule[];
-} | {
-    not: Rule;
-} | {
-    when: (ctx: RuleCtx) => boolean;
-};
-/** Constant rules. Kept here so they have a single source. */
-declare const ALWAYS: Rule;
-/** A rule that never passes. `any` of nothing is false. */
-declare const NEVER: Rule;
-/**
- * Render a {@link Rule} as a short human-readable string, for inspectors and
- * diagnostics that need to say WHICH rule decided something.
- *
- * ```
- * { capability: 'edits-page' }               → capability:edits-page
- * { all: [{ mode: 'normal' }, { focused: true }] } → all(mode:normal, focused:true)
- * { not: { selection: { empty: true } } }    → not(selection:empty=true)
- * { when: function hasPath() { … } }         → when(hasPath)
- * ```
- *
- * Never throws and always terminates.
- */
-declare function describeRule(rule: Rule): string;
-/** Evaluate a rule against a context. Pure, and cheap enough to run per
- *  frame for every piece of chrome. */
-declare function evaluate(rule: Rule, ctx: RuleCtx): boolean;
-/**
- * Composable eligibility predicate with a fluent surface. `cond(ctx)`
- * evaluates its `Rule` tree, carried at `.rule`; the fluent methods return new
- * Conditions wrapping new trees.
- *
- * **Chain semantics: strict left-to-right, no precedence.** `a.and(b).or(c)` is
- * `(a && b) || c`; `a.or(b).and(c)` is `(a || b) && c`. For grouped
- * disjunction, name the subexpression or use the top-level `or(...)`.
- */
-interface Condition {
-    (ctx: RuleCtx): boolean;
-    readonly rule: Rule;
-    /** `this && other` */
-    and(other: Condition | Rule): Condition;
-    /** `this || other` */
-    or(other: Condition | Rule): Condition;
-    /** `this && !other` */
-    andNot(other: Condition | Rule): Condition;
-    /** `this || !other` */
-    orNot(other: Condition | Rule): Condition;
+    /** Which nodes this affordance belongs to. */
+    targetIds?: string[];
+    /** 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
+     *  active tool's cursor. */
+    cursor?: CursorSpec;
+    /**
+     * Free-form payload from whatever produced the hit, carried through to the
+     * matching action untouched. Kit affordances leave it unset; it exists for
+     * a registered layer's own chrome, where the hit-test already resolved
+     * *which* of its pieces was hit.
+     */
+    payload?: unknown;
 }
-
-/**
- * Whether two rules can never hold at once — no `RuleCtx` passes both.
- *
- * Conservative: `true` is a proof, `false` means "may overlap". It reasons
- * about the selector values themselves (two different `mode`s, an empty
- * selection against a non-empty one, `focused: true` against `false`) and
- * through `all` / `any` / `not`; a `when` closure is opaque, so it overlaps
- * everything. The route-conflict check uses it to stay quiet about bindings
- * that share a tuple but are never eligible together.
- */
-declare function rulesExclusive(a: Rule, b: Rule): boolean;
-/**
- * Whether `rule` can hold while `mode` is active. Only its `mode` and
- * `capability` tests are settled by the mode; every other test could go either
- * way, so `false` is a proof and `true` means "may hold".
- */
-declare function ruleCanHoldIn(rule: Rule, mode: ActiveMode): boolean;
-
-/** The detected half of a profile — everything except the derived scale. */
-type DetectedDeviceFacts = Omit<DeviceProfile, 'targetScale'>;
-/**
- * Handle/hit multiplier applied on a coarse pointer.
- *
- * 8px handle → 14px; 24px rotation distance → 42px. Counting the
- * surrounding grab zone, that lands in the Apple HIG 44pt / Material 48dp
- * minimum-touch-target band. One constant so it is tunable in one place.
- */
-declare const COARSE_TARGET_SCALE = 1.75;
-/**
- * Fold consumer overrides over detected facts and derive `targetScale`.
- *
- * `targetScale` is re-derived AFTER the merge, so an override of
- * `coarsePointer` alone scales the chrome as expected. An explicit
- * `targetScale` override wins over the derivation.
- */
-declare function resolveDeviceProfile(detected: DetectedDeviceFacts, overrides?: Partial<DeviceProfile>): DeviceProfile;
 /**
- * Assumed when `matchMedia` is unavailable (SSR, jsdom) and used as the
- * absent-means value for `RuleCtx.device`.
+ * One accumulated point on a drag trail: world-space position plus whatever
+ * stylus state the originating `PointerEvent` carried.
  *
- * Derived from `resolveDeviceProfile` rather than hand-written, so it can
- * never drift from what the function would compute for the same facts. A
- * mouse-like device is the safe default: it is what the kit has always
- * assumed, so an absent profile changes nothing for existing consumers.
- */
-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 stylus fields are absent for mouse/touch on browsers that don't report
+ * them, and for synthetic events.
  */
-
-/** 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;
+interface DragSample extends Point2 {
+    /** 0..1. Mouse/touch report 0.5 while a button is held, per the spec. */
+    pressure?: number;
+    /** Degrees, ±90. Zero for mouse/touch. */
+    tiltX?: number;
+    /** Degrees, ±90. Zero for mouse/touch. */
+    tiltY?: number;
 }
-/** 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.
- *
- * An Action's `invoker` field describes how it's run. `immediate` invokers
- * fire once (delete, align, undo). `ongoing` invokers open a phase machine
- * driven by the dispatcher (move, resize, pinch-zoom).
- */
-
-/** 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`.
- *
- * `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.
- */
-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. */
-    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;
-        y: number;
-    };
-    /** Which nodes this affordance belongs to. */
-    targetIds?: string[];
-    /** 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
-     *  active tool's cursor. */
-    cursor?: CursorSpec;
-    /**
-     * Free-form payload from whatever produced the hit, carried through to the
-     * matching action untouched. Kit affordances leave it unset; it exists for
-     * a registered layer's own chrome, where the hit-test already resolved
-     * *which* of its pieces was hit.
-     */
-    payload?: unknown;
-}
-/**
- * One accumulated point on a drag trail: world-space position plus whatever
- * stylus state the originating `PointerEvent` carried.
- *
- * The stylus fields are absent for mouse/touch on browsers that don't report
- * them, and for synthetic events.
- */
-interface DragSample extends Point2 {
-    /** 0..1. Mouse/touch report 0.5 while a button is held, per the spec. */
-    pressure?: number;
-    /** Degrees, ±90. Zero for mouse/touch. */
-    tiltX?: number;
-    /** Degrees, ±90. Zero for mouse/touch. */
-    tiltY?: number;
-}
-/** Per-invocation runtime context the dispatcher hands to an Invoker.
- *  Gesture-kind-specific fields (`drag`, `wheel`, `multiTouch`, `key`) are
- *  populated only for matching gesture kinds. */
-interface InvocationCtx {
-    world: Point2;
-    /**
-     * The pointer in client/screen pixels, for an action that has to place DOM
-     * at the pointer. Absent on every invocation whose event carries no client
-     * coordinates — a keystroke, a UI-driven trigger, a synthetic probe — so
-     * read it with a fallback rather than assuming a point.
-     *
-     * A view-mutating drag wants `drag.screenDelta`, not the difference of two
-     * of these: world deltas are self-referential mid-pan, and so is any delta
-     * taken across a view change.
-     */
-    screen?: Point2;
+/** Per-invocation runtime context the dispatcher hands to an Invoker.
+ *  Gesture-kind-specific fields (`drag`, `wheel`, `multiTouch`, `key`) are
+ *  populated only for matching gesture kinds. */
+interface InvocationCtx {
+    world: Point2;
+    /**
+     * The pointer in client/screen pixels, for an action that has to place DOM
+     * at the pointer. Absent on every invocation whose event carries no client
+     * coordinates — a keystroke, a UI-driven trigger, a synthetic probe — so
+     * read it with a fallback rather than assuming a point.
+     *
+     * A view-mutating drag wants `drag.screenDelta`, not the difference of two
+     * of these: world deltas are self-referential mid-pan, and so is any delta
+     * taken across a view change.
+     */
+    screen?: Point2;
     modifiers: ModifierState;
     deps: ActionDeps;
     drag?: {
@@ -777,6 +534,12 @@ interface BindingOpts {
      * binding; this tells the route-conflict check the order is the design.
      */
     yields?: boolean;
+    /**
+     * For a key binding: live while the pointer is over the surface, whichever
+     * canvas holds the keys, and only then. For a key that means "here" — a
+     * magnifier's peek — on a page with more than one surface that hears it.
+     */
+    over?: boolean;
     /**
      * Keys for some of the action's `modifierRoles` on this binding, by role
      * id, over the action's defaults and any tuning's.
@@ -822,8 +585,11 @@ interface OngoingHandle {
      *
      * `previewIds()` enumerates the displaced node ids; `previewPose(id)`
      * returns the interim pose for one of them (shape opaque — the canvas
-     * casts to its `TPose` parameter). Returning `null`, or omitting the
-     * method, means "no preview this gesture".
+     * casts to its `TPose` parameter). `previewIds` returning `null`, or
+     * omitted, means "no preview this gesture". An id with no `previewPose`
+     * is shown at its effective pose: an action that publishes its poses to
+     * the scene's pose overrides, as move, resize and rotate do, leaves
+     * `previewPose` out rather than answering the same pose twice.
      */
     previewIds?(): Iterable<string> | null;
     previewPose?(id: string): unknown | null;
@@ -873,63 +639,615 @@ interface ImmediateInvoker {
      *  is undefined; descriptors should default to a sensible variant. */
     run(deps: ActionDeps, params?: Record<string, unknown>): void;
 }
-/** Phase-machine invocation. `start` opens the phase and returns the handle
- *  the dispatcher pumps. */
-interface OngoingInvoker {
-    timing: 'ongoing';
-    start(ctx: InvocationCtx, opts?: BindingOpts): OngoingHandle;
+/** Phase-machine invocation. `start` opens the phase and returns the handle
+ *  the dispatcher pumps. */
+interface OngoingInvoker {
+    timing: 'ongoing';
+    start(ctx: InvocationCtx, opts?: BindingOpts): OngoingHandle;
+}
+/** Pluggable invocation strategy for an Action. */
+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.
+ */
+
+/** An interaction: a gesture spec composed with the id of the action it
+ *  invokes. Tools declare arrays of these; the dispatcher matches an incoming
+ *  input event against them and runs the winner's action. */
+interface GestureBinding {
+    spec: GestureSpec;
+    actionId: string;
+    opts?: BindingOpts;
+}
+/**
+ * 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' } }`).
+ * Use the object form when two bindings for the same action differ only in
+ * a runtime parameter — the dispatcher extracts `opts.params` and passes
+ * them to `ImmediateInvoker.run` as its second argument.
+ */
+type BoundGesture = GestureSpec | {
+    spec: GestureSpec;
+    opts: BindingOpts;
+};
+/**
+ * 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.
+ */
+interface BindingSource {
+    id: string;
+    /** The gesture-spec form of the binding, read by the gesture dispatcher.
+     *  May be a single `GestureSpec`, a bare `GestureSpec[]` (any-of semantics),
+     *  or a `BoundGesture[]` where each entry is either a bare `GestureSpec` or
+     *  `{ spec, opts }` — use the object form for parametric actions where two
+     *  bindings for the same action differ only by `opts.params` (e.g. `flip`
+     *  with `axis: 'x'` vs `'y'`). The dispatcher extracts `opts.params` and
+     *  passes them to `ImmediateInvoker.run` as its second argument. */
+    defaultBinding?: GestureSpec | BoundGesture[];
+}
+/**
+ * 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[];
+
+/**
+ * Re-exports the pure matcher primitives from `@weasel-js/gestures` and layers
+ * the actions-layer binding-scope / matchBest logic on top.
+ */
+
+/** Where a binding came from, which is also its priority: a held hotkey beats
+ *  the active tool, which beats bindings that are always in scope. */
+type BindingScope = 'ambient' | 'active' | 'hotkey';
+/** A binding paired with where it came from, ready to be matched against an
+ *  event. */
+interface ScopedBinding {
+    binding: GestureBinding;
+    scope: BindingScope;
+    /** Id of the tool or contribution that declared this binding —
+     *  `'&'`-channel phase atoms resolve to it. `null` for a registered
+     *  action's own binding. */
+    ownerId: string | null;
+}
+/** The binding that won a match. */
+interface MatchResult {
+    binding: GestureBinding;
+    scope: BindingScope;
+    /** Id of the entry that declared the binding — propagated from
+     *  `ScopedBinding` so the dispatcher can record it as the handle owner. */
+    ownerId: string | null;
+}
+/**
+ * True when a spec's target actually consults the affordance hit rather than
+ * only the body classification. `kindOf` predicates are handed the hit;
+ * `affordance:<k>` matches on its `kind`. The body-class strings (`'empty'`,
+ * `'selected-body'`, `'unselected-body'`) and the `kind:` forms resolve from
+ * `bodyTarget` / `bodyKind` and never see it.
+ *
+ * A predicate declares which it is with `readsAffordance`; one that declares
+ * nothing, which only untyped code can write, counts as not reading the hit.
+ */
+declare function targetConsultsAffordance(specTarget: TargetSpec | undefined): boolean;
+/** The first of {@link matchSorted}'s matches, or null when nothing matches. */
+declare function matchBest(e: InputEvent, bindings: readonly ScopedBinding[], isMac: boolean, engagedChannels?: ReadonlySet<string>): MatchResult | null;
+/**
+ * Find every binding that matches the event, sorted by precedence
+ * (best → worst). Ordering rules:
+ *
+ *   - Scopes by priority: hotkey > active > ambient.
+ *   - Within a scope, more-specific bindings beat less-specific (see
+ *     `specificity()`).
+ *   - Among same-specificity bindings, first-declared wins.
+ */
+declare function matchSorted(e: InputEvent, bindings: readonly ScopedBinding[], isMac: boolean, engagedChannels?: ReadonlySet<string>, warn?: (message: string) => void): MatchResult[];
+/** {@link matchSorted}, plus what an exclusive claim on the event barred. */
+interface MatchOutcome {
+    matches: MatchResult[];
+    /** Bindings whose spec matched the event but which the claim barred, in
+     *  the same order `matches` uses. Filled only when `collectBarred` is set. */
+    barred: MatchResult[];
+    /** Owner of the exclusive claim, when one applied. */
+    claimOwner?: string;
+}
+/**
+ * {@link matchSorted} that can also report the bindings an exclusive claim
+ * kept out. Collecting them costs a spec match per barred binding, so it is
+ * opt-in — the dispatcher asks only when it is recording.
+ */
+declare function matchSortedWithBarred(e: InputEvent, bindings: readonly ScopedBinding[], isMac: boolean, engagedChannels?: ReadonlySet<string>, opts?: {
+    collectBarred?: boolean;
+    warn?: (message: string) => void;
+}): MatchOutcome;
+
+/**
+ * How one input was resolved: every binding that matched it, what each filter
+ * dropped, the order the rest were ranked in and why, and what the walk down
+ * that order did. The dispatcher fills one per input in dev builds, and
+ * `Dispatcher.explain` fills one on request without invoking anything.
+ *
+ * Plain data — no functions, no live objects — so it can be kept in a trace
+ * buffer, serialized, or built by hand as a fixture.
+ */
+interface DispatchRecord {
+    kind: 'dispatch';
+    ts: number;
+    input: DispatchRecordInput;
+    /** Every binding whose spec matched the input, in matcher order, including
+     *  those a filter then dropped. */
+    matched: readonly RecordCandidate[];
+    dropped: readonly DroppedCandidate[];
+    /** The candidates that survived both filters, best first. */
+    ranked: readonly RankedCandidate[];
+    /** True when nothing was invoked: the record answers "what would happen". */
+    predicted: boolean;
+    /** Action id of the candidate that fired (or would), else `null`. */
+    fired: string | null;
+    outcome: 'handled' | 'unhandled';
+}
+/** The input a {@link DispatchRecord} describes, reduced to plain data. */
+interface DispatchRecordInput {
+    /** `InputEvent.kind`: `'key'`, `'pointerdown'`, `'wheel'`, … */
+    eventKind: string;
+    /** For `key` / `key-held` events, the key id (`'Escape'`, `' '`, `'a'`). */
+    key?: string;
+    modifiers: {
+        alt: boolean;
+        ctrl: boolean;
+        meta: boolean;
+        shift: boolean;
+    };
+    /** The view the input was routed to; `null` for the surface's own camera. */
+    viewId: string | null;
+    /** World point, for events that carry one. */
+    world?: {
+        x: number;
+        y: number;
+    };
+    /** Active mode id, when the host supplies a rule context. */
+    mode?: string;
+}
+/** One matched binding. */
+interface RecordCandidate {
+    actionId: string;
+    /** The binding's spec in route grammar — one per arg alternative. */
+    routes: readonly string[];
+    scope: BindingScope;
+    /** The tool or contribution that declared the binding; `null` for an action's own binding. */
+    ownerId: string | null;
+    /** Whether the binding's `views` names the routed view. */
+    namesView: boolean;
+    /** `specificity(spec)`: target, modifiers, phase, exact. */
+    specificity: readonly [number, number, number, number];
+    /** The action's `eligible` rule as text, when it declares one. */
+    eligible?: string;
+}
+/** A matched candidate a filter removed before ranking, and which filter. */
+type DroppedCandidate = 
+/** An exclusive claim on the input barred bindings that do not read the
+ *  claim's affordance. */
+{
+    candidate: RecordCandidate;
+    filter: 'claim';
+    owner?: string;
+}
+/** The action's `eligible` rule does not hold. */
+ | {
+    candidate: RecordCandidate;
+    filter: 'ineligible';
+    rule: string;
+};
+/** One field of the `specificity` tuple, in the order it is compared. */
+type SpecificityPart = 'target' | 'mods' | 'phase' | 'exact';
+/** The ranking step that put a candidate below the one before it. */
+type PlacedBy = {
+    step: 'first';
+}
+/** The one above names the routed view; this one does not. */
+ | {
+    step: 'view';
+}
+/** The one above sits in a higher scope tier. */
+ | {
+    step: 'tier';
+}
+/** Same tier; the one above is more specific in `part`. */
+ | {
+    step: 'specificity';
+    part: SpecificityPart;
+}
+/** Tied; the one above is gated by an `eligible` rule that holds. */
+ | {
+    step: 'context';
+}
+/** Tied on everything; registration order. */
+ | {
+    step: 'order';
+};
+/** What the walk did with one ranked candidate. */
+type WalkStep = {
+    kind: 'fired';
+}
+/** Predicted records only: this candidate would fire. Nothing was started,
+ *  so an ongoing action here may still bail at `start()` for real. */
+ | {
+    kind: 'would-fire';
+}
+/** `enabled()` returned this reason. */
+ | {
+    kind: 'declined';
+    reason: string;
+}
+/** An ongoing action's `start()` returned an empty handle. */
+ | {
+    kind: 'empty-handle';
+}
+/** An ongoing action bound to a press-time `pointerDown` spec; refused. */
+ | {
+    kind: 'misbound';
+}
+/** Its action was already tried higher up; each runs at most once. */
+ | {
+    kind: 'duplicate';
+} | {
+    kind: 'no-such-action';
+}
+/** Below the winner; never asked. */
+ | {
+    kind: 'not-asked';
+}
+/** Below the winner, asked anyway (`evaluateShadowed`), and it passed. */
+ | {
+    kind: 'outranked';
+};
+/** A candidate that survived the filters: why it sits where it does, and
+ *  what the walk did with it. */
+interface RankedCandidate {
+    candidate: RecordCandidate;
+    placedBy: PlacedBy;
+    walk: WalkStep;
+}
+
+/** One entry per "mode change" — a kit state transition that isn't a
+ *  dispatched input event but explains why an input was (or wasn't) handled
+ *  later. Pushed via {@link DispatchTrace.recordModeSwitch}. */
+interface ModeSwitchLogEntry {
+    kind: 'mode';
+    ts: number;
+    /** Logical mode name, e.g. `'editAnchors.editingId'`. */
+    mode: string;
+    from: string | null;
+    to: string | null;
+    /** Optional free-form context — `'enterPathEdit'`, `'exitPathEdit'`,
+     *  `'selection-dropped target'`, etc. */
+    detail?: string;
+}
+/** A trace entry: one {@link DispatchRecord} per resolved input, or a mode switch. */
+type TraceLogEntry = DispatchRecord | ModeSwitchLogEntry;
+/** A rolling buffer that records in a dev build, and in any build while something watches it. */
+interface TraceRing<T> {
+    /** Whether a push now keeps its entry. A caller building an entry checks first. */
+    recording(): boolean;
+    push(entry: T): void;
+    /** The entries pushed after `cursor`, oldest first, and the cursor to pass
+     *  next time. Start from 0. Entries the buffer has dropped are skipped. */
+    since(cursor: number): {
+        entries: T[];
+        cursor: number;
+    };
+    /** Turn recording on until the returned release is called. */
+    watch(): () => void;
+    /** Hear each kept push. Returns the unsubscribe. */
+    subscribe(listener: () => void): () => void;
+}
+/** A {@link TraceRing} keeping the last `limit` entries. `dev` defaults to the build's. */
+declare function createTraceRing<T>(limit?: number, dev?: boolean): TraceRing<T>;
+/** One canvas's dispatch trace. `useGestureDispatcher` makes one, puts it on
+ *  every `DispatcherContext` it builds, and publishes it as the `dispatchTrace` dep. */
+interface DispatchTrace extends TraceRing<TraceLogEntry> {
+    recordModeSwitch(mode: string, from: string | null, to: string | null, detail?: string): void;
+    /** Offer the record for what a press at the pointer would do, built only
+     *  when {@link DispatchTrace.live} reads it. `null` withdraws it. */
+    setLive(explain: (() => DispatchRecord) | null): void;
+    live(): DispatchRecord | null;
+}
+/** A {@link DispatchTrace} keeping the last `limit` entries. `dev` defaults to the build's. */
+declare function createDispatchTrace(limit?: number, dev?: boolean): DispatchTrace;
+
+/**
+ * Live state read by rule evaluation. Built once per frame on the consuming
+ * surface — chrome-caps, the affordance pipeline, the dispatcher's
+ * eligibility filter — and discarded.
+ *
+ * Adding a new field is additive: existing rules don't change, new
+ * selector atoms can read it.
+ */
+interface RuleCtx {
+    readonly focused: boolean;
+    readonly selection: readonly NodeId[];
+    readonly multiActive: boolean;
+    readonly modifiers: ModifierState;
+    readonly action: {
+        readonly kind: string | null;
+        readonly id: string | null;
+    };
+    readonly hover: NodeId | null;
+    /**
+     * How far the viewport is zoomed in, as one number — `1` at native scale.
+     *
+     * A scalar rather than the `View` this used to carry, because `zoomAtLeast`
+     * is the only selector that ever read one and a number is all it needs. A
+     * host whose viewport is a camera has no `View` to hand over and would
+     * otherwise have to invent one to use eligibility at all; it omits this
+     * instead, and `zoomAtLeast` declines rather than matching on a fiction.
+     */
+    readonly zoom?: number;
+    /** Active mode id. `'normal'` when no non-default mode is engaged. */
+    readonly mode: string;
+    /** Capability tags allowed by the active mode (the union of
+     *  `ModeDefinition.allows` plus implicit tags). The `capability:`
+     *  selector reads this to determine whether a tag is permitted. */
+    readonly allowedCapabilities: ReadonlySet<CapabilityTag>;
+    /** Whether the current selection may be resized. `<SceneCanvas>` folds
+     *  `selectTool.resize.resizable` over the selection (true only when every
+     *  selected node is resizable). Read by the `resizable:` selector to gate
+     *  `selection.resize-handles`. Absent (legacy ctx builders) is treated as
+     *  resizable — back-compat: handles show unless a consumer opts a node out. */
+    readonly selectionResizable?: boolean;
+    /** Whether a path is currently in anchor-edit mode. Read by the
+     *  `editingAnchors:` selector, which gates the path-edit chrome.
+     *
+     *  This is deliberately a fact about state, not about permission: the
+     *  anchor overlay and the anchor hit-test must agree, and the thing they
+     *  must agree on is "is there an edited path right now", which no
+     *  capability or mode id answers. A mode that allows `edits-anchors`
+     *  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;
+    /** The view the input being dispatched landed in — a view id, or `null`
+     *  for the surface's own camera. The dispatcher fills it; absent anywhere
+     *  else a rule is evaluated. */
+    readonly viewId?: string | null;
+}
+/** The live state a `RuleCtx` is assembled from — the chrome context plus
+ *  what the active mode allows. */
+interface BuildRuleCtxArgs {
+    focused: boolean;
+    selection: readonly NodeId[];
+    multiActive: boolean;
+    modifiers: ModifierState;
+    action: {
+        kind: string | null;
+        id: string | null;
+    };
+    hover: NodeId | null;
+    /** See {@link RuleCtx.zoom}. */
+    zoom?: number;
+    mode: string;
+    allowedCapabilities: ReadonlySet<CapabilityTag>;
+    /** Optional — omitted means "resizable" (handles show). See {@link RuleCtx}. */
+    selectionResizable?: boolean;
+    /** Optional — omitted means "no path is being anchor-edited". */
+    editingAnchors?: boolean;
+    /** Optional — omitted means {@link DEFAULT_DEVICE_PROFILE}. */
+    device?: DeviceProfile;
 }
-/** Pluggable invocation strategy for an Action. */
-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.
+ * Capability set to assume when no mode registry is wired.
+ *
+ * "No modes configured" means *everything the default mode permits*, not
+ * *nothing permitted*. The empty set is the wrong default: it makes every
+ * `capability:` rule evaluate false, so a kit default written the
+ * recommended way (capability rules outlive new modes; mode rules have to
+ * be edited) would silently hide its chrome for every consumer that hasn't
+ * opted into modality. `NORMAL.allows` plus the implicit tags is what a
+ * mode-less canvas actually behaves like.
  */
+declare const DEFAULT_ALLOWED_CAPABILITIES: ReadonlySet<CapabilityTag>;
+/** Gather the current canvas and mode state into the context that action
+ *  eligibility and chrome-visibility rules are evaluated against. */
+declare function buildRuleCtx(args: BuildRuleCtxArgs): RuleCtx;
 
-/** An interaction: a gesture spec composed with the id of the action it
- *  invokes. Tools declare arrays of these; the dispatcher matches an incoming
- *  input event against them and runs the winner's action. */
-interface GestureBinding {
-    spec: GestureSpec;
-    actionId: string;
-    opts?: BindingOpts;
+/**
+ * A selector is a conjunction of key/value tests. Multiple keys at the same
+ * level AND together. Each key maps to a selector primitive in the evaluator.
+ */
+interface Selector {
+    selection?: {
+        is?: number;
+        atLeast?: number;
+        empty?: boolean;
+    };
+    mode?: string | {
+        not: string;
+    } | {
+        in: readonly string[];
+    };
+    capability?: CapabilityTag | readonly CapabilityTag[] | {
+        in: readonly CapabilityTag[];
+    } | {
+        not: CapabilityTag;
+    };
+    gesturing?: boolean;
+    actionIs?: string;
+    modifierHeld?: keyof ModifierState;
+    focused?: boolean;
+    hovering?: boolean;
+    hoveringSelected?: boolean;
+    zoomAtLeast?: number;
+    /** Matches `ctx.editingAnchors` — true while a path is in anchor-edit
+     *  mode. Absent flag is treated as `false`. */
+    editingAnchors?: boolean;
+    /** Matches `ctx.selectionResizable`. Absent flag is treated as `true`
+     *  (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;
 }
 /**
- * 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' } }`).
- * Use the object form when two bindings for the same action differ only in
- * a runtime parameter — the dispatcher extracts `opts.params` and passes
- * them to `ImmediateInvoker.run` as its second argument.
+ * Composable visibility/eligibility rule. Trees of `all`/`any`/`not` nodes
+ * over `Selector` leaves. `when` is the escape hatch — its closure is
+ * opaque to introspection and should be avoided when a declarative form
+ * exists. Empty `all` is true; empty `any` is false.
  */
-type BoundGesture = GestureSpec | {
-    spec: GestureSpec;
-    opts: BindingOpts;
+type Rule = Selector | {
+    all: readonly Rule[];
+} | {
+    any: readonly Rule[];
+} | {
+    not: Rule;
+} | {
+    when: (ctx: RuleCtx) => boolean;
 };
+/** Constant rules. Kept here so they have a single source. */
+declare const ALWAYS: Rule;
+/** A rule that never passes. `any` of nothing is false. */
+declare const NEVER: Rule;
 /**
- * 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.
+ * Render a {@link Rule} as a short human-readable string, for inspectors and
+ * diagnostics that need to say WHICH rule decided something.
+ *
+ * ```
+ * { capability: 'edits-page' }               → capability:edits-page
+ * { all: [{ mode: 'normal' }, { focused: true }] } → all(mode:normal, focused:true)
+ * { not: { selection: { empty: true } } }    → not(selection:empty=true)
+ * { when: function hasPath() { … } }         → when(hasPath)
+ * ```
+ *
+ * Never throws and always terminates.
  */
-interface BindingSource {
-    id: string;
-    /** The gesture-spec form of the binding, read by the gesture dispatcher.
-     *  May be a single `GestureSpec`, a bare `GestureSpec[]` (any-of semantics),
-     *  or a `BoundGesture[]` where each entry is either a bare `GestureSpec` or
-     *  `{ spec, opts }` — use the object form for parametric actions where two
-     *  bindings for the same action differ only by `opts.params` (e.g. `flip`
-     *  with `axis: 'x'` vs `'y'`). The dispatcher extracts `opts.params` and
-     *  passes them to `ImmediateInvoker.run` as its second argument. */
-    defaultBinding?: GestureSpec | BoundGesture[];
+declare function describeRule(rule: Rule): string;
+/** Evaluate a rule against a context. Pure, and cheap enough to run per
+ *  frame for every piece of chrome. */
+declare function evaluate(rule: Rule, ctx: RuleCtx): boolean;
+/**
+ * Composable eligibility predicate with a fluent surface. `cond(ctx)`
+ * evaluates its `Rule` tree, carried at `.rule`; the fluent methods return new
+ * Conditions wrapping new trees.
+ *
+ * **Chain semantics: strict left-to-right, no precedence.** `a.and(b).or(c)` is
+ * `(a && b) || c`; `a.or(b).and(c)` is `(a || b) && c`. For grouped
+ * disjunction, name the subexpression or use the top-level `or(...)`.
+ */
+interface Condition {
+    (ctx: RuleCtx): boolean;
+    readonly rule: Rule;
+    /** `this && other` */
+    and(other: Condition | Rule): Condition;
+    /** `this || other` */
+    or(other: Condition | Rule): Condition;
+    /** `this && !other` */
+    andNot(other: Condition | Rule): Condition;
+    /** `this || !other` */
+    orNot(other: Condition | Rule): Condition;
+}
+
+/**
+ * Whether two rules can never hold at once — no `RuleCtx` passes both.
+ *
+ * Conservative: `true` is a proof, `false` means "may overlap". It reasons
+ * about the selector values themselves (two different `mode`s, an empty
+ * selection against a non-empty one, `focused: true` against `false`) and
+ * through `all` / `any` / `not`; a `when` closure is opaque, so it overlaps
+ * everything. The route-conflict check uses it to stay quiet about bindings
+ * that share a tuple but are never eligible together.
+ */
+declare function rulesExclusive(a: Rule, b: Rule): boolean;
+/**
+ * Whether `rule` can hold while `mode` is active. Only its `mode` and
+ * `capability` tests are settled by the mode; every other test could go either
+ * way, so `false` is a proof and `true` means "may hold".
+ */
+declare function ruleCanHoldIn(rule: Rule, mode: ActiveMode): boolean;
+
+/** The detected half of a profile — everything except the derived scale. */
+type DetectedDeviceFacts = Omit<DeviceProfile, 'targetScale'>;
+/**
+ * Handle/hit multiplier applied on a coarse pointer.
+ *
+ * 8px handle → 14px; 24px rotation distance → 42px. Counting the
+ * surrounding grab zone, that lands in the Apple HIG 44pt / Material 48dp
+ * minimum-touch-target band. One constant so it is tunable in one place.
+ */
+declare const COARSE_TARGET_SCALE = 1.75;
+/**
+ * Fold consumer overrides over detected facts and derive `targetScale`.
+ *
+ * `targetScale` is re-derived AFTER the merge, so an override of
+ * `coarsePointer` alone scales the chrome as expected. An explicit
+ * `targetScale` override wins over the derivation.
+ */
+declare function resolveDeviceProfile(detected: DetectedDeviceFacts, overrides?: Partial<DeviceProfile>): DeviceProfile;
+/**
+ * Assumed when `matchMedia` is unavailable (SSR, jsdom) and used as the
+ * absent-means value for `RuleCtx.device`.
+ *
+ * Derived from `resolveDeviceProfile` rather than hand-written, so it can
+ * never drift from what the function would compute for the same facts. A
+ * mouse-like device is the safe default: it is what the kit has always
+ * assumed, so an absent profile changes nothing for existing consumers.
+ */
+declare const DEFAULT_DEVICE_PROFILE: DeviceProfile;
+
+/**
+ * A settings form an action carries: what a surface draws in place of a bare
+ * trigger for an action whose job is to change settings on the selection.
+ */
+
+/** What a settings form shows for the selection right now. */
+interface ActionSettingsState {
+    /** The values, nested as the schema's groups nest. */
+    values: Record<string, unknown>;
+    /** The leaf paths where the selected items disagree. */
+    mixed?: readonly string[];
 }
 /**
- * Flatten an action's `defaultBinding` into `GestureBinding`s. A bare
- * `GestureSpec` has `kind` at top level; the object form has `spec`.
+ * The settings form an action carries. A bar or a panel draws the action as a
+ * button opening it, a menu as a submenu of its fields, and a palette as a
+ * dialog; each change triggers the action with the params it makes.
  */
-declare function actionBindings(action: BindingSource): GestureBinding[];
+interface ActionSettings {
+    /** The form. Its `name` titles the popover, submenu or dialog. */
+    schema: PrefGroup;
+    /** The selection's current values, from the deps `enabled` is given. Under
+     *  `enabled`'s contract: pure, fast, and it must not throw. */
+    read(deps: ActionDeps): ActionSettingsState;
+    /** The params one field's change triggers the action with, or `null` for
+     *  none. Default: `{ [path]: value }`. */
+    params?(path: string, value: unknown): Record<string, unknown> | null;
+}
+/** `action`'s settings as they stand under `deps`, or `null` for an action
+ *  with no settings. A `read` that throws shows nothing rather than breaking
+ *  the surface. */
+declare function readActionSettings(action: Action, deps: ActionDeps | undefined): ActionSettingsState | null;
+/** The params a change of the field at `path` to `value` triggers the action with. */
+declare function actionSettingsParams(settings: ActionSettings, path: string, value: unknown): Record<string, unknown> | null;
 
+/** What content being routed brings to `Action.enabled`: a drop's or a
+ *  paste's items, or a carry's payload with no items. */
+interface Carried {
+    items: readonly IngestItem[];
+    carry?: {
+        type: string;
+        value: unknown;
+    };
+}
 /**
  * Closed enum of reasons an action might report itself as disabled. The
  * consumer (palette, menu, etc.) maps these symbolic values to display
@@ -972,6 +1290,11 @@ interface ActionPresentation {
      *  triggers the action with that variant's `params`. Omitted = the action
      *  is one entry. See `actionItems`. */
     variants?: readonly ActionVariant[];
+    /** A form of the settings the action changes on the selection. A surface
+     *  draws the action as that form instead of a bare trigger, and each change
+     *  triggers it with the params `settings.params` makes. Not combined with
+     *  `variants`. */
+    settings?: ActionSettings;
 }
 /**
  * One entry a parametric action contributes to a bar, menu or palette.
@@ -1037,18 +1360,17 @@ interface ActionDispatch extends BindingSource {
      * 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
-     * browser withholds contents until the drop. An action that takes only
-     * some content refuses the rest here, so a drag it would not take is not
-     * accepted and a paste it would not take stays the page's.
+     * `carried` is what a drop, a paste or a carry being routed brings. For
+     * an OS drag still in flight its items hold a MIME and nothing else, since
+     * a browser withholds contents until the drop. A carry has no items and
+     * hands over its payload whole. An action that takes only some content
+     * refuses the rest here, so a drag it would not take is not accepted and a
+     * paste it would not take stays the page's.
      */
     enabled?: (deps?: ActionDeps, at?: {
         x: number;
         y: number;
-    }, carried?: {
-        items: readonly IngestItem[];
-    }) => true | ActionDisabledReason;
+    }, carried?: Carried) => true | ActionDisabledReason;
     /**
      * Whether the action reads as held down right now: bold on the selected
      * text, snapping switched on. A toolbar button draws it as pressed.
@@ -1179,8 +1501,9 @@ interface MenuSources {
  * 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
+ * rows, and a number and a string a row edited in place (all through `src.values`/`src.onChange`);
+ * a color shows as a swatch, read-only, and so does a string as a disabled row when it is a readout
+ * or nothing writes it. 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
@@ -1475,7 +1798,10 @@ declare function evaluateActive(action: Action, deps?: ActionDeps): boolean | un
  *  Sources are thunks, read at invocation time, so an action never captures
  *  stale state. */
 interface DepRegistry {
-    register<K extends DepName>(name: K, source: () => DepSchema[K]): () => void;
+    /** Adds a live source for `name` over any already there. `below` answers
+     *  what the registry would without this source, so one can handle part of
+     *  a dep and hand the rest to the default it displaced. */
+    register<K extends DepName>(name: K, source: DepSource<K>): () => void;
     get<K extends DepName>(name: K): DepSchema[K] | undefined;
     /** Hear that what the registry answers may have changed: a source was
      *  registered or released anywhere in its tree, or an owner called
@@ -1486,6 +1812,20 @@ interface DepRegistry {
      *  so its owner is the only one who knows; chrome showing an action's
      *  `enabled` or `active` state re-reads on this. */
     changed?(): void;
+    /** Every name a `get` here would answer, sorted, with where its live
+     *  source sits. For inspection; a hand-built registry may leave it out. */
+    list?(): readonly DepListing[];
+}
+/** A live source for dep `K`: a thunk read at invocation time. `below` reads
+ *  the source this one displaced, under it in its scope or in a scope above. */
+type DepSource<K extends DepName> = (below: () => DepSchema[K] | undefined) => DepSchema[K];
+/** One name a dep registry answers, as {@link DepRegistry.list} reports it. */
+interface DepListing {
+    name: string;
+    /** How many scopes above the asking one the live source was registered: 0 for its own. */
+    depth: number;
+    /** How many sources that scope holds under the name, the live one included. */
+    stacked: number;
 }
 /** One node of the dep tree: the sources registered at it, over its parent's.
  *  Each name holds a stack of sources, newest live, so a displaced source is
@@ -1612,222 +1952,6 @@ interface Contribution<TOverlay = KernelOverlay> extends ContributionRouting, Co
     def?: unknown;
 }
 
-/**
- * Re-exports the pure matcher primitives from `@weasel-js/gestures` and layers
- * the actions-layer binding-scope / matchBest logic on top.
- */
-
-/** Where a binding came from, which is also its priority: a held hotkey beats
- *  the active tool, which beats bindings that are always in scope. */
-type BindingScope = 'ambient' | 'active' | 'hotkey';
-/** A binding paired with where it came from, ready to be matched against an
- *  event. */
-interface ScopedBinding {
-    binding: GestureBinding;
-    scope: BindingScope;
-    /** Id of the tool or contribution that declared this binding —
-     *  `'&'`-channel phase atoms resolve to it. `null` for a registered
-     *  action's own binding. */
-    ownerId: string | null;
-}
-/** The binding that won a match. */
-interface MatchResult {
-    binding: GestureBinding;
-    scope: BindingScope;
-    /** Id of the entry that declared the binding — propagated from
-     *  `ScopedBinding` so the dispatcher can record it as the handle owner. */
-    ownerId: string | null;
-}
-/**
- * True when a spec's target actually consults the affordance hit rather than
- * only the body classification. `kindOf` predicates are handed the hit;
- * `affordance:<k>` matches on its `kind`. The body-class strings (`'empty'`,
- * `'selected-body'`, `'unselected-body'`) and the `kind:` forms resolve from
- * `bodyTarget` / `bodyKind` and never see it.
- *
- * A predicate declares which it is with `readsAffordance`; one that declares
- * nothing, which only untyped code can write, counts as not reading the hit.
- */
-declare function targetConsultsAffordance(specTarget: TargetSpec | undefined): boolean;
-/** The first of {@link matchSorted}'s matches, or null when nothing matches. */
-declare function matchBest(e: InputEvent, bindings: readonly ScopedBinding[], isMac: boolean, engagedChannels?: ReadonlySet<string>): MatchResult | null;
-/**
- * Find every binding that matches the event, sorted by precedence
- * (best → worst). Ordering rules:
- *
- *   - Scopes by priority: hotkey > active > ambient.
- *   - Within a scope, more-specific bindings beat less-specific (see
- *     `specificity()`).
- *   - Among same-specificity bindings, first-declared wins.
- */
-declare function matchSorted(e: InputEvent, bindings: readonly ScopedBinding[], isMac: boolean, engagedChannels?: ReadonlySet<string>, warn?: (message: string) => void): MatchResult[];
-/** {@link matchSorted}, plus what an exclusive claim on the event barred. */
-interface MatchOutcome {
-    matches: MatchResult[];
-    /** Bindings whose spec matched the event but which the claim barred, in
-     *  the same order `matches` uses. Filled only when `collectBarred` is set. */
-    barred: MatchResult[];
-    /** Owner of the exclusive claim, when one applied. */
-    claimOwner?: string;
-}
-/**
- * {@link matchSorted} that can also report the bindings an exclusive claim
- * kept out. Collecting them costs a spec match per barred binding, so it is
- * opt-in — the dispatcher asks only when it is recording.
- */
-declare function matchSortedWithBarred(e: InputEvent, bindings: readonly ScopedBinding[], isMac: boolean, engagedChannels?: ReadonlySet<string>, opts?: {
-    collectBarred?: boolean;
-    warn?: (message: string) => void;
-}): MatchOutcome;
-
-/**
- * How one input was resolved: every binding that matched it, what each filter
- * dropped, the order the rest were ranked in and why, and what the walk down
- * that order did. The dispatcher fills one per input in dev builds, and
- * `Dispatcher.explain` fills one on request without invoking anything.
- *
- * Plain data — no functions, no live objects — so it can be kept in a trace
- * buffer, serialized, or built by hand as a fixture.
- */
-interface DispatchRecord {
-    kind: 'dispatch';
-    ts: number;
-    input: DispatchRecordInput;
-    /** Every binding whose spec matched the input, in matcher order, including
-     *  those a filter then dropped. */
-    matched: readonly RecordCandidate[];
-    dropped: readonly DroppedCandidate[];
-    /** The candidates that survived both filters, best first. */
-    ranked: readonly RankedCandidate[];
-    /** True when nothing was invoked: the record answers "what would happen". */
-    predicted: boolean;
-    /** Action id of the candidate that fired (or would), else `null`. */
-    fired: string | null;
-    outcome: 'handled' | 'unhandled';
-}
-/** The input a {@link DispatchRecord} describes, reduced to plain data. */
-interface DispatchRecordInput {
-    /** `InputEvent.kind`: `'key'`, `'pointerdown'`, `'wheel'`, … */
-    eventKind: string;
-    /** For `key` / `key-held` events, the key id (`'Escape'`, `' '`, `'a'`). */
-    key?: string;
-    modifiers: {
-        alt: boolean;
-        ctrl: boolean;
-        meta: boolean;
-        shift: boolean;
-    };
-    /** The view the input was routed to; `null` for the surface's own camera. */
-    viewId: string | null;
-    /** World point, for events that carry one. */
-    world?: {
-        x: number;
-        y: number;
-    };
-    /** Active mode id, when the host supplies a rule context. */
-    mode?: string;
-}
-/** One matched binding. */
-interface RecordCandidate {
-    actionId: string;
-    /** The binding's spec in route grammar — one per arg alternative. */
-    routes: readonly string[];
-    scope: BindingScope;
-    /** The tool or contribution that declared the binding; `null` for an action's own binding. */
-    ownerId: string | null;
-    /** Whether the binding's `views` names the routed view. */
-    namesView: boolean;
-    /** `specificity(spec)`: target, modifiers, phase, exact. */
-    specificity: readonly [number, number, number, number];
-    /** The action's `eligible` rule as text, when it declares one. */
-    eligible?: string;
-}
-/** A matched candidate a filter removed before ranking, and which filter. */
-type DroppedCandidate = 
-/** An exclusive claim on the input barred bindings that do not read the
- *  claim's affordance. */
-{
-    candidate: RecordCandidate;
-    filter: 'claim';
-    owner?: string;
-}
-/** The action's `eligible` rule does not hold. */
- | {
-    candidate: RecordCandidate;
-    filter: 'ineligible';
-    rule: string;
-};
-/** One field of the `specificity` tuple, in the order it is compared. */
-type SpecificityPart = 'target' | 'mods' | 'phase' | 'exact';
-/** The ranking step that put a candidate below the one before it. */
-type PlacedBy = {
-    step: 'first';
-}
-/** The one above names the routed view; this one does not. */
- | {
-    step: 'view';
-}
-/** The one above sits in a higher scope tier. */
- | {
-    step: 'tier';
-}
-/** Same tier; the one above is more specific in `part`. */
- | {
-    step: 'specificity';
-    part: SpecificityPart;
-}
-/** Tied; the one above is gated by an `eligible` rule that holds. */
- | {
-    step: 'context';
-}
-/** Tied on everything; registration order. */
- | {
-    step: 'order';
-};
-/** What the walk did with one ranked candidate. */
-type WalkStep = {
-    kind: 'fired';
-}
-/** Predicted records only: this candidate would fire. Nothing was started,
- *  so an ongoing action here may still bail at `start()` for real. */
- | {
-    kind: 'would-fire';
-}
-/** `enabled()` returned this reason. */
- | {
-    kind: 'declined';
-    reason: string;
-}
-/** An ongoing action's `start()` returned an empty handle. */
- | {
-    kind: 'empty-handle';
-}
-/** An ongoing action bound to a press-time `pointerDown` spec; refused. */
- | {
-    kind: 'misbound';
-}
-/** Its action was already tried higher up; each runs at most once. */
- | {
-    kind: 'duplicate';
-} | {
-    kind: 'no-such-action';
-}
-/** Below the winner; never asked. */
- | {
-    kind: 'not-asked';
-}
-/** Below the winner, asked anyway (`evaluateShadowed`), and it passed. */
- | {
-    kind: 'outranked';
-};
-/** A candidate that survived the filters: why it sits where it does, and
- *  what the walk did with it. */
-interface RankedCandidate {
-    candidate: RecordCandidate;
-    placedBy: PlacedBy;
-    walk: WalkStep;
-}
-
 /**
  * The dispatcher's contract: what a host hands it per input
  * (`DispatcherContext`) and what it answers with (`Dispatcher`).
@@ -1866,6 +1990,19 @@ interface DispatcherContext {
      * reads as the root.
      */
     viewId?: string | null;
+    /**
+     * For a key from the page: whether this surface holds the keys, and whether
+     * the pointer is over it. Bindings with `opts.over` are live only while it
+     * is, the rest only while it holds them. Absent, every binding is live.
+     */
+    keyReach?: KeyReach;
+    /** Where the dispatcher records how it resolved each input. Absent records nothing. */
+    trace?: DispatchTrace;
+}
+/** Which of a surface's key bindings a key from the page reaches. */
+interface KeyReach {
+    held: boolean;
+    over: boolean;
 }
 /**
  * Handle returned by `Dispatcher.beginUiOngoing()` for driving an
@@ -2073,31 +2210,6 @@ interface Dispatcher {
     beginUiOngoing(actionId: string, deps: ActionDeps, params?: Record<string, unknown>): UiOngoingControl | null;
 }
 
-/**
- * Dev-only trace of what the dispatcher did: one record per resolved input and
- * one per mode switch, in a rolling buffer the dev tools read.
- */
-
-/** One entry per "mode change" — a kit state transition that isn't a
- *  dispatched input event but explains why an input was (or wasn't) handled
- *  later. Pushed via `recordModeSwitch()`. */
-interface ModeSwitchLogEntry {
-    kind: 'mode';
-    ts: number;
-    /** Logical mode name, e.g. `'editAnchors.editingId'`. */
-    mode: string;
-    from: string | null;
-    to: string | null;
-    /** Optional free-form context — `'enterPathEdit'`, `'exitPathEdit'`,
-     *  `'selection-dropped target'`, etc. */
-    detail?: string;
-}
-/** A trace entry: one {@link DispatchRecord} per resolved input, or a mode switch. */
-type TraceLogEntry = DispatchRecord | ModeSwitchLogEntry;
-/** Push a mode-switch record into the trace log. Safe to call from
- *  anywhere; no-ops outside DEV. */
-declare function recordModeSwitch(mode: string, from: string | null, to: string | null, detail?: string): void;
-
 /**
  * The slot an in-flight ongoing handle is keyed by:
  * - `key-held`: `key-held-<code>` (`key-held-Space`), so two keys that share a
@@ -2798,6 +2910,29 @@ interface ToolDef<TOverlay = KernelOverlay> {
  */
 declare function defineTool<TOverlay = KernelOverlay>(def: ToolDef<TOverlay>): Tool<TOverlay>;
 
+/**
+ * Tool sets: a named group of tool ids, the unit a consumer opts into whole.
+ * A set names ids, never tools, because a tool is built by a hook that holds
+ * its state; whatever mounts the set supplies the tool for each id.
+ */
+/** A named group of tool ids. A member is an id or another set, whose ids it takes in order. */
+interface ToolSet<TId extends string = string> {
+    readonly id: string;
+    readonly members: readonly (TId | ToolSet<TId>)[];
+}
+/** One entry of a list of tools to mount: an id, or a set of them. */
+type ToolEntry<TId extends string = string> = TId | ToolSet<TId>;
+/** A set named `id` of `members`, in palette order. */
+declare function toolSet<TId extends string>(id: string, members: readonly ToolEntry<TId>[]): ToolSet<TId>;
+/** Whether `entry` is a set rather than a single id. */
+declare function isToolSet<TId extends string>(entry: ToolEntry<TId>): entry is ToolSet<TId>;
+/** Every id `entries` name, sets opened in place, each id once at its first place. */
+declare function toolIdsOf<TId extends string>(entries: readonly ToolEntry<TId>[]): TId[];
+/** `set` less every id `omit` names, sets opened. Keeps `set`'s id with a `-without` suffix. */
+declare function withoutTools<TId extends string>(set: ToolSet<TId>, ...omit: readonly ToolEntry<TId>[]): ToolSet<TId>;
+/** Whether `set` names `id`, directly or through a set inside it. */
+declare function toolSetHas<TId extends string>(set: ToolSet<TId>, id: string): boolean;
+
 /**
  * One row in the route registry — a single `GestureBinding` on one tool,
  * flattened into the route grammar's vocabulary so the inspector, the
@@ -3092,12 +3227,21 @@ declare function deleteScratch<T>(store: ScratchStore, key: ScratchKey<T>): bool
  *
  * Output shape: **files first (source order), then strings (item order)**.
  * For paste (`itemsFromClipboardData`) string flavors are emitted in
- * `INGEST_STRING_MIMES` order: text/plain, text/html, text/uri-list.
+ * `INGEST_STRING_MIMES` order: text/plain, text/html, text/uri-list, then
+ * the admitted ones in the order they were first admitted.
  */
 
-/** The string flavors the kit normalizes. Everything else (browser-internal
- *  custom flavors, etc.) is dropped at materialization. */
+/** The string flavors the kit always keeps. Any other is dropped at
+ *  materialization unless {@link admitIngestMime} has admitted it. */
 declare const INGEST_STRING_MIMES: ReadonlySet<string>;
+/**
+ * Keep string flavors of `mime` on drops, drags and pastes as well as the
+ * {@link INGEST_STRING_MIMES}, so content from the app's own UI can travel
+ * under a type of its own. Returns a release; the flavor is kept while any
+ * admission of it is unreleased. Core admits each exact MIME a registered
+ * content handler names.
+ */
+declare function admitIngestMime(mime: string): () => void;
 /** Wrap raw `File`s (file picker, `CanvasExtensionApi.ingest`) as
  *  `IngestItem`s, normalizing each MIME the same way the drop/paste paths
  *  do. Synchronous — `File` objects are already fully owned. */
@@ -3202,6 +3346,8 @@ interface DepSchema {
     activeTool: ActiveToolContextValue;
     /** The menu host of the `ActionsProvider` in scope. */
     menuHost?: MenuHost;
+    /** The canvas's dispatch trace, for a dep to record a mode switch into. */
+    dispatchTrace?: DispatchTrace;
 }
 /** Every dep name declared by anything that has merged into {@link DepSchema}. */
 type DepName = keyof DepSchema;
@@ -3249,4 +3395,4 @@ type KernelOverlay = OverlaySchema extends {
     overlay: infer O;
 } ? O : unknown;
 
-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 };
+export { type Bounds as $, type Action as A, type BoundGesture as B, type Contribution as C, type DepRegistry as D, type ActionPresentation as E, type ActionSettings as F, type ActionSettingsState as G, type ActionShortcut as H, type ActionSource as I, type ActionTuning as J, type KernelOverlay as K, type LongPressOptions as L, type MenuHost as M, type NodeId as N, type OverlayPosition as O, type ActionTunings as P, type ActionsProp as Q, type RuleCtx as R, ScopeNode as S, ToolNode as T, type AnyTool as U, type AssemblyInputs as V, BROWSER_RESERVED_CHORDS as W, type BindingOpts as X, type BindingScope as Y, type BindingSource as Z, type BodyPredicate as _, type DepName as a, type PointerSessionCallbacks as a$, type BuildRuleCtxArgs as a0, COARSE_TARGET_SCALE as a1, type Carried as a2, type Carry as a3, type CarryCallbacks as a4, type CarryPayload as a5, type CarryPointer as a6, type CarryStage as a7, type Condition as a8, type Conflict as a9, type KeyReach as aA, type LongPressState as aB, type LongPressStore as aC, type MatchOutcome as aD, type MatchResult as aE, type MenuHit as aF, type MenuOpenRequest as aG, type MenuSources as aH, type MenuWhen as aI, type ModeShortcutHandlers as aJ, type ModeSwitchLogEntry as aK, type ModifierRole as aL, type ModifierRoles as aM, type ModifierState as aN, NEVER as aO, type OngoingHandle as aP, type OngoingInvoker as aQ, type OngoingOverlay as aR, type OpenMenu as aS, type OverlayRole as aT, type OverlaySchema as aU, type OwnedMenuDef as aV, PREDICATE_TARGET as aW, type PendingLongPress as aX, type PlacedBy as aY, type Point2 as aZ, type PointerSession as a_, type ContributionChrome as aa, type ContributionDeps as ab, type ContributionRouting as ac, DEFAULT_ALLOWED_CAPABILITIES as ad, DEFAULT_DEVICE_PROFILE as ae, type DebugSink as af, type DepListing as ag, type DetectedDeviceFacts as ah, type DeviceProfile as ai, type DispatchRecord as aj, type DispatchRecordInput as ak, type DispatcherContext as al, type DragSample as am, type DroppedCandidate as an, type Eligibility as ao, type EligibilityState as ap, type GestureBinding as aq, type GestureKitSettings as ar, type HandleKind as as, type HitShape as at, type HotkeyTrigger as au, INGEST_STRING_MIMES as av, type ImmediateInvoker as aw, type InvocationCtx as ax, type Invoker as ay, type KeyBinding as az, type DepSource as b, evaluateActive as b$, type PointerSessionCancelReason as b0, type PointerSessionOptions as b1, type RankedCandidate as b2, type RecordCandidate as b3, type RegistryEntry as b4, type ReservedChord as b5, type ResizeAnchor as b6, type ResolveAllOptions as b7, type ResolveOnlyResult as b8, type ResolvedCandidate as b9, actionCursor as bA, actionItemTitle as bB, actionItems as bC, actionSettingsParams as bD, actionShortcuts as bE, actionsTagged as bF, admitIngestMime as bG, assembleEntries as bH, browserReservedChord as bI, buildDepsFromRequires as bJ, buildRouteRegistry as bK, buildRuleCtx as bL, buildToolOffhandBindings as bM, clientToCanvas as bN, clientToCanvasRect as bO, createDepRegistry as bP, createDispatchTrace as bQ, createDispatcher as bR, createLongPressStore as bS, createMenuHost as bT, createTraceRing as bU, defineTool as bV, deleteScratch as bW, describeRule as bX, dlog as bY, dwarn as bZ, evaluate as b_, type RoleKeys as ba, type RoleRebinds as bb, type Rule as bc, type ScopedBinding as bd, type ScratchKey as be, type ScratchStore as bf, type SelectionApi as bg, type Selector as bh, type SpecificityPart as bi, TOOL_OFFHAND_ID as bj, type ToolDef as bk, type ToolEntry as bl, type ToolKeybinding as bm, type ToolModifiers as bn, type ToolOffhandBindingSpec as bo, type ToolPresentation as bp, type ToolScopes as bq, type ToolSet as br, type ToolSlot as bs, type TraceLogEntry as bt, type TraceRing as bu, type TunedBinding as bv, type UiOngoingControl as bw, type ViewportGestureKind as bx, type WalkStep as by, actionBindings as bz, type ActionDeps as c, tuneAction as c$, evaluateEnabled as c0, findConflicts as c1, getScratch as c2, heldKeySpec as c3, historyKey as c4, isAnchor as c5, isAnchorOrControl as c6, isBalanceGrip as c7, isBody as c8, isControlHandle as c9, modeShortcutSpec as cA, modeShortcuts as cB, multiTouchGestureId as cC, offhandKeyFor as cD, openPointerSession as cE, overlaysOf as cF, pickMenu as cG, pointerGestureId as cH, readActionSettings as cI, reportRouteConflicts as cJ, resolveDeviceProfile as cK, resolveMenu as cL, resolveParams as cM, resolveSchemaMenu as cN, roleReader as cO, routesForSpec as cP, ruleCanHoldIn as cQ, rulesExclusive as cR, scopeBindings as cS, scratchKey as cT, setScratch as cU, startCarry as cV, taggedActionItems as cW, targetConsultsAffordance as cX, toolIdsOf as cY, toolSet as cZ, toolSetHas as c_, isCornerWidget as ca, isDebugEnabled as cb, isEmpty as cc, isPathEditPart as cd, isResizeHandle as ce, isRotateHandle as cf, isSegment as cg, isSelectedBody as ch, isTool as ci, isToolSet as cj, isUnselectedBody as ck, itemTypesFromDataTransfer as cl, itemsFromClipboardData as cm, itemsFromDataTransfer as cn, itemsFromFiles as co, keySpecShortcut as cp, keysHeld as cq, liveScope as cr, makeToolOffhandAction as cs, matchActionItem as ct, matchBest as cu, matchSorted as cv, matchSortedWithBarred as cw, matchesKeyBinding as cx, mergeContributions as cy, mergeMenuDefs as cz, type ActionsRegistry as d, validateActionDefaultBinding as d0, validateActionId as d1, withoutTools as d2, 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, type DispatchTrace as q, type DepSchema as r, ALWAYS as s, type ActionDispatch as t, useActiveToolContext as u, type ActionEnabledResult as v, type ActionEntry as w, type ActionItem as x, type ActionParamSchema as y, type ActionParams as z };