@weasel-js/gestures 1.10.0 → 1.11.0

package/README.md

@@ -1,10 +1,13 @@
 # @weasel-js/gestures
 
-Pure gesture taxonomy, route grammars, and matcher primitives. No React, no DOM, no scene.
+The vocabulary weasel uses to say which user input fires what, and the pure
+functions that decide whether an input matches. It has no React, no scene, and
+no dependencies, so it can run in a test, a worker, or a host that is not
+weasel at all.
 
 Part of [weasel](https://github.com/orochi235/weasel), a domain-agnostic 2D
 scene-graph canvas kit for React. See the
-[API reference](https://orochi235.github.io/weasel/api/).
+[API reference](https://orochi235.github.io/weasel/#pkg/gestures).
 
 ## Install
 
@@ -12,12 +15,111 @@ scene-graph canvas kit for React. See the
 npm install @weasel-js/gestures
 ```
 
-## Usage
+## Terms
+
+These words have fixed meanings across weasel:
+
+- A **gesture** is a form of input: a click, a drag, a wheel turn, a keystroke,
+  a pinch, a file dropped on the canvas.
+- An **action** is a user-intent operation: move, delete, zoom in.
+- An **interaction** is a gesture bound to an action: "shift-click on empty
+  canvas adds to the selection".
+
+This package covers the gesture side only. It describes gestures, recognizes
+them from raw pointer input, and matches them against descriptions. Actions,
+and the dispatcher that runs the action a matched gesture is bound to, live in
+other weasel packages.
+
+## What is in it
+
+### Describing a gesture
+
+A `GestureSpec` is an object describing one gesture a binding listens for:
+its `kind` (`'click'`, `'drag'`, `'key'`, `'wheel'`, and so on), and optionally
+the modifier keys that must be held, what the pointer must be over, and the
+phase the owning tool must be in.
+
+A **route** is the same description as a string, short enough to write inline
+and to show in a shortcut list: `[initial] click => empty +shift`.
+
+`parseRoute` turns a route into a `ParsedRoute`, `formatRoute` writes the
+canonical string back, `routeToSpec` converts a parsed route into the
+`GestureSpec` the matcher takes, and `describeRoute` renders it as an English
+sentence. `GESTURE_DESCRIPTORS` is the table of gesture names the grammar
+accepts, with whether each takes a target and what argument it carries.
+
+### Matching input against a description
+
+An `InputEvent` is one normalized input: a union keyed by `kind`, each arm
+carrying the modifier state and whatever that kind of input reports.
+
+`matchSpec(event, spec, isMac)` returns whether an event satisfies a spec.
+Its parts are exported too: `matchModifiers`, `matchKey`, `matchTarget`, and
+`matchPhase`. When several specs match one event, `specificity(spec)` gives a
+tuple to rank them by, so the narrower description wins.
+
+### Recognizing gestures from pointer input
+
+`createPointerRecognizer` turns a stream of pointer presses, moves, and
+releases into `InputEvent`s. It decides when a press has moved far enough to be
+a drag, when a release in place is a click, when two clicks make a double
+click, when a held touch is a long-press, and when several pointers form a
+multitouch gesture. It touches no DOM: the host feeds it samples and supplies
+the clock, and it hands each recognized event to a sink the host provides.
+
+The thresholds it uses are exported as constants: `DRAG_THRESHOLD_PX`,
+`LONG_PRESS_MS`, `DOUBLE_CLICK_MAX_MS`, `DOUBLE_CLICK_MAX_PX`, and
+`TAP_THRESHOLD_PX`.
+
+### How they fit together
+
+| From | Through | To |
+|---|---|---|
+| Pointer samples | `createPointerRecognizer` | `InputEvent` |
+| Route string | `parseRoute`, then `routeToSpec` | `GestureSpec` |
+| `InputEvent` and `GestureSpec` | `matchSpec` | `true` or `false` |
+
+A host listens to the DOM, feeds pointer samples to a recognizer, and builds
+key, wheel, and drop events itself. Each binding carries a `GestureSpec`,
+written directly or parsed from a route. For every event, the host asks
+`matchSpec` which bindings apply, ranks them with `specificity`, and runs the
+winner's action.
+
+The package also exports a few helpers a host needs while doing this:
+`isApplePlatform` to decide what the `mod` modifier means, and
+`isEditableTarget`, `focusedControlOwnsKey`, and `isInControlWithin` to leave
+keys and presses alone when they belong to a text field or a button.
+
+## Example
+
+Parse a route, turn it into a spec, and test an event against it:
 
 ```ts
-import { /* … */ } from '@weasel-js/gestures';
+import {
+  describeRoute, matchSpec, parseRoute, routeToSpec, type InputEvent,
+} from '@weasel-js/gestures';
+
+const route = parseRoute('[*:*] click => empty +shift');
+const spec = routeToSpec(route);
+// { kind: 'click', target: 'empty', mods: { shift: true } }
+
+const shiftClick: InputEvent = {
+  kind: 'click',
+  bodyTarget: 'empty',
+  altKey: false, ctrlKey: false, metaKey: false, shiftKey: true,
+};
+
+matchSpec(shiftClick, spec, false);                       // true
+matchSpec({ ...shiftClick, shiftKey: false }, spec, false); // false: shift is required
+
+describeRoute(parseRoute('[initial] drag +mod ?shift'));
+// 'Fires when the user Mod-drags anywhere, while the tool is idle (Shift optional).'
 ```
 
+Modifier matching is strict. A modifier the spec does not mention must not be
+held, so a spec for plain `click` does not match a shift-click. Mark a modifier
+`?shift` in a route, or `shift: 'optional'` in a spec, to accept it either way.
+
 ## License
 
 MIT

package/dist/index.d.ts

@@ -1,3 +1,5 @@
+import { MenuShortcut } from '@weasel-js/menu';
+
 /**
  * Declarative gesture taxonomy. Single source of truth for:
  *   - which gestures hit-test (have a `.target` slot in the route string)
@@ -7,7 +9,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' | 'hover' | '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' | 'carry' | 'paste';
 /**
  * Gesture kinds an affordance claim can bar, in the spec vocabulary bindings
  * are written in. `'pointer'` is one token because `pointerDown` / `click` /
@@ -338,6 +340,11 @@ interface PointerDownSpec {
  * 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.
  *
+ * With `motion: 'leave'` it fires instead when the pointer passes out of what
+ * the binding targets: onto something its `target` does not match, or off the
+ * surface. With no `target` that is the whole surface. Its params are the
+ * move's that took the pointer out, or the last move's before it left the surface.
+ *
  * 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
@@ -346,6 +353,7 @@ interface PointerDownSpec {
  */
 interface HoverSpec {
     kind: 'hover';
+    motion?: 'move' | 'leave';
     target?: TargetSpec;
     mods?: ModSpec;
     phase?: PhaseSpec;
@@ -391,6 +399,24 @@ interface DropSpec {
     mods?: ModSpec;
     phase?: PhaseSpec;
 }
+/**
+ * A press that began elsewhere on the page, carried over the canvas: a palette
+ * item dragged in, a row dragged out of a list. The in-app sibling of
+ * {@link DropSpec}, which is the OS's drag. A carry is begun with `startCarry`.
+ * `types` filters by the payload's `type`, as globs; omitted or empty matches
+ * any carry.
+ *
+ * An ongoing action bound here starts when the carry comes over the surface:
+ * its moves update it, the release commits it, and leaving the surface or
+ * canceling the press cancels it. An immediate action fires once, on the
+ * release.
+ */
+interface CarrySpec {
+    kind: 'carry';
+    types?: string[];
+    mods?: ModSpec;
+    phase?: PhaseSpec;
+}
 /** System-clipboard paste of external content. Same `types` semantics as
  *  {@link DropSpec} — omitted or empty = matches any paste. */
 interface PasteSpec {
@@ -400,7 +426,7 @@ interface PasteSpec {
     phase?: PhaseSpec;
 }
 /** 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;
+type GestureSpec = KeySpec | KeyHeldSpec | WheelSpec | PinchSpec | ClickSpec | DoubleClickSpec | ContextMenuSpec | DragSpec | PointerDownSpec | HoverSpec | LongPressSpec | MultiTouchSpec | MultiTouchTapSpec | DropSpec | CarrySpec | PasteSpec;
 
 /**
  * Mini-grammar for the `arg` slot of `keyDown` / `keyUp` routes.
@@ -441,7 +467,7 @@ declare function keyRouteToSpec(r: ParsedKeyRoute): KeySpec;
  * Wildcards become omitted fields: a `*` target, direction or MIME list, and a
  * `[*:*]` phase slot. `[*]` is `[&:*]`, which an ambient binding never
  * matches, so it stays a phase atom. A `keyDown` / `keyHeld` arg is read as a
- * key route, so `keyDown(z?shift)` yields `mods.shift: 'optional'`; a drop or
+ * key route, so `keyDown(z?shift)` yields `mods.shift: 'optional'`; a drop, carry, or
  * paste arg is a `|`-separated MIME list.
  *
  * Throws on a route no spec can express: `keyUp`, a key or finger-count
@@ -513,13 +539,6 @@ 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. */
-interface EventModifiers {
-    altKey: boolean;
-    ctrlKey: boolean;
-    metaKey: boolean;
-    shiftKey: boolean;
-}
 /**
  * Body-target classification from the scene hit-test. Populated by
  * `useGestureDispatcher` when a `classifyTarget` thunk is supplied to its
@@ -546,6 +565,28 @@ interface BodyClassification {
     /** Semantic kind of the hit body. Undefined on empty canvas, and undefined
      *  on a body whose kind the scene can't name — never guessed. */
     kind?: BodyKind;
+    /** The node classified. Matching ignores it. */
+    id?: string;
+    /** What a double-click at this point names, where that is not the body hit: the group a hit
+     *  member belongs to. A double click's targets match against it. Absent, the hit is named. */
+    doubleClick?: {
+        body: BodyTarget;
+        kind?: BodyKind;
+        id?: string;
+    };
+}
+/** The body a double-click names, as a press carries it to the double click it composes. */
+interface DoubleClickBody {
+    bodyTarget: BodyTarget;
+    bodyKind?: BodyKind;
+}
+
+/** Keyboard/pointer modifier flags carried by every {@link InputEvent} arm. */
+interface EventModifiers {
+    altKey: boolean;
+    ctrlKey: boolean;
+    metaKey: boolean;
+    shiftKey: boolean;
 }
 /** A keystroke. */
 interface KeyEvent extends EventModifiers {
@@ -741,9 +782,19 @@ interface ContextMenuEvent extends EventModifiers {
     bodyTarget?: BodyTarget;
     bodyKind?: BodyKind;
 }
-/** A move of a pointer with no button pressed. Matched by `hover` specs. */
+/** What a hover found under the pointer. */
+interface HoverWhere {
+    affordance?: unknown;
+    bodyTarget?: BodyTarget;
+    bodyKind?: BodyKind;
+}
+/** A move of a pointer with no button pressed, or its leaving the surface. Matched by `hover` specs. */
 interface HoverEvent extends EventModifiers {
     kind: 'hover';
+    /** What the pointer was over at its last move, when it has made one since coming onto the surface. */
+    from?: HoverWhere;
+    /** The pointer has left the surface. Where it is and what it is over are its last move's. */
+    off?: boolean;
     /** World-space position of the pointer. */
     x: number;
     y: number;
@@ -834,6 +885,21 @@ interface DropEvent extends EventModifiers {
     clientX?: number;
     clientY?: number;
 }
+/** A carry over the canvas (`startCarry`). `stage` is what it did here: came
+ *  over, moved, was released, or left — off the surface, or canceled on it. */
+interface CarryEvent extends EventModifiers {
+    kind: 'carry';
+    stage: 'enter' | 'move' | 'drop' | 'leave';
+    pointerId?: number;
+    /** The payload's type, which a spec's `types` globs filter, and the payload. */
+    type: string;
+    value: unknown;
+    /** World-space position (post view transform). */
+    x: number;
+    y: number;
+    clientX: number;
+    clientY: number;
+}
 /** External content pasted from the system clipboard. Carries no point. */
 interface PasteEvent extends EventModifiers {
     kind: 'paste';
@@ -848,7 +914,7 @@ interface PasteEvent extends EventModifiers {
  * The `affordance?` field on {@link PointerDownEvent} is widened to `unknown`
  * in this package — the kit narrows it back to `AffordanceHit` at consumption.
  */
-type InputEvent = KeyEvent | KeyHeldEvent | WheelEvent | PinchEvent | PointerDownEvent | PointerMoveEvent | HoverEvent | 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 | CarryEvent | PasteEvent;
 
 /**
  * The stylus fields `src` carries, as a spread-able partial: a sample that
@@ -856,29 +922,8 @@ type InputEvent = KeyEvent | KeyHeldEvent | WheelEvent | PinchEvent | PointerDow
  */
 declare function stylusOf(src: PointerSampleStylus): PointerSampleStylus;
 
-/** Pure gesture matcher — no React, no state, no DOM. */
+/** Target matching: a `TargetSpec` against what an event classified under its point. */
 
-/** The modifier-state fields `matchModifiers` reads. Structural, so a DOM
- *  `KeyboardEvent` or `PointerEvent` satisfies it directly. */
-type ModifiersEvent = {
-    altKey: boolean;
-    ctrlKey: boolean;
-    metaKey: boolean;
-    shiftKey: boolean;
-};
-/**
- * Strict modifier match.
- *
- * - 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:
@@ -932,6 +977,30 @@ declare function parseTargetSpec(spec: TargetSpec): TargetSpecForm | null;
  * silent wildcard.
  */
 declare function matchTarget(target: unknown, specTarget: TargetSpec | undefined, bodyTarget?: string, bodyKind?: string): boolean;
+
+/** 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. */
+type ModifiersEvent = {
+    altKey: boolean;
+    ctrlKey: boolean;
+    metaKey: boolean;
+    shiftKey: boolean;
+};
+/**
+ * Strict modifier match.
+ *
+ * - 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;
 /** 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
@@ -979,6 +1048,126 @@ declare function matchIngestTypes(items: readonly {
  */
 declare function isApplePlatform(): boolean;
 
+/** One key of a shortcut as a keyboard prints it. */
+interface KeyLegend {
+    /** Glyph drawn for the key (modifier or key). */
+    label: string;
+    /** When true, the key may be held but is not required to trigger the action
+     *  (e.g. an optional modifier). Defaults to false. */
+    optional?: boolean;
+}
+/** Logical modifier name. Matches the kit's `ModifierKey` in shape — kept as a
+ *  local type so `weasel-ui` stays independent of `@weasel-js/core`. */
+type LogicalMod = 'mod' | 'shift' | 'alt' | 'ctrl' | 'meta';
+/** Detected (or overridden) platform. `'mod'` resolves to ⌘ on macOS,
+ *  Ctrl on Windows / Linux. */
+type Platform = 'macos' | 'windows' | 'linux';
+/** Visual form of a modifier or named-key label.
+ *
+ *  - `'auto'` (default): the per-entry, per-platform default — whatever
+ *    label is actually printed on the physical key. macOS keys show the
+ *    Apple glyphs (⌘ ⌥ ⌃ ⇧ ⎋ ↵ ⇥). Windows keys mostly show text
+ *    (Ctrl, Alt, Shift) BUT the Win key shows its logo (⊞) and the
+ *    context-menu key shows ▤. Linux mirrors Windows with Super (⊞).
+ *  - `'symbol'` forces a glyph wherever the key has one: Apple's on macOS,
+ *    ISO/IEC 9995-7's elsewhere (⎈ Ctrl, ⎇ Alt, ⎋ Esc). A key with no
+ *    symbol still falls back to text.
+ *  - `'text'` always spells the label out (Cmd / Option / Esc / Enter). */
+type LegendStyle = 'auto' | 'symbol' | 'text';
+/** A modifier to render, named platform-independently. */
+interface LogicalModSpec {
+    name: LogicalMod;
+    /** Marks this modifier as optional (may be held but isn't required).
+     *  Forwarded as the resulting `KeyLegend.optional`. */
+    optional?: boolean;
+}
+/** Options for {@link keySpecsFromMods}. */
+interface KeySpecsFromModsOptions {
+    /** Override OS detection. Defaults to {@link detectPlatform}. */
+    platform?: Platform;
+    /** Defaults to `'auto'`. Pass `'symbol'` or `'text'` to force a specific
+     *  style regardless of platform. */
+    legend?: LegendStyle;
+    /** Labels that replace the platform and legend tables', by a modifier's
+     *  logical name (`mod`, `shift`, `alt`, `ctrl`, `meta`) or a key's
+     *  `KeyboardEvent.key` (`Escape`, `Home`, `z`): a whole keyboard's worth
+     *  for a layout, a locale, or a keyboard of one's own. */
+    labels?: KeyLabels;
+}
+/** Key labels by modifier name or `KeyboardEvent.key`. See {@link KeySpecsFromModsOptions.labels}. */
+type KeyLabels = Readonly<Record<string, string>>;
+/** Every label {@link keySpecsFromMods} can produce, on any platform and legend. */
+declare const MODIFIER_LABELS: ReadonlySet<string>;
+/** The platform whose key legends to draw. Whether `mod` is ⌘ comes from
+ *  `isApplePlatform`, the same read the dispatcher
+ *  matches `mod` with, so a keycap names the key that fires. With no
+ *  `navigator` (a server render) it answers `'macos'`, the kit's docs
+ *  convention; an unrecognized browser reads as `'linux'`. */
+declare function detectPlatform(): Platform;
+/**
+ * Map a list of **logical** modifiers (`'mod'`, `'shift'`, …) to **visual**
+ * `KeyLegend`s appropriate for the current platform — `'mod'` means "Cmd on
+ * Mac, Ctrl on Win/Linux".
+ *
+ * ```ts
+ * <KeySequence
+ *   keys={keySpecsFromMods([{ name: 'mod' }, { name: 'shift', optional: true }])}
+ * />
+ * ```
+ */
+declare function keySpecsFromMods(mods: readonly LogicalModSpec[], opts?: KeySpecsFromModsOptions): readonly KeyLegend[];
+/**
+ * Render a raw `KeyboardEvent.key` value as a platform-appropriate
+ * `KeyLegend`. Named non-modifier keys (Esc, Enter, Tab, Space, Backspace,
+ * Delete, arrows) get the platform's conventional form. Letter / digit /
+ * other keys pass through upper-cased.
+ *
+ * ```ts
+ * keySpecFromKey('Escape', { platform: 'macos' })   // { label: '⎋' }
+ * keySpecFromKey('Escape', { platform: 'windows' }) // { label: 'Esc' }
+ * keySpecFromKey('p')                               // { label: 'P' }
+ * ```
+ *
+ * Symbol mode off macOS draws ISO/IEC 9995-7's symbols where the key
+ * has one, though Windows and Linux keyboards print the text form.
+ */
+declare function keySpecFromKey(raw: string, opts?: KeySpecsFromModsOptions & {
+    optional?: boolean;
+}): KeyLegend;
+
+/** A keyboard shortcut as the formatters read it: `@weasel-js/menu`'s `MenuShortcut`. */
+type ShortcutInput = MenuShortcut;
+/** Options for {@link formatShortcut} and {@link formatShortcutParts}. */
+interface FormatShortcutOptions {
+    /** Defaults to the detected platform. */
+    platform?: Platform;
+}
+/** Format a shortcut as an array of display chips, one per key: the
+ *  modifiers, then the key, each as the platform's keyboard prints it, so
+ *  `mod` is `⌘` on macOS and `Ctrl` elsewhere. UIs that want a boxed per-key
+ *  look render each chip in its own element. `shift: 'optional'` is treated
+ *  as falsy. */
+declare function formatShortcutParts(b: ShortcutInput | undefined, opts?: FormatShortcutOptions): readonly string[] | undefined;
+/** Format a shortcut as a single display string. Order: mod, shift, alt,
+ *  key. On macOS the glyphs run together (`⌘⇧Z`); elsewhere the keys are
+ *  spelled out and joined with `+` (`Ctrl+Shift+Z`). Returns `undefined` for
+ *  `undefined` input so callers can `??` a fallback. When `key` is an array,
+ *  the first element is used. `shift: 'optional'` is treated as falsy. */
+declare function formatShortcut(b: ShortcutInput | undefined, opts?: FormatShortcutOptions): string | undefined;
+
+/**
+ * A shortcut as key legends, one per key, as `@weasel-js/ui`'s `KeySequence` draws them: mod, shift, alt, then the
+ * key, each in the platform's own legend (`⌘` on macOS, `Ctrl` elsewhere).
+ * `formatShortcutParts` is these labels as strings. `shift: 'optional'`
+ * becomes an optional key; a key list
+ * renders its first key. Returns `undefined` for no shortcut.
+ *
+ * ```tsx
+ * <KeySequence keys={keySpecsFromShortcut({ key: 'z', mod: true, shift: true })} />
+ * ```
+ */
+declare function keySpecsFromShortcut(shortcut: ShortcutInput | undefined, opts?: KeySpecsFromModsOptions): readonly KeyLegend[] | undefined;
+
 /**
  * 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.
@@ -1008,7 +1197,7 @@ declare function fixedSeat(from: Element | null | undefined): FixedSeat;
  *    [1] mods   — count of required modifier keys (shift/alt/ctrl/meta/mod).
  *                 `'optional'` does NOT count.
  *    [2] phase  — how much the spec's `phase` narrows; see `phaseRank`.
- *    [3] exact  — per-kind tiebreak: 2 for a drop/paste spec with a
+ *    [3] exact  — per-kind tiebreak: 2 for a drop/carry/paste spec with a
  *                 non-empty `types` MIME filter, else 1.
  *
  *  Identical tuples fall back to registration order in the matcher's
@@ -1083,6 +1272,8 @@ interface PressFacts extends EventModifiers {
     affordance?: unknown;
     bodyTarget?: BodyTarget;
     bodyKind?: BodyKind;
+    /** Replayed onto the double click in place of `bodyTarget` and `bodyKind`. */
+    doubleClickBody?: DoubleClickBody;
 }
 /** Where and how a press was released, for the click it turned out to be. */
 interface ReleaseFacts extends EventModifiers {
@@ -1176,6 +1367,8 @@ interface PressSample extends PointerSample {
     affordance?: unknown;
     bodyTarget?: BodyTarget;
     bodyKind?: BodyKind;
+    /** What a double click this press completes lands on, where not the body hit. */
+    doubleClickBody?: DoubleClickBody;
 }
 
 /**
@@ -1214,6 +1407,14 @@ interface PointerRecognizerOptions {
     toSurface?: (client: Point) => Point;
     /** Long-press hold time in ms, read at each press. Default `LONG_PRESS_MS`. */
     longPressMs?: () => number | undefined;
+    /** Longest gap in ms between two clicks of a double click, read at each click. Default `DOUBLE_CLICK_MAX_MS`. */
+    doubleClickMs?: () => number | undefined;
+    /** Farthest two clicks of a double click may land apart, in CSS px. Default `DOUBLE_CLICK_MAX_PX`. */
+    doubleClickPx?: () => number | undefined;
+    /** Farthest a multitouch tap's fingers may travel, in CSS px. Default `TAP_THRESHOLD_PX`. */
+    tapPx?: () => number | undefined;
+    /** Travel in CSS px that makes a press a drag, read at each move. Default `DRAG_THRESHOLD_PX`. */
+    dragPx?: () => number | undefined;
     clicks?: ClickMemory;
     observer?: RecognizerObserver;
 }
@@ -1250,6 +1451,22 @@ declare const CONTROL_SELECTOR: string;
  */
 declare function isInControlWithin(target: EventTarget | null, host: Element): boolean;
 
+/**
+ * Which pointers are down on an element: pressed on it or inside it, with any
+ * button, and not yet released. The one answer to "is this move a hover" for
+ * everything listening on that element.
+ */
+interface HeldPointers {
+    count(): number;
+    /** Stop reading. The element's listeners go with its last reader. */
+    release(): void;
+}
+/**
+ * Read the pointers held on `element`. Every reader of one element shares one
+ * set of listeners, so they cannot disagree.
+ */
+declare function heldPointers(element: Element): HeldPointers;
+
 /** Returns true when the target takes typed text: an input, a textarea, or a contenteditable element. */
 declare function isEditableTarget(target: EventTarget | null): boolean;
 /**
@@ -1268,4 +1485,4 @@ declare function activatesFocusedControl(e: KeyboardEvent): boolean;
  */
 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 };
+export { ACTIVE_SIGILS, type BodyClassification, type BodyKind, type BodyTarget, CONTROL_SELECTOR, type CarryEvent, type CarrySpec, 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 DoubleClickBody, type DoubleClickEvent, type DoubleClickSpec, type DragSpec, type DropEvent, type DropSpec, type EventModifiers, type FixedSeat, type FormatShortcutOptions, GESTURE_DESCRIPTORS, type GestureArgSpec, type GestureDescriptor, type GestureName, type GestureSpec, type HeldPointers, type HeldPress, type HoverEvent, type HoverSpec, type HoverWhere, type IngestItem, type InputEvent, type KeyEvent, type KeyHeldEvent, type KeyHeldSpec, type KeyLabels, type KeyLegend, type KeySpec, type KeySpecsFromModsOptions, LONG_PRESS_MS, type LegendStyle, type LogicalMod, type LogicalModSpec, type LongPressEvent, type LongPressSpec, MODIFIER_LABELS, 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 Platform, 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, type ShortcutInput, 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, detectPlatform, fixedSeat, focusedControlOwnsKey, formatKeyRoute, formatPhaseAtom, formatRoute, formatShortcut, formatShortcutParts, getGestureDescriptor, heldPointers, hitPredicate, isApplePlatform, isEditableTarget, isInControlWithin, isKnownGestureName, keyRouteToSpec, keySpecFromKey, keySpecsFromMods, keySpecsFromShortcut, longPressEvents, matchIngestTypes, matchKey, matchModifiers, matchPhase, matchSpec, matchTarget, mimeMatchesGlob, modifierComboToParsed, mods, multiTouchGeometry, nearestPortalHost, parseKeyRoute, parseRoute, parseTargetSpec, pastDragThreshold, routeGestureForSpecKind, routeToSpec, specKindForRouteGesture, specificity, stylusOf };