@weasel-js/gestures 1.9.4 → 1.10.0

package/dist/index.d.ts

@@ -7,7 +7,7 @@
  * Reflection, matcher, and inspector UI all read this table. Adding a new
  * gesture name in one place updates every consumer.
  */
-type GestureName = 'click' | 'pointerDown' | 'dblTap' | 'drag' | 'wheel' | 'pinch' | 'keyDown' | 'keyUp' | 'keyHeld' | 'contextMenu' | 'longPress' | 'multiTouch' | 'multiTouchTap' | 'drop' | 'paste';
+type GestureName = 'click' | 'pointerDown' | 'hover' | 'dblTap' | 'drag' | 'wheel' | 'pinch' | 'keyDown' | 'keyUp' | 'keyHeld' | 'contextMenu' | 'longPress' | 'multiTouch' | 'multiTouchTap' | 'drop' | 'paste';
 /**
  * Gesture kinds an affordance claim can bar, in the spec vocabulary bindings
  * are written in. `'pointer'` is one token because `pointerDown` / `click` /
@@ -62,9 +62,9 @@ type ModifierCombo = 'default' | 'mod' | 'shift' | 'alt' | 'mod+shift' | 'mod+al
  */
 declare function mods(...keys: ReadonlyArray<'mod' | 'shift' | 'alt'>): ModifierCombo;
 
-/** Phase of a gesture lifecycle. `initial` means the tool is idle
- *  (scratch null); `engaged` means a gesture is in progress (scratch
- *  populated). The route-grammar's `[phase]` slot draws from this set. */
+/** Where a tool stands when a binding is matched: `engaged` while an action it
+ *  began is still in flight, `initial` otherwise. The route grammar's `[phase]`
+ *  slot draws from this set. */
 type RoutePhase = 'initial' | 'engaged';
 
 /**
@@ -83,9 +83,7 @@ type RoutePhase = 'initial' | 'engaged';
  *   sigil       = '+' | '?'                            -- ! @ # $ % ^ & * reserved as id-prefix
  *   modName     = 'mod' | 'shift' | 'alt' | 'ctrl' | 'meta'
  *
- * Shorthand: a bare phaseValue (no `:`) implies channel `&` ("this tool's
- * own phase"). `[engaged]` ≡ `[&:engaged]`; `[*]` ≡ `[&:*]`. The truly-loose
- * form (any channel, any phase) is `[*:*]`.
+ * The truly-loose form (any channel, any phase) is `[*:*]`.
  *
  * Examples:
  *   [initial] click => empty +shift            -- self idle
@@ -118,9 +116,7 @@ declare const RESERVED_ID_NAMES: ReadonlySet<string>;
 /** v3 modifier requirement on a single modifier key. Absent from a
  *  `ParsedModifiers` map means "must not be held" (the strict default). */
 type ModRequirement = 'required' | 'optional';
-/** Canonical modifier names accepted in the modSlot, in canonical order.
- *  Single source of truth: the {@link ModifierKey} type and the runtime
- *  validator (`MOD_NAME_SET`) are both derived from this tuple. */
+/** Canonical modifier names accepted in the modSlot, in canonical order. */
 declare const VALID_MOD_NAMES: readonly ["mod", "shift", "alt", "ctrl", "meta"];
 /** A single modifier name accepted in the modSlot. */
 type ModifierKey = (typeof VALID_MOD_NAMES)[number];
@@ -167,18 +163,12 @@ declare function parseRoute(input: string): ParsedRoute;
 declare function formatPhaseAtom(a: PhaseAtom): string;
 /** Visual-collapse pass: given a list of route strings, fold pairs that
  *  differ ONLY in `shift` presence (one has `+shift`, the other doesn't,
- *  everything else identical) into a single route with `?shift`. Useful
- *  for inspector / palette displays that want to show "Cmd+[" and
- *  "Cmd+Shift+[" as one Cmd+?Shift+[ chip rather than two rows.
+ *  everything else identical) into a single route with `?shift`.
  *
  *  Preserves input order — the first member of each fold-pair holds the
- *  position; the second is dropped. Routes that don't have a `+shift`
- *  vs absent twin pass through unchanged. Does NOT fold other modifier
+ *  position; the second is dropped. Does NOT fold other modifier
  *  pairs (alt/ctrl/meta/mod) — those tend to carry meaning across the
- *  same key (e.g., Cmd+Z vs Cmd+Shift+Z are usually two distinct
- *  actions, but Cmd+] vs Cmd+Shift+] is more often parametric variation
- *  of one action). Open the helper if a use case for the other
- *  modifiers shows up.
+ *  same key.
  */
 declare function collapseShiftPairs(routes: readonly string[]): string[];
 /** Render a parsed route back to a canonical route string: shorthand where
@@ -186,32 +176,20 @@ declare function collapseShiftPairs(routes: readonly string[]): string[];
  *  `parseRoute(formatRoute(r))` yields `r` again. */
 declare function formatRoute(r: ParsedRoute): string;
 
-/**
- * GestureSpec — describes the form of a user input event that can fire an action.
- *
- * Used by `Action.defaultBinding` (the action's preferred gesture) and by
- * `GestureBinding.spec` (a tool's binding table entry). The dispatcher matches
- * incoming input events against registered specs to determine which action to
- * invoke.
- *
- * See `docs/superpowers/specs/2026-05-16-registry-unification-design.md` § "Types".
- */
+/** GestureSpec — describes the form of a user input event that can fire an action. */
 /** Optional modifier-key requirement for a gesture spec.
  *
- *  Matching semantics (strict): an omitted modifier field means the
- *  modifier MUST NOT be held — i.e., a bare `{ kind: 'key', key: 'Escape' }`
- *  matches only unmodified Escape, NOT Cmd+Escape. A `true` means the
- *  modifier MUST be held; `false` is the same as omitted (must be absent).
- *  This mirrors today's `KeyBinding` matcher and keeps conflict detection
- *  coherent.
+ *  Matching is strict: an omitted modifier field means the modifier MUST NOT
+ *  be held — a bare `{ kind: 'key', key: 'Escape' }` matches only unmodified
+ *  Escape, NOT Cmd+Escape. A `true` means the modifier MUST be held; `false`
+ *  is the same as omitted.
  *
  *  `mod` is a platform-aware shorthand: matches `metaKey` on mac, `ctrlKey`
- *  elsewhere (mirrors `KeyBinding.mod`).
+ *  elsewhere.
  *
  *  Every modifier additionally accepts `'optional'`, meaning "held or not,
- *  both acceptable" — the explicit opt-in for loose matching, used by
- *  actions like nudge whose step size depends on shift but whose firing
- *  does not.
+ *  both acceptable" — used by actions like nudge whose step size depends on
+ *  shift but whose firing does not.
  */
 type ModSpec = Partial<{
     alt: boolean | 'optional';
@@ -242,10 +220,8 @@ declare function hitPredicate(fn: (hit: unknown, bodyTarget?: string) => boolean
 declare function bodyPredicate(fn: (bodyTarget: string | undefined) => boolean): TargetPredicate & {
     readsAffordance: false;
 };
-/** Target selector for click and drag gesture specs. String forms are sugar
- *  for the kit-owned object-kind registry (TODO.md Tier 1 follow-up); until
- *  that ships, consumers can pass `{ kindOf: predicate }` to classify hits
- *  themselves.
+/** Target selector for click and drag gesture specs. Consumers can pass
+ *  `{ kindOf: predicate }` to classify hits themselves.
  *
  *  Adding a form here is a compile error in `parseTargetSpec` until
  *  `TargetSpecForm` grows a matching variant — which is in turn a compile
@@ -254,19 +230,16 @@ type TargetSpec = 'empty' | 'selected-body' | 'unselected-body' | `kind:${string
     kindOf: TargetPredicate;
 };
 /** Phase qualifier on a gesture spec. Restricts when the spec matches based
- *  on per-tool gesture-lifecycle state.
+ *  on per-tool gesture-lifecycle state. When omitted, matches in any phase.
  *
- *  Shorthand forms (most common case — gate on the binding's own tool):
+ *  Shorthand forms gate on the binding's own tool:
  *    `'engaged'` → `[{ channel: '&', phase: 'engaged' }]`  // self mid-gesture
  *    `'initial'` → `[{ channel: '&', phase: 'initial' }]`  // self idle
  *    `'*'`       → `[{ channel: '&', phase: '*' }]`        // either self phase
  *
  *  Array form for explicit channel:phase atoms — e.g. `[{ channel: 'rect',
  *  phase: 'engaged' }]` for "when the rect tool is mid-gesture, regardless of
- *  which scope I'm in." See the v3 route grammar in
- *  `@weasel-js/gestures/grammar` for the full lattice.
- *
- *  When omitted, matches in any phase (preserves pre-phase behavior). */
+ *  which scope I'm in." */
 type PhaseSpec = 'initial' | 'engaged' | '*' | readonly PhaseAtom[];
 /** Single-keystroke gesture (keydown). */
 interface KeySpec {
@@ -292,10 +265,8 @@ interface KeyHeldSpec {
     mods?: ModSpec;
     phase?: PhaseSpec;
 }
-/** Wheel-event gesture. `direction` filters by deltaY sign; default `'*'`.
- *  - `'up'`   → matches only deltaY < 0
- *  - `'down'` → matches only deltaY > 0
- *  - `'*'`    → matches either sign (default; universal-wildcard convention) */
+/** Wheel-event gesture. `direction` filters by deltaY sign: `'up'` matches
+ *  only deltaY < 0, `'down'` only deltaY > 0, and the default `'*'` either. */
 interface WheelSpec {
     kind: 'wheel';
     direction?: 'up' | 'down' | '*';
@@ -304,10 +275,9 @@ interface WheelSpec {
     phase?: PhaseSpec;
 }
 /** Pinch reported as a scale factor about a focal point (WebKit
- *  `gesturechange`). `direction` filters by the sample's scale; default `'*'`.
- *  - `'out'` → fingers spreading, scale > 1
- *  - `'in'`  → fingers closing, scale < 1
- *  A touchscreen pinch is {@link MultiTouchSpec}, not this. */
+ *  `gesturechange`). `direction` filters by the sample's scale: `'out'` is
+ *  scale > 1, `'in'` is scale < 1; default `'*'`. A touchscreen pinch is
+ *  {@link MultiTouchSpec}, not this. */
 interface PinchSpec {
     kind: 'pinch';
     direction?: 'in' | 'out' | '*';
@@ -324,9 +294,7 @@ interface ClickSpec {
     phase?: PhaseSpec;
 }
 /** Double-click: two `click` events within 600ms and 8px of each other.
- *  Synthesized by `useGestureDispatcher`; emitted AFTER the second
- *  `click`. Bindings that want to handle a double-click should declare
- *  this kind rather than chasing two `click` events. */
+ *  Synthesized by `useGestureDispatcher`; emitted AFTER the second `click`. */
 interface DoubleClickSpec {
     kind: 'doubleClick';
     target?: TargetSpec;
@@ -351,13 +319,10 @@ interface DragSpec {
 }
 /**
  * Bare pointer press, matched at down time — before the dispatcher knows
- * whether the gesture will become a click or a drag.
- *
- * Reach for this only when the effect must be visible while the button is
- * still held. Selection is the motivating case: pressing an unselected node
- * highlights it immediately, and the drag that may follow then starts from an
- * already-correct selection. Anything that can wait for the release belongs on
- * a `click` spec, which does not fire on a press that turns into a drag.
+ * whether the gesture will become a click or a drag. Reach for this only when
+ * the effect must be visible while the button is still held; anything that
+ * can wait for the release belongs on a `click` spec, which does not fire on
+ * a press that turns into a drag.
  *
  * A matching binding does NOT own the gesture: the same press goes on to open
  * a drag or synthesize a click as usual. Bind an immediate action here, not an
@@ -369,17 +334,30 @@ interface PointerDownSpec {
     mods?: ModSpec;
     phase?: PhaseSpec;
 }
+/**
+ * The pointer moving over the surface with no button pressed. Fires on every
+ * such move; a held pointer's moves belong to its drag and fire nothing here.
+ *
+ * A hover binding claims nothing. Every live binding that matches the move
+ * runs, not only the best one, and the move still reaches the hover-cursor
+ * pump. There is no press to own, so bind an immediate action, not an ongoing
+ * one. Its params carry `worldX` / `worldY`, `clientX` / `clientY`,
+ * `affordance`, `bodyTarget`, and `mods`.
+ */
+interface HoverSpec {
+    kind: 'hover';
+    target?: TargetSpec;
+    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.
+ * Fires for `touch` and `pen` pointers only: a mouse held still is an
+ * ordinary slow click.
  *
  * 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.
+ * `contextmenu` event, so `contextMenu` bindings work under a finger.
  */
 interface LongPressSpec {
     kind: 'longPress';
@@ -421,10 +399,8 @@ interface PasteSpec {
     mods?: ModSpec;
     phase?: PhaseSpec;
 }
-/** The full union of supported gesture spec kinds. New invocation forms
- *  (two-stage, modal-dialog) extend this union without touching
- *  the `Action` type. */
-type GestureSpec = KeySpec | KeyHeldSpec | WheelSpec | PinchSpec | ClickSpec | DoubleClickSpec | ContextMenuSpec | DragSpec | PointerDownSpec | LongPressSpec | MultiTouchSpec | MultiTouchTapSpec | DropSpec | PasteSpec;
+/** The full union of supported gesture spec kinds. */
+type GestureSpec = KeySpec | KeyHeldSpec | WheelSpec | PinchSpec | ClickSpec | DoubleClickSpec | ContextMenuSpec | DragSpec | PointerDownSpec | HoverSpec | LongPressSpec | MultiTouchSpec | MultiTouchTapSpec | DropSpec | PasteSpec;
 
 /**
  * Mini-grammar for the `arg` slot of `keyDown` / `keyUp` routes.
@@ -537,11 +513,7 @@ declare function modifierComboToParsed(key: ModifierCombo): ParsedModifiers;
  *  `name=req` pairs joined by `&`. */
 declare function canonicalModifiers(mods: ParsedModifiers): string;
 
-/**
- * Keyboard/pointer modifier flags carried by every {@link InputEvent} arm.
- * Factored out so the four booleans are documented once instead of repeated
- * on all twelve event shapes.
- */
+/** Keyboard/pointer modifier flags carried by every {@link InputEvent} arm. */
 interface EventModifiers {
     altKey: boolean;
     ctrlKey: boolean;
@@ -558,24 +530,15 @@ type BodyTarget = 'empty' | 'selected-body' | 'unselected-body';
 /**
  * Semantic kind of the node body under the point — `'text'`, `'rect'`, or an
  * app's own `'app:note'`. Companion to {@link BodyTarget}, which says only how
- * the body relates to the selection; this says *what it is*. Read by
- * `matchTarget` to resolve the `kind:<k>` / `kind:<k>:selected` TargetSpec
- * forms.
- *
- * Supplied by the same `classifyTarget` thunk that supplies `bodyTarget`, and
- * absent for the same reasons plus one more: the thunk hit a body whose kind
- * the scene can't name. An absent `bodyKind` makes every `kind:` form
- * no-match, never a wildcard.
+ * the body relates to the selection. Supplied by the same `classifyTarget`
+ * thunk; an absent `bodyKind` makes every `kind:` form no-match, never a
+ * wildcard.
  */
 type BodyKind = string;
 /**
  * What a scene hit-test found under a point — the shape a `classifyTarget`
  * thunk returns, and the source of both {@link BodyTarget} and
  * {@link BodyKind} on the events the matcher sees.
- *
- * One thunk returns both halves rather than two thunks returning one each:
- * the two answers come from the same hit-test, and splitting them would cost
- * a second pick on every pointer event.
  */
 interface BodyClassification {
     /** How the hit body relates to the current selection. */
@@ -650,14 +613,10 @@ interface PointerSampleStylus {
     tiltY?: number;
 }
 /**
- * Which physical pointer a sample came from.
- *
- * Carried by every pointer-kind event so the dispatcher can key in-flight
- * gesture handles per pointer (`pointer-<pointerId>`) instead of funneling
- * mouse, each touch, and the stylus into one slot. Optional because
- * synthesized events (tests, programmatic drags, the hover pump's
- * `resolveOnly` probe) have no originating `PointerEvent`; those all key to
- * the same default slot, which is the pre-`pointerId` behavior.
+ * Which physical pointer a sample came from, so the dispatcher can key
+ * in-flight gesture handles per pointer. Optional because synthesized events
+ * (tests, programmatic drags, the hover pump's `resolveOnly` probe) have no
+ * originating `PointerEvent`; those all key to the same default slot.
  */
 interface PointerIdentity {
     /** `PointerEvent.pointerId` from the originating DOM event. */
@@ -667,21 +626,17 @@ interface PointerIdentity {
 interface PointerDownEvent extends EventModifiers, PointerSampleStylus, PointerIdentity {
     kind: 'pointerdown';
     /**
-     * Which of the two dispatches this press produces.
-     *
-     * A physical pointerdown is dispatched twice, for two different audiences:
+     * Which of the two dispatches this press produces. A physical pointerdown
+     * is dispatched twice:
      *
      * - `'press'` — emitted immediately, at down time. Matches `pointerDown`
-     *   specs only. This is the dispatch that lets a binding act *before* the
-     *   gesture is classified (select applies the selection here, so
-     *   press-and-hold highlights without waiting for a release).
+     *   specs only.
      * - omitted — the copy the dispatcher buffers and flushes once movement
      *   crosses the drag threshold. Matches `drag` specs only, and is what
      *   opens a drag handle.
      *
      * The split is what keeps one press from firing both a `pointerDown` and a
-     * `drag` binding. Synthetic probes (the hover pump's `resolveOnly`) leave it
-     * omitted, so drag prediction is unaffected.
+     * `drag` binding.
      */
     stage?: 'press';
     target?: unknown;
@@ -728,8 +683,6 @@ interface ClickEvent extends EventModifiers {
     /**
      * World-space coordinates of the click, derived via the `clientToWorld`
      * thunk supplied to the dispatcher. Absent when the thunk isn't wired.
-     * Forwarded into action params so click invokers can act on the click's
-     * position without their own pointer-listener plumbing.
      */
     x?: number;
     y?: number;
@@ -743,23 +696,18 @@ interface ClickEvent extends EventModifiers {
     /**
      * World-space coordinates of the *press* that opened this click, as opposed
      * to `x`/`y`, which are the release. The two differ by up to the
-     * drag threshold (`DRAG_THRESHOLD_PX`, in screen pixels).
-     *
-     * Actions that place geometry at the click want this one — a click's
-     * location reads as where the user put the pointer down, and pinning to the
-     * press point keeps a snapped coordinate stable against the small drift
-     * between press and release. Absent when the `clientToWorld` thunk isn't
-     * wired, same as `x`/`y`.
+     * drag threshold (`DRAG_THRESHOLD_PX`, in screen pixels). Actions that place
+     * geometry at the click want this one: pinning to the press point keeps a
+     * snapped coordinate stable against the drift between press and release.
+     * Absent when the `clientToWorld` thunk isn't wired, same as `x`/`y`.
      */
     pressX?: number;
     pressY?: number;
     /**
      * Affordance the *press* landed on, carried forward from the pointerdown
-     * exactly like {@link ClickEvent.bodyTarget} is. A click's target is
-     * whatever the press hit — chrome doesn't move out from under a pointer
-     * between down and up — and without this a `kindOf` target on a click spec
-     * would receive the raw DOM element while the same predicate on a drag spec
-     * receives the affordance.
+     * like {@link ClickEvent.bodyTarget} is. Without this a `kindOf` target on
+     * a click spec would receive the raw DOM element while the same predicate
+     * on a drag spec receives the affordance.
      */
     affordance?: unknown;
     bodyTarget?: BodyTarget;
@@ -793,6 +741,18 @@ interface ContextMenuEvent extends EventModifiers {
     bodyTarget?: BodyTarget;
     bodyKind?: BodyKind;
 }
+/** A move of a pointer with no button pressed. Matched by `hover` specs. */
+interface HoverEvent extends EventModifiers {
+    kind: 'hover';
+    /** World-space position of the pointer. */
+    x: number;
+    y: number;
+    clientX?: number;
+    clientY?: number;
+    affordance?: unknown;
+    bodyTarget?: BodyTarget;
+    bodyKind?: BodyKind;
+}
 /** A press held past the long-press threshold without moving. */
 interface LongPressEvent extends EventModifiers {
     kind: 'longpress';
@@ -818,9 +778,8 @@ interface MultiTouchEvent extends EventModifiers {
      * which is the space `zoomAt` anchors in. Not client coords, and not world:
      * calling `clientToWorld` on it subtracts the canvas origin a second time.
      *
-     * Populated by `useGestureDispatcher` on the pointermove-pump of a running
-     * multitouch handle (updated each frame). Absent on the initial
-     * pointerdown-triggered multitouch event.
+     * Present on the event a finger landing produces and on each move of a
+     * running gesture; absent on the one that ends it.
      */
     centroid?: {
         x: number;
@@ -829,10 +788,15 @@ interface MultiTouchEvent extends EventModifiers {
     /**
      * Distance between the two primary pointers, in CSS pixels. A distance is
      * origin-free, so it reads the same in client and canvas-local space.
-     * Populated on move-pump events alongside `centroid`. Absent on the initial
-     * event.
+     * Present and absent alongside `centroid`.
      */
     spread?: number;
+    /**
+     * Direction from the first of the two primary pointers to the second, in
+     * degrees in (-180, 180], growing clockwise on screen. Present and absent
+     * alongside `centroid`.
+     */
+    angle?: number;
     /**
      * Set on the event that ends the running multitouch gesture, whatever its
      * finger count: `'commit'` when a finger lifts, `'cancel'` when one of its
@@ -876,47 +840,23 @@ interface PasteEvent extends EventModifiers {
     items: readonly IngestItem[];
 }
 /**
- * Normalized input-event shape consumed by the pure matcher. Built by the
- * React seam (`useGestureDispatcher`) from DOM events. Pump-only events
+ * Normalized input-event shape consumed by the pure matcher. Pump-only events
  * ({@link PointerMoveEvent}, {@link PointerUpEvent}, {@link PointerCancelEvent})
  * ride in the same union so the dispatcher's `handleInput` signature stays
  * uniform; the matcher itself never matches them.
  *
  * The `affordance?` field on {@link PointerDownEvent} is widened to `unknown`
  * in this package — the kit narrows it back to `AffordanceHit` at consumption.
- * This keeps `@weasel-js/gestures` free of any kit-affordance type.
  */
-type InputEvent = KeyEvent | KeyHeldEvent | WheelEvent | PinchEvent | PointerDownEvent | PointerMoveEvent | PointerUpEvent | PointerCancelEvent | ClickEvent | DoubleClickEvent | ContextMenuEvent | LongPressEvent | MultiTouchEvent | MultiTouchTapEvent | DropEvent | PasteEvent;
+type InputEvent = KeyEvent | KeyHeldEvent | WheelEvent | PinchEvent | PointerDownEvent | PointerMoveEvent | HoverEvent | PointerUpEvent | PointerCancelEvent | ClickEvent | DoubleClickEvent | ContextMenuEvent | LongPressEvent | MultiTouchEvent | MultiTouchTapEvent | DropEvent | PasteEvent;
 
 /**
- * Pure gesture matcher — no React, no state, no DOM.
- *
- * The kit's dispatcher orchestrator wraps these primitives with its
- * actions-layer concerns (BindingScope, ScopedBinding, MatchResult, matchBest).
- *
- * ## key-held phase decision
- * `matchSpec` returns `true` only for `phase: 'down'`, not `phase: 'up'`.
- * The dispatcher tracks the held key independently and handles the `up` phase
- * itself; the matcher never sees an "un-match" it needs to distinguish.
- * This keeps the matcher's output a simple boolean and avoids a three-valued
- * return type.
- *
- * ## TargetSpec string forms
- * Every form `TargetSpec` declares is resolved here, each from a different
- * field the dispatcher packs onto the event:
- *
- * | Form | Read from | Supplied by |
- * | --- | --- | --- |
- * | `'empty'` / `'selected-body'` / `'unselected-body'` | `bodyTarget` | the `classifyTarget` thunk |
- * | `kind:<k>` / `kind:<k>:selected` | `bodyKind` + `bodyTarget` | the `classifyTarget` thunk's node-kind resolver |
- * | `affordance:<k>` | the raw target's `.kind` | the `affordanceAt` thunk |
- * | `{ kindOf }` | the raw target + `bodyTarget` | both |
- *
- * A form whose source field is absent does not match — an unwired
- * `classifyTarget` makes every `bodyTarget`/`bodyKind` form `false` rather
- * than a silent wildcard. That is deliberate: a binding that can't be
- * evaluated should stay out of the way of one that can.
+ * The stylus fields `src` carries, as a spread-able partial: a sample that
+ * carries none of them adds no `undefined`-valued keys to what it is spread into.
  */
+declare function stylusOf(src: PointerSampleStylus): PointerSampleStylus;
+
+/** Pure gesture matcher — no React, no state, no DOM. */
 
 /** The modifier-state fields `matchModifiers` reads. Structural, so a DOM
  *  `KeyboardEvent` or `PointerEvent` satisfies it directly. */
@@ -929,27 +869,21 @@ type ModifiersEvent = {
 /**
  * Strict modifier match.
  *
- * - Omitted modifier MUST NOT be held.
- * - `true`       MUST be held.
- * - `false`      MUST NOT be held (same as omitted; both forms accepted for clarity).
- * - `'optional'` accepts either held or unheld. Supported on every modifier
- *   (`alt`, `ctrl`, `meta`, `mod`, `shift`).
- * - `mod` is platform-aware: matches `metaKey` on mac, `ctrlKey` elsewhere.
- *   When `mod` is set, the corresponding `meta`/`ctrl` field is implied AND
- *   the *other* platform key is forbidden. Callers should not combine `mod`
- *   with `meta`/`ctrl`.
+ * - Omitted or `false`: MUST NOT be held.
+ * - `true`: MUST be held.
+ * - `'optional'`: accepts either held or unheld.
+ * - `mod` is platform-aware: matches `metaKey` on mac, `ctrlKey` elsewhere,
+ *   and the *other* platform key is forbidden. Callers should not combine
+ *   `mod` with `meta`/`ctrl`.
  */
 declare function matchModifiers(e: ModifiersEvent, mods: ModSpec | undefined, isMac: boolean): boolean;
 /** Case-insensitive key match; supports string or string[] (any-of). */
 declare function matchKey(eventKey: string, specKey: string | string[]): boolean;
 /**
  * A {@link TargetSpec} resolved to its form, with the parts each form encodes
- * in its string pulled out.
- *
- * This is the one enumeration of the target forms. Three sites act on it and
- * each does something different — `matchTarget` below, and `targetRank` /
- * `targetConsultsAffordance` in `@weasel-js/core`'s dispatcher matcher — so
- * they switch on `form` exhaustively rather than re-deriving the prefixes.
+ * in its string pulled out. This is the one enumeration of the target forms:
+ * sites that act on it switch on `form` exhaustively rather than re-deriving
+ * the prefixes.
  */
 type TargetSpecForm = {
     form: 'body';
@@ -976,16 +910,13 @@ declare function parseTargetSpec(spec: TargetSpec): TargetSpecForm | null;
 /**
  * Match a target value + event against a TargetSpec.
  *
- * - `{ kindOf: predicate }` — calls the predicate with the raw target value
- *   (affordance hit on pointerdown; event.target otherwise) AND the
- *   `bodyTarget` string. Predicates that only need the target can ignore
- *   the second arg.
+ * - `{ kindOf: predicate }` — calls the predicate with the affordance hit and
+ *   the `bodyTarget` string.
  * - `'empty'`, `'selected-body'`, `'unselected-body'` — compared against
- *   `bodyTarget` on the event (populated by `useGestureDispatcher` when a
- *   `classifyTarget` thunk is supplied).
+ *   `bodyTarget` on the event.
  * - `kind:<k>` — compared against `bodyKind`, the *semantic* kind of the node
- *   body under the point (`'text'`, `'rect'`, an app's own `'app:note'`), as
- *   resolved by `classifyTarget`. Selection-agnostic.
+ *   body under the point (`'text'`, `'rect'`, an app's own `'app:note'`).
+ *   Selection-agnostic.
  * - `kind:<k>:selected` — the same, and additionally requires the body to be
  *   in the current selection. Only the final `:selected` is a suffix, so a
  *   kind may itself contain colons.
@@ -1001,16 +932,11 @@ declare function parseTargetSpec(spec: TargetSpec): TargetSpecForm | null;
  * silent wildcard.
  */
 declare function matchTarget(target: unknown, specTarget: TargetSpec | undefined, bodyTarget?: string, bodyKind?: string): boolean;
-/** Per-tool gesture-lifecycle state at match time.
- *
- *  - `selfChannel` is the tool id `'&'` resolves to — i.e., the tool that
- *    owns the binding being evaluated. `null` for bindings without an
- *    owning tool (e.g. ambient actions registered without scope ties); in
- *    that case any `phase: '&'` atom can't match.
- *  - `engagedChannels` is the set of tool ids that currently have an
- *    in-flight handle. Derived by the dispatcher from its `inFlight()`
- *    map keyed by tool id at match time.
- */
+/** Per-tool gesture-lifecycle state at match time. `selfChannel` is the tool
+ *  id `'&'` resolves to — the tool that owns the binding being evaluated — or
+ *  `null` for a binding without an owning tool, in which case no `'&'` atom
+ *  can match. `engagedChannels` is the set of tool ids that currently have an
+ *  in-flight handle. */
 interface PhaseContext {
     selfChannel: string | null;
     engagedChannels: ReadonlySet<string>;
@@ -1020,14 +946,6 @@ interface PhaseContext {
  *  constraint). Union semantics: a phase atom list matches when ANY
  *  atom matches. */
 declare function matchPhase(spec: PhaseSpec | undefined, ctx: PhaseContext): boolean;
-/** MIME-glob match: `'image/*'` prefix-matches the major type; anything
- *  else is an exact (case-insensitive) match; bare `'*'` or `'*\/*'` matches all. */
-declare function mimeMatchesGlob(mime: string, glob: string): boolean;
-/** True if ANY item's MIME matches ANY of the `types` globs.
- *  `types: []` (empty) ≡ omitted = match any. */
-declare function matchIngestTypes(items: readonly {
-    mime: string;
-}[], types: string[] | undefined): boolean;
 /**
  * Match a single GestureSpec against an InputEvent.
  *
@@ -1036,6 +954,20 @@ declare function matchIngestTypes(items: readonly {
  */
 declare function matchSpec(e: InputEvent, spec: GestureSpec, isMac: boolean, phaseCtx?: PhaseContext): boolean;
 
+/** Which external content a `drop` or `paste` spec's MIME globs let through. */
+/** MIME-glob match: `'image/*'` prefix-matches the major type; anything
+ *  else is an exact (case-insensitive) match; bare `'*'` or `'*\/*'` matches all. */
+declare function mimeMatchesGlob(mime: string, glob: string): boolean;
+/** The MIME of an item whose type is not known yet: a file hovering in an OS
+ *  drag, which some browsers do not name until it is dropped. */
+declare const UNKNOWN_MIME = "*/*";
+/** True if ANY item's MIME matches ANY of the `types` globs.
+ *  `types: []` (empty) ≡ omitted = match any. An item of
+ *  {@link UNKNOWN_MIME} passes every glob. */
+declare function matchIngestTypes(items: readonly {
+    mime: string;
+}[], types: string[] | undefined): boolean;
+
 /**
  * Whether this is an Apple platform, where `mod` means the Command key and
  * not Ctrl. iPhone and iPad count: with a keyboard attached their shortcuts
@@ -1047,6 +979,28 @@ declare function matchSpec(e: InputEvent, spec: GestureSpec, isMac: boolean, pha
  */
 declare function isApplePlatform(): boolean;
 
+/**
+ * The nearest element `from` sits inside that can host a portalled overlay,
+ * or `null` when there is none and the body is the only answer.
+ */
+declare function nearestPortalHost(from: Element | null | undefined): HTMLElement | null;
+/**
+ * Where a `position: fixed` element following the pointer mounts: `host`, and
+ * the client-space point its `left: 0; top: 0` lands on.
+ */
+interface FixedSeat {
+    host: HTMLElement;
+    left: number;
+    top: number;
+}
+/**
+ * The seat for something drawn at a client-space point on behalf of `from`, a
+ * drag ghost above all: the nearest portal host, so it resolves the theme
+ * `from` is drawn in, or the body. Subtract `left` and `top` from the client
+ * point to place it.
+ */
+declare function fixedSeat(from: Element | null | undefined): FixedSeat;
+
 /** CSS-style specificity tuple for a GestureSpec. Higher tuple wins under
  *  lexicographic compare. Dimensions, in order of precedence:
  *
@@ -1058,14 +1012,14 @@ declare function isApplePlatform(): boolean;
  *                 non-empty `types` MIME filter, else 1.
  *
  *  Identical tuples fall back to registration order in the matcher's
- *  stable sort, preserving the pre-specificity tiebreaker. */
+ *  stable sort. */
 declare function specificity(spec: GestureSpec): readonly [number, number, number, number];
 
 /**
  * How far, in CSS pixels, a press must travel before it is a drag rather than
- * a click. `drag` specs match only past it: routing's `useGestureDispatcher`
- * holds a pointerdown back until the pointer crosses it, so a press-and-release
- * that stays under it never opens a drag.
+ * a click. `drag` specs match only past it: the pointer recognizer holds a
+ * pointerdown back until the pointer crosses it, so a press-and-release that
+ * stays under it never opens a drag.
  */
 declare const DRAG_THRESHOLD_PX = 4;
 /** Whether a pointer that went down at `from` has travelled far enough, by
@@ -1078,6 +1032,214 @@ declare function pastDragThreshold(from: {
     clientY: number;
 }, threshold?: number): boolean;
 
+/**
+ * The times and distances that tell one pointer gesture from another. The
+ * drag threshold sits with its helper in `ui/dragThreshold.ts`.
+ */
+/** How long a touch or pen press is held before it fires `longPress`, in ms. */
+declare const LONG_PRESS_MS = 500;
+/** The longest gap between two clicks that still makes a double click, in ms:
+ *  the upper end of OS double-click settings. */
+declare const DOUBLE_CLICK_MAX_MS = 600;
+/** How far apart, in CSS pixels, two clicks may land and still make a double
+ *  click: the drift of a real mouse or trackpad between them. */
+declare const DOUBLE_CLICK_MAX_PX = 8;
+/** How far, in CSS pixels, a finger or the centroid of a multitouch gesture
+ *  may travel before the gesture stops being a tap. */
+declare const TAP_THRESHOLD_PX = 8;
+
+/** A position in whatever space the recognizer's `positionOf` reports. */
+interface Point {
+    x: number;
+    y: number;
+}
+/** Where two or more pointers sit: what `multiTouchGeometry` reads from their positions. */
+interface MultiTouchGeometry {
+    centroid: Point;
+    /** Distance between the first two pointers. */
+    spread: number;
+    /** Direction from the first pointer to the second, in degrees in (-180, 180],
+     *  growing clockwise on screen. */
+    angle: number;
+}
+/** Every pointer's centroid, and the first two's spread and angle. All zero with fewer than 2 pointers. */
+declare function multiTouchGeometry(positions: Iterable<Point>): MultiTouchGeometry;
+
+/**
+ * What the recognizer remembers of a press, and the events a release or a
+ * hold on it synthesizes.
+ */
+
+/** Press-time state replayed onto a synthesized click, long-press or
+ *  contextmenu, whose matchers resolve targets against it. */
+interface PressFacts extends EventModifiers {
+    target: unknown;
+    clientX: number;
+    clientY: number;
+    /** World-space press point, forwarded onto the synthesized click as
+     *  `pressX`/`pressY` — see `ClickEvent`. */
+    worldX: number;
+    worldY: number;
+    affordance?: unknown;
+    bodyTarget?: BodyTarget;
+    bodyKind?: BodyKind;
+}
+/** Where and how a press was released, for the click it turned out to be. */
+interface ReleaseFacts extends EventModifiers {
+    target: unknown;
+    clientX: number;
+    clientY: number;
+    worldX: number;
+    worldY: number;
+}
+/** A press released where it went down, as a click, and as the double click
+ *  it is when it follows another closely. Both happen at the release, with the
+ *  release's modifiers, on what the press landed on. */
+declare function clickEvents(down: PressFacts, up: ReleaseFacts): {
+    click: InputEvent;
+    doubleclick: InputEvent;
+};
+/** A held press as a long-press, and as the contextmenu it falls back to when
+ *  the long-press matches nothing. The fallback is what makes existing
+ *  `contextMenu` bindings reachable by touch with no consumer change. */
+declare function longPressEvents(down: PressFacts): {
+    longpress: InputEvent;
+    contextmenu: InputEvent;
+};
+
+/** A press released in place: its click, and the double click a second one makes. */
+
+/**
+ * The click a double click would follow. Held by the host rather than the
+ * recognizer when it has to outlive one: a host that rebuilds its recognizer
+ * between two clicks would otherwise drop the double click.
+ */
+interface ClickMemory {
+    last: {
+        t: number;
+        clientX: number;
+        clientY: number;
+    } | null;
+}
+/** Told of clicks without competing for them, as a binding would. */
+interface ClickObserver {
+    /** After the click was dispatched, so whatever its binding changed is readable. */
+    click?(world: Point): void;
+    /** Before the double click is dispatched, whichever binding then handles it. */
+    doubleClick?(world: Point): void;
+}
+/** What a release composed. `doubleClick` is absent unless one was dispatched. */
+interface ReleaseOutcome {
+    doubleClick?: 'handled' | 'unhandled';
+}
+
+/** The one press being timed toward a long-press. */
+
+/** A clock and a timer, so a host or a test supplies its own. */
+interface RecognizerClock {
+    now(): number;
+    setTimer(fn: () => void, ms: number): unknown;
+    clearTimer(timer: unknown): void;
+}
+/** A press held toward a long-press. */
+interface HeldPress {
+    pointerId: number;
+    /** A mouse never arms one. */
+    pointerType: 'touch' | 'pen';
+    press: PressFacts;
+    /** `RecognizerClock.now()` when the hold started. */
+    startedAt: number;
+    /** How long the hold must last before the long-press fires, in ms. */
+    duration: number;
+}
+
+/**
+ * What a host feeds the pointer recognizer, one per pointer event, and the
+ * pump events each becomes.
+ */
+
+/** One pointer event, in client space. */
+interface PointerSample extends EventModifiers, PointerSampleStylus {
+    pointerId: number;
+    clientX: number;
+    clientY: number;
+    /** What the originating event was aimed at. */
+    target?: unknown;
+}
+/** A pointer going down, with what the host found under it. */
+interface PressSample extends PointerSample {
+    /** The world point the host hit-tested at. */
+    x: number;
+    y: number;
+    /** `PointerEvent.pointerType`. Only `'touch'` and `'pen'` arm a long-press. */
+    pointerType: string;
+    affordance?: unknown;
+    bodyTarget?: BodyTarget;
+    bodyKind?: BodyKind;
+}
+
+/**
+ * Turns pointer samples into the gestures they add up to: a press, the drag
+ * it becomes past the threshold, the click it is when released in place, the
+ * double click two of those make, a long-press, and multitouch.
+ *
+ * It decides with its sink's answers, so it is not a pure function of its
+ * input: a long-press only spends its press when something handled it.
+ */
+
+/** Where recognized events go. */
+interface RecognizerSink {
+    dispatch(ev: InputEvent): 'handled' | 'unhandled';
+    /** Whether a multitouch gesture of `fingers` fingers is running, to be pumped. */
+    multiTouchInFlight(fingers: number): boolean;
+}
+/** What a host hears about beyond the events themselves, to drive press feedback. */
+interface RecognizerObserver extends ClickObserver {
+    /** The press being held toward a long-press, or `null` once it fires or is abandoned. */
+    holdChanged?(pending: HeldPress | null): void;
+    /** A long-press something handled, as itself or as its contextmenu fallback. */
+    longPress?(pointerType: 'touch' | 'pen'): void;
+}
+/** What {@link createPointerRecognizer} needs from its host. */
+interface PointerRecognizerOptions {
+    sink: RecognizerSink;
+    clock: RecognizerClock;
+    /**
+     * Client point to world point; the identity by default. Asked as each event
+     * is built rather than once per sample: an event dispatched earlier in the
+     * same sample, a pinch step say, may have moved the view.
+     */
+    toWorld?: (clientX: number, clientY: number) => Point;
+    /** Client point to the space a multitouch centroid is reported in. The identity by default. */
+    toSurface?: (client: Point) => Point;
+    /** Long-press hold time in ms, read at each press. Default `LONG_PRESS_MS`. */
+    longPressMs?: () => number | undefined;
+    clicks?: ClickMemory;
+    observer?: RecognizerObserver;
+}
+/** A recognizer for one surface. Its host feeds it every pointer sample the surface receives. */
+interface PointerRecognizer {
+    press(sample: PressSample): void;
+    /** A move of any pointer, held or not. */
+    move(sample: PointerSample): void;
+    release(sample: PointerSample): ReleaseOutcome;
+    /** A held pointer ended without a release. */
+    cancel(pointerId: number): void;
+    /**
+     * Whether a touch or pen that armed a long-press is still held. One still
+     * pending fires here, ahead of its timer: a platform that reports the hold
+     * itself is reporting the same one.
+     */
+    takeHold(): boolean;
+    heldCount(): number;
+    /** A held pointer's latest client position. */
+    positionOf(pointerId: number): Point | undefined;
+    /** Forget every held pointer and stop timing, dispatching nothing. */
+    reset(): void;
+}
+/** Build a recognizer holding no pointers. It touches no DOM: time and timers come from `opts.clock`. */
+declare function createPointerRecognizer(opts: PointerRecognizerOptions): PointerRecognizer;
+
 /** Elements that handle their own press and keys. */
 declare const CONTROL_SELECTOR: string;
 /**
@@ -1088,4 +1250,22 @@ declare const CONTROL_SELECTOR: string;
  */
 declare function isInControlWithin(target: EventTarget | null, host: Element): boolean;
 
-export { ACTIVE_SIGILS, type BodyClassification, type BodyKind, type BodyTarget, CONTROL_SELECTOR, type ChannelRef, type ClaimableGesture, type ClickEvent, type ClickSpec, type ContextMenuEvent, type ContextMenuSpec, DRAG_THRESHOLD_PX, type DescribeRouteOptions, type DoubleClickEvent, type DoubleClickSpec, type DragSpec, type DropEvent, type DropSpec, type EventModifiers, GESTURE_DESCRIPTORS, type GestureArgSpec, type GestureDescriptor, type GestureName, type GestureSpec, type IngestItem, type InputEvent, type KeyEvent, type KeyHeldEvent, type KeyHeldSpec, type KeySpec, type LongPressEvent, type LongPressSpec, MOD_NAME_SET, type ModRequirement, type ModSpec, type ModifierCombo, type ModifierKey, type ModifiersEvent, type MultiTouchEvent, type MultiTouchSpec, type MultiTouchTapEvent, type MultiTouchTapSpec, type OptionalMod, type ParsedKeyRoute, type ParsedModifiers, type ParsedRoute, type PasteEvent, type PasteSpec, type PhaseAtom, type PhaseContext, type PhaseSpec, type PinchEvent, type PinchSpec, type PointerCancelEvent, type PointerDownEvent, type PointerDownSpec, type PointerIdentity, type PointerMoveEvent, type PointerSampleStylus, type PointerUpEvent, RESERVED_ID_NAMES, RESERVED_ID_PREFIXES, RESERVED_SIGILS, ROUTE_FIELD_DEFINITIONS, ROUTE_TERMS, type RouteDescriptionPart, type RouteFieldName, type RoutePhase, type RouteTermLabel, type TargetPredicate, type TargetSpec, type TargetSpecForm, VALID_MOD_NAMES, type WheelEvent, type WheelSpec, bodyPredicate, canonicalModifiers, collapseShiftPairs, describeRoute, describeRouteParts, formatKeyRoute, formatPhaseAtom, formatRoute, getGestureDescriptor, hitPredicate, isApplePlatform, isInControlWithin, isKnownGestureName, keyRouteToSpec, matchIngestTypes, matchKey, matchModifiers, matchPhase, matchSpec, matchTarget, mimeMatchesGlob, modifierComboToParsed, mods, parseKeyRoute, parseRoute, parseTargetSpec, pastDragThreshold, routeGestureForSpecKind, routeToSpec, specKindForRouteGesture, specificity };
+/** Returns true when the target takes typed text: an input, a textarea, or a contenteditable element. */
+declare function isEditableTarget(target: EventTarget | null): boolean;
+/**
+ * True when `e` is Space or Enter on a focused control those keys activate — a
+ * button, a link, a checkbox. The key is that control's, so a page-level
+ * listener that claims it cancels the control's own activation.
+ */
+declare function activatesFocusedControl(e: KeyboardEvent): boolean;
+/**
+ * True when the key `e` reports belongs to the control it was typed on: Space
+ * or Enter on anything those activate, and a `<select>`'s type-ahead
+ * characters and navigation keys. A select claims nothing else, so Delete,
+ * Escape, and every modifier chord typed on one are still a page-level
+ * listener's to take. A text field is {@link isEditableTarget}'s question,
+ * since it owns every key.
+ */
+declare function focusedControlOwnsKey(e: KeyboardEvent): boolean;
+
+export { ACTIVE_SIGILS, type BodyClassification, type BodyKind, type BodyTarget, CONTROL_SELECTOR, type ChannelRef, type ClaimableGesture, type ClickEvent, type ClickMemory, type ClickObserver, type ClickSpec, type ContextMenuEvent, type ContextMenuSpec, DOUBLE_CLICK_MAX_MS, DOUBLE_CLICK_MAX_PX, DRAG_THRESHOLD_PX, type DescribeRouteOptions, type DoubleClickEvent, type DoubleClickSpec, type DragSpec, type DropEvent, type DropSpec, type EventModifiers, type FixedSeat, GESTURE_DESCRIPTORS, type GestureArgSpec, type GestureDescriptor, type GestureName, type GestureSpec, type HeldPress, type HoverEvent, type HoverSpec, type IngestItem, type InputEvent, type KeyEvent, type KeyHeldEvent, type KeyHeldSpec, type KeySpec, LONG_PRESS_MS, type LongPressEvent, type LongPressSpec, MOD_NAME_SET, type ModRequirement, type ModSpec, type ModifierCombo, type ModifierKey, type ModifiersEvent, type MultiTouchEvent, type MultiTouchGeometry, type MultiTouchSpec, type MultiTouchTapEvent, type MultiTouchTapSpec, type OptionalMod, type ParsedKeyRoute, type ParsedModifiers, type ParsedRoute, type PasteEvent, type PasteSpec, type PhaseAtom, type PhaseContext, type PhaseSpec, type PinchEvent, type PinchSpec, type Point, type PointerCancelEvent, type PointerDownEvent, type PointerDownSpec, type PointerIdentity, type PointerMoveEvent, type PointerRecognizer, type PointerRecognizerOptions, type PointerSample, type PointerSampleStylus, type PointerUpEvent, type PressFacts, type PressSample, RESERVED_ID_NAMES, RESERVED_ID_PREFIXES, RESERVED_SIGILS, ROUTE_FIELD_DEFINITIONS, ROUTE_TERMS, type RecognizerClock, type RecognizerObserver, type RecognizerSink, type ReleaseFacts, type ReleaseOutcome, type RouteDescriptionPart, type RouteFieldName, type RoutePhase, type RouteTermLabel, TAP_THRESHOLD_PX, type TargetPredicate, type TargetSpec, type TargetSpecForm, UNKNOWN_MIME, VALID_MOD_NAMES, type WheelEvent, type WheelSpec, activatesFocusedControl, bodyPredicate, canonicalModifiers, clickEvents, collapseShiftPairs, createPointerRecognizer, describeRoute, describeRouteParts, fixedSeat, focusedControlOwnsKey, formatKeyRoute, formatPhaseAtom, formatRoute, getGestureDescriptor, hitPredicate, isApplePlatform, isEditableTarget, isInControlWithin, isKnownGestureName, keyRouteToSpec, longPressEvents, matchIngestTypes, matchKey, matchModifiers, matchPhase, matchSpec, matchTarget, mimeMatchesGlob, modifierComboToParsed, mods, multiTouchGeometry, nearestPortalHost, parseKeyRoute, parseRoute, parseTargetSpec, pastDragThreshold, routeGestureForSpecKind, routeToSpec, specKindForRouteGesture, specificity, stylusOf };