@astryxdesign/core 0.7.7-canary.36f8ea1 → 0.7.7-canary.550ff21

package/src/gestures/GestureHost.ts

@@ -177,7 +177,13 @@ import {
 } from '../utils/clickGuard';
 import {subscribeInput} from '../utils/inputStream';
 import {isPrimaryClick} from '../utils/primaryClick';
-import {locksSelectionFor} from '../utils/selectionLock';
+import {
+  type DragSelectionReleaseOptions,
+  lockDragSelection,
+  locksSelectionFor,
+  selectionRangesOf,
+  startsOnSelectableText,
+} from '../utils/selectionLock';
 import {isCoarsePointer, watchCoarsePointer} from '../utils/coarsePointer';
 import {gestureHosts} from './hostRegistry';
 
@@ -635,7 +641,35 @@ export class GestureHost {
   /** Cancels the scheduled next-frame read (readCallerTouchActionInNextFrame). */
   private cancelCallerRead: (() => void) | null = null;
   /** The selection lock each contact holds, by host contact id. */
-  private readonly lockedBy = new Map<number, () => void>();
+  private readonly lockedBy = new Map<
+    number,
+    (options?: DragSelectionReleaseOptions) => void
+  >();
+  /**
+   * The page's selection when each mouse or pen press began: a drag a
+   * recognizer claims keeps it.
+   */
+  private readonly pressSelections = new Map<
+    number,
+    ReadonlyArray<AbstractRange>
+  >();
+  /**
+   * Mouse and pen contacts that began on selectable text. Once one moves, the
+   * browser keeps the drag for a selection, and no recognizer claims it.
+   */
+  private readonly selectingContacts = new Set<number>();
+  /**
+   * Drag selection holds until their last task ends, a task after their lift
+   * (lockDragSelection); the last detach ends them at once.
+   */
+  private readonly dragHolds = new Set<
+    (options?: DragSelectionReleaseOptions) => void
+  >();
+  /** Each claimed contact's drag hold, until its lift or a give-back. */
+  private readonly claimHolds = new Map<
+    number,
+    (options?: DragSelectionReleaseOptions) => void
+  >();
   private readonly presentedHitTesting: 'auto' | 'always' | 'never';
   /**
    * Contacts sent to what is drawn instead of what the engine hit, by host
@@ -816,6 +850,11 @@ export class GestureHost {
       // tap) ends here: an armed press stops listening (FR24).
       onIdle: () => this.releaseArmedPress(),
       onTransition: options.onTransition,
+      onClaim: (ids, claimer) => this.lockClaimedDrags(ids, claimer),
+      onRelease: ids => this.releaseClaimedDrags(ids),
+      refusesClaim: touch =>
+        this.selectingContacts.has(touch.id) &&
+        (touch.x !== touch.startX || touch.y !== touch.startY),
     });
     const view = doc.defaultView;
     // A test may pass its own read; otherwise the one coarse-pointer gate,
@@ -1779,6 +1818,13 @@ export class GestureHost {
       }
       this.ownScrollFrames.clear();
       this.ownedScrolls.clear();
+      // A drag's hold whose press lifted in this task ends now, not a task
+      // later: nothing is attached to meet its mouseup or click.
+      for (const release of [...this.dragHolds]) {
+        release({isCancel: true});
+      }
+      this.pressSelections.clear();
+      this.selectingContacts.clear();
     });
   }
 
@@ -2506,6 +2552,94 @@ export class GestureHost {
     }
   }
 
+  /**
+   * Hold the page's selection for a mouse or pen contact that a recognizer
+   * claims. Examples are a pan's drag and a press a group claims at its own
+   * pointerdown. While the contact is down, the claiming recognizers'
+   * elements refuse a new selection. The selection the page had at the press
+   * is put back over anything that replaced it. That includes the press's own
+   * collapse and a selection the drag made before its claim. The claiming
+   * recognizer's element holds from its claim, in any state: a waiting
+   * recognizer claims while possible, and a swipe claims as ended. The
+   * participants that already recognize hold too. A claim given back to the
+   * browser lets its hold go (releaseClaimedDrags). A drag that starts on
+   * selectable text never gets here, because no recognizer claims it
+   * (`selectingContacts`). A tap claims only at its lift, so a click keeps
+   * the selection it made. A finger keeps the touch-down lock alone.
+   */
+  private lockClaimedDrags(
+    ids: ReadonlyArray<number>,
+    claimer: GestureRecognizer,
+  ): void {
+    for (const id of ids) {
+      if (this.claimHolds.has(id)) {
+        continue;
+      }
+      const touch = this.arena.touches.find(each => each.id === id);
+      // A claim made at the contact's own lift (a tap's) holds nothing: the
+      // drag is over, and a click keeps the selection it made. A wheel's
+      // contact keeps the page's selection, as a scroll does.
+      if (
+        touch == null ||
+        touch.pointerType === 'touch' ||
+        touch.scrollType != null ||
+        touch.phase === 'ended' ||
+        touch.phase === 'cancelled'
+      ) {
+        continue;
+      }
+      const elements = new Set<Element>();
+      for (const recognizer of this.arena.participantsOf(id)) {
+        if (
+          (recognizer.state === 'began' || recognizer.state === 'changed') &&
+          (recognizer.view as Node | null)?.nodeType === 1
+        ) {
+          elements.add(recognizer.view as Element);
+        }
+      }
+      if ((claimer.view as Node | null)?.nodeType === 1) {
+        elements.add(claimer.view as Element);
+      }
+      if (elements.size === 0) {
+        continue;
+      }
+      const release = lockDragSelection(
+        elements,
+        this.doc.defaultView,
+        this.pressSelections.get(id) ?? [],
+        () => {
+          this.dragHolds.delete(release);
+        },
+      );
+      this.dragHolds.add(release);
+      // A press lock the contact took at its press stays in `lockedBy`. The
+      // hold sits beside it, and the contact's end releases both.
+      if (!this.lockedBy.has(id)) {
+        this.lockedBy.set(id, release);
+      }
+      this.claimHolds.set(id, release);
+    }
+  }
+
+  /**
+   * Claimed contacts the arena gave back. Their drag holds end at once, so
+   * the browser's drag selects again. A contact's press lock (lockSelection)
+   * is not a drag hold and stays.
+   */
+  private releaseClaimedDrags(ids: ReadonlyArray<number>): void {
+    for (const id of ids) {
+      const release = this.claimHolds.get(id);
+      if (release == null) {
+        continue;
+      }
+      this.claimHolds.delete(id);
+      if (this.lockedBy.get(id) === release) {
+        this.lockedBy.delete(id);
+      }
+      release({isCancel: true});
+    }
+  }
+
   /**
    * End the trackpad pan a recognizer still drives, when the page loses focus
    * or hides, and return its contacts to cancel. The rest of its stream is
@@ -2583,10 +2717,44 @@ export class GestureHost {
     );
   }
 
-  /** Undo `lockSelection` for a contact that ended; idempotent. */
-  private unlockSelection(id: number): void {
-    this.lockedBy.get(id)?.();
+  /**
+   * At a mouse or pen press, mark one that lands on selectable text: once it
+   * moves, it is the browser's drag, and selects text.
+   * Text whose hold does something is locked at this press already
+   * (lockSelection), so it is not selectable text.
+   */
+  private noteSelectingPress(
+    id: number,
+    x: number,
+    y: number,
+    target: EventTarget | null,
+  ): void {
+    if (
+      !this.lockedBy.has(id) &&
+      startsOnSelectableText(this.doc, x, y, target)
+    ) {
+      this.selectingContacts.add(id);
+    }
+  }
+
+  /**
+   * Undo a contact's selection locks, its press lock and its drag hold, at
+   * once for a cancel, and forget its press's selection; idempotent. A
+   * drag's hold keeps its last task after a lift (lockDragSelection).
+   */
+  private unlockSelection(id: number, isCancel = false): void {
+    const lock = this.lockedBy.get(id);
+    lock?.({isCancel});
+    // A press lock keeps `lockedBy` when the contact also has a drag hold.
+    // Release the hold too.
+    const hold = this.claimHolds.get(id);
+    if (hold != null && hold !== lock) {
+      hold({isCancel});
+    }
     this.lockedBy.delete(id);
+    this.claimHolds.delete(id);
+    this.pressSelections.delete(id);
+    this.selectingContacts.delete(id);
   }
 
   // --- Touch events ----------------------------------------------------------
@@ -3349,6 +3517,11 @@ export class GestureHost {
     if (target !== landed && target != null) {
       this.retargeted.set(id, {x: event.clientX, y: event.clientY, target});
     }
+    // Before the arena admits it: a press a group claims at its own
+    // pointerdown keeps the selection the page has now.
+    if (event.pointerType !== 'touch') {
+      this.pressSelections.set(id, selectionRangesOf(this.doc.defaultView));
+    }
     this.arena.began([
       {
         id,
@@ -3373,6 +3546,10 @@ export class GestureHost {
         consumerElement,
       );
     }
+    if (event.pointerType !== 'touch') {
+      // The engine's own hit: the text its caret query and a drag select.
+      this.noteSelectingPress(id, event.clientX, event.clientY, landed);
+    }
   };
 
   private readonly onPointerMove = (event: PointerEvent): void => {
@@ -3524,7 +3701,7 @@ export class GestureHost {
     const id = this.pointerIds.get(event.pointerId);
     if (id != null) {
       this.pointerIds.delete(event.pointerId);
-      this.unlockSelection(id);
+      this.unlockSelection(id, true);
       this.retargeted.delete(id);
       this.arena.cancelled([id], eventTime(event));
     }
@@ -3765,7 +3942,7 @@ export class GestureHost {
   private cancelEverything(time: number): void {
     const ids = [...this.pointerIds.values()];
     for (const id of ids) {
-      this.unlockSelection(id);
+      this.unlockSelection(id, true);
     }
     for (const identifier of [...this.touchIds.keys()]) {
       // The browser may keep the touch alive: its lift must not click.

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

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

@@ -7,7 +7,8 @@ source), the spring, decay, rubber-band and projection math UIKit uses, and a
 compositor animator that plays it. Nothing here is exported from the package
 entry point. Core's motion and gesture modules read the table by path;
 components read touch motion through its internal motion roles (`roles.ts`),
-so each keeps its measured value; no shipped component reads the roles yet.
+so each keeps its measured value; ProgressBar plays the progress table's two
+roles through `resolveMotion`.
 
 ## Files
 
@@ -15,9 +16,11 @@ 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/progressBar.ts`                           | UIProgressView's fill: the whole-track duration and curve (two roles), its minimum length and empty alpha.                                                           |
 | `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.             |
 | `roleValue.ts`                                   | A role's CSS form, written: a spring's duration and bounce, a duration in ms, a curve's `cubic-bezier()`.                                                            |
@@ -28,8 +31,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. |

package/src/motion/animator.ts

@@ -1052,7 +1052,7 @@ export function createAnimator(
     if (segment == null) {
       return null;
     }
-    if (time >= segment.start + segment.duration) {
+    if (time >= endOf(property, segment)) {
       return null;
     }
     return segment;
@@ -1089,6 +1089,53 @@ export function createAnimator(
       ? null
       : {latest, start: segment.start + latest - segment.group.provisional};
 
+  /**
+   * When a waiting curve's call had its first frame, which put the curve on
+   * screen. Undefined for a curve that does not wait, or whose call has had
+   * no first frame.
+   */
+  const shownSince = (
+    property: MotionProperty,
+    segment: Segment,
+  ): number | undefined =>
+    segment.group?.resolved === false
+      ? segment.group.latest?.get(CHANNEL_OF[property])
+      : undefined;
+
+  /** A curve's end, dated from its call's first frame while it waits. */
+  const endOf = (property: MotionProperty, segment: Segment): number =>
+    (datedFromLatest(segment, shownSince(property, segment))?.start ??
+      segment.start) + segment.duration;
+
+  /**
+   * Takes a curve on screen out of the call that still waits for the
+   * browser's start. The curve keeps its course, dated from the call's first
+   * frame. A call that has no channel left starts at that frame.
+   */
+  const leaveWaitingCall = (
+    segment: Segment,
+    channel: Channel,
+    latest: number,
+  ) => {
+    const group = segment.group;
+    if (group == null) {
+      return;
+    }
+    const index = group.segments.indexOf(segment);
+    if (index >= 0) {
+      group.segments.splice(index, 1);
+    }
+    segment.start += latest - group.provisional;
+    segment.group = undefined;
+    if (!CHANNELS[channel].some(p => segments.get(p)?.group === group)) {
+      group.latest?.delete(channel);
+      group.channels.delete(channel);
+    }
+    if (group.channels.size === 0 && group.segments.length === 0) {
+      resolveGroup(group, latest);
+    }
+  };
+
   /**
    * The value on screen at `time`. Until the browser reports its start, a
    * held curve shows its first value. A frame that ran without that start
@@ -1316,12 +1363,25 @@ export function createAnimator(
     // Settled curves become resting values.
     for (const property of properties) {
       const segment = segments.get(property);
-      if (segment != null && time >= segment.start + segment.duration) {
+      if (segment != null && time >= endOf(property, segment)) {
         resting[property] = segment.target;
         segments.delete(property);
       }
     }
     const moving = properties.filter(p => segments.has(p));
+    if (callGroup == null) {
+      // A call that starts now rebuilds a channel the compositor has moving
+      // since a first frame without a known start. The channel carries on
+      // from that frame, with a start of its own, instead of starting its
+      // curve again.
+      for (const property of moving) {
+        const segment = segments.get(property) as Segment;
+        const latest = shownSince(property, segment);
+        if (latest != null) {
+          leaveWaitingCall(segment, channel, latest);
+        }
+      }
+    }
     // An explicit call can rebuild a channel while one of its curves still
     // waits for the browser's start. The animation then joins the current
     // call, or else that waiting call, with no start of its own.
@@ -2017,10 +2077,14 @@ export function createAnimator(
     for (const channel of start === 'commit' ? [] : channels) {
       for (const property of CHANNELS[channel]) {
         const segment = segments.get(property);
+        // A call's first frame puts its channels on screen, even before the
+        // browser reports the start. So such a channel is not at rest either.
         if (
           segment != null &&
-          time < segment.start + segment.duration &&
-          (segment.group == null || segment.group.resolved)
+          time < endOf(property, segment) &&
+          (segment.group == null ||
+            segment.group.resolved ||
+            shownSince(property, segment) != null)
         ) {
           return null;
         }
@@ -3739,9 +3803,11 @@ export function createAnimator(
         }
         owners.add(segment.owner);
         // A curve still waiting for the browser's start stays in its call:
-        // it starts with that call's commit.
+        // it starts with that call's commit. A curve whose call had its first
+        // frame is on screen already, so it leaves the call (leaveWaitingCall).
+        const latest = shownSince(property, segment);
         const group =
-          segment.group != null && !segment.group.resolved
+          latest == null && segment.group != null && !segment.group.resolved
             ? segment.group
             : undefined;
         const replace = (next: Segment) => {
@@ -3758,6 +3824,9 @@ export function createAnimator(
         if (segment.spring != null) {
           const from = valueAt(property, time) + delta;
           const velocity = velocityAt(property, time);
+          if (latest != null) {
+            leaveWaitingCall(segment, CHANNEL_OF[property], latest);
+          }
           const curve = solveSpring(toSpring(segment.spring), {
             from,
             to: segment.target,
@@ -3778,6 +3847,9 @@ export function createAnimator(
             spring: segment.spring,
           });
         } else {
+          if (latest != null) {
+            leaveWaitingCall(segment, CHANNEL_OF[property], latest);
+          }
           replace({
             ...segment,
             target: segment.target + delta,

package/src/motion/paging.ts

@@ -0,0 +1,138 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file paging.ts
+ * @input A release velocity, a settle's start, end and velocity, and the UIKit
+ *   paging constants
+ * @output Exports `pagingSettleVelocity`, `solvePaging` (UIKit's paging settle
+ *   as a curve the animator plays) and `solveAnimatedPageScroll`
+ * @position Pure math, with no DOM and no React
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/motion/paging.test.ts
+ * - /packages/core/src/motion/README.md
+ */
+
+import type {MotionCurve} from './animator';
+import {paging} from './uikit/paging';
+
+/**
+ * The velocity a paging settle starts at. It is the release velocity that every
+ * gesture reads, zeroed below `velocityFloor`. The page choice reads the
+ * release velocity itself.
+ */
+export function pagingSettleVelocity(velocity: number): number {
+  return Math.abs(velocity) < paging.release.velocityFloor ? 0 : velocity;
+}
+
+/** A paging settle: the curve and where it ends. */
+export interface PagingCurve extends MotionCurve {
+  readonly from: number;
+  readonly to: number;
+  /** Integration steps the settle took. */
+  readonly steps: number;
+}
+
+/**
+ * UIKit's paging settle from `from` (px), moving at `velocity` (px/s), onto
+ * `to`. It steps `paging.integrator` `stepsPerSecond` times a second and ends
+ * exactly on `to`. The same motion returns an overscrolled pager to its first
+ * or last page.
+ *
+ * Positions are content offsets along the paging axis, 0 at page 0 and growing
+ * toward later pages. Velocities are px/s of that offset.
+ *
+ * No closed form reproduces the per-frame stepping, so the settle integrates
+ * once into a table, and the curve reads the table. A release needs at most
+ * about 400 steps, well under a millisecond of work.
+ *
+ * The release velocity enters in px per millisecond per step, as UIKit hands it
+ * to the integrator. At 960 steps a second, the content starts at 96 % of the
+ * finger's speed, as in UIKit.
+ */
+export function solvePaging({
+  from,
+  velocity,
+  to,
+}: {
+  from: number;
+  velocity: number;
+  to: number;
+}): PagingCurve {
+  const {springPull, friction, stepsPerSecond, restDistance, restSpeed} =
+    paging.integrator;
+  const xs: number[] = [from];
+  const vs: number[] = [velocity / 1000];
+  let x = from;
+  let v = velocity / 1000;
+  // ~10 s of steps: far beyond any settle (≈ 0.35 s from rest).
+  const maxSteps = stepsPerSecond * 10;
+  let steps = 0;
+  while (steps < maxSteps) {
+    if (Math.abs(to - x) < restDistance && Math.abs(v) < restSpeed) {
+      break;
+    }
+    v = (v + (to - x) * springPull) * friction;
+    x += v;
+    steps += 1;
+    xs.push(x);
+    vs.push(v);
+  }
+  xs[xs.length - 1] = to;
+  vs[vs.length - 1] = 0;
+  const duration = steps / stepsPerSecond;
+  const last = xs.length - 1;
+  const read = (table: number[], t: number): number => {
+    if (!(t > 0)) {
+      return table[0];
+    }
+    const s = t * stepsPerSecond;
+    if (s >= last) {
+      return table[last];
+    }
+    const i = Math.floor(s);
+    const f = s - i;
+    return table[i] + (table[i + 1] - table[i]) * f;
+  };
+  return {
+    from,
+    to,
+    steps,
+    duration,
+    at: t => read(xs, t),
+    // px per step × steps per second
+    velocity: t => read(vs, t) * stepsPerSecond,
+  };
+}
+
+/**
+ * `setContentOffset(_:animated:)`: `paging.animatedScroll.duration` on a
+ * sinusoidal ease-in-out, whatever the distance. UIKit starts it from the
+ * current offset and drops any velocity, as here.
+ */
+export function solveAnimatedPageScroll({
+  from,
+  to,
+}: {
+  from: number;
+  to: number;
+}): MotionCurve {
+  const {duration} = paging.animatedScroll;
+  const distance = to - from;
+  return {
+    duration,
+    at: t => {
+      const u = Math.min(1, Math.max(0, t / duration));
+      return from + (distance * (1 - Math.cos(Math.PI * u))) / 2;
+    },
+    velocity: t => {
+      if (t <= 0 || t >= duration) {
+        return 0;
+      }
+      return (
+        ((distance * Math.PI) / (2 * duration)) *
+        Math.sin((Math.PI * t) / duration)
+      );
+    },
+  };
+}

package/src/motion/uikit/index.ts

@@ -4,9 +4,9 @@
  * @file index.ts
  * @input The domain files of the UIKit constants table
  * @output Re-exports `springs` and one constant per spring (`SHEET_PRESENT_SPRING`,
- *   …), `scroll`, `timing`, `navigation`, the `slider` domain and the
- *   gesture thresholds (one `UIKIT_*` group per recognizer, their union
- *   `UIKIT_GESTURES`, and the haptic tables)
+ *   …), `scroll`, `timing`, `navigation`, `progressBar`, the `slider` domain
+ *   and the gesture thresholds (one `UIKIT_*` group per recognizer, their
+ *   union `UIKIT_GESTURES`, and the haptic tables)
  * @position Entry of the UIKit constants table (motion/uikit). Internal to
  *   core: not exported from the package entry point
  *
@@ -39,6 +39,7 @@ export {
   type HapticFeedbackKind,
 } from './gestures';
 export {navigation, registerNavigationTable} from './navigation';
+export {progressBar, registerProgressBarTable} from './progressBar';
 export {registerScrollTable, scroll} from './scroll';
 export {slider} from './slider';
 export {