@astryxdesign/core 0.7.6 → 0.7.7-canary.0eb44a2

package/src/gestures/GestureRecognizer.ts

@@ -36,6 +36,7 @@ import type {
   GestureTouch,
   Point,
   PointerKind,
+  ScrollType,
 } from './types';
 import {DEFAULT_ENVIRONMENT} from './types';
 
@@ -81,6 +82,16 @@ export interface GestureRecognizerOptions<R = GestureRecognizer> {
   delaysTouchesEnded?: boolean;
   /** Pointer kinds this recognizer listens to (UIKit's `allowedTouchTypes`). @default all */
   allowedPointerTypes?: ReadonlyArray<PointerKind>;
+  /**
+   * Scroll input this recognizer takes, as UIKit's `allowedScrollTypesMask`.
+   * A pan follows a trackpad's two-finger scroll (`continuous`), never a
+   * mouse wheel's notches. It moves as a contact with the content, along its
+   * own axis, after the scrollers under the pointer. A pinch takes a
+   * ctrl-wheel of either, as a trackpad pinches.
+   * @default none; a pinch takes both, the screen-edge pan none whatever a
+   *   caller passes
+   */
+  allowedScrollTypes?: ReadonlyArray<ScrollType>;
   /** Ignore a touch of a different kind than the ones already tracked. @default true */
   requiresExclusiveTouchType?: boolean;
   /**
@@ -202,6 +213,8 @@ export abstract class GestureRecognizer {
   delaysTouchesBegan: boolean;
   delaysTouchesEnded: boolean;
   allowedPointerTypes: ReadonlySet<PointerKind> | null;
+  /** See GestureRecognizerOptions.allowedScrollTypes. */
+  readonly allowedScrollTypes: ReadonlySet<ScrollType>;
   requiresExclusiveTouchType: boolean;
   /**
    * The element (or any object) the recognizer is attached to. The DOM host
@@ -247,6 +260,9 @@ export abstract class GestureRecognizer {
       options.allowedPointerTypes == null
         ? null
         : new Set(options.allowedPointerTypes);
+    this.allowedScrollTypes = new Set(
+      options.allowedScrollTypes ?? this.defaultScrollTypes,
+    );
     this.requiresExclusiveTouchType =
       options.requiresExclusiveTouchType ?? true;
   }
@@ -479,6 +495,11 @@ export abstract class GestureRecognizer {
   /** Clear per-gesture state before the next attempt. */
   protected reset(): void {}
 
+  /** The scroll types taken when the options name none (UIKit's: none). */
+  protected get defaultScrollTypes(): ReadonlyArray<ScrollType> {
+    return [];
+  }
+
   /**
    * Whether a touch may join. The base checks enabled, pointer kind and
    * exclusivity of kind; subclasses narrow it (a one-finger pan ignores a
@@ -488,6 +509,13 @@ export abstract class GestureRecognizer {
     if (!this.isEnabled) {
       return false;
     }
+    if (touch.scrollType != null) {
+      // Scroll input is no pointer: only the scroll types allowed count.
+      return (
+        this.allowedScrollTypes.has(touch.scrollType) &&
+        (this.options.shouldReceiveTouch?.(this, touch) ?? true)
+      );
+    }
     if (
       this.allowedPointerTypes != null &&
       !this.allowedPointerTypes.has(touch.pointerType)

package/src/gestures/PanGestureRecognizer.ts

@@ -73,6 +73,14 @@ export interface PanGestureRecognizerOptions extends GestureRecognizerOptions<Pa
    * at the start only (UIScrollView's directional lock).
    */
   lockAxis?: boolean;
+  /**
+   * A trackpad's two-finger scroll (`continuous`) drives the pan where its
+   * owner allows it. It moves as a contact with the content, along its own
+   * axis, after the scrollers under the pointer. A mouse wheel's notches
+   * never drive a pan; they scroll what is under the pointer.
+   * @default [] (none)
+   */
+  allowedScrollTypes?: ReadonlyArray<'continuous'>;
   /** Begin only when the native scrollers under the touch are at the edge. */
   scrollEdge?: boolean;
 }

package/src/gestures/PinchGestureRecognizer.ts

@@ -27,7 +27,12 @@ import {
   type GestureRecognizerOptions,
   type NativeTouchBehavior,
 } from './GestureRecognizer';
-import type {GestureEventContext, GestureTouch, Point} from './types';
+import type {
+  GestureEventContext,
+  GestureTouch,
+  Point,
+  ScrollType,
+} from './types';
 import {VelocityTracker} from './VelocityTracker';
 
 export interface PinchGestureRecognizerOptions extends GestureRecognizerOptions<PinchGestureRecognizer> {
@@ -51,6 +56,16 @@ export class PinchGestureRecognizer extends GestureRecognizer {
     this.hysteresis = options.hysteresis ?? UIKIT_PINCH.hysteresis.value;
   }
 
+  /** @internal The host's brand: a ctrl-wheel drives a pinch (recognizerInternals). */
+  protected get family(): 'pinch' {
+    return 'pinch';
+  }
+
+  /** A ctrl-wheel drives a pinch, from a trackpad or a mouse. */
+  protected override get defaultScrollTypes(): ReadonlyArray<ScrollType> {
+    return ['continuous', 'discrete'];
+  }
+
   /** Current span over the span the fingers started at. */
   get scale(): number {
     return this.scaleValue;

package/src/gestures/PressTracker.ts

@@ -95,6 +95,12 @@ export interface PressTrackerOptions {
    * does nothing passes none. @default undefined
    */
   selectionLock?: SelectionLock;
+  /**
+   * Whether the press of `touchId` holds the browser's context menu closed
+   * now; the host then cancels it. For a control whose hold acts, such as a
+   * switch. @default undefined
+   */
+  holdsContextMenu?: (touchId: number) => boolean;
   trackingExpansion?: number;
   /**
    * When the highlight waits `contentTouchDelay`: inside a scroller (a
@@ -312,6 +318,10 @@ export function createPressTracker(options: PressTrackerOptions): PressTracker {
       return options.isEnabled?.() !== false;
     },
 
+    holdsContextMenu(id: number): boolean {
+      return options.holdsContextMenu?.(id) === true;
+    },
+
     touchBegan(touch: GestureTouch): void {
       if (
         touchId != null ||

package/src/gestures/README.md

@@ -304,9 +304,25 @@ presses nothing.
   controller's surfaces (`usePressFeedback` rows), keep the browser's
   long-press selection; a tap never selects. A non-text input under the finger inside such an element (a checkbox, a radio, a switch's input) is locked too: WebKit's own stylesheet makes every input selectable, which no ancestor's lock reaches. A text field keeps its selection, since a held finger places its caret. A
   finger or a pen takes the lock under any primary pointer, a touchscreen
-  laptop and a desktop pen tablet included; a mouse never does, so mouse
-  selection is unchanged (`spec:AST-017` FR59); content under a sheet's or a
-  pager's pan stays selectable.
+  laptop and a desktop pen tablet included; a mouse never does
+  (`spec:AST-017` FR59).
+
+  A mouse or pen drag that a recognizer claims takes no new text selection
+  and never clears the page's (`spec:AST-094` FR41): from the claim until a
+  task after the lift (the press's own `mouseup` and `click` come in its
+  task), the claiming elements and the document refuse a selection, and the
+  selection the page had when the press began is put back over whatever the
+  press or the drag made of it. The hold starts at the claim of whichever
+  recognizer makes it, whatever its state: a swipe recognizes as `ended`
+  while the button is still down, and a recognizer that waits on another's
+  failure claims while still `possible`. A claim given back to the browser
+  (that waiting recognizer failing or cancelled, with no other owner) lets
+  the hold go, and the drag selects again. A drag that starts on selectable text (a
+  character of text that allows a selection, or a text field) is not
+  claimed: no recognizer recognizes with it while it is down, so it selects
+  text, and content under a sheet's or a pager's pan stays selectable. A
+  press a recognizer claims at its own pointerdown, before it moves, is no
+  drag, and a tap claims only at its lift.
 
 - **Claiming.** When a recognizer recognizes, it owns its touches. Each
   element with a recognizer that can claim a moving touch (a pan, a swipe, a
@@ -452,6 +468,69 @@ anywhere (often on a plain row no recognizer is on) fails a pan limited to
 one finger, so the two fingers zoom the page (WCAG 1.4.4) instead of the pan
 claiming them midway.
 
+## Wheel and trackpad
+
+A recognizer takes scroll input only where it allows that scroll type
+(`allowedScrollTypes`, UIKit's `allowedScrollTypesMask`): `continuous`
+for a trackpad's two-finger scroll or pinch, `discrete` for a mouse wheel's
+notches. A pan follows a trackpad, never a mouse wheel (`spec:AST-094` FR43,
+DEC-24): it allows only `continuous`, and none by default, so it takes a
+trackpad's scroll only where its owner allows it, its element then getting
+the one wheel listener, and a mouse wheel's notches always scroll what is
+under the pointer. A pinch allows both, for a ctrl-wheel from a trackpad or
+a mouse. The screen-edge pan takes none, as it takes no mouse, trackpad or
+pen (FR43). A control's thumb, a slider's or a switch's, tracks as a control,
+not a pan, and takes no wheel, so a page scroll over it never changes its
+value (DEC-23). The web reports no wheel phases or device, so the deltas
+tell, and what they cannot tell apart reads as a mouse wheel: a line- or
+page-mode delta; a scroll with Shift held (Shift+wheel); a pixel delta a hair
+off a whole pixel (a mouse wheel on Windows); a scroll with no legacy `wheelDelta` (an engine that
+sends none); a delta that is not a third of its legacy `wheelDelta`; or a 120
+tick over a 40 px delta. A trackpad's precise deltas, a third of their legacy
+`wheelDelta` (Chromium and WebKit), read as a trackpad.
+
+A wheel gesture drives a pan as a contact moving with the content, along the
+pan's own axis, and only once every scroller between the pointer and the
+pan's element is at its edge that way, decided at the gesture's first wheel:
+a wheel the pan does not take is never prevented. A watcher
+(`claimsTouches: false`) never takes one, and a gesture whose first wheel
+another handler already prevented, or that cannot be cancelled, stays the
+page's. A scroll-edge pan (a pull to
+refresh) takes one only if no scroller under the pointer could scroll for it,
+its own scroll owner and the page included, as its finger's rule reads them
+(`spec:AST-094` FR19); `touch-action` narrows only a finger's pan, so a wheel
+reads every scroller past it. A ctrl-wheel (a trackpad
+pinch, or Control and a mouse wheel) drives a pinch, whose scale follows
+`exp(-deltaY / 100)`; a pinch takes it by default and ends 100 ms after its
+last wheel. While the fingers move, a trackpad scroll ends 180 ms after its
+last wheel vertically and 220 ms horizontally, whoever keeps it (a pan, a
+scroller under the pointer, or the page), as a slow drag pauses between
+wheels (DEC-24). A gesture's release is never stamped
+later than an input that ends it sooner (FR16).
+
+The web reports no trackpad contact or phase either, so one splitter reads
+every trackpad stream (`wheelSegmenter.ts`, DEC-24): at the fourth or later
+delta of a shrinking run, once the run has lost a fifth of its size, the
+fingers lifted and momentum began. Until it decides,
+the shrinking deltas wait, and a pan it follows moves on at the fingers' last
+speed, never past what that speed projects. At the lift the pan keeps that
+travel and lets go there, still moving at that speed, and the momentum after
+it never moves it; when the fingers carry on instead, their moves absorb
+what the pan showed past their travel, or short of it, so it never steps
+back and ends on their travel. Fingers that stop release still, once the end
+time passes. In momentum, a reversal, a delta that grows
+against the decay, or a 50 ms pause starts a new gesture. A finger, mouse or
+pen that comes down ends it, and a wheel claim keeps the page's text
+selection. A gesture a
+recognizer took is latched to it, as a browser latches a scroller: while it
+lasts, the host hears every step first, through the shared input stream's
+window-capture listener, wherever it lands, so a pan whose element moves from
+under a still pointer keeps the gesture. A page that loses focus or hides
+cancels a trackpad pan a recognizer still drives, as it cancels every touch;
+the rest of that stream is the page's. A ctrl-wheel pinch keeps its stream,
+so the page never zooms for it, and a pan its lift released keeps its
+momentum latched until the stream ends.
+
 ## Time
 
 Every input carries its own timestamp (`event.timeStamp`), and timers are

package/src/gestures/ScreenEdgePanGestureRecognizer.ts

@@ -71,12 +71,12 @@ interface EdgeLayout {
 }
 
 /**
- * A screen-edge pan is a finger's: it takes no `allowedPointerTypes`
- * (`spec:AST-094` FR43).
+ * A screen-edge pan is a finger's: it takes no `allowedPointerTypes` and no
+ * `allowedScrollTypes`, so neither a mouse, a trackpad nor a pen drives it.
  */
 export interface ScreenEdgePanGestureRecognizerOptions extends Omit<
   PanGestureRecognizerOptions,
-  'direction' | 'allowedPointerTypes'
+  'direction' | 'allowedPointerTypes' | 'allowedScrollTypes'
 > {
   /** The edges a touch may start from. @default ['leading'] */
   edges?: ReadonlyArray<ScreenEdge>;
@@ -109,9 +109,11 @@ export class ScreenEdgePanGestureRecognizer extends PanGestureRecognizer {
       maximumNumberOfTouches: 1,
       hysteresis: UIKIT_SCREEN_EDGE_PAN.hysteresis.value,
       ...options,
-      // A finger's only: under a mouse, a trackpad or a pen the screen-edge
-      // pan stays off (`spec:AST-094` FR43), whatever a caller passes.
+      // A finger's only (`spec:AST-094` FR43). Under a mouse, a trackpad or
+      // a pen, the screen-edge pan stays off, whatever a caller passes. It
+      // takes no wheel or trackpad scrolling.
       allowedPointerTypes: ['touch'],
+      allowedScrollTypes: [],
     });
     this.edges = options.edges ?? ['leading'];
     this.edgeRegion =

package/src/gestures/nativeScroll.ts

@@ -4,7 +4,8 @@
  * @file nativeScroll.ts
  * @input An element a touch landed on
  * @output Exports createNativeScrollProbe (the NativeScrollProbe a host gives
- *   each touch) and parseTouchAction
+ *   each touch, and each wheel gesture without the touch-action narrowing)
+ *   and parseTouchAction
  * @position DOM half of the scroll coordination in packages/core/src/gestures
  *
  * Answers one question for a recognizer without letting it touch the DOM:
@@ -82,7 +83,7 @@ interface Chain {
   readonly allowsPan: boolean;
 }
 
-function buildChain(target: Element): Chain {
+function buildChain(target: Element, readsTouchAction: boolean): Chain {
   const doc = target.ownerDocument;
   const view = doc.defaultView;
   if (view == null) {
@@ -103,9 +104,11 @@ function buildChain(target: Element): Chain {
       continue;
     }
     const style = view.getComputedStyle(node);
-    const pans = parseTouchAction(style.touchAction || 'auto');
-    allowX &&= pans.x;
-    allowY &&= pans.y;
+    if (readsTouchAction) {
+      const pans = parseTouchAction(style.touchAction || 'auto');
+      allowX &&= pans.x;
+      allowY &&= pans.y;
+    }
     const isRoot = node === root || node === doc.documentElement;
     if (isRoot) {
       reachedRoot = true;
@@ -196,7 +199,10 @@ function canMoveY(element: Element, dy: number): boolean {
         element.scrollHeight - element.clientHeight - EDGE_TOLERANCE + 0.5;
 }
 
-function canMoveX(entry: ChainEntry, dx: number): boolean {
+function canMoveX(
+  entry: Pick<ChainEntry, 'element' | 'isRtl'>,
+  dx: number,
+): boolean {
   const {element} = entry;
   const overflow = element.scrollWidth - element.clientWidth;
   if (overflow <= EDGE_TOLERANCE) {
@@ -210,13 +216,47 @@ function canMoveX(entry: ChainEntry, dx: number): boolean {
     : element.scrollLeft < max - EDGE_TOLERANCE + 0.5;
 }
 
-/** A probe of the native scrollers under `target`. */
-export function createNativeScrollProbe(target: unknown): NativeScrollProbe {
+/**
+ * Whether `element` itself scrolls natively now for a finger moving by
+ * (dx, dy). It uses the probe's own test of each scroller: overflow that
+ * scrolls on that axis, and room past the edge tolerance. The position must
+ * also be short of the end it moves toward, a right-to-left range included.
+ * A wheel moves the content the other way, so pass its deltas negated.
+ */
+export function canElementScroll(
+  element: Element,
+  dx: number,
+  dy: number,
+): boolean {
+  const view = element.ownerDocument.defaultView;
+  if (view == null) {
+    return false;
+  }
+  const style = view.getComputedStyle(element);
+  if (dy !== 0 && SCROLLABLE.has(style.overflowY) && canMoveY(element, dy)) {
+    return true;
+  }
+  return (
+    dx !== 0 &&
+    SCROLLABLE.has(style.overflowX) &&
+    canMoveX({element, isRtl: isRtlElement(element as HTMLElement)}, dx)
+  );
+}
+
+/**
+ * A probe of the native scrollers under `target`. A wheel scrolls whatever
+ * `touch-action` says, which narrows only a finger's pan: a wheel's probe
+ * passes `readsTouchAction: false`.
+ */
+export function createNativeScrollProbe(
+  target: unknown,
+  {readsTouchAction = true}: {readsTouchAction?: boolean} = {},
+): NativeScrollProbe {
   let chain: Chain | null = null;
   const getChain = (): ChainEntry[] => {
     chain ??=
       target instanceof Element
-        ? buildChain(target)
+        ? buildChain(target, readsTouchAction)
         : {entries: [], allowsPan: false};
     return chain.entries;
   };

package/src/gestures/recognizerInternals.ts

@@ -20,7 +20,12 @@
 
 import type {GestureArena} from './GestureArena';
 import type {GestureRecognizer} from './GestureRecognizer';
-import type {GestureEventContext, GestureState, GestureTouch} from './types';
+import type {
+  GestureEventContext,
+  GestureState,
+  GestureTouch,
+  Point,
+} from './types';
 
 /**
  * The kinds of recognizer the host and touch-action treat specially. Each of
@@ -28,12 +33,14 @@ import type {GestureEventContext, GestureState, GestureTouch} from './types';
  * never imports a recognizer class: a page ships only the recognizers it
  * constructs.
  */
-export type RecognizerFamily = 'tap' | 'longPress' | 'pan';
+export type RecognizerFamily = 'tap' | 'longPress' | 'pan' | 'pinch';
 
 /** The members of a recognizer only the gesture system calls. */
 export interface RecognizerInternals {
   /** The recognizer's family, when the host treats it specially. */
   readonly family?: RecognizerFamily;
+  /** A pan's direction rule for a translation, `axisRatio` included. */
+  classify?(translation: Point): 'begin' | 'fail' | 'wait';
   arena: GestureArena | null;
   pending: 'began' | 'ended' | null;
   readonly seenTouchIds: Set<number>;

package/src/gestures/types.ts

@@ -21,6 +21,14 @@ export type GestureState =
 /** What made the contact. A pen on an iPad is `pen`, not `touch`. */
 export type PointerKind = 'touch' | 'mouse' | 'pen';
 
+/**
+ * Scroll input a recognizer can take, as UIKit's `UIScrollTypeMask`: a
+ * trackpad's two-finger scroll or pinch (`continuous`), or a mouse wheel's
+ * notches (`discrete`). A pan takes only a trackpad's; a pinch takes a
+ * ctrl-wheel of either.
+ */
+export type ScrollType = 'continuous' | 'discrete';
+
 export interface Point {
   readonly x: number;
   readonly y: number;
@@ -85,6 +93,8 @@ export interface GestureTouch {
   readonly target: unknown;
   /** The native scrollers under the contact, when the host knows them. */
   readonly scroll: NativeScrollProbe | null;
+  /** Set for a wheel's or a trackpad's scroll input, which is no contact. */
+  readonly scrollType?: ScrollType;
   /** The browser took this contact for its own pan or zoom. */
   takenByBrowser: boolean;
 }
@@ -104,6 +114,8 @@ export interface TouchBeganInput extends TouchInput {
   readonly pointerType: PointerKind;
   readonly target: unknown;
   readonly scroll?: NativeScrollProbe | null;
+  /** Set for a wheel's or a trackpad's scroll input. */
+  readonly scrollType?: ScrollType;
 }
 
 /** What a recognizer is told alongside the touches that changed. */
@@ -190,6 +202,12 @@ export interface TouchConsumer {
    * undefined and keeps the browser's long-press selection.
    */
   readonly selectionLock?: SelectionLock;
+  /**
+   * Whether this touch's press holds the browser's context menu closed now.
+   * A control whose hold acts uses it (a switch's hold toggles it). The host
+   * then cancels the menu, as for a claimed touch.
+   */
+  holdsContextMenu?(touchId: number): boolean;
   /**
    * Whether the consumer takes touches now (a disabled control does not).
    * The host listens only while something enabled is attached

package/src/gestures/usePressTracker.ts

@@ -132,6 +132,8 @@ export function usePressTracker(
           recognizer,
         ),
       isEnabled: () => optionsRef.current.isEnabled?.() ?? true,
+      holdsContextMenu: id =>
+        optionsRef.current.holdsContextMenu?.(id) === true,
       // The caller's brake, or the host's: a touch that stops a flick
       // presses nothing, as a UIKit control in a decelerating scroll view.
       isBraking: touch => {

package/src/gestures/wheelSegmenter.ts

@@ -0,0 +1,143 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file wheelSegmenter.ts
+ * @input A wheel stream's deltas along one axis, with their event times
+ * @output Exports WheelSegmenter and isBunched. WheelSegmenter splits the
+ *   stream into gestures and reads a trackpad's lift (the onset of momentum).
+ *   isBunched tells one stall's merge from a frame.
+ * @position Read by GestureHost.ts's wheel input: the web reports no
+ *   trackpad contact or phase, so both are inferred.
+ */
+
+export type WheelBoundary = 'first' | 'idle' | 'reversal' | 'jump' | 'gap';
+export type WheelPhase = 'finger' | 'momentum';
+
+export interface WheelSegment {
+  /** Why this event starts a new gesture, or null when it continues one. */
+  readonly boundary: WheelBoundary | null;
+  readonly phase: WheelPhase;
+  /** The gesture's number, counting from 1. */
+  readonly gesture: number;
+  /** This event is where the fingers lifted (momentum begins with it). */
+  readonly liftNow: boolean;
+  /** This event shrank, so it may be momentum: hold it until known. */
+  readonly decaying: boolean;
+  /** This event came so soon after the one before that it is a merge. */
+  readonly bunched: boolean;
+}
+
+/** Momentum arrives at frame rate: a pause this long ends it. */
+const MOMENTUM_GAP_MS = 50;
+/**
+ * A wheel this close to the one before, ms, is one stall's merge. Frames come
+ * further apart at every display rate up to 500 Hz, which is 2 ms.
+ */
+const BUNCHED_MS = 1.5;
+/** Shrinking deltas in a row before the lift is read. */
+const LIFT_RUN = 4;
+/** And how much of its size the run has lost by then. */
+const LIFT_DECAY = 0.8;
+
+/**
+ * Whether a wheel `intervalMs` after the one before is one stall's merge, not
+ * a frame. A stalled page receives the wheels it held back together, within
+ * 1.5 ms of each other. The rule reads no history, so slow wheels never make
+ * a real frame look like a merge.
+ */
+export function isBunched(intervalMs: number): boolean {
+  return intervalMs <= BUNCHED_MS;
+}
+
+/**
+ * A trackpad gesture has a finger phase and, after a fling, a momentum phase.
+ * In the finger phase, deltas come while the fingers move, with pauses when
+ * they move slowly. In the momentum phase, deltas come at frame rate and
+ * shrink smoothly. The lift is the start of a run of shrinking deltas that
+ * has lost a fifth of its size. In the finger phase, a pause of `idleMs`
+ * ends the gesture. In the momentum phase, a reversal, a jump up against the
+ * decay, or a pause of 50 ms starts a new gesture. A bunched wheel is never
+ * a jump. The decay reads it by its last step. Momentum never pauses,
+ * reverses or grows.
+ */
+export class WheelSegmenter {
+  gesture = 0;
+  phase: WheelPhase = 'finger';
+  private last = -Infinity;
+  private previous = 0;
+  private sign = 0;
+  private count = 0;
+  private run = 0;
+  private runStart = 0;
+
+  push(time: number, delta: number, idleMs: number): WheelSegment {
+    const size = Math.abs(delta);
+    const sign = Math.sign(delta);
+    const gap = time - this.last;
+    const bunched = this.count > 0 && isBunched(gap);
+    let boundary: WheelBoundary | null = null;
+    if (this.count === 0) {
+      boundary = this.gesture === 0 ? 'first' : 'idle';
+    } else if (this.phase === 'finger' && gap >= idleMs) {
+      boundary = 'idle';
+    } else if (this.phase === 'momentum') {
+      if (sign !== 0 && this.sign !== 0 && sign !== this.sign) {
+        boundary = 'reversal';
+      } else if (gap >= MOMENTUM_GAP_MS) {
+        boundary = 'gap';
+      } else if (!bunched && size >= 2 && size > this.previous * 1.3 + 0.5) {
+        boundary = 'jump';
+      }
+    }
+    // A bunched wheel carries the steps of the frames it merged. The decay
+    // goes on from its last step, so the steps after it read as they are.
+    const steps =
+      boundary == null && bunched && this.previous > 0
+        ? Math.max(1, Math.round(size / this.previous))
+        : 1;
+    if (boundary != null) {
+      this.gesture += 1;
+      this.phase = 'finger';
+      this.count = 0;
+      this.run = 0;
+    }
+    let liftNow = false;
+    let decaying = false;
+    if (this.phase === 'finger' && this.count >= 3 && size > 0) {
+      // A bunched wheel is read by its last step, as the decay goes on from it.
+      const step = size / steps;
+      decaying = step <= this.previous * 0.995 && step >= this.previous * 0.5;
+      if (decaying) {
+        if (this.run === 0) {
+          this.runStart = this.previous;
+        }
+        this.run += 1;
+      } else {
+        this.run = 0;
+      }
+      if (this.run >= LIFT_RUN && step <= this.runStart * LIFT_DECAY) {
+        this.phase = 'momentum';
+        liftNow = true;
+      }
+    }
+    this.count += 1;
+    this.previous = size / steps;
+    if (sign !== 0) {
+      this.sign = sign;
+    }
+    this.last = time;
+    return {
+      boundary,
+      phase: this.phase,
+      gesture: this.gesture,
+      liftNow,
+      decaying: decaying && !liftNow,
+      bunched: boundary == null && bunched,
+    };
+  }
+
+  /** The gesture ended on its own (its timer): the next event starts one. */
+  end(): void {
+    this.count = 0;
+  }
+}