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

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/README.md

@@ -452,6 +452,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. */

package/src/gestures/wheelSegmenter.ts

@@ -0,0 +1,114 @@
+// 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: splits the stream into gestures and reads
+ *   a trackpad's lift (the onset of momentum)
+ * @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;
+}
+
+/** Momentum arrives at frame rate: a pause this long ends it. */
+const MOMENTUM_GAP_MS = 50;
+/** 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;
+
+/**
+ * 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. 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;
+    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 (size >= 2 && size > this.previous * 1.3 + 0.5) {
+        boundary = 'jump';
+      }
+    }
+    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) {
+      decaying = size <= this.previous * 0.995 && size >= 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 && size <= this.runStart * LIFT_DECAY) {
+        this.phase = 'momentum';
+        liftNow = true;
+      }
+    }
+    this.count += 1;
+    this.previous = size;
+    if (sign !== 0) {
+      this.sign = sign;
+    }
+    this.last = time;
+    return {
+      boundary,
+      phase: this.phase,
+      gesture: this.gesture,
+      liftNow,
+      decaying: decaying && !liftNow,
+    };
+  }
+
+  /** The gesture ended on its own (its timer): the next event starts one. */
+  end(): void {
+    this.count = 0;
+  }
+}

package/src/motion/MEASUREMENTS.md

@@ -43,7 +43,7 @@ installed); rows marked † also on iOS 18 for the pre-glass delta. iPhone
 | M-S2  | Momentum coast             | A long list (Contacts, or a probe table of 500 rows): flicks released at 1000, 2500, 5000 pt/s                                                        | contentOffset(t) from release to rest; decay constant; per-millisecond vs per-frame model; the speed at which it stops | C      | `scroll.decelerationRate`                                                                                                                         |
 | M-S3  | Bounce-back spring         | Same list: drag 120 pt past the top, hold still, release; a flick into the top edge at 3000 pt/s                                                      | contentOffset(t) after release and after edge contact; spring response and damping ratio; velocity hand-off            | C      | `scroll.bounce`                                                                                                                                   |
 | M-S5  | Rubber band                | Same list on an 852 pt view: drag 100, 300, 600 pt past the top; a horizontal pager                                                                   | displayed overflow against finger overflow; confirm c = 0.55 and d = the view's size on the axis                       | C      | `scroll.rubberBand`                                                                                                                               |
-| M-PG1 | Paging                     | Photos full-screen swipes; a probe paging scroll view                                                                                                 | page chosen per release position × velocity (thresholds; at most one page?); contentOffset(t) onto the page            | B, C   | `scroll.paging`                                                                                                                                   |
+| M-PG1 | Paging                     | Photos full-screen swipes; a probe paging scroll view                                                                                                 | page chosen per release position × velocity (thresholds; at most one page?); contentOffset(t) onto the page            | B, C   | `paging`                                                                                                                                          |
 | M-ST1 | Scroll to top              | Settings scrolled down 500, 2000, 8000 pt; tap the status bar                                                                                         | contentOffset(t); duration against distance; curve or spring fit                                                       | B, C   | `scroll.scrollToTopRate`                                                                                                                          |
 | M-N1  | Navigation push            | Settings: tap General                                                                                                                                 | incoming leading edge x(t), outgoing x(t) (parallax fraction), dimming alpha(t); animation parameters                  | A, B   | `springs.navigationPush`                                                                                                                          |
 | M-N2  | Navigation pop             | General: back button                                                                                                                                  | same as M-N1                                                                                                           | A, B   | `springs.navigationPop`                                                                                                                           |
@@ -72,6 +72,13 @@ initial velocity's sign flipped, a curve that overshoots. Push and pop are
 not Core Animation animations on iOS 26.2: UIKit writes presentation
 modifiers every frame from the main thread.
 
+## Paging (UIScrollView `isPagingEnabled`, UIPageViewController)
+
+| ID     | What                  | App and gesture                                                                          | Extract                                                                                | Method | Feeds                          |
+| ------ | --------------------- | ---------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | ------ | ------------------------------ |
+| M-PG12 | End of a settle       | Same pager: releases at rest from 10 %, 49 %, 60 % and 90 % of a page, logged at 120 fps | remaining distance and step velocity at the frame the offset lands exactly on the page | C      | `paging.integrator.restSpeed`  |
+| M-PG13 | Settle velocity floor | Same pager: steady releases from 200 to 250 pt/s in 5 pt/s steps, at 25 % of a page      | the slowest release whose `scrollViewWillEndDragging` velocity is not 0                | C      | `paging.release.velocityFloor` |
+
 ## Gestures (UIKit gesture recognizers)
 
 Thresholds the gesture system reads (`uikit/gestures.ts`). Safari on iOS runs

package/src/motion/README.md

@@ -15,8 +15,9 @@ so each keeps its measured value; no shipped component reads the roles yet.
 | ------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `uikit/`                                         | THE constants table: every spring, duration, deceleration rate, rubber-band constant and curve, with its source.                                                     |
 | `uikit/springs.ts`                               | Interaction springs (navigation, sheets, alerts, menus, controls, keyboard, banners) and the SwiftUI / UIKit presets.                                                |
-| `uikit/scroll.ts`                                | UIScrollView: deceleration rates, rubber band, bounce-back spring, paging, `delaysContentTouches`, scroll to top.                                                    |
+| `uikit/scroll.ts`                                | UIScrollView: deceleration rates, rubber band, bounce-back spring, `delaysContentTouches`, scroll to top.                                                            |
 | `uikit/timing.ts`                                | Non-spring clocks and curves: press highlight, Core Animation's named curves, keyboard, Reduced Motion cross-fade.                                                   |
+| `uikit/paging.ts`                                | A paging UIScrollView: the integrator that settles a release on its page, the page rule, the catch, `setContentOffset(animated:)`.                                   |
 | `uikit/navigation.ts`                            | UINavigationController: push velocity, parallax, dimming, transition clock, interactive pop finish rule.                                                             |
 | `uikit/gestures.ts`                              | Gesture recognizer thresholds, the velocity filter and haptic stand-ins, as `{value, unit}` entries (sources in JSDoc).                                              |
 | `roles.ts`                                       | The internal motion roles: the springs, durations and curves `spec:AST-094` FR4 names, registered by the shared tables, and a role's CSS form read back.             |
@@ -28,8 +29,8 @@ so each keeps its measured value; no shipped component reads the roles yet.
 | `coast.ts`                                       | A release's momentum curves for `animator.decay`: the coast, the edge spring, a release past an edge.                                                                |
 | `rubberBand.ts`                                  | UIScrollView's resistance past an edge, and its inverse.                                                                                                             |
 | `projection.ts`                                  | Release targets: the rest point nearest the projected coast.                                                                                                         |
+| `paging.ts`                                      | Paging: UIKit's paging settle as a playable curve, its velocity floor, the animated page scroll.                                                                     |
 | `resolveSnapPoint.ts`                            | Release policy: the snap point a release lands on (flick, back-out cancel, step limit), on `selectSnapPoint`. Internal.                                              |
-| `selectPage.ts`                                  | Paging: at most one page per release, on `resolveSnapPoint`.                                                                                                         |
 | `bezier.ts`                                      | Cubic-bézier timing functions (Core Animation's named curves).                                                                                                       |
 | `animator.ts`                                    | Compositor animator: springs, coasts and any closed-form curve compiled to Web Animations, read back analytically.                                                   |
 | `presentation.ts`                                | Where each moving element is drawn relative to where the engine hit-tests it, reported by the animator while translate runs; read by the gesture host at touch-down. |