@astryxdesign/core 0.7.5 → 0.7.6-canary.0135af4

package/dist/gestures/GestureHost.js

@@ -0,0 +1,1773 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file GestureHost.ts
+ * @input DOM touch, pointer, click, contextmenu, scroll and focus events of
+ *   one document; elements with recognizers and consumers attached, and
+ *   consumer types found by attribute
+ * @output Exports GestureHost (the DOM side of the gesture system),
+ *   getGestureHost (one host per document) and the delegated consumer type
+ * @position Browser adapter of packages/core/src/gestures: turns real events
+ *   into GestureArena input, and carries out what the arena decides
+ *
+ * FOR EVERY POINTER
+ *
+ * - Recognizers and press consumers attach for a mouse, a pen and a finger
+ *   alike (`spec:AST-094` FR43, FR19). Where the primary pointer is coarse
+ *   the host listens on the page while something enabled could take a
+ *   touch. Where it is fine, each element with an enabled recognizer or
+ *   consumer keeps one passive `pointerdown` listener and the page has none:
+ *   a press on it (a mouse's primary button, a pen, or a finger, whose
+ *   `pointerdown` comes before its `touchstart`) installs the host's page
+ *   listeners, which go once that press's contacts end; the click listener
+ *   alone stays through the swallower's window, for the click a claimed lift
+ *   owes (FR21, FR24). An element whose recognizer claims a moving finger
+ *   keeps its blocking `touchmove` under every pointer, a listener FR24
+ *   counts apart.
+ * - A right click, a pen's barrel button and a ctrl-click on macOS start no
+ *   press (primaryClick.ts).
+ * - The host follows the primary pointer (a tablet docking a mouse): turning
+ *   fine with no press held removes the page listeners and cancels every
+ *   touch in flight.
+ * - A delegated consumer type has no element to listen on: where the
+ *   primary pointer is fine, the document keeps one passive `pointerdown`
+ *   listener for every type, counted once per page (FR24).
+ *
+ * INPUT CHANNELS
+ *
+ * - Fingers begin and end with Touch Events: they are the only cancelable
+ *   channel (a pointer event's preventDefault cannot stop a scroll or a
+ *   click), they keep arriving after the browser takes a pan (which a scroll
+ *   handoff needs), and every event lists all the fingers at once. A
+ *   finger's movement comes from BOTH its `touchmove`s and its
+ *   `pointermove`s (paired at touchstart by target and position), the echo
+ *   of one in the other dropped: Chromium sends no `touchmove` until a
+ *   finger has travelled about 16 px, while a tap fails and a pan begins at
+ *   10.
+ * - A finger's events go to the element it landed on even after that
+ *   element leaves the document, and then never reach the document. Each
+ *   tracked finger's target therefore gets its own listeners, and a finger
+ *   the events say is no longer down is cancelled, so a re-rendered or
+ *   removed target never strands a gesture.
+ * - Mice and pens come from Pointer Events, with coalesced samples for
+ *   velocity. A pen on an iPad also produces `stylus` touches; those are left
+ *   to the pointer path.
+ * - `pointercancel` on a finger is the browser saying it took that finger
+ *   for its own pan or zoom; so is a `touchmove` that can no longer be
+ *   cancelled where `touch-action` let the browser pan, and a scroll above
+ *   the touch.
+ *
+ * WHAT THE BROWSER IS TOLD
+ *
+ * - Each element gets the `touch-action` its recognizers leave the browser
+ *   (touchAction.ts), set inline when they attach and restored when they
+ *   detach.
+ * - Each element with a recognizer that can claim a touch while it moves (a
+ *   pan, a swipe, a long press that then drags, a pinch) gets a
+ *   NON-passive `touchmove` listener that cancels the event only while a
+ *   recognizer owns one of its touches (a pan claims when it begins, at
+ *   UIKit's 10 pt, `spec:AST-094` FR17). Nothing else is ever cancelled, so a
+ *   touch nobody claims scrolls exactly as it would without the system. The
+ *   known cost: a scroll that BEGINS on such an element waits for a busy main
+ *   thread (measured in iOS Safari; a passive listener would hand every
+ *   diagonal to the scroll instead). Elements whose recognizers only claim
+ *   at the lift (taps) and press consumers get no blocking listener, so a
+ *   scroll starting on them never waits.
+ * - A lift whose click must not happen cancels its `touchend` (no click, no
+ *   compatibility mouse events) and arms a one-shot swallower for the next
+ *   trusted click; a click held for a recognizer that may still recognize is
+ *   replayed if they all fail. Keyboard and assistive-technology clicks
+ *   (`detail === 0`) always pass.
+ * - A `contextmenu` while a recognizer owns a touch is cancelled, so a long
+ *   press never also opens the browser's menu.
+ *
+ * DELEGATED CONSUMERS. A consumer type registered with an attribute (a
+ * pressable row) is found at touch-down by walking up from the touch target,
+ * and an instance is created for that one touch: a list of a thousand rows
+ * costs nothing until a finger lands on one.
+ *
+ * SSR-safe: nothing touches `window` or `document` until something attaches.
+ *
+ * SYNC: When modified, update GestureHost.test.ts and README.md.
+ */
+
+import { UIKIT_GESTURES } from "../motion/uikit/gestures.js";
+import { browserClock, GestureArena } from "./GestureArena.js";
+import { HAPTIC_SWITCH_ATTRIBUTE } from "./haptics.js";
+import { isPrimaryClick } from "../utils/primaryClick.js";
+import { createNativeScrollProbe, parentAcrossShadow } from "./nativeScroll.js";
+import { gestureHostStyle, holdSelectionStyle, intersectTouchAction } from "./touchAction.js";
+import { markTouchAction, TOUCH_ACTION_ATTRIBUTE, unmarkTouchAction } from "./touchActionRule.js";
+
+/**
+ * A kind of view-level consumer found by attribute instead of attached to
+ * each element.
+ */
+
+const STYLE_PROPERTIES = {
+  touchAction: 'touch-action',
+  WebkitTouchCallout: '-webkit-touch-callout',
+  WebkitUserSelect: '-webkit-user-select',
+  userSelect: 'user-select'
+};
+
+/**
+ * Whether a recognizer can take a touch while it moves, and so needs the
+ * blocking `touchmove` listener that stops the browser's pan. A tap claims
+ * only at the lift (it fails once the finger travels), so it needs none.
+ */
+function claimsWhileMoving(recognizer) {
+  return recognizer.acceptsTouchInput && recognizer.kind !== 'tap';
+}
+
+/**
+ * A CSS-wide keyword, which names no touch-action of its own: the value in
+ * force resolves it (`initial` and `unset` to `auto`, `inherit` to the
+ * parent's).
+ */
+function isCssWideKeyword(value) {
+  return CSS_WIDE_KEYWORDS.has(value.trim().toLowerCase());
+}
+const CSS_WIDE_KEYWORDS = new Set(['initial', 'inherit', 'unset', 'revert', 'revert-layer']);
+
+/**
+ * Run `task` in the next frame, before it paints: a read there styles what
+ * the frame must style anyway, and its writes are what the frame shows.
+ */
+function inNextFrame(view, task) {
+  if (view != null && typeof view.requestAnimationFrame === 'function') {
+    view.requestAnimationFrame(task);
+  } else {
+    setTimeout(task, 0);
+  }
+}
+const PASSIVE_CAPTURE = {
+  capture: true,
+  passive: true
+};
+
+/**
+ * A screen-edge pan, told apart by its kind (architecture:react-component-runtime
+ * INV13), so the host can report its layout changes without importing it.
+ */
+function asScreenEdgePan(recognizer) {
+  return recognizer.kind === 'screenEdgePan' ? recognizer : null;
+}
+
+/** The inline properties a held press sets to none (holdSelectionStyle). */
+const HOLD_SELECTION_PROPERTIES = ['-webkit-touch-callout', '-webkit-user-select', 'user-select'];
+
+/** Elements a held press turned selection off on, and what to restore. */
+const heldSelection = new WeakMap();
+const ACTIVE_CAPTURE = {
+  capture: true,
+  passive: false
+};
+/** A touchstart and a pointerdown describe one finger: same target, same spot. */
+function isSamePlace(a, b) {
+  return a.target === b.target && Math.abs(a.x - b.x) <= 1 && Math.abs(a.y - b.y) <= 1;
+}
+function isPointerKind(type) {
+  return type === 'touch' || type === 'mouse' || type === 'pen';
+}
+
+/**
+ * An event's time on the arena's clock (`performance.now()`). Some engines
+ * and DOM emulators stamp events in epoch milliseconds instead.
+ */
+function eventTime(event) {
+  const time = event.timeStamp;
+  if (time > 1e12 && typeof performance !== 'undefined' && performance.timeOrigin > 0) {
+    return time - performance.timeOrigin;
+  }
+  return time;
+}
+
+/** A touch list as an array; a synthetic event may carry none. */
+function touchesOf(list) {
+  return list == null ? [] : Array.from(list);
+}
+export class GestureHost {
+  registry = new Map();
+  delegated = new Set();
+  /** Touch.identifier → arena id, for live fingers. */
+  touchIds = new Map();
+  /** Touch.identifier → the element the finger landed on. */
+  touchTargets = new Map();
+  /**
+   * Finger targets with listeners of their own: how many fingers each, and
+   * how many of those a recognizer could claim while they move (only those
+   * need the blocking `touchmove` listener).
+   */
+  watched = new Map();
+  /** Fingers whose target listener is the blocking one. */
+  blockingFingers = new Set();
+  /** Touch events already handled (the document's and the target's listeners both see one). */
+  processed = new WeakSet();
+  /** pointerId → arena id, for live mouse and pen contacts. */
+  pointerIds = new Map();
+  /** Elements whose caller touch-action waits for a read after paint. */
+  pendingCallerReads = new Set();
+  isCallerReadScheduled = false;
+  /**
+   * The boxes the host watches for screen-edge pans (syncLayoutWatch): each
+   * element with an enabled one, and the root for one whose band moves with
+   * the viewport (spec:AST-094 FR18, FR19, DEC-22), and the one observer
+   * that watches them.
+   */
+  layoutWatched = new Set();
+  layoutObserver = null;
+  /** Fingers whose first uncancelable `touchmove` was already judged. */
+  judgedUncancelable = new Set();
+  /**
+   * A finger's pointerId → its arena id, once its pointerdown and its
+   * touchstart are paired. Chromium sends no `touchmove` until a finger has
+   * travelled its slop (about 16 px), but sends every `pointermove`, so the
+   * finger's movement comes from both channels; and its `pointercancel` is
+   * the browser's claim of exactly that finger.
+   */
+  fingerPointers = new Map();
+  /** Finger pointerdowns still waiting for their touchstart. */
+  pendingPointers = new Map();
+  /**
+   * Under `inputMode: 'pointer-events'`, where claimed fingers lifted: the
+   * `touchend` that follows their `pointerup` is cancelled (FR21).
+   */
+  claimedLifts = [];
+  /** Fingers still waiting for their pointerdown, by arena id. */
+  unpairedTouches = new Map();
+  /** The elements each held contact turned selection off on. */
+  heldSelectionBy = new Map();
+  isWatchingPointer = false;
+  onPointerKindChange = () => this.refreshAll();
+  /** The last position fed per contact, so one channel's echo is dropped. */
+  lastFed = new Map();
+  /** When a finger was last down or lifted, and where it landed. */
+  lastTouch = null;
+  /** Scrollers a recognizer is scrolling itself this frame (ownScroll). */
+  ownedScrolls = new Set();
+  /** The last scroll a finger drove, and when. */
+  lastScroll = null;
+  nextId = 1;
+  isInstalled = false;
+  usesTouchEvents = true;
+  swallowDeadline = Number.NEGATIVE_INFINITY;
+  /**
+   * Where the primary pointer is fine: what listens for a press itself (the
+   * elements that use a gesture, and the document for delegated consumers),
+   * with its removal; whether a press one armed is held, the page's
+   * listeners lasting that long; and the pending removal of the click
+   * listener a released press kept (FR21, FR24).
+   */
+  armed = new Map();
+  isArmedPress = false;
+  clickRemoval = null;
+  constructor(doc, options = {}) {
+    this.doc = doc;
+    this.inputMode = options.inputMode ?? 'auto';
+    const environment = {
+      viewportSize: () => ({
+        width: doc.defaultView?.innerWidth ?? 0,
+        height: doc.defaultView?.innerHeight ?? 0
+      }),
+      isRtl: view => view instanceof Element && doc.defaultView?.getComputedStyle(view).direction === 'rtl',
+      // A screen-edge pan tells a view within its edge band from any other
+      // by its box (spec:AST-094 FR18).
+      viewRect: view => {
+        if (!(view instanceof Element)) {
+          return null;
+        }
+        const {
+          left,
+          top,
+          width,
+          height
+        } = view.getBoundingClientRect();
+        return {
+          left,
+          top,
+          width,
+          height
+        };
+      }
+    };
+    this.arena = new GestureArena({
+      clock: options.clock ?? browserClock,
+      environment,
+      onDeferredClick: (touch, allowed) => this.replayClick(touch, allowed),
+      onTransition: options.onTransition
+    });
+    const view = doc.defaultView;
+    const coarseQuery = options.isPrimaryPointerCoarse == null && typeof view?.matchMedia === 'function' ? view.matchMedia('(pointer: coarse)') : null;
+    this.isPrimaryPointerCoarse = options.isPrimaryPointerCoarse ?? (() => coarseQuery?.matches ?? false);
+    this.coarseQuery = coarseQuery;
+  }
+
+  /** Re-derive every element's styles and the host's listeners. */
+  refreshAll() {
+    for (const [element, registration] of this.registry) {
+      this.refresh(element, registration);
+    }
+    this.syncListeners();
+  }
+
+  // --- Attachment ------------------------------------------------------------
+
+  /** Attach a recognizer to an element. Returns the detach function. */
+  attach(element, recognizer, options = {}) {
+    const registration = this.registrationFor(element);
+    registration.manageStyle = options.manageStyle ?? registration.manageStyle;
+    registration.actionGroup = options.actionGroup ?? registration.actionGroup;
+    recognizer.view = element;
+    registration.recognizers.push(recognizer);
+    recognizer.onEnabledChange = () => {
+      this.refresh(element, registration);
+      this.syncListeners();
+    };
+    const edgePan = asScreenEdgePan(recognizer);
+    if (edgePan != null) {
+      // A new answer may also move the band the pan watches onto or off the
+      // right side, whose band moves with the viewport (an in-place switch
+      // of direction): the layout watch follows (FR18, FR24, DEC-22).
+      edgePan.onTouchBehaviorChange = () => {
+        this.refresh(element, registration);
+        this.syncLayoutWatch();
+      };
+    }
+    this.refresh(element, registration);
+    this.syncListeners();
+    return () => {
+      recognizer.onEnabledChange = null;
+      if (edgePan != null) {
+        edgePan.onTouchBehaviorChange = null;
+      }
+      const index = registration.recognizers.indexOf(recognizer);
+      if (index >= 0) {
+        registration.recognizers.splice(index, 1);
+      }
+      // A recognizer whose view goes away mid-gesture is cancelled, as in
+      // UIKit when a view leaves the window.
+      if (recognizer.state !== 'possible' || recognizer.isInvolved()) {
+        recognizer.cancel();
+      }
+      this.refresh(element, registration);
+      // Even when the element keeps other attachments: one left disabled
+      // keeps no listener or observer (FR24).
+      this.syncListeners();
+      this.cleanup(element, registration);
+    };
+  }
+
+  /**
+   * Watch the box of each element with an enabled screen-edge pan, and the
+   * root's for a pan that watches the right side, whose band moves with the
+   * viewport: a resize may move an element into or out of its edge band, and
+   * the pan then measures again and re-derives the element's touch-action
+   * (FR19). The host sets touch-action for every pointer (FR43), so it
+   * watches under any primary pointer. One ResizeObserver serves every
+   * element and goes with the last one, and no listener is added (FR24); an
+   * engine without ResizeObserver keeps each pan's first measurement.
+   */
+  syncLayoutWatch() {
+    const wanted = new Set();
+    let watchesViewport = false;
+    for (const [element, registration] of this.registry) {
+      for (const recognizer of registration.recognizers) {
+        const edgePan = asScreenEdgePan(recognizer);
+        if (edgePan != null && edgePan.isEnabled) {
+          wanted.add(element);
+          watchesViewport ||= edgePan.watchesViewport;
+        }
+      }
+    }
+    if (watchesViewport) {
+      wanted.add(this.doc.documentElement);
+    }
+    for (const element of [...this.layoutWatched]) {
+      if (!wanted.has(element)) {
+        this.layoutObserver?.unobserve(element);
+        this.layoutWatched.delete(element);
+      }
+    }
+    if (wanted.size === 0) {
+      this.layoutObserver?.disconnect();
+      this.layoutObserver = null;
+      return;
+    }
+    const view = this.doc.defaultView;
+    if (this.layoutObserver == null && view != null && typeof view.ResizeObserver === 'function') {
+      this.layoutObserver = new view.ResizeObserver(this.onLayoutChange);
+      for (const element of this.layoutWatched) {
+        this.layoutObserver.observe(element);
+      }
+    }
+    for (const element of wanted) {
+      if (!this.layoutWatched.has(element)) {
+        this.layoutObserver?.observe(element);
+        this.layoutWatched.add(element);
+      }
+    }
+  }
+
+  /** A watched box or the root resized: each enabled edge pan measures again. */
+  onLayoutChange = () => {
+    for (const registration of this.registry.values()) {
+      for (const recognizer of registration.recognizers) {
+        const edgePan = asScreenEdgePan(recognizer);
+        if (edgePan != null && edgePan.isEnabled) {
+          edgePan.layoutChanged();
+        }
+      }
+    }
+  };
+
+  /** Attach the view-level touch consumer of an element (a pressable control). */
+  attachConsumer(element, consumer) {
+    const registration = this.registrationFor(element);
+    registration.consumer = consumer;
+    this.syncListeners();
+    return () => {
+      if (registration.consumer === consumer) {
+        registration.consumer = null;
+      }
+      // Even when the element keeps a recognizer: one left disabled keeps
+      // no listener or observer (FR24).
+      this.syncListeners();
+      this.cleanup(element, registration);
+    };
+  }
+
+  /**
+   * Find consumers of a kind by attribute, one instance per contact. Returns
+   * the function that stops it.
+   */
+  addDelegatedConsumer(type) {
+    this.delegated.add(type);
+    this.syncListeners();
+    return () => {
+      this.delegated.delete(type);
+      this.syncListeners();
+    };
+  }
+
+  /**
+   * Re-derive an element's styles and the host's listeners after its
+   * recognizers' options or its consumer's enabled state changed.
+   */
+  update(element) {
+    const registration = this.registry.get(element);
+    if (registration != null) {
+      this.refresh(element, registration);
+    }
+    this.syncListeners();
+  }
+
+  /**
+   * The Pointer Events `pointerId` of a contact the arena tracks: a mouse's
+   * or a pen's own, and for a finger driven by touch events the pointer its
+   * touch was paired with (null before the pairing, or without Pointer
+   * Events). It hands a held finger to code that follows pointers, as a
+   * menu does when a long press turns into a press-drag selection.
+   */
+  pointerIdOf(touch) {
+    const id = typeof touch === 'number' ? touch : touch.id;
+    for (const [pointerId, arenaId] of this.fingerPointers) {
+      if (arenaId === id) {
+        return pointerId;
+      }
+    }
+    for (const [pointerId, arenaId] of this.pointerIds) {
+      if (arenaId === id) {
+        return pointerId;
+      }
+    }
+    return null;
+  }
+
+  /**
+   * Whether a finger set a scroller containing `node` moving within the last
+   * `window` ms. A touch there now brakes the scroll rather than pressing
+   * whatever is under it: a native list highlights nothing for one.
+   */
+  isScrollBraking(node, window = UIKIT_GESTURES.press.scrollBrake.value) {
+    const last = this.lastScroll;
+    return last != null && this.arena.now() - last.time < window && last.scroller.contains(node);
+  }
+  registrationFor(element) {
+    let registration = this.registry.get(element);
+    if (registration == null) {
+      registration = {
+        recognizers: [],
+        consumer: null,
+        touchMoveListener: null,
+        touchEndListener: null,
+        savedStyle: new Map(),
+        authorTouchAction: null,
+        manageStyle: true,
+        actionGroup: false
+      };
+      this.registry.set(element, registration);
+    }
+    return registration;
+  }
+  refresh(element, registration) {
+    if (registration.manageStyle && element instanceof HTMLElement) {
+      this.applyStyle(element, registration);
+    }
+    // For every pointer (FR43): a finger's claim cancels its moves here
+    // (FR19), a listener FR24 counts apart from the one an element keeps for
+    // its press.
+    const needsListener = registration.recognizers.some(r => r.isEnabled && claimsWhileMoving(r));
+    if (needsListener && registration.touchMoveListener == null) {
+      const listener = event => this.cancelIfClaimed(event);
+      registration.touchMoveListener = listener;
+      element.addEventListener('touchmove', listener, {
+        passive: false
+      });
+    } else if (!needsListener && registration.touchMoveListener != null) {
+      element.removeEventListener('touchmove', registration.touchMoveListener);
+      registration.touchMoveListener = null;
+    }
+    // Pointer Events only: a claimed finger's touchend is not the host's
+    // own document listener's to cancel, so the element cancels it.
+    const needsEndListener = this.inputMode === 'pointer-events' && registration.recognizers.some(r => r.isEnabled && r.acceptsTouchInput);
+    if (needsEndListener && registration.touchEndListener == null) {
+      const listener = event => this.cancelClaimedLift(event);
+      registration.touchEndListener = listener;
+      element.addEventListener('touchend', listener, {
+        passive: false
+      });
+    } else if (!needsEndListener && registration.touchEndListener != null) {
+      element.removeEventListener('touchend', registration.touchEndListener);
+      registration.touchEndListener = null;
+    }
+  }
+  applyStyle(element, registration) {
+    // Where no attached recognizer is enabled the host manages no style: the
+    // element keeps its own touch-action, and any value set before is
+    // restored (FR24). Every pointer gets it: a touchscreen laptop's finger
+    // as a phone's (spec:AST-094 FR43).
+    const enabled = registration.recognizers.filter(r => r.isEnabled);
+    const style = enabled.length > 0 ? gestureHostStyle(enabled) : {};
+    for (const key of Object.keys(STYLE_PROPERTIES)) {
+      const property = STYLE_PROPERTIES[key];
+      let value = style[key];
+      if (key === 'touchAction') {
+        value = this.touchActionToWrite(element, registration, value);
+      }
+      if (value != null) {
+        if (!registration.savedStyle.has(property)) {
+          registration.savedStyle.set(property, element.style.getPropertyValue(property));
+        }
+        element.style.setProperty(property, value);
+      } else if (registration.savedStyle.has(property)) {
+        const saved = registration.savedStyle.get(property) ?? '';
+        registration.savedStyle.delete(property);
+        if (saved === '') {
+          element.style.removeProperty(property);
+        } else {
+          element.style.setProperty(property, saved);
+        }
+      }
+    }
+  }
+
+  /**
+   * The touch-action to write inline, if any. The author's value (a
+   * trigger's own `touch-action: none`) stays in force and the host never
+   * allows more (spec:AST-094 FR18, DEC-8):
+   * - an inline value is the style's own, read with no recalc, and the host
+   *   writes what both allow, inline; a CSS-wide keyword (`initial`,
+   *   `inherit`, `unset`, `revert`, `revert-layer`) names no touch-action of
+   *   its own, so it is read as an author rule is, as what it resolves to;
+   * - otherwise the element is marked with the derived value, under a rule
+   *   any author rule outranks, as the recognizer attaches: a subtree that
+   *   mounts with it is styled once, never restyled for it in a later frame.
+   *   The next frame reads what is in force, styles clean, and the host
+   *   writes inline only what both allow where that is narrower than an
+   *   author rule's value.
+   */
+  touchActionToWrite(element, registration, derived) {
+    if (derived == null) {
+      unmarkTouchAction(element);
+      registration.authorTouchAction = null;
+      return undefined;
+    }
+    const property = STYLE_PROPERTIES.touchAction;
+    const inline = registration.savedStyle.has(property) ? registration.savedStyle.get(property) ?? '' : element.style.getPropertyValue(property);
+    if (inline !== '' && !isCssWideKeyword(inline)) {
+      unmarkTouchAction(element);
+      return intersectTouchAction(derived, inline);
+    }
+    if (!markTouchAction(element, derived)) {
+      // No document or shadow root to hold the rule (a detached element):
+      // nothing is styled there, and the next frame looks again.
+      this.readCallerTouchActionInNextFrame(element);
+      return undefined;
+    }
+    const read = registration.authorTouchAction;
+    if (read == null || read.derived !== derived) {
+      // The rule is in force until the read: the derived value, or the
+      // author's where the author sets one.
+      this.readCallerTouchActionInNextFrame(element);
+      return undefined;
+    }
+    if (read.author == null) {
+      return undefined;
+    }
+    const both = intersectTouchAction(derived, read.author);
+    return both === read.author ? undefined : both;
+  }
+
+  /**
+   * Read the touch-action in force on each marked element in the next frame,
+   * then apply its style again. Batched: one style read serves every pending
+   * element, and the writes follow the reads. The host has written no
+   * touch-action inline on them, so a value other than the mark is an author
+   * rule's.
+   */
+  readCallerTouchActionInNextFrame(element) {
+    this.pendingCallerReads.add(element);
+    if (this.isCallerReadScheduled) {
+      return;
+    }
+    this.isCallerReadScheduled = true;
+    inNextFrame(this.doc.defaultView, () => {
+      this.isCallerReadScheduled = false;
+      const pending = [];
+      for (const candidate of this.pendingCallerReads) {
+        const registration = this.registry.get(candidate);
+        if (registration != null) {
+          pending.push([candidate, registration]);
+        }
+      }
+      this.pendingCallerReads.clear();
+      const view = this.doc.defaultView;
+      for (const [candidate, registration] of pending) {
+        const derived = candidate.getAttribute(TOUCH_ACTION_ATTRIBUTE);
+        if (derived == null || view == null) {
+          continue;
+        }
+        const inForce = view.getComputedStyle(candidate).touchAction || 'auto';
+        registration.authorTouchAction = {
+          derived,
+          author: inForce === derived ? null : inForce
+        };
+      }
+      for (const [candidate, registration] of pending) {
+        this.applyStyle(candidate, registration);
+      }
+    });
+  }
+  cleanup(element, registration) {
+    if (registration.recognizers.length > 0 || registration.consumer != null) {
+      return;
+    }
+    if (registration.touchMoveListener != null) {
+      element.removeEventListener('touchmove', registration.touchMoveListener);
+    }
+    if (registration.touchEndListener != null) {
+      element.removeEventListener('touchend', registration.touchEndListener);
+      registration.touchEndListener = null;
+    }
+    this.registry.delete(element);
+    this.syncListeners();
+  }
+
+  /**
+   * Listen only while something could take a touch now (`spec:AST-094`
+   * FR24, FR43): where the primary pointer is coarse, while an enabled
+   * recognizer or consumer, or a delegated consumer, is attached; where it is
+   * fine, only during a press something armed (syncArmed). Otherwise no page
+   * listener is registered, so an idle page and a disabled control pay
+   * nothing.
+   */
+  syncListeners() {
+    this.syncLayoutWatch();
+    // The primary pointer can change (a tablet's keyboard attached or
+    // removed): while anything is attached, styles and listeners follow it.
+    // Nothing touch-related stays once the last attachment goes (FR24).
+    const hasAttachments = this.registry.size > 0 || this.delegated.size > 0;
+    if (hasAttachments && !this.isWatchingPointer) {
+      this.coarseQuery?.addEventListener?.('change', this.onPointerKindChange);
+      this.isWatchingPointer = true;
+    } else if (!hasAttachments && this.isWatchingPointer) {
+      this.coarseQuery?.removeEventListener?.('change', this.onPointerKindChange);
+      this.isWatchingPointer = false;
+    }
+    this.syncArmed();
+    if (this.shouldListen()) {
+      this.install();
+    } else if (this.isInstalled) {
+      this.uninstall();
+    }
+  }
+  shouldListen() {
+    if (!this.isPrimaryPointerCoarse()) {
+      return this.isArmedPress;
+    }
+    if (this.delegated.size > 0) {
+      return true;
+    }
+    for (const registration of this.registry.values()) {
+      if (isServed(registration)) {
+        return true;
+      }
+    }
+    return false;
+  }
+
+  /**
+   * Where the primary pointer is fine, each element with an enabled
+   * recognizer or press consumer listens for a press itself: one passive
+   * `pointerdown` listener, in the capture phase, so the outermost one hears
+   * a press first and serves every recognizer on its path. Delegated
+   * consumer types, which have no element, arm the document once. A press
+   * installs the host's page listeners for as long as its contacts last
+   * (`spec:AST-094` FR24, FR43). Where the primary pointer is coarse the
+   * page's listeners serve every press, and nothing is armed.
+   */
+  syncArmed() {
+    const wanted = new Set();
+    if (!this.isPrimaryPointerCoarse()) {
+      for (const [element, registration] of this.registry) {
+        if (isServed(registration)) {
+          wanted.add(element);
+        }
+      }
+      if (this.delegated.size > 0) {
+        wanted.add(this.doc);
+      }
+    }
+    for (const [target, disarm] of [...this.armed]) {
+      if (!wanted.has(target)) {
+        disarm();
+        this.armed.delete(target);
+      }
+    }
+    for (const target of wanted) {
+      if (this.armed.has(target)) {
+        continue;
+      }
+      target.addEventListener('pointerdown', this.onArmedPress, PASSIVE_CAPTURE);
+      this.armed.set(target, () => {
+        target.removeEventListener('pointerdown', this.onArmedPress, PASSIVE_CAPTURE);
+      });
+    }
+  }
+
+  /**
+   * A press on something armed, where the primary pointer is fine: a
+   * mouse's primary button, a pen, or a finger. The page's listeners come
+   * for this press, and the press goes on to them, its capture phase on the
+   * page being over.
+   */
+  onArmedPress = event => {
+    const press = event;
+    if (this.isInstalled || !isPointerKind(press.pointerType) || press.pointerType !== 'touch' && !isPrimaryClick(press)) {
+      return;
+    }
+    this.isArmedPress = true;
+    this.install();
+    this.onPointerDown(press);
+    // A mouse's or a pen's press that nothing took has nothing to wait for;
+    // a finger's contact begins at its touchstart, which comes next.
+    if (press.pointerType !== 'touch') {
+      this.releaseArmedPress();
+    }
+  };
+
+  /**
+   * After a contact ends: once no contact of the press that armed the page's
+   * listeners is down, they go (FR24). A recognizer still deciding after the
+   * lift needs no input; the click it may owe keeps its listener
+   * (releaseClickListener).
+   */
+  releaseArmedPress() {
+    if (this.isArmedPress && !this.arena.touches.some(touch => touch.phase !== 'ended' && touch.phase !== 'cancelled')) {
+      this.isArmedPress = false;
+      this.syncListeners();
+    }
+  }
+
+  /**
+   * The click listener outlives the page's others while the swallower is
+   * armed: a claimed lift's click comes after its pointerup or touchend
+   * (`spec:AST-094` FR21; FR24 counts it as press work). It goes when that
+   * window closes, unless the host listens again by then.
+   */
+  releaseClickListener() {
+    const view = this.doc.defaultView;
+    if (this.clickRemoval != null) {
+      clearTimeout(this.clickRemoval);
+      this.clickRemoval = null;
+    }
+    const remaining = this.swallowDeadline - browserClock.now();
+    if (view == null || remaining < 0) {
+      view?.removeEventListener('click', this.onClick, ACTIVE_CAPTURE);
+      return;
+    }
+    this.clickRemoval = setTimeout(() => {
+      this.clickRemoval = null;
+      if (!this.isInstalled) {
+        view.removeEventListener('click', this.onClick, ACTIVE_CAPTURE);
+      }
+    }, remaining + 1);
+  }
+
+  // --- Listeners -------------------------------------------------------------
+
+  install() {
+    if (this.isInstalled) {
+      return;
+    }
+    if (this.clickRemoval != null) {
+      clearTimeout(this.clickRemoval);
+      this.clickRemoval = null;
+    }
+    const view = this.doc.defaultView;
+    this.isInstalled = true;
+    this.usesTouchEvents = this.inputMode === 'auto' && view != null && 'ontouchstart' in view;
+    const doc = this.doc;
+    // Pointer Events only: a finger comes from its pointer events alone. A
+    // browser that has Touch Events still sends them for the same finger, and
+    // reading both would track it twice (a long press needs one touch).
+    if (this.inputMode === 'auto') {
+      doc.addEventListener('touchstart', this.onTouchStart, PASSIVE_CAPTURE);
+      doc.addEventListener('touchmove', this.onTouchMove, PASSIVE_CAPTURE);
+      doc.addEventListener('touchend', this.onTouchEnd, ACTIVE_CAPTURE);
+      doc.addEventListener('touchcancel', this.onTouchCancel, PASSIVE_CAPTURE);
+    }
+    doc.addEventListener('pointerdown', this.onPointerDown, PASSIVE_CAPTURE);
+    doc.addEventListener('pointermove', this.onPointerMove, PASSIVE_CAPTURE);
+    doc.addEventListener('pointerup', this.onPointerUp, PASSIVE_CAPTURE);
+    doc.addEventListener('pointercancel', this.onPointerCancel, PASSIVE_CAPTURE);
+    doc.addEventListener('contextmenu', this.onContextMenu, ACTIVE_CAPTURE);
+    doc.addEventListener('scroll', this.onScroll, PASSIVE_CAPTURE);
+    doc.addEventListener('visibilitychange', this.onVisibilityChange);
+    view?.addEventListener('click', this.onClick, ACTIVE_CAPTURE);
+    view?.addEventListener('blur', this.onBlur);
+  }
+  uninstall() {
+    if (!this.isInstalled) {
+      return;
+    }
+    this.isInstalled = false;
+    const doc = this.doc;
+    const view = doc.defaultView;
+    doc.removeEventListener('touchstart', this.onTouchStart, PASSIVE_CAPTURE);
+    doc.removeEventListener('touchmove', this.onTouchMove, PASSIVE_CAPTURE);
+    doc.removeEventListener('touchend', this.onTouchEnd, ACTIVE_CAPTURE);
+    doc.removeEventListener('touchcancel', this.onTouchCancel, PASSIVE_CAPTURE);
+    doc.removeEventListener('pointerdown', this.onPointerDown, PASSIVE_CAPTURE);
+    doc.removeEventListener('pointermove', this.onPointerMove, PASSIVE_CAPTURE);
+    doc.removeEventListener('pointerup', this.onPointerUp, PASSIVE_CAPTURE);
+    doc.removeEventListener('pointercancel', this.onPointerCancel, PASSIVE_CAPTURE);
+    doc.removeEventListener('contextmenu', this.onContextMenu, ACTIVE_CAPTURE);
+    doc.removeEventListener('scroll', this.onScroll, PASSIVE_CAPTURE);
+    doc.removeEventListener('visibilitychange', this.onVisibilityChange);
+    this.releaseClickListener();
+    view?.removeEventListener('blur', this.onBlur);
+    this.cancelEverything(this.arena.now());
+    this.lastTouch = null;
+    this.lastScroll = null;
+  }
+
+  // --- Hit path --------------------------------------------------------------
+
+  /**
+   * The recognizers on the path from `target` to the document, innermost
+   * first, and (for a contact) its consumer: the innermost element with an
+   * attached consumer or a delegated consumer type's attribute.
+   */
+  participantsAt(target, pointerType) {
+    const recognizers = [];
+    let consumer = null;
+    let hasConsumerOwner = pointerType == null;
+    for (let node = target instanceof Node ? target : null; node != null; node = parentAcrossShadow(node)) {
+      if (!(node instanceof Element)) {
+        continue;
+      }
+      const registration = this.registry.get(node);
+      if (registration != null) {
+        recognizers.push(...registration.recognizers);
+      }
+      if (hasConsumerOwner || pointerType == null) {
+        continue;
+      }
+      if (registration?.consumer != null) {
+        consumer = registration.consumer;
+        hasConsumerOwner = true;
+        continue;
+      }
+      for (const type of this.delegated) {
+        if (node.hasAttribute(type.attribute)) {
+          consumer = type.create(node, pointerType);
+          hasConsumerOwner = true;
+          break;
+        }
+      }
+    }
+    return {
+      recognizers,
+      consumer
+    };
+  }
+
+  // --- Touch events ----------------------------------------------------------
+
+  /** Whether this event is new to the host (and mark it handled). */
+  takeEvent(event) {
+    if (this.processed.has(event)) {
+      return false;
+    }
+    this.processed.add(event);
+    return true;
+  }
+  onTouchStart = event => {
+    if (!this.takeEvent(event)) {
+      return;
+    }
+    const time = eventTime(event);
+    const inputs = [];
+    const untracked = [];
+    const stale = [];
+    for (const touch of touchesOf(event.changedTouches)) {
+      if (touch.touchType === 'stylus') {
+        continue;
+      }
+      // A finger number still tracked here began again: the touch it named
+      // ended where no listener of ours could hear it.
+      const previous = this.forgetFinger(touch.identifier);
+      if (previous != null) {
+        stale.push(previous);
+      }
+      const target = touch.target instanceof Node ? touch.target : event.target;
+      const {
+        recognizers,
+        consumer
+      } = this.participantsAt(target, 'touch');
+      if (recognizers.length === 0 && consumer == null) {
+        // Nothing here takes part: the touch stays the page's, but a
+        // recognizer tracking another finger hears it began (a second
+        // finger beside an open menu ends its press, spec:AST-094 FR28).
+        untracked.push({
+          id: this.nextId++,
+          x: touch.clientX,
+          y: touch.clientY,
+          time,
+          pointerType: 'touch',
+          target
+        });
+        continue;
+      }
+      const id = this.nextId++;
+      this.touchIds.set(touch.identifier, id);
+      this.holdSelection(id, recognizers);
+      this.watchTarget(touch.identifier, target, recognizers.some(claimsWhileMoving));
+      this.lastFed.set(id, {
+        x: touch.clientX,
+        y: touch.clientY,
+        time
+      });
+      this.pairTouch(id, {
+        x: touch.clientX,
+        y: touch.clientY,
+        target
+      });
+      inputs.push({
+        id,
+        x: touch.clientX,
+        y: touch.clientY,
+        time,
+        pointerType: 'touch',
+        target,
+        scroll: createNativeScrollProbe(target),
+        recognizers,
+        consumer
+      });
+    }
+    if (stale.length > 0) {
+      this.arena.cancelled(stale, time);
+    }
+    this.arena.began(inputs);
+    for (const input of untracked) {
+      this.arena.untrackedBegan(input);
+    }
+    // Stamped after the consumers judged the touch: the brake asks whether
+    // an EARLIER finger is still driving a scroll.
+    if (event.target instanceof Node) {
+      this.lastTouch = {
+        target: event.target,
+        time
+      };
+    }
+  };
+  onTouchMove = event => {
+    if (!this.takeEvent(event)) {
+      return;
+    }
+    this.dropFingersNotDown(event);
+    const time = eventTime(event);
+    const ids = [];
+    const inputs = [];
+    for (const touch of touchesOf(event.changedTouches)) {
+      const id = this.touchIds.get(touch.identifier);
+      if (id == null) {
+        continue;
+      }
+      ids.push(id);
+      inputs.push({
+        id,
+        x: touch.clientX,
+        y: touch.clientY,
+        time
+      });
+    }
+    if (inputs.length === 0) {
+      return;
+    }
+    if (!event.cancelable) {
+      // The browser no longer asks the page about these fingers. WebKit
+      // stops asking when it takes the touch to pan (its pointercancel comes
+      // with it); Chromium also stops after one unconsumed touchmove, even
+      // when `touch-action` keeps it from panning the way the finger went (a
+      // horizontal drag under pan-y). So a finger's FIRST uncancelable move
+      // counts as the browser's claim only if the browser could pan along
+      // the finger's main axis since touch-down; later ones add nothing, and
+      // pointercancel or a scroll still report any real pan.
+      const placed = new Map(inputs.map(input => [input.id, input]));
+      const taken = ids.filter(id => {
+        const touch = this.arena.getTouch(id);
+        if (touch == null || touch.takenByBrowser || this.arena.isClaimed(id) || touch.scroll?.allowsNativePan === false || this.judgedUncancelable.has(id)) {
+          return false;
+        }
+        this.judgedUncancelable.add(id);
+        const input = placed.get(id);
+        if (input == null || touch.scroll == null) {
+          return true;
+        }
+        const dx = input.x - touch.startX;
+        const dy = input.y - touch.startY;
+        return Math.abs(dx) >= Math.abs(dy) ? touch.scroll.canScroll(dx, 0) : touch.scroll.canScroll(0, dy);
+      });
+      if (taken.length > 0) {
+        this.arena.browserTookOver(taken, time);
+      }
+    }
+    this.feedMoves(inputs);
+  };
+
+  /**
+   * Under `inputMode: 'pointer-events'` a finger comes from its pointer
+   * events, so its touches carry no id of ours: the live finger it is, the
+   * nearest pointer-fed finger on the same target. Its touchmoves can then
+   * be cancelled once a recognizer claims it (`spec:AST-094` FR19, FR21).
+   */
+  pointerFingerAt(touch) {
+    let best = null;
+    let bestDistance = Number.POSITIVE_INFINITY;
+    for (const finger of this.arena.touches) {
+      if (finger.pointerType !== 'touch' || finger.phase === 'ended' || finger.phase === 'cancelled' || !(finger.target instanceof Node) || !(touch.target instanceof Node) || !(finger.target === touch.target || finger.target.contains(touch.target) || touch.target.contains(finger.target))) {
+        continue;
+      }
+      const d = Math.hypot(finger.x - touch.clientX, finger.y - touch.clientY);
+      if (d < bestDistance) {
+        best = finger;
+        bestDistance = d;
+      }
+    }
+    return best?.id;
+  }
+
+  /**
+   * Cancel the `touchend` of a finger a recognizer owned when it lifted
+   * (`inputMode: 'pointer-events'`): its `pointerup` came first, at the same
+   * place on the same target (`spec:AST-094` FR21).
+   */
+  cancelClaimedLift(event) {
+    if (!event.cancelable || event.defaultPrevented) {
+      return;
+    }
+    for (const touch of touchesOf(event.changedTouches)) {
+      const index = this.claimedLifts.findIndex(lift => isSamePlace(lift, {
+        x: touch.clientX,
+        y: touch.clientY,
+        target: touch.target
+      }));
+      if (index >= 0) {
+        this.claimedLifts.splice(index, 1);
+        event.preventDefault();
+        return;
+      }
+    }
+  }
+
+  /**
+   * Cancel a `touchmove` while a recognizer owns one of its fingers. A touch
+   * no recognizer owns keeps its moves (`spec:AST-094` FR19): nothing is
+   * cancelled before a recognizer begins, or for a touch it does not track.
+   */
+  cancelIfClaimed(event) {
+    if (!event.cancelable || event.defaultPrevented) {
+      return;
+    }
+    // Only the touches this move reports: another finger a recognizer owns
+    // does not make this one its own.
+    const moved = touchesOf(event.changedTouches);
+    for (const touch of moved) {
+      const id = this.touchIds.get(touch.identifier) ?? (this.inputMode === 'pointer-events' ? this.pointerFingerAt(touch) : undefined);
+      if (id != null && this.arena.isClaimed(id)) {
+        event.preventDefault();
+        return;
+      }
+    }
+    if (moved.some(touch => touch.touchType === 'stylus')) {
+      for (const id of this.pointerIds.values()) {
+        if (this.arena.isClaimed(id)) {
+          // A pen whose pointer a recognizer owns: its stylus touches too,
+          // never a finger no recognizer owns.
+          event.preventDefault();
+          return;
+        }
+      }
+    }
+  }
+  onTouchEnd = event => {
+    if (!this.takeEvent(event)) {
+      return;
+    }
+    this.dropFingersNotDown(event);
+    const time = eventTime(event);
+    const inputs = [];
+    for (const touch of touchesOf(event.changedTouches)) {
+      const id = this.forgetFinger(touch.identifier);
+      if (id == null) {
+        continue;
+      }
+      inputs.push({
+        id,
+        x: touch.clientX,
+        y: touch.clientY,
+        time
+      });
+    }
+    // The lift is when momentum starts: the clock the brake wants most.
+    if (event.target instanceof Node) {
+      this.lastTouch = {
+        target: event.target,
+        time
+      };
+    }
+    if (inputs.length === 0) {
+      this.releaseArmedPress();
+      return;
+    }
+    const dispositions = this.arena.ended(inputs);
+    if (needsSuppression(dispositions)) {
+      if (event.cancelable) {
+        event.preventDefault();
+      }
+      this.armSwallower();
+    }
+    this.releaseArmedPress();
+  };
+  onTouchCancel = event => {
+    if (!this.takeEvent(event)) {
+      return;
+    }
+    const listed = touchesOf(event.changedTouches);
+    // A cancel that names no finger is the system taking them all.
+    const identifiers = listed.length > 0 ? listed.map(touch => touch.identifier) : [...this.touchIds.keys()];
+    const ids = [];
+    for (const identifier of identifiers) {
+      const id = this.forgetFinger(identifier);
+      if (id != null) {
+        ids.push(id);
+      }
+    }
+    if (ids.length > 0) {
+      this.arena.cancelled(ids, eventTime(event));
+    }
+    this.releaseArmedPress();
+  };
+
+  /** The target's own listeners, for a target that left the document. */
+  onTargetTouchMove = event => {
+    this.onTouchMove(event);
+    this.cancelIfClaimed(event);
+  };
+
+  /** The same for a finger nothing could claim while it moves: never blocks. */
+  onTargetTouchMovePassive = event => {
+    this.onTouchMove(event);
+  };
+  onTargetTouchEnd = event => {
+    this.onTouchEnd(event);
+  };
+  onTargetTouchCancel = event => {
+    this.onTouchCancel(event);
+  };
+
+  /**
+   * Cancel tracked fingers the event says are no longer down. `touches`
+   * lists every finger on the screen; one missing from it (and not lifting
+   * in this very event) ended where we could not see it.
+   */
+  dropFingersNotDown(event) {
+    if (event.touches == null || this.touchIds.size === 0) {
+      return;
+    }
+    const down = new Set();
+    for (const touch of touchesOf(event.touches)) {
+      down.add(touch.identifier);
+    }
+    for (const touch of touchesOf(event.changedTouches)) {
+      down.add(touch.identifier);
+    }
+    const gone = [...this.touchIds.keys()].filter(identifier => !down.has(identifier));
+    const ids = [];
+    for (const identifier of gone) {
+      const id = this.forgetFinger(identifier);
+      if (id != null) {
+        ids.push(id);
+      }
+    }
+    if (ids.length > 0) {
+      this.arena.cancelled(ids, eventTime(event));
+    }
+  }
+  watchTarget(identifier, target, isBlocking) {
+    if (target == null || typeof target.addEventListener !== 'function') {
+      return;
+    }
+    this.touchTargets.set(identifier, target);
+    const state = this.watched.get(target);
+    if (state == null) {
+      this.watched.set(target, {
+        count: 1,
+        blocking: isBlocking ? 1 : 0
+      });
+      if (isBlocking) {
+        this.blockingFingers.add(identifier);
+      }
+      target.addEventListener('touchmove', isBlocking ? this.onTargetTouchMove : this.onTargetTouchMovePassive, {
+        passive: !isBlocking
+      });
+      target.addEventListener('touchend', this.onTargetTouchEnd, {
+        passive: false
+      });
+      target.addEventListener('touchcancel', this.onTargetTouchCancel, {
+        passive: true
+      });
+      return;
+    }
+    const wasBlocking = state.blocking > 0;
+    state.count += 1;
+    if (isBlocking) {
+      state.blocking += 1;
+      this.blockingFingers.add(identifier);
+    }
+    this.swapTargetTouchMove(target, wasBlocking, state.blocking > 0);
+  }
+  unwatchTarget(identifier) {
+    const target = this.touchTargets.get(identifier);
+    if (target == null) {
+      return;
+    }
+    this.touchTargets.delete(identifier);
+    const state = this.watched.get(target);
+    if (state == null) {
+      return;
+    }
+    const wasBlocking = state.blocking > 0;
+    state.count -= 1;
+    if (this.blockingFingers.delete(identifier)) {
+      state.blocking -= 1;
+    }
+    if (state.count > 0) {
+      this.swapTargetTouchMove(target, wasBlocking, state.blocking > 0);
+      return;
+    }
+    this.watched.delete(target);
+    target.removeEventListener('touchmove', wasBlocking ? this.onTargetTouchMove : this.onTargetTouchMovePassive);
+    target.removeEventListener('touchend', this.onTargetTouchEnd);
+    target.removeEventListener('touchcancel', this.onTargetTouchCancel);
+  }
+
+  /**
+   * Keeps one `touchmove` listener on a watched target: the blocking one
+   * while a finger on it could be claimed as it moves, a passive one
+   * otherwise, so a scroll starting there never waits on the main thread
+   * (`spec:AST-094` FR19).
+   */
+  swapTargetTouchMove(target, wasBlocking, isBlocking) {
+    if (wasBlocking === isBlocking) {
+      return;
+    }
+    target.removeEventListener('touchmove', wasBlocking ? this.onTargetTouchMove : this.onTargetTouchMovePassive);
+    target.addEventListener('touchmove', isBlocking ? this.onTargetTouchMove : this.onTargetTouchMovePassive, {
+      passive: !isBlocking
+    });
+  }
+
+  /** Stop tracking a finger by its Touch.identifier; returns its arena id. */
+  forgetFinger(identifier) {
+    const id = this.touchIds.get(identifier);
+    this.touchIds.delete(identifier);
+    this.unwatchTarget(identifier);
+    if (id != null) {
+      this.forgetContact(id);
+    }
+    return id;
+  }
+  pairTouch(id, place) {
+    for (const [pointerId, pending] of this.pendingPointers) {
+      if (isSamePlace(pending, place)) {
+        this.pendingPointers.delete(pointerId);
+        this.fingerPointers.set(pointerId, id);
+        return;
+      }
+    }
+    this.unpairedTouches.set(id, place);
+  }
+  pairPointer(pointerId, place) {
+    for (const [id, unpaired] of this.unpairedTouches) {
+      if (isSamePlace(unpaired, place)) {
+        this.unpairedTouches.delete(id);
+        this.fingerPointers.set(pointerId, id);
+        return;
+      }
+    }
+    this.pendingPointers.set(pointerId, place);
+  }
+
+  /** Feed moves, dropping the echo of a move the other channel delivered. */
+  feedMoves(inputs) {
+    const fresh = inputs.filter(input => {
+      const last = this.lastFed.get(input.id);
+      if (last != null && (input.time < last.time || input.time === last.time && input.x === last.x && input.y === last.y)) {
+        return false;
+      }
+      this.lastFed.set(input.id, {
+        x: input.x,
+        y: input.y,
+        time: input.time
+      });
+      return true;
+    });
+    if (fresh.length > 0) {
+      this.arena.moved(fresh);
+    }
+  }
+
+  /**
+   * For one held press by a finger or a pen: text selection and the touch
+   * callout off on the elements whose hold does something (a long press),
+   * as `holdSelectionStyle` decides (`spec:AST-094` FR41, DEC-9).
+   * Everything else keeps the browser's long-press selection. Restored when
+   * the contact ends; refcounted across contacts on one element.
+   */
+  holdSelection(id, recognizers) {
+    const elements = new Set();
+    for (const recognizer of recognizers) {
+      if (recognizer.view instanceof HTMLElement && recognizer.isEnabled &&
+      // An element attached with manageStyle: false keeps its own styles.
+      this.registry.get(recognizer.view)?.manageStyle !== false && holdSelectionStyle([recognizer]) != null) {
+        elements.add(recognizer.view);
+      }
+    }
+    if (elements.size === 0) {
+      return;
+    }
+    const held = [...elements];
+    for (const element of held) {
+      const entry = heldSelection.get(element);
+      if (entry != null) {
+        entry.count += 1;
+        continue;
+      }
+      const saved = HOLD_SELECTION_PROPERTIES.map(name => ({
+        name,
+        value: element.style.getPropertyValue(name),
+        priority: element.style.getPropertyPriority(name)
+      }));
+      for (const name of HOLD_SELECTION_PROPERTIES) {
+        element.style.setProperty(name, 'none');
+      }
+      heldSelection.set(element, {
+        count: 1,
+        saved
+      });
+    }
+    this.heldSelectionBy.set(id, held);
+  }
+
+  /** Undo `holdSelection` for a contact that ended; idempotent. */
+  releaseSelection(id) {
+    const held = this.heldSelectionBy.get(id);
+    if (held == null) {
+      return;
+    }
+    this.heldSelectionBy.delete(id);
+    for (const element of held) {
+      const entry = heldSelection.get(element);
+      if (entry == null) {
+        continue;
+      }
+      entry.count -= 1;
+      if (entry.count > 0) {
+        continue;
+      }
+      heldSelection.delete(element);
+      for (const {
+        name,
+        value,
+        priority
+      } of entry.saved) {
+        if (value === '') {
+          element.style.removeProperty(name);
+        } else {
+          element.style.setProperty(name, value, priority);
+        }
+      }
+    }
+  }
+
+  /** Forget a contact's pairing and echo state. */
+  forgetContact(id) {
+    this.releaseSelection(id);
+    this.lastFed.delete(id);
+    this.judgedUncancelable.delete(id);
+    this.unpairedTouches.delete(id);
+    for (const [pointerId, paired] of this.fingerPointers) {
+      if (paired === id) {
+        this.fingerPointers.delete(pointerId);
+      }
+    }
+  }
+
+  // --- Pointer events --------------------------------------------------------
+
+  onPointerDown = event => {
+    // A new press: whatever click is still owed to the last one is not this.
+    this.disarmSwallower();
+    if (!isPointerKind(event.pointerType)) {
+      return;
+    }
+    if (event.pointerType === 'touch' && this.usesTouchEvents) {
+      this.pairPointer(event.pointerId, {
+        x: event.clientX,
+        y: event.clientY,
+        target: event.target
+      });
+      return;
+    }
+    // A right click, a pen's barrel button and a ctrl-click on macOS start
+    // no press (FR43).
+    if (event.pointerType !== 'touch' && !isPrimaryClick(event)) {
+      return;
+    }
+    const {
+      recognizers,
+      consumer
+    } = this.participantsAt(event.target, event.pointerType);
+    if (recognizers.length === 0 && consumer == null) {
+      return;
+    }
+    const id = this.nextId++;
+    this.pointerIds.set(event.pointerId, id);
+    if (event.pointerType !== 'mouse') {
+      this.holdSelection(id, recognizers);
+    }
+    this.arena.began([{
+      id,
+      x: event.clientX,
+      y: event.clientY,
+      time: eventTime(event),
+      pointerType: event.pointerType,
+      target: event.target,
+      scroll: createNativeScrollProbe(event.target),
+      recognizers,
+      consumer
+    }]);
+  };
+  onPointerMove = event => {
+    if (event.pointerType === 'touch' && this.usesTouchEvents) {
+      const id = this.fingerPointers.get(event.pointerId);
+      if (id != null) {
+        this.feedMoves([{
+          id,
+          x: event.clientX,
+          y: event.clientY,
+          time: eventTime(event),
+          history: coalescedHistory(event)
+        }]);
+      }
+      return;
+    }
+    const id = this.pointerIds.get(event.pointerId);
+    if (id != null) {
+      this.arena.moved([{
+        id,
+        x: event.clientX,
+        y: event.clientY,
+        time: eventTime(event),
+        history: coalescedHistory(event)
+      }]);
+      return;
+    }
+  };
+  onPointerUp = event => {
+    if (event.pointerType === 'touch' && this.usesTouchEvents) {
+      // The lift itself is the touchend's: it alone can cancel the click.
+      this.fingerPointers.delete(event.pointerId);
+      this.pendingPointers.delete(event.pointerId);
+      return;
+    }
+    const id = this.pointerIds.get(event.pointerId);
+    if (id == null) {
+      this.releaseArmedPress();
+      return;
+    }
+    this.pointerIds.delete(event.pointerId);
+    this.releaseSelection(id);
+    if (event.pointerType === 'touch' && this.arena.isClaimed(id)) {
+      this.claimedLifts.push({
+        x: event.clientX,
+        y: event.clientY,
+        target: event.target
+      });
+      if (this.claimedLifts.length > 8) {
+        this.claimedLifts.shift();
+      }
+    }
+    const dispositions = this.arena.ended([{
+      id,
+      x: event.clientX,
+      y: event.clientY,
+      time: eventTime(event)
+    }]);
+    if (needsSuppression(dispositions)) {
+      this.armSwallower();
+    }
+    this.releaseArmedPress();
+  };
+  onPointerCancel = event => {
+    if (event.pointerType === 'touch' && this.usesTouchEvents) {
+      const id = this.fingerPointers.get(event.pointerId) ?? this.touchForCancelledPointer(event);
+      this.fingerPointers.delete(event.pointerId);
+      this.pendingPointers.delete(event.pointerId);
+      if (id != null) {
+        this.arena.browserTookOver([id], eventTime(event));
+      }
+      return;
+    }
+    const id = this.pointerIds.get(event.pointerId);
+    if (id != null) {
+      this.pointerIds.delete(event.pointerId);
+      this.releaseSelection(id);
+      this.arena.cancelled([id], eventTime(event));
+    }
+    this.releaseArmedPress();
+  };
+
+  /**
+   * Which live finger a touch `pointercancel` is about. The pointer keeps
+   * the target the finger landed on (implicit capture), as the Touch does;
+   * among fingers on that target, the nearest. WebKit also numbers the
+   * pointer like the Touch, which settles what position cannot.
+   */
+  touchForCancelledPointer(event) {
+    let best = null;
+    let bestDistance = Number.POSITIVE_INFINITY;
+    for (const touch of this.arena.touches) {
+      if (touch.pointerType !== 'touch' || touch.phase === 'ended' || touch.phase === 'cancelled' || touch.target !== event.target) {
+        continue;
+      }
+      const d = Math.hypot(touch.x - event.clientX, touch.y - event.clientY);
+      if (d < bestDistance) {
+        best = touch;
+        bestDistance = d;
+      }
+    }
+    if (best != null) {
+      return best.id;
+    }
+    return this.touchIds.get(event.pointerId) ?? null;
+  }
+
+  // --- Clicks, menus, scrolls, focus -----------------------------------------
+
+  armSwallower() {
+    this.swallowDeadline = browserClock.now() + UIKIT_GESTURES.click.strayClickWindow.value;
+  }
+  disarmSwallower() {
+    this.swallowDeadline = Number.NEGATIVE_INFINITY;
+  }
+  onClick = event => {
+    if (browserClock.now() > this.swallowDeadline) {
+      return;
+    }
+    if (!event.isTrusted || event.detail === 0) {
+      return;
+    }
+    if (event.target instanceof Element && event.target.hasAttribute(HAPTIC_SWITCH_ATTRIBUTE)) {
+      return;
+    }
+    this.disarmSwallower();
+    event.preventDefault();
+    event.stopImmediatePropagation();
+  };
+  replayClick(touch, allowed) {
+    if (!allowed) {
+      return;
+    }
+    // The browser's own click was swallowed while recognizers decided; they
+    // all failed, so the click the touch earned is delivered now.
+    this.disarmSwallower();
+    const target = touch.target;
+    const view = this.doc.defaultView;
+    if (!(target instanceof Element) || !target.isConnected || view == null) {
+      return;
+    }
+    target.dispatchEvent(new view.MouseEvent('click', {
+      bubbles: true,
+      cancelable: true,
+      composed: true,
+      detail: 1,
+      clientX: touch.x,
+      clientY: touch.y
+    }));
+  }
+  onContextMenu = event => {
+    for (const touch of this.arena.touches) {
+      if (this.arena.isClaimed(touch.id)) {
+        event.preventDefault();
+        return;
+      }
+    }
+  };
+
+  /**
+   * A recognizer is about to scroll `scroller` itself (a menu's edge
+   * autoscroll, spec:AST-094 FR30): the scroll that write fires is not a
+   * finger's and not the browser taking one. It passes until the end of the
+   * next frame, when that event has fired; a real pan in that window still
+   * reports itself through pointercancel or touchcancel.
+   */
+  ownScroll(scroller) {
+    this.ownedScrolls.add(scroller);
+    const view = this.doc.defaultView;
+    if (view == null) {
+      return;
+    }
+    view.requestAnimationFrame(() => {
+      view.requestAnimationFrame(() => {
+        this.ownedScrolls.delete(scroller);
+      });
+    });
+  }
+  onScroll = event => {
+    const time = eventTime(event);
+    const scroller = event.target === this.doc ? this.doc : event.target;
+    if (!(scroller instanceof Node) || this.ownedScrolls.has(scroller)) {
+      return;
+    }
+    // A scroll is a finger's only if that finger was inside this scroller,
+    // recently; anything else is the program moving something.
+    const last = this.lastTouch;
+    if (last != null && time - last.time < UIKIT_GESTURES.press.momentumMemory.value && scroller.contains(last.target)) {
+      this.lastScroll = {
+        scroller,
+        time
+      };
+    }
+    const taken = [];
+    for (const touch of this.arena.touches) {
+      if (touch.takenByBrowser || touch.phase === 'ended' || touch.phase === 'cancelled' || touch.pointerType !== 'touch' || this.arena.isClaimed(touch.id)) {
+        continue;
+      }
+      if (touch.target instanceof Node && scroller.contains(touch.target) &&
+      // Only a pan this finger drove takes the touch: the browser starts
+      // one only once the finger has travelled the take distance
+      // (spec:AST-094 FR20). A scroll under a finger that has not
+      // (scrollIntoView, a transcript pinned to its end, scroll
+      // anchoring) is the page's own: the touch, and the click it earns,
+      // stay where they are.
+      Math.hypot(touch.x - touch.startX, touch.y - touch.startY) >= UIKIT_GESTURES.press.slop.value) {
+        taken.push(touch.id);
+      }
+    }
+    if (taken.length > 0) {
+      this.arena.browserTookOver(taken, time);
+    }
+  };
+  onVisibilityChange = () => {
+    if (this.doc.visibilityState === 'hidden') {
+      this.cancelEverything(this.arena.now());
+      this.releaseArmedPress();
+    }
+  };
+  onBlur = () => {
+    this.cancelEverything(this.arena.now());
+    this.releaseArmedPress();
+  };
+
+  /** The app lost focus: UIKit cancels every touch in flight. */
+  cancelEverything(time) {
+    const ids = [...this.pointerIds.values()];
+    for (const id of ids) {
+      this.releaseSelection(id);
+    }
+    for (const identifier of [...this.touchIds.keys()]) {
+      const id = this.forgetFinger(identifier);
+      if (id != null) {
+        ids.push(id);
+      }
+    }
+    this.pointerIds.clear();
+    this.fingerPointers.clear();
+    this.pendingPointers.clear();
+    this.unpairedTouches.clear();
+    this.lastFed.clear();
+    if (ids.length > 0) {
+      this.arena.cancelled(ids, time);
+    }
+  }
+}
+
+/** Whether an attachment could take a press now: something on it is enabled. */
+function isServed(registration) {
+  return registration.recognizers.some(r => r.isEnabled) || registration.consumer != null && registration.consumer.isEnabled?.() !== false;
+}
+function needsSuppression(dispositions) {
+  for (const disposition of dispositions.values()) {
+    if (disposition !== 'allow') {
+      return true;
+    }
+  }
+  return false;
+}
+function coalescedHistory(event) {
+  if (typeof event.getCoalescedEvents !== 'function') {
+    return [];
+  }
+  const coalesced = event.getCoalescedEvents();
+  return coalesced.slice(0, -1).map(sample => ({
+    x: sample.clientX,
+    y: sample.clientY,
+    time: eventTime(sample)
+  }));
+}
+const hosts = new WeakMap();
+
+/** The gesture host of a document, created on first use. */
+export function getGestureHost(doc) {
+  let host = hosts.get(doc);
+  if (host == null) {
+    host = new GestureHost(doc);
+    hosts.set(doc, host);
+  }
+  return host;
+}