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

package/src/motion/MEASUREMENTS.md

@@ -37,27 +37,28 @@ installed); rows marked † also on iOS 18 for the pre-glass delta. iPhone
 
 ## Shared (foundation)
 
-| ID    | What                       | App and gesture                                                                                                                                       | Extract                                                                                                                | Method | Feeds                                                                                                                                             |
-| ----- | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------- |
-| M-S1  | Deceleration rates         | none                                                                                                                                                  | `UIScrollView.DecelerationRate.normal.rawValue`, `.fast.rawValue`                                                      | D      | `scroll.decelerationRate`                                                                                                                         |
-| 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-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`                                                                                                                           |
-| M-N3  | Interactive pop            | Settings ▸ General: edge swipe released at 40 % of the width at 600 pt/s (finishes) and at 30 % at rest (cancels)                                     | x(t) after release; spring parameters; the finish / cancel rule (position, velocity)                                   | A, B   | `springs.navigationInteractivePopFinish`                                                                                                          |
-| M-A1  | Alert                      | Probe app: `UIAlertController(.alert)` presented and dismissed                                                                                        | scale(t), alpha(t) of the alert and the dimming view; animation parameters                                             | A      | `springs.alertPresent`, `.alertDismiss`                                                                                                           |
-| M-AS1 | Action sheet and menu      | Probe app: `.actionSheet`; a button with a `UIMenu` as its primary action; Files: the … menu                                                          | scale, alpha, position (t) on open and close; animation parameters                                                     | A, B   | `springs.actionSheet*`, `.menu*`                                                                                                                  |
-| M-CM1 | Context menu               | Files: long-press an item; dismiss by tapping outside                                                                                                 | preview scale(t) on lift, backdrop blur and dim (t), menu scale(t); the preview's return on dismiss                    | A, B   | `springs.contextMenu*`                                                                                                                            |
-| M-K1  | UIKit legacy spring        | Probe app: `UIView.animate(withDuration:usingSpringWithDamping:initialSpringVelocity:)`, durations 0.3, 0.5, 1 × ratios 0.5, 0.8, 1 × velocities 0, 2 | the `CASpringAnimation` UIKit attaches: mass, stiffness, damping, initialVelocity, duration, settlingDuration          | A      | `springs.ts` (UIKit's legacy springs)                                                                                                             |
-| M-K2  | Default spring, keyboard   | Probe app: an animator with `UISpringTimingParameters()`; focus and blur a text field                                                                 | both springs' parameters and allowsOverdamping; the keyboard notification's duration and curve                         | A, D   | `springs.viewChange`, `.keyboard`, `timing.keyboard*`                                                                                             |
-| M-CA1 | Settling duration          | none: `CASpringAnimation` mass 1, stiffness 100, damping 5, 10, 15, 20, 40 × initialVelocity 0, 5, −5 × allowsOverdamping on, off                     | `settlingDuration` of each (checks the critically damped and overdamped branches)                                      | D      | `springs.ts` (settling)                                                                                                                           |
-| M-T1  | Banner                     | A notification pushed to the simulator while an app is in the foreground                                                                              | banner y(t) in and out; time on screen                                                                                 | B      | `springs.banner`                                                                                                                                  |
-| M-RM1 | Reduced Motion             | Reduce Motion on, Prefer Cross-Fade Transitions on and off: Settings push and pop, an alert (sheets: M-SH13; controls: M-SW11, M-SL12, M-SG15)        | which transitions become cross-fades; alpha(t), duration and curve; what still moves                                   | B      | `timing.reducedMotionCrossFadeMs` (played at 200 ms: `design:reduced-motion` DR2 caps it, DEC-1 of 2026-10-24, departing from the measured 0.5 s) |
-| M-PR1 | Press release curve        | Settings and Contacts: a row tapped and released (the deselect cross-fade)                                                                            | the timing function Core Animation attaches to the deselect fade (control points)                                      | A      | `timing.press.highlightOutCurve`                                                                                                                  |
-| M-NB1 | Navigation bar hide / show | none                                                                                                                                                  | `UINavigationController.hideShowBarDuration`                                                                           | D      | `timing.navigationBarHideShowMs`                                                                                                                  |
+| ID    | What                       | App and gesture                                                                                                                                       | Extract                                                                                                                                        | Method | Feeds                                                                                                                                             |
+| ----- | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| M-S1  | Deceleration rates         | none                                                                                                                                                  | `UIScrollView.DecelerationRate.normal.rawValue`, `.fast.rawValue`                                                                              | D      | `scroll.decelerationRate`                                                                                                                         |
+| 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   | `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`                                                                                                                           |
+| M-N3  | Interactive pop            | Settings ▸ General: edge swipe released at 40 % of the width at 600 pt/s (finishes) and at 30 % at rest (cancels)                                     | x(t) after release; spring parameters; the finish / cancel rule (position, velocity)                                                           | A, B   | `springs.navigationInteractivePopFinish`                                                                                                          |
+| M-A1  | Alert                      | Probe app: `UIAlertController(.alert)` presented and dismissed                                                                                        | scale(t), alpha(t) of the alert and the dimming view; animation parameters                                                                     | A      | `springs.alertPresent`, `.alertDismiss`                                                                                                           |
+| M-AS1 | Action sheet and menu      | Probe app: `.actionSheet`; a button with a `UIMenu` as its primary action; Files: the … menu                                                          | scale, alpha, position (t) on open and close; animation parameters                                                                             | A, B   | `springs.actionSheet*`, `.menu*`                                                                                                                  |
+| M-CM1 | Context menu               | Files: long-press an item; dismiss by tapping outside                                                                                                 | preview scale(t) on lift, backdrop blur and dim (t), menu scale(t); the preview's return on dismiss                                            | A, B   | `springs.contextMenu*`                                                                                                                            |
+| M-K1  | UIKit legacy spring        | Probe app: `UIView.animate(withDuration:usingSpringWithDamping:initialSpringVelocity:)`, durations 0.3, 0.5, 1 × ratios 0.5, 0.8, 1 × velocities 0, 2 | the `CASpringAnimation` UIKit attaches: mass, stiffness, damping, initialVelocity, duration, settlingDuration                                  | A      | `springs.ts` (UIKit's legacy springs)                                                                                                             |
+| M-K2  | Default spring, keyboard   | Probe app: an animator with `UISpringTimingParameters()`; focus and blur a text field                                                                 | both springs' parameters and allowsOverdamping; the keyboard notification's duration and curve                                                 | A, D   | `springs.viewChange`, `.keyboard`, `timing.keyboard*`                                                                                             |
+| M-CA1 | Settling duration          | none: `CASpringAnimation` mass 1, stiffness 100, damping 5, 10, 15, 20, 40 × initialVelocity 0, 5, −5 × allowsOverdamping on, off                     | `settlingDuration` of each (checks the critically damped and overdamped branches)                                                              | D      | `springs.ts` (settling)                                                                                                                           |
+| M-T1  | Banner                     | A notification pushed to the simulator while an app is in the foreground                                                                              | banner y(t) in and out; time on screen                                                                                                         | B      | `springs.banner`                                                                                                                                  |
+| M-RM1 | Reduced Motion             | Reduce Motion on, Prefer Cross-Fade Transitions on and off: Settings push and pop, an alert (sheets: M-SH13; controls: M-SW11, M-SL12, M-SG15)        | which transitions become cross-fades; alpha(t), duration and curve; what still moves                                                           | B      | `timing.reducedMotionCrossFadeMs` (played at 200 ms: `design:reduced-motion` DR2 caps it, DEC-1 of 2026-10-24, departing from the measured 0.5 s) |
+| M-PR1 | Press release curve        | Settings and Contacts: a row tapped and released (the deselect cross-fade)                                                                            | the timing function Core Animation attaches to the deselect fade (control points)                                                              | A      | `timing.press.highlightOutCurve`                                                                                                                  |
+| M-NB1 | Navigation bar hide / show | none                                                                                                                                                  | `UINavigationController.hideShowBarDuration`                                                                                                   | D      | `timing.navigationBarHideShowMs`                                                                                                                  |
+| M-PB1 | Indeterminate pulse        | Reduce Motion on: Safari loading a page (its indeterminate bar) beside ProgressBar's reduced-motion pulse                                             | Not a parity value: an owner value (`component:ProgressBar` DEC-2); confirm the 2000 ms pulse reads as calm and the 0.84 floor keeps 3:1 (AR4) | B      | `progressBar.reducedMotionPulseMs`, `progressBar.reducedMotionPulseFloor`                                                                         |
 
 Done (UIKit lab, iOS 26.2 simulator, Oct 23 2026; values in `uikit/` tagged
 `measured:`): M-S1, M-NB1, M-K2, M-CA1 (underdamped grid matched to the last
@@ -72,6 +73,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
@@ -121,12 +129,13 @@ Subject "switch S": the first switch in Settings ▸ Accessibility ▸ Display &
 Text Size (Bold Text row); a minimal host app holds a UISwitch on a plain view
 where a switch outside any scroll view is needed.
 
-Captured (iOS 26.2 simulator, Oct 23 2026), with their values landing in the
-switch's own table: M-SW02, M-SW03, M-SW04, M-SW05, M-SW06, M-SW09 (UISwitch
-makes no haptic call), M-SW11 (Reduce Motion: the lift stays, the stretch
-goes), M-SW16 (iOS 26.2). Until that table lands they stay open here, and
-`springs.switchThumbMove` and `switchThumbStretch` keep WebKit's values.
-Partly: M-SW07 (a single tap only). Still open: M-SW17, and M-SW11's On/Off
+Captured (iOS 26.2 simulator, Oct 23 2026), with their values in the
+switch's own table (`uikit/switch.ts`): M-SW02, M-SW03, M-SW04, M-SW05,
+M-SW06, M-SW09 (UISwitch makes no haptic call), M-SW11 (Reduce Motion: the
+lift stays, the stretch goes), M-SW16 (iOS 26.2). `springs.switchThumbMove`
+holds the measured travel the switch's table reads; WebKit's
+`switchThumbStretch` is retired for the table's `lift`. Partly: M-SW07 (a single
+tap only). Still open: M-SW17, and M-SW11's On/Off
 labels, Reduce Transparency and Bold Text.
 
 | ID     | Scene                                                                                                                                              | Gesture                                                                                                                                                                                           | Extract                                                                                                                                    | Method  |

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,10 +16,13 @@ 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, its minimum length and empty alpha; the reduced-motion pulse (three roles).                               |
 | `uikit/gestures.ts`                              | Gesture recognizer thresholds, the velocity filter and haptic stand-ins, as `{value, unit}` entries (sources in JSDoc).                                              |
+| `uikit/switch.ts`                                | UISwitch on iOS 26.2: geometry, the lift, settle, travel and tracking springs, the flip distance, the track colour.                                                  |
 | `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()`.                                                            |
 | `resolveMotion.ts`                               | A role's value: its table value, as the per-role tables stay internal (`spec:AST-094` DEC-15).                                                                       |
@@ -28,8 +32,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

@@ -517,6 +517,14 @@ interface StartGroup {
   madeInFrame?: boolean;
   /** The task it was made in, with every call made in that task. */
   task?: TaskMark;
+  /**
+   * Per channel, when its animation's first frame ran without a known start.
+   * That frame came too late to stand for the start, and the browser had not
+   * told it yet. The compositor starts the animation within about a frame of
+   * this time. Until the browser tells its start, a read of the channel takes
+   * the curve from here.
+   */
+  latest?: Map<Channel, number>;
   /** A later call in the same task that took over its curves. */
   adoptedBy?: StartGroup;
   readonly resolve: (start: number) => void;
@@ -1044,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;
@@ -1070,16 +1078,89 @@ export function createAnimator(
   };
 
   /**
-   * The value on screen at `time`. A curve the browser has not started is at
-   * its start up to now; a later time reads the curve from its provisional
-   * start, the model's best guess until the browser's start moves it (a
-   * companion that samples a curve ahead follows its shape).
+   * A held curve's start once a frame dated its call, as the browser's start
+   * moves it: by that frame's lead over the call's own time.
+   */
+  const datedFromLatest = (
+    segment: Segment,
+    latest: number | undefined,
+  ): {latest: number; start: number} | null =>
+    latest == null || segment.group == null
+      ? 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
+   * dates the curve. Without that frame, a later time reads from the
+   * provisional start, so a companion that samples ahead follows the curve's
+   * shape.
    */
   const valueAt = (property: MotionProperty, time: number): number => {
     const segment = segments.get(property);
-    if (segment != null && isHeld(segment) && time <= now()) {
+    if (segment != null && isHeld(segment)) {
+      // The compositor starts the call near its first frame. The curve is
+      // dated as the browser's start would date it. A curve that joined by an
+      // older clock keeps its lead over the call's own time.
+      const latest = segment.group?.latest?.get(CHANNEL_OF[property]);
+      const dated = datedFromLatest(segment, latest);
+      if (dated != null) {
+        const elapsed = Math.max(time, dated.latest) - dated.start;
+        return elapsed >= segment.duration
+          ? segment.target
+          : segment.at(elapsed);
+      }
       // Nothing has moved on screen until the browser starts the call.
-      return segment.at(0);
+      if (time <= now()) {
+        return segment.at(0);
+      }
     }
     return curveAt(property, time);
   };
@@ -1087,10 +1168,22 @@ export function createAnimator(
   const velocityAt = (property: MotionProperty, time: number): number => {
     const held = segments.get(property);
     if (held != null && isHeld(held)) {
-      // Still at its start on screen, but moving in the model: a retarget
-      // carries the velocity the curve has reached by now, so a flick whose
-      // moves all land before the browser starts any keeps its speed.
-      return held.speed(Math.max(0, time - held.start));
+      // Still at its start on screen, but moving in the model. A retarget
+      // carries the velocity the curve has reached by now. So a flick whose
+      // moves all land before the browser starts any keeps its speed. Past
+      // its first frame, it reads from that frame, as its value does.
+      const dated = datedFromLatest(
+        held,
+        held.group?.latest?.get(CHANNEL_OF[property]),
+      );
+      return held.speed(
+        Math.max(
+          0,
+          dated != null && time > dated.latest
+            ? time - dated.start
+            : time - held.start,
+        ),
+      );
     }
     const segment = segmentAt(property, time);
     if (segment == null || time < segment.start) {
@@ -1270,12 +1363,54 @@ 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.
+    const waiting =
+      callGroup ??
+      moving
+        .map(p => (segments.get(p) as Segment).group)
+        .find(group => group != null && !group.resolved) ??
+      null;
+    const rebuiltAfterFirstFrame = waiting?.framed === true;
+    // The new animation starts at the frame that commits it, from its first
+    // keyframe. That holds for a waiting call it joins after that call's
+    // first frame, and for every waiting call it takes a curve from. So this
+    // channel's reads below, and until that frame, take that first value.
+    const restarted = new Set<StartGroup>();
+    if (rebuiltAfterFirstFrame) {
+      restarted.add(waiting);
+    }
+    if (callGroup != null) {
+      for (const property of moving) {
+        const group = (segments.get(property) as Segment).group;
+        if (group != null && group !== callGroup && !group.resolved) {
+          restarted.add(group);
+        }
+      }
+    }
+    for (const group of restarted) {
+      group.latest?.delete(channel);
+    }
     if (channel === 'translate') {
       // The animation built below starts from the value at `time` (its first
       // keyframe); a rebase or a retarget builds a new one, so a new start.
@@ -1308,15 +1443,6 @@ export function createAnimator(
       previous?.cancel();
       return;
     }
-    // A channel rebuilt by an explicit call (set, rebase, a retarget of
-    // another axis) while one of its curves still waits for the browser's
-    // start keeps that start: no explicit start for this animation.
-    const waiting =
-      callGroup ??
-      moving
-        .map(p => (segments.get(p) as Segment).group)
-        .find(group => group != null && !group.resolved) ??
-      null;
     // The keyframes start where the animation will: at the waiting call's
     // own time, which its start moves to the browser's (resolveGroup), so a
     // write later in the task keeps the screen on the model's clock.
@@ -1431,6 +1557,20 @@ export function createAnimator(
       waiting.channels.add(channel);
       // A cancel before the first frame rejects its ready promise.
       (animation as Partial<Animation>).ready?.catch(() => {});
+      if (rebuiltAfterFirstFrame) {
+        // The frame that commits it dates this channel's start again. The
+        // call's other channels keep their own.
+        requestFrame?.(() => {
+          if (
+            !waiting.resolved &&
+            running.get(channel) === animation &&
+            animation.startTime == null &&
+            animation.playState === 'running'
+          ) {
+            (waiting.latest ??= new Map()).set(channel, now());
+          }
+        });
+      }
     } else {
       // One clock: the keyframes were sampled from `time`.
       animation.startTime = time;
@@ -1937,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;
         }
@@ -2135,6 +2279,22 @@ export function createAnimator(
       ) {
         resolveGroup(group, now());
       }
+      // The browser's start is still unread. The compositor starts the call
+      // near this frame, so each moving channel's reads take the curve from
+      // now until the browser tells its start.
+      if (!group.resolved) {
+        for (const channel of group.channels) {
+          const animation = running.get(channel);
+          if (
+            animation != null &&
+            group.animations.includes(animation) &&
+            animation.startTime == null &&
+            animation.playState === 'running'
+          ) {
+            (group.latest ??= new Map()).set(channel, now());
+          }
+        }
+      }
     });
     ready.then(
       () => syncGroup(group),
@@ -3643,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) => {
@@ -3662,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,
@@ -3682,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,161 @@
+// 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; hooks/usePager.ts reads it
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/motion/paging.test.ts
+ * - /packages/core/src/motion/README.md
+ */
+
+import type {MotionCurve} from './animator';
+import {cubicBezier, type BezierPoints} from './bezier';
+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.durationMs` on its
+ * curve, from the current offset, at any distance. The pager passes the
+ * duration and curve that `resolveMotion` gives, which are the measured values
+ * of the table.
+ *
+ * `velocity` (px/s) is the velocity of a move that this one retargets. The new
+ * curve starts at it and still ends on `to`, at rest and on time. A new target
+ * keeps the current velocity, where UIKit drops it. The carry is a Hermite
+ * term, v × duration × u(1 − u)², less the curve's own starting slope. So a
+ * move from rest is the curve itself.
+ */
+export function solveAnimatedPageScroll({
+  from,
+  to,
+  durationMs = paging.animatedScroll.durationMs,
+  curve = paging.animatedScroll.curve,
+  velocity,
+}: {
+  from: number;
+  to: number;
+  durationMs?: number;
+  curve?: BezierPoints;
+  velocity?: number;
+}): MotionCurve {
+  const duration = durationMs / 1000;
+  const distance = to - from;
+  const ease = cubicBezier(curve);
+  const progress = (u: number) => ease(Math.min(1, Math.max(0, u)));
+  // The carry, in px: the retargeted velocity over the whole duration, less
+  // what the curve's own starting slope already gives.
+  const startSlope = progress(1e-4) / 1e-4;
+  const carry =
+    velocity == null ? 0 : velocity * duration - distance * startSlope;
+  const at = (t: number) => {
+    const u = Math.min(1, Math.max(0, t / duration));
+    return from + distance * progress(u) + carry * u * (1 - u) * (1 - u);
+  };
+  return {
+    duration,
+    at,
+    velocity: t => {
+      if (t <= 0) {
+        return velocity ?? 0;
+      }
+      if (t >= duration) {
+        return 0;
+      }
+      const h = Math.min(1e-4, t / 2, (duration - t) / 2);
+      return (at(t + h) - at(t - h)) / (2 * h);
+    },
+  };
+}