@weasel-js/gestures 1.10.0 → 1.10.1

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

@@ -338,6 +338,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 +351,7 @@ interface PointerDownSpec {
  */
 interface HoverSpec {
     kind: 'hover';
+    motion?: 'move' | 'leave';
     target?: TargetSpec;
     mods?: ModSpec;
     phase?: PhaseSpec;
@@ -741,9 +747,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;
@@ -856,29 +872,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 +927,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
@@ -1250,6 +1269,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 +1303,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 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 HeldPointers, type HeldPress, type HoverEvent, type HoverSpec, type HoverWhere, 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, heldPointers, 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 };

package/dist/index.js

@@ -2,7 +2,7 @@
 var GESTURE_DESCRIPTORS = [
   { name: "click", hasTarget: true },
   { name: "pointerDown", hasTarget: true },
-  { name: "hover", hasTarget: true },
+  { name: "hover", hasTarget: true, arg: { name: "motion", values: ["move", "leave"], default: "move" } },
   { name: "dblTap", hasTarget: true },
   { name: "drag", hasTarget: true },
   { name: "wheel", hasTarget: true, arg: { name: "direction", values: ["up", "down", "*"], default: "*" } },
@@ -286,47 +286,7 @@ function matchIngestTypes(items, types) {
   return items.some((it) => it.mime === UNKNOWN_MIME || types.some((g) => mimeMatchesGlob(it.mime, g)));
 }
 
-// src/ui/match.ts
-function resolveSpecValue(value) {
-  if (value === true) return "required";
-  if (value === "optional") return "optional";
-  return "forbidden";
-}
-function matchModifiers(e, mods2, isMac) {
-  let alt = "forbidden";
-  let ctrl = "forbidden";
-  let meta = "forbidden";
-  let shift = "forbidden";
-  if (mods2) {
-    alt = resolveSpecValue(mods2.alt);
-    shift = resolveSpecValue(mods2.shift);
-    if (mods2.mod !== void 0) {
-      const modReq = resolveSpecValue(mods2.mod);
-      if (isMac) meta = modReq;
-      else ctrl = modReq;
-    } else {
-      meta = resolveSpecValue(mods2.meta);
-      ctrl = resolveSpecValue(mods2.ctrl);
-    }
-  }
-  return checkKey(alt, e.altKey) && checkKey(ctrl, e.ctrlKey) && checkKey(meta, e.metaKey) && checkKey(shift, e.shiftKey);
-}
-function checkKey(req, held) {
-  if (req === "required") return held;
-  if (req === "forbidden") return !held;
-  return true;
-}
-function matchKey(eventKey, specKey) {
-  const lower = eventKey.toLowerCase();
-  if (Array.isArray(specKey)) {
-    return specKey.some((k) => k.toLowerCase() === lower);
-  }
-  return specKey.toLowerCase() === lower;
-}
-function matchKeyOrCode(e, spec) {
-  if (spec.code !== void 0 && e.code !== void 0 && [spec.code].flat().includes(e.code)) return true;
-  return matchKey(e.key, spec.key);
-}
+// src/ui/matchTarget.ts
 function affordanceKindOf(target) {
   if (typeof target !== "object" || target === null) return void 0;
   const k = target.kind;
@@ -379,6 +339,48 @@ function matchTarget(target, specTarget, bodyTarget, bodyKind) {
     }
   }
 }
+
+// src/ui/match.ts
+function resolveSpecValue(value) {
+  if (value === true) return "required";
+  if (value === "optional") return "optional";
+  return "forbidden";
+}
+function matchModifiers(e, mods2, isMac) {
+  let alt = "forbidden";
+  let ctrl = "forbidden";
+  let meta = "forbidden";
+  let shift = "forbidden";
+  if (mods2) {
+    alt = resolveSpecValue(mods2.alt);
+    shift = resolveSpecValue(mods2.shift);
+    if (mods2.mod !== void 0) {
+      const modReq = resolveSpecValue(mods2.mod);
+      if (isMac) meta = modReq;
+      else ctrl = modReq;
+    } else {
+      meta = resolveSpecValue(mods2.meta);
+      ctrl = resolveSpecValue(mods2.ctrl);
+    }
+  }
+  return checkKey(alt, e.altKey) && checkKey(ctrl, e.ctrlKey) && checkKey(meta, e.metaKey) && checkKey(shift, e.shiftKey);
+}
+function checkKey(req, held) {
+  if (req === "required") return held;
+  if (req === "forbidden") return !held;
+  return true;
+}
+function matchKey(eventKey, specKey) {
+  const lower = eventKey.toLowerCase();
+  if (Array.isArray(specKey)) {
+    return specKey.some((k) => k.toLowerCase() === lower);
+  }
+  return specKey.toLowerCase() === lower;
+}
+function matchKeyOrCode(e, spec) {
+  if (spec.code !== void 0 && e.code !== void 0 && [spec.code].flat().includes(e.code)) return true;
+  return matchKey(e.key, spec.key);
+}
 function normalizePhase(spec) {
   if (typeof spec === "string") {
     return [{ channel: "&", phase: spec }];
@@ -406,6 +408,16 @@ function matchPhaseAtom(a, ctx) {
   const isEngaged = ctx.engagedChannels.has(id);
   return a.phase === "engaged" ? isEngaged : !isEngaged;
 }
+function matchPress(e, spec, isMac) {
+  if (e.kind !== "pointerdown") return false;
+  if (spec.kind === "drag") {
+    if (e.stage === "press") return false;
+  } else if (e.stage !== "press") {
+    return false;
+  }
+  if (!matchModifiers(e, spec.mods, isMac)) return false;
+  return matchTarget(e.affordance, spec.target, e.bodyTarget, e.bodyKind);
+}
 function matchSpec(e, spec, isMac, phaseCtx) {
   if (spec.phase !== void 0) {
     const ctx = phaseCtx ?? { selfChannel: null, engagedChannels: EMPTY_ENGAGED };
@@ -452,24 +464,22 @@ function matchSpec(e, spec, isMac, phaseCtx) {
     // Each happens at a point, so its target is what the event classified
     // there: for a long-press, the affordance its press landed on.
     case "contextMenu":
-    case "longPress":
-    case "hover": {
-      if (e.kind !== "contextmenu" && e.kind !== "longpress" && e.kind !== "hover") return false;
+    case "longPress": {
+      if (e.kind !== "contextmenu" && e.kind !== "longpress") return false;
       if (e.kind !== spec.kind.toLowerCase()) return false;
       if (!matchModifiers(e, spec.mods, isMac)) return false;
       return matchTarget(e.affordance, spec.target, e.bodyTarget, e.bodyKind);
     }
-    case "drag": {
-      if (e.kind !== "pointerdown") return false;
-      if (e.stage === "press") return false;
-      if (!matchModifiers(e, spec.mods, isMac)) return false;
-      return matchTarget(e.affordance, spec.target, e.bodyTarget, e.bodyKind);
-    }
-    case "pointerDown": {
-      if (e.kind !== "pointerdown" || e.stage !== "press") return false;
+    case "hover": {
+      if (e.kind !== "hover") return false;
       if (!matchModifiers(e, spec.mods, isMac)) return false;
-      return matchTarget(e.affordance, spec.target, e.bodyTarget, e.bodyKind);
+      const on = !e.off && matchTarget(e.affordance, spec.target, e.bodyTarget, e.bodyKind);
+      if (spec.motion !== "leave") return on;
+      return !on && e.from !== void 0 && matchTarget(e.from.affordance, spec.target, e.from.bodyTarget, e.from.bodyKind);
     }
+    case "drag":
+    case "pointerDown":
+      return matchPress(e, spec, isMac);
     case "multiTouch": {
       if (e.kind !== "multitouch") return false;
       if (e.fingers !== spec.fingers) return false;
@@ -557,9 +567,10 @@ function routeToSpec(parsed) {
   switch (kind) {
     case void 0:
       return fail(`${parsed.gesture} has no GestureSpec kind`);
+    case "hover":
+      return withMods({ kind, ...arg === "leave" ? { motion: "leave" } : {}, ...t });
     case "click":
     case "pointerDown":
-    case "hover":
     case "doubleClick":
     case "drag":
     case "contextMenu":
@@ -626,6 +637,10 @@ function partitionModifiers(mods2) {
   }
   return { required, optional };
 }
+function leftClause(target) {
+  if (target === void 0 || target === "*") return "off the surface";
+  return target === "empty" ? "off empty canvas" : `off a ${target}`;
+}
 function phaseAtomParts({ channel, phase }) {
   const subject = channel === "&" ? "the tool" : channel === "*" ? "any tool" : `the ${channel} tool`;
   if (phase === "initial") return [`${subject} is `, term("idle")];
@@ -688,7 +703,7 @@ function actionClause(parsed, required) {
     case "pointerDown":
       return userDoes(required, `presses${target}`);
     case "hover":
-      return userDoes(required, `moves the pointer${target}`);
+      return userDoes(required, arg === "leave" ? `moves the pointer ${leftClause(parsed.target)}` : `moves the pointer${target}`);
     case "dblTap":
       return userDoes(required, `double-taps${target}`);
     case "drag":
@@ -1172,6 +1187,65 @@ function isInControlWithin(target, host) {
   return control !== null && control !== host && host.contains(control);
 }
 
+// src/ui/heldPointers.ts
+var trackers = /* @__PURE__ */ new WeakMap();
+function attach(element) {
+  const doc = element.ownerDocument;
+  const win = doc.defaultView;
+  const held = /* @__PURE__ */ new Map();
+  const down = (e) => {
+    const p = e;
+    held.set(p.pointerId, !!p.buttons);
+  };
+  const up = (e) => {
+    held.delete(e.pointerId);
+  };
+  const move = (e) => {
+    const p = e;
+    if (held.get(p.pointerId) && p.buttons === 0) held.delete(p.pointerId);
+  };
+  const blur = () => {
+    held.clear();
+  };
+  element.addEventListener("pointerdown", down, true);
+  doc.addEventListener("pointerup", up, true);
+  doc.addEventListener("pointercancel", up, true);
+  doc.addEventListener("pointermove", move, true);
+  win?.addEventListener("blur", blur);
+  return {
+    readers: 0,
+    held,
+    detach() {
+      element.removeEventListener("pointerdown", down, true);
+      doc.removeEventListener("pointerup", up, true);
+      doc.removeEventListener("pointercancel", up, true);
+      doc.removeEventListener("pointermove", move, true);
+      win?.removeEventListener("blur", blur);
+    }
+  };
+}
+function heldPointers(element) {
+  let tracker = trackers.get(element);
+  if (!tracker) {
+    tracker = attach(element);
+    trackers.set(element, tracker);
+  }
+  const shared = tracker;
+  shared.readers += 1;
+  let released = false;
+  return {
+    count: () => shared.held.size,
+    release() {
+      if (released) return;
+      released = true;
+      shared.readers -= 1;
+      if (shared.readers > 0) return;
+      shared.detach();
+      if (trackers.get(element) === shared) trackers.delete(element);
+    }
+  };
+}
+
 // src/ui/keyOwner.ts
 function isEditableTarget(target) {
   if (!target || !(target instanceof Element)) return false;
@@ -1213,6 +1287,6 @@ function focusedControlOwnsKey(e) {
   return activatesFocusedControl(e) || selectOwnsKey(e);
 }
 
-export { ACTIVE_SIGILS, CONTROL_SELECTOR, DOUBLE_CLICK_MAX_MS, DOUBLE_CLICK_MAX_PX, DRAG_THRESHOLD_PX, GESTURE_DESCRIPTORS, LONG_PRESS_MS, MOD_NAME_SET, RESERVED_ID_NAMES, RESERVED_ID_PREFIXES, RESERVED_SIGILS, ROUTE_FIELD_DEFINITIONS, ROUTE_TERMS, TAP_THRESHOLD_PX, UNKNOWN_MIME, VALID_MOD_NAMES, 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, CONTROL_SELECTOR, DOUBLE_CLICK_MAX_MS, DOUBLE_CLICK_MAX_PX, DRAG_THRESHOLD_PX, GESTURE_DESCRIPTORS, LONG_PRESS_MS, MOD_NAME_SET, RESERVED_ID_NAMES, RESERVED_ID_PREFIXES, RESERVED_SIGILS, ROUTE_FIELD_DEFINITIONS, ROUTE_TERMS, TAP_THRESHOLD_PX, UNKNOWN_MIME, VALID_MOD_NAMES, activatesFocusedControl, bodyPredicate, canonicalModifiers, clickEvents, collapseShiftPairs, createPointerRecognizer, describeRoute, describeRouteParts, fixedSeat, focusedControlOwnsKey, formatKeyRoute, formatPhaseAtom, formatRoute, getGestureDescriptor, heldPointers, 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 };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map