Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

chore(core): UIKit's paging values and math, measured on iOS 26.2 (#8145)

Christopher Chedeaud1118274bd23
diff --git a/.changeset/uikit-paging-values.md b/.changeset/uikit-paging-values.md
new file mode 100644
index 0000000000..0e4639c28f
--- /dev/null
+++ b/.changeset/uikit-paging-values.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/core': patch
+---
+
+[chore] Internal: UIKit's paging values and math for touch presentations, measured on iOS 26.2: the thresholds that pick the page a release settles on, the settle that carries it there and `setContentOffset(animated:)`. The settle and `setContentOffset(animated:)` replay the recorded frames to under half a pixel. The unused projection rule (`selectPage` and `scroll.paging`) is gone, so the measured thresholds are the one paging rule. Not exported from the package entry point.
+
+@vjeux
diff --git a/docs/specs/AST-094-touch-presentations/spec.md b/docs/specs/AST-094-touch-presentations/spec.md
index c8b32b00a0..87194f4b4b 100644
--- a/docs/specs/AST-094-touch-presentations/spec.md
+++ b/docs/specs/AST-094-touch-presentations/spec.md
@@ -111,6 +111,17 @@ a measured, sourced difference exists.
measures (0.55 for a scroll view and a sheet), and a release MUST pick its
rest point by projecting its velocity the way its UIKit counterpart does:
with a deceleration rate, or with a measured projection time.
+ A paging scroll view (the pager, and Carousel with `hasSnap` where the
+ pager runs) picks its rest page as its UIKit counterpart measures it, with no
+ projection: the nearest page, or the next page in the release's direction
+ when the release is at least `paging.release.advanceSpeed` (300 pt/s) fast,
+ at any position on the page. It moves at most
+ `paging.release.maxPagesFromStart` (one page) from the page the drag started
+ on, and a release moving back toward that page stays on it (FR37). Both
+ values are measured on the iOS 26.2 simulator, 2026-10-23: steady releases
+ at 10, 25 and 40 % of a 402 pt page stay at 292.7–298.6 pt/s and advance at
+ 310.7–329.9 pt/s; releases at rest stay at 45–48.5 % and advance at
+ 55–57.5 % (DEC-25).
- **FR4 — Touch motion uses named roles.** Every spring, duration and curve a
touch presentation plays MUST be a motion role named for its use
(`architecture:theme-tokens` INV3). The roles this record names are listed below with their defaults and
@@ -165,6 +176,10 @@ a measured, sourced difference exists.
and `component:ContextMenu` owns them (DEC-5). They play only in a
ContextMenu that a touch opens.
+ Implementation gap: the pager's measured paging motion (its settle
+ integrator, its 300 ms animated scroll and that scroll's sinusoidal curve,
+ DEC-25) plays from internal constants and is not yet a named role.
+
### Motion
- **FR5 — Motion runs on the compositor.** Every release and every
@@ -180,6 +195,14 @@ a measured, sourced difference exists.
MUST come from the curve, not from a layout read. A new target MUST keep the
current velocity, and a release MUST hand its velocity to the spring that
follows.
+ A pager's release slower than `paging.release.velocityFloor` (225 pt/s)
+ starts its settle from rest, as UIKit's does; a faster release hands its
+ velocity to the settle. The floor is a guess inside the measured bracket
+ (UIKit zeroes steady releases at 175 and 200 pt/s and keeps 249 pt/s, iOS
+ 26.2 simulator, 2026-10-23) until a measurement replaces it (FR2). A
+ programmatic page change on a pager (a page control's tap, a keyboard step)
+ starts from rest: this is a known gap against this requirement until the
+ pager carries the current velocity into the page change (DEC-25).
- **FR7 — Exits animate as the native counterpart's do.** A touch
presentation MUST play the exit its UIKit counterpart plays, on every touch
platform. FR8 governs their reduced-motion form. Each overlay's own record states its
@@ -680,7 +703,9 @@ under a finger, and a mouse follows `module:DropdownMenu/useMenuPress` FR3 and
stretch for the same travel; a mouse wheel scrolls its content and never
moves it. Implementation gap: a finger drags it one for one below rest.
- The shared pager (Carousel's paging presentation, Lightbox's viewer): a
- trackpad swipe follows FR43's pager rule.
+ trackpad swipe follows FR43's pager rule in Lightbox's viewer under every
+ pointer (`component:Lightbox` FR11), and in Carousel's paging presentation
+ where the primary pointer is coarse.
- `architecture:react-component-runtime` INV13: gestures attach for every
pointer, within FR24's listener budget.
- `design:user-states` DR1, DR3 and `family:buttons`: press timing follows
@@ -721,9 +746,11 @@ under a finger, and a mouse follows `module:DropdownMenu/useMenuPress` FR3 and
| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| FR1, FR2 | Value check over every measured value and its uses | every value; a guess and its measurement task; a platform-specific value; two components playing the same motion | an unsourced value, an unknown source kind, a guess without a listed measurement, an unsourced platform split, or two values for one use fails |
| FR3 | Unit tests of the spring, decay, rubber band and projection math against an independent integration and values read from UIKit | under-, critically and overdamped springs; release velocities; both rates; overscroll depths | changing a formula or a constant breaks the agreement with UIKit's values |
+| FR3 pager | Unit tests of the pager's page choice against the recorded UIKit releases | releases at 292.7–298.6 pt/s that stay and 310.7–329.9 pt/s that advance, at 10, 25 and 40 % of a page; releases at rest at 45–48.5 % and 55–57.5 %; a 1.5-page drag released at 0, 600 and 3000 pt/s; a release moving back toward the start page | a page chosen by projection, a release at or past 300 pt/s that stays, or a release that travels more than one page from its start fails |
| FR4 | Role unit tests over every touch motion | each role at its table value; a theme that writes `motion` | a literal played in place of a role, a value that differs from the table at `tempo` 1 and `'standard'`, or a theme that changes a role other than through its motion knobs fails |
| FR5 | Browser proof: an animation keeps advancing frame by frame through a 1 s main-thread block, with no layout or paint per frame | Chromium phone emulation; WebKit | a script-driven or layout-animating implementation freezes or lays out |
| FR6 | Unit and browser tests catching an animation mid-flight and retargeting it | catch at peak velocity; retarget with a new spring; a retarget before the browser reports the call's start | a layout read, a jump, or a lost velocity fails |
+| FR6 pager | Unit and browser tests of a pager's settle start | releases just under and over 225 pt/s; a catch mid-settle; a programmatic page change mid-settle | a release under the floor whose settle starts moving, a release over it whose settle starts from rest, or a catch that loses the on-screen velocity fails; a programmatic page change from rest is the recorded gap |
| FR7, FR8 | Component browser tests and storyboards with and without Reduce Motion | entrance, exit, move; a drag and its lift under Reduce Motion | a missing exit, any travel, scale or spring under Reduce Motion other than a coast after a throw and its settle at an edge (`design:reduced-motion` DR2), or an opacity fade over 200 ms fails |
| FR9, FR10 | Recognizer unit tests on synthetic streams and browser tests with real touch input | drag, second finger, pinch, page zoom, main-thread block | a second finger that breaks a drag, or a page pinch blocked other than by the author's `touch-action`, fails |
| FR11, FR12 | Press and long-press tests on synthetic streams with explicit timestamps | inside and outside a scroll view; a drag the browser takes; a lift inside; a menu row under a finger; a press on a row of a menu whose rows fit and of one that scrolls; a slide-off lift on a Switch and on a Radio | the wrong profile's timing, a press that survives the browser taking the touch, or a control outside an action group activated other than by the browser's click, outside `spec:AST-020` FR9's slide-off exception, a row of a menu whose rows fit that waits 150 ms, or one of a scrolling menu that does not, or a slide-off lift that completes a control outside `spec:AST-020` FR9's exception, fails |
@@ -739,7 +766,7 @@ under a finger, and a mouse follows `module:DropdownMenu/useMenuPress` FR3 and
| FR29 | Trigger tests with explicit timestamps | a press in a fixed bar; a press in scrolling content held 149 and 150 ms; a quick tap in scrolling content; a scroll taking the touch before 150 ms; a drift of 12 and 14 pt; moves before and after the handoff; `presentation="popover"` | a fixed-bar press that waits, a held finger's scroll-view open before 150 ms or after a scroll, a quick tap that does not open at its lift, an open past the drift allowance, a lift that acts before the handoff, or a `popover` trigger that opens on press fails |
| FR31–FR33 | Browser tests and storyboards under a finger | a menu, a Popover and a ContextMenu lift: open, close, a pan outside, a tap outside, a pinch over the surface; a mouse | a surface that does not grow from and shrink into its trigger, a pan outside that leaves a menu open, a Popover whose dismissal changed, a pinch blocked other than by the author's `touch-action`, a tap outside that reaches the page, or a changed mouse path fails |
| FR34, FR35 | Browser tests and storyboards under a finger | a sub-menu drilling in and its Back row returning; a tap and a drag during a popover's and a menu's growth; a pinch during growth; a mouse; a tap and a drag during an alert's, a sheet's, and a dialog's entrance; a key and a screen reader during an entrance; a pinch during an alert's and a sheet's entrance; a tap and a scroll on the page beside an entering non-modal sheet, which pass | a drill-in that leaves the parent's rows in place, a change between levels that does not play on its roles, a tap during growth that closes, scrolls or moves focus, a pinch blocked other than by the author's `touch-action`, or a changed mouse path, a held key or assistive-technology activation, a hidden content tree, or a tap or drag during an entrance that closes the presentation, scrolls a held page, moves focus or reaches anything beneath, fails |
-| FR36–FR40 | Release tests on synthetic touch streams with explicit timestamps, per use | below and past each commit point; a flick that projects past it; a slow drag past it; a release moving back; Reduce Motion; keyboard and mouse paths | a decision that changes mid-settle, a release moving back that commits, a settle that does not start at the release velocity, or an action with no keyboard or mouse path fails |
+| FR36–FR40 | Release tests on synthetic touch streams with explicit timestamps, per use | below and past each commit point; a flick that projects past it; a slow drag past it; a release moving back; Reduce Motion; keyboard and mouse paths | a decision that changes mid-settle, a release moving back that commits, a settle that does not start at the release velocity (a paging release starts its settle per FR6's paging paragraph, DEC-25), or an action with no keyboard or mouse path fails |
| FR41 | Browser tests with real touch input (`spec:AST-013` FR10) | a tap; a long press on a ContextMenu trigger, a DropdownMenu trigger the caller renders, a row with a context menu, and a slider thumb; a long press on a checkbox row's label and on plain text; a cancelled press; mouse and keyboard selection; a pen long press; a mouse long press, which makes no context request | a tap that selects, a hold with an action that starts a selection or callout, a label or plain text whose long press does not select natively, a suppression that outlives the press, or a change to native selection elsewhere or to mouse, keyboard, or assistive-technology selection fails |
| FR42 | Default-theme geometry tests under a coarse and a fine pointer, and hit-testing between adjacent targets | every component at phone width with a finger and with a mouse; a dense toolbar; a chip and its remove button; a Switch beside a label link | a default-theme box that grows under touch or at phone width other than with its text, or, where no component or module record sets the hit area, a touch target under 44 px where neighbors allow it or a hit area that overlaps a neighbor's target, fails |
| FR43 | Browser tests with a mouse, a trackpad, a pen, a finger, and the keyboard, and resource counts | a pan by drag and by wheel; a slider's thumb under a wheel and a trackpad scroll; a ctrl-wheel pinch; a long press, a right click, and Shift+F10; a mouse press; a handle drag; a row swipe with a mouse and a trackpad; a component with no gesture | a gesture missing under a mouse or pen, a mouse-drag swipe action, a pen pinch, an edge pan under a mouse, a trackpad, or a pen, a press delay under a fine pointer, a wheel or trackpad scroll that changes a thumb's value or does not reach the scroll under it, an idle listener in a component with no gesture, or added stylesheet bytes, fails |
@@ -1036,6 +1063,25 @@ from its top.
Rejected: cancelling moves only after the pan begins.
+### DEC-25 — A pager pages as UIKit measures it
+
+**Reference:** `spec:AST-094/DEC-25`
+**Decider:** `cixzhang`, `2026-11-01`
+
+A pager, Carousel with `hasSnap` where the pager runs, and Lightbox's gallery pick the rest page and
+start the settle as UIKit's paging scroll view does on iOS 26.2. UIKit
+chooses the page by a speed threshold, the same 300 pt/s at 10, 25 and 40 %
+of a page, not by a projection, and starts a slow release's settle from rest.
+The owner tried this paging on the pager and the paging Carousel on
+2026-11-01, with a trackpad and on a phone: "trackpad is good", "phone good".
+This narrows FR3 and FR6 for paging only; every other release keeps them. A
+programmatic page change starts from rest until the pager carries velocity
+into it. A paging release decides by FR3's paging rule, and its settle starts
+as FR6's paging paragraph says; FR37 applies unchanged.
+
+Rejected: projecting a paging release with a deceleration rate; handing a
+slow paging release's velocity to the settle.
+
## Open questions
- **OQ1 — Scroll view bounce-back curve.** What curve brings a scroll view
diff --git a/docs/specs/components/Lightbox/Lightbox.spec.md b/docs/specs/components/Lightbox/Lightbox.spec.md
index c28e10d405..8c28a713c8 100644
--- a/docs/specs/components/Lightbox/Lightbox.spec.md
+++ b/docs/specs/components/Lightbox/Lightbox.spec.md
@@ -139,7 +139,7 @@ FR21). Consumer props and usage remain documented in `Lightbox.doc.mjs`.
| FR4 | The open viewer is a focus region through Core's shared focus-region module (`component:Dialog/DEC-2`): Tab from its last control moves focus to its first and Shift+Tab from its first moves focus to its last, so focus never leaves the viewer for the browser's own interface. | `component:Dialog/DEC-2` | settled; implementation gap |
| FR5 | Under a coarse primary pointer, after hydration, Lightbox presents FR6–FR10 with no opt-in. Every spring, duration, and curve they play is a named motion role (zoom settle, page settle, dismiss, pinch close, controls fade, zoom transition) read through the motion role table, never a literal. Under reduced motion they follow AR6. | `spec:AST-094` FR4, FR13 | settled; implementation gap |
| FR6 | With `hasZoom`, on an image, a pinch zooms about the fingers and pans while it zooms; past the minimum or maximum the photo resists and eases back without overshoot. A double tap zooms to the larger of filling the viewer and 2×, about the tapped point; a second double tap returns to the fitted size. A zoomed photo pans with momentum and rubber-band edges. A pinch on the controls or the caption still zooms the page. | `spec:AST-094` FR3, FR10 | settled; implementation gap |
-| FR7 | In a gallery, a horizontal drag moves the row of items, which sit apart by the measured gap. The release lands on at most one neighbouring item by the projection rule. Paging applies over a video item's frame as over a photo; a drag that starts on the video's own controls, such as its scrubber or volume, stays the video's. A zoomed photo pans to its edge before a new drag pages. A pinch never pages. Previous, Next, and the arrow keys keep paging. A controlled `index` the caller refuses springs back. `onIndexChange` reports a swipe. | `spec:AST-094` FR14, FR36–FR39 | settled; implementation gap |
+| FR7 | In a gallery, a horizontal drag moves the row of items, which sit apart by the measured gap. The release lands on at most one neighbouring item by `spec:AST-094` FR3's paging rule (DEC-25). Paging applies over a video item's frame as over a photo; a drag that starts on the video's own controls, such as its scrubber or volume, stays the video's. A zoomed photo pans to its edge before a new drag pages. A pinch never pages. Previous, Next, and the arrow keys keep paging. A controlled `index` the caller refuses springs back. `onIndexChange` reports a swipe. | `spec:AST-094` FR3, FR14, FR36–FR39, DEC-25 | settled; implementation gap |
| FR8 | On a fitted image, a downward drag moves the photo with the finger, shrinks it, and fades the backdrop. The release decides once: a projected travel past the commit point closes the viewer and reports `onOpenChange(false)` at the lift; a release moving back springs back. Video is unchanged. | `spec:AST-094` FR36–FR40 | settled; implementation gap |
| FR9 | With `hasZoom`, a pinch in from the fitted size is a release decision: below the measured fraction of the fitted size the release closes the viewer; opening the fingers again by the measured amount before the lift is moving back and cancels. A pinch that starts zoomed in never closes the viewer. | `spec:AST-094` FR36, FR37 | settled; implementation gap |
| FR10 | With `hasZoom`, under a coarse pointer only, a tap on the photo fades the controls and caption and darkens the backdrop. While they are hidden, the next tap on the photo, a tap beside the photo, or a cancelled drag brings them back, and that tap beside the photo does not close the viewer (ORD3). AR5 governs keyboard and assistive-technology access while they are hidden. | `architecture:public-component-api` INV16 | settled; implementation gap |
diff --git a/packages/core/src/motion/MEASUREMENTS.md b/packages/core/src/motion/MEASUREMENTS.md
index fe236bf310..da3fac0b72 100644
--- a/packages/core/src/motion/MEASUREMENTS.md
+++ b/packages/core/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
diff --git a/packages/core/src/motion/README.md b/packages/core/src/motion/README.md
index 6a0f6b68ac..43ace5d4e5 100644
--- a/packages/core/src/motion/README.md
+++ b/packages/core/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. |
diff --git a/packages/core/src/motion/paging.test.ts b/packages/core/src/motion/paging.test.ts
new file mode 100644
index 0000000000..bb0e585a17
--- /dev/null
+++ b/packages/core/src/motion/paging.test.ts
@@ -0,0 +1,393 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file paging.test.ts
+ * @input vitest, the paging math, and UIKit reference curves recorded on the
+ * iOS 26.2 simulator (a 402 pt paging UIScrollView, contentOffset per 60 Hz
+ * frame)
+ * @output Holds solvePaging and solveAnimatedPageScroll to the recorded
+ * motion
+ * @position Testing; validates paging.ts without a browser
+ */
+
+import {describe, expect, it} from 'vitest';
+import {
+ pagingSettleVelocity,
+ solveAnimatedPageScroll,
+ solvePaging,
+} from './paging';
+import {paging} from './uikit/paging';
+
+/**
+ * contentOffset per frame after a release at rest, from the frame the settle
+ * starts (ms, px). UIKit lab, iOS 26.2 simulator, 402 pt pages.
+ */
+const SETTLES: Record<
+ string,
+ {from: number; velocity?: number; to: number; frames: number[][]}
+> = {
+ // 60 % of the way from page 1 to page 2, released at rest: page 2.
+ forwardFrom60: {
+ from: 633.33,
+ to: 804,
+ frames: [
+ [0.7, 633.33],
+ [17.4, 639],
+ [34.0, 652],
+ [50.7, 668.67],
+ [67.4, 686.67],
+ [84.0, 704.67],
+ [100.7, 721.33],
+ [117.4, 736.33],
+ [134.0, 749.67],
+ [150.7, 761],
+ [167.4, 770.67],
+ [184.0, 778.33],
+ [200.7, 784.67],
+ [217.4, 789.67],
+ [234.0, 793.67],
+ [250.7, 796.67],
+ [267.4, 799],
+ [284.0, 800.67],
+ [300.7, 802],
+ [317.4, 803],
+ [334.0, 803.67],
+ [350.7, 804],
+ ],
+ },
+ // 46 % (content) of the way to page 2, released at rest: back to page 1.
+ backFrom46: {
+ from: 589,
+ to: 402,
+ frames: [
+ [0.6, 589],
+ [17.3, 583],
+ [33.9, 569],
+ [50.6, 550.67],
+ [67.3, 531],
+ [83.9, 511.33],
+ [100.6, 493],
+ [117.3, 476.33],
+ [133.9, 461.67],
+ [150.6, 449.33],
+ [167.3, 439],
+ [183.9, 430.33],
+ [200.6, 423.33],
+ [217.3, 417.67],
+ [233.9, 413.33],
+ [250.6, 410],
+ [267.3, 407.33],
+ [283.9, 405.33],
+ [300.6, 404],
+ [317.3, 403],
+ [333.9, 402.33],
+ [350.6, 402],
+ ],
+ },
+ // Dragged back 23 % toward page 0, released at rest: page 1.
+ forwardFromMinus23: {
+ from: 311.33,
+ to: 402,
+ frames: [
+ [0.6, 311.33],
+ [17.2, 314.33],
+ [33.9, 321],
+ [50.6, 330],
+ [67.2, 339.67],
+ [83.9, 349.33],
+ [100.6, 358.33],
+ [117.2, 366.33],
+ [133.9, 373.33],
+ [150.6, 379.33],
+ [167.2, 384.33],
+ [183.9, 388.33],
+ [200.6, 391.67],
+ [217.2, 394.33],
+ [233.9, 396.33],
+ [250.6, 398],
+ [267.2, 399.33],
+ [283.9, 400.33],
+ [300.6, 401],
+ [317.2, 401.33],
+ [333.9, 401.67],
+ [350.6, 402],
+ ],
+ },
+ // Released moving forward at 25 % with a settle velocity of 0.314 pt/ms
+ // (steady 320 pt/s drag): the next page.
+ flick314From24: {
+ from: 499.67,
+ velocity: 314,
+ to: 804,
+ frames: [
+ [15.0, 499.67],
+ [31.7, 513.33],
+ [48.4, 538.33],
+ [65.0, 569],
+ [81.7, 601.67],
+ [98.4, 633.33],
+ [115.0, 662.67],
+ [131.7, 689],
+ [148.4, 712],
+ [165.0, 731.67],
+ [181.7, 748],
+ [198.4, 761.33],
+ [215.0, 772],
+ [231.7, 780.33],
+ [248.4, 787],
+ [265.0, 792],
+ [281.7, 796],
+ [298.4, 799],
+ [315.0, 801],
+ [331.7, 802.33],
+ [348.4, 803.33],
+ [365.0, 804],
+ ],
+ },
+ // 600 pt/s drag released with no hold: settle velocity 0.565 pt/ms.
+ flick565From24: {
+ from: 497.33,
+ velocity: 565,
+ to: 804,
+ frames: [
+ [-3.2, 497.33],
+ [13.5, 514.33],
+ [30.2, 541.33],
+ [46.8, 573],
+ [63.5, 606],
+ [80.2, 637.67],
+ [96.8, 667],
+ [113.5, 693],
+ [130.2, 715.33],
+ [146.8, 734.33],
+ [163.5, 750],
+ [180.2, 763],
+ [196.8, 773.33],
+ [213.5, 781.67],
+ [230.2, 788],
+ [246.8, 793],
+ [263.5, 796.67],
+ [280.2, 799.33],
+ [296.8, 801.33],
+ [313.5, 802.67],
+ [330.2, 803.67],
+ [346.8, 804],
+ ],
+ },
+ // 290 pt of pan past page 0 (114.33 pt shown), released at rest.
+ overscrollReturn: {
+ from: -114.33,
+ to: 0,
+ frames: [
+ [0, -114.33],
+ [10.6, -113],
+ [27.3, -105.67],
+ [43.9, -95.33],
+ [60.6, -83.33],
+ [77.3, -71],
+ [93.9, -59.33],
+ [110.6, -48.67],
+ [127.3, -39.33],
+ [143.9, -31.33],
+ [160.6, -24.67],
+ [177.3, -19],
+ [193.9, -14.33],
+ [210.6, -10.67],
+ [227.3, -7.67],
+ [243.9, -5.33],
+ [260.6, -3.67],
+ [277.3, -2.33],
+ [293.9, -1.33],
+ [310.6, -0.67],
+ [327.3, -0.33],
+ [343.9, 0],
+ ],
+ },
+};
+
+/** `setContentOffset(_:animated:)` per frame from its first frame (ms, px). */
+const ANIMATED: Record<string, {from: number; to: number; frames: number[][]}> =
+ {
+ twoPages: {
+ from: 402,
+ to: 1206,
+ frames: [
+ [0, 402],
+ [16.7, 408],
+ [33.3, 426.33],
+ [50, 456],
+ [66.7, 496],
+ [83.3, 545.67],
+ [100, 603],
+ [116.7, 666.67],
+ [133.3, 734.33],
+ [150, 804],
+ [166.7, 873.67],
+ [183.3, 941.33],
+ [200, 1005],
+ [216.7, 1062.33],
+ [233.3, 1112],
+ [250, 1152],
+ [266.7, 1181.67],
+ [283.3, 1200],
+ [300, 1206],
+ ],
+ },
+ fivePages: {
+ from: 0,
+ to: 2010,
+ frames: [
+ [0, 0],
+ [16.7, 15.33],
+ [33.3, 60.67],
+ [50, 134.67],
+ [66.7, 235],
+ [83.3, 359],
+ [100, 502.67],
+ [116.7, 661.33],
+ [133.3, 830.33],
+ [150, 1005],
+ [166.7, 1179.67],
+ [183.3, 1348.67],
+ [200, 1507.67],
+ [216.7, 1651],
+ [233.3, 1775],
+ [250, 1875.33],
+ [266.7, 1949.33],
+ [283.3, 1994.67],
+ [300, 2010],
+ ],
+ },
+ };
+
+/**
+ * Residuals of a curve against recorded frames. The paging integrator runs
+ * floor(elapsed ms) steps on each frame. So a frame shows the curve after the
+ * floored steps since the start (`steps`). A timed curve, such as the animated
+ * scroll, is read at the frame times (`time`).
+ */
+function errors(
+ curve: {at(t: number): number},
+ frames: number[][],
+ clock: 'steps' | 'time',
+): {rms: number; max: number} {
+ let steps = 0;
+ const residuals = frames.map(([ms, x], i) => {
+ if (clock === 'steps' && i > 0) {
+ steps += Math.floor(ms - frames[i - 1][0] + 1e-6);
+ }
+ const t =
+ clock === 'steps' ? steps / paging.integrator.stepsPerSecond : ms / 1000;
+ return curve.at(t) - x;
+ });
+ const rms = Math.sqrt(
+ residuals.reduce((sum, r) => sum + r * r, 0) / residuals.length,
+ );
+ return {rms, max: Math.max(...residuals.map(Math.abs))};
+}
+
+describe('pagingSettleVelocity: the floor on the one release velocity (spec:AST-100 FR3)', () => {
+ it('zeroes a release velocity below the floor, either way', () => {
+ expect(pagingSettleVelocity(200)).toBe(0);
+ expect(pagingSettleVelocity(-200)).toBe(0);
+ });
+
+ it('keeps a velocity at or above the floor: UIKit keeps a steady 249 pt/s release (0.249 pt/ms)', () => {
+ expect(pagingSettleVelocity(249)).toBe(249);
+ expect(pagingSettleVelocity(-260)).toBe(-260);
+ });
+});
+
+describe("solvePaging: UIKit's paging settle, frame by frame", () => {
+ it.each(Object.entries(SETTLES))(
+ 'reproduces the recorded %s within a pixel',
+ (_, {from, velocity = 0, to, frames}) => {
+ const curve = solvePaging({from, velocity, to});
+ const {rms, max} = errors(curve, frames, 'steps');
+ expect(rms).toBeLessThan(0.35);
+ expect(max).toBeLessThan(0.8);
+ },
+ );
+
+ it('ends exactly on the page about 0.33 s after a release at rest', () => {
+ const curve = solvePaging({from: 633.33, velocity: 0, to: 804});
+ expect(curve.at(curve.duration)).toBe(804);
+ expect(curve.velocity(curve.duration)).toBe(0);
+ expect(curve.duration).toBeGreaterThan(0.3);
+ expect(curve.duration).toBeLessThan(0.36);
+ });
+
+ it("starts at the release position with UIKit's step velocity", () => {
+ const curve = solvePaging({from: 500, velocity: 1000, to: 804});
+ expect(curve.at(0)).toBe(500);
+ // 1000 px/s enters as 1 px per step; 960 steps a second.
+ expect(curve.velocity(0)).toBeCloseTo(960, 6);
+ });
+
+ it('is continuous and monotonic for a release at rest', () => {
+ const curve = solvePaging({from: 589, velocity: 0, to: 402});
+ let previous = curve.at(0);
+ for (let t = 0.001; t <= curve.duration; t += 0.001) {
+ const value = curve.at(t);
+ expect(value).toBeLessThanOrEqual(previous + 1e-9);
+ expect(Math.abs(value - previous)).toBeLessThan(3);
+ previous = value;
+ }
+ });
+
+ it('carries a forward flick on with a small overshoot-free approach', () => {
+ const curve = solvePaging({from: 450, velocity: 600, to: 804});
+ // The pull is underdamped (ζ ≈ 0.88): it may pass the page by a hair.
+ let maxValue = -Infinity;
+ for (let t = 0; t <= curve.duration; t += 0.004) {
+ maxValue = Math.max(maxValue, curve.at(t));
+ }
+ expect(maxValue).toBeLessThan(804 + 2);
+ expect(curve.at(curve.duration)).toBe(804);
+ });
+
+ it('settles at once when already on the page and at rest', () => {
+ const curve = solvePaging({from: 804, velocity: 0, to: 804});
+ expect(curve.steps).toBe(0);
+ expect(curve.duration).toBe(0);
+ expect(curve.at(0.1)).toBe(804);
+ });
+
+ it('runs the documented integrator', () => {
+ const {springPull, friction} = paging.integrator;
+ const curve = solvePaging({from: 0, velocity: 0, to: 100});
+ // One step from rest: v = (0 + 100·pull)·friction.
+ const oneStep = 100 * springPull * friction;
+ expect(curve.at(1 / paging.integrator.stepsPerSecond)).toBeCloseTo(
+ oneStep,
+ 9,
+ );
+ });
+});
+
+describe('solveAnimatedPageScroll: setContentOffset(_:animated:)', () => {
+ it.each(Object.entries(ANIMATED))(
+ 'reproduces the recorded %s',
+ (_, {from, to, frames}) => {
+ const curve = solveAnimatedPageScroll({from, to});
+ const {rms, max} = errors(curve, frames, 'time');
+ expect(rms).toBeLessThan(0.5);
+ expect(max).toBeLessThan(1.2);
+ },
+ );
+
+ it('lasts 0.3 s whatever the distance and ends at rest', () => {
+ for (const distance of [402, 804, 2010]) {
+ const curve = solveAnimatedPageScroll({from: 0, to: distance});
+ expect(curve.duration).toBe(0.3);
+ expect(curve.at(0.3)).toBe(distance);
+ expect(curve.velocity(0.3)).toBe(0);
+ expect(curve.velocity(0)).toBe(0);
+ }
+ });
+
+ it('peaks at π/2 times the average speed halfway', () => {
+ const curve = solveAnimatedPageScroll({from: 0, to: 402});
+ expect(curve.velocity(0.15)).toBeCloseTo((Math.PI / 2) * (402 / 0.3), 6);
+ });
+});
diff --git a/packages/core/src/motion/paging.ts b/packages/core/src/motion/paging.ts
new file mode 100644
index 0000000000..77dce46938
--- /dev/null
+++ b/packages/core/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)
+ );
+ },
+ };
+}
diff --git a/packages/core/src/motion/selectPage.test.ts b/packages/core/src/motion/selectPage.test.ts
deleted file mode 100644
index 39d8785d2d..0000000000
--- a/packages/core/src/motion/selectPage.test.ts
+++ /dev/null
@@ -1,31 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-import {describe, expect, it} from 'vitest';
-import {selectPage} from './selectPage';
-
-describe('selectPage', () => {
- it('lands on a real page when the current page is past the end', () => {
- const result = selectPage({
- position: 400,
- velocity: 0,
- pageSize: 100,
- pageCount: 3,
- currentPage: 4,
- });
- expect(result.value).toBeDefined();
- expect(result.index).toBeGreaterThanOrEqual(0);
- expect(result.index).toBeLessThanOrEqual(2);
- });
-
- it('moves at most one page per release', () => {
- const page = (position: number, velocity: number, currentPage: number) =>
- selectPage({position, velocity, pageSize: 390, pageCount: 6, currentPage})
- .index;
- expect(page(390, 0, 1)).toBe(1);
- expect(page(430, 8000, 1)).toBe(2);
- expect(page(350, -8000, 1)).toBe(0);
- // A slow drag past half a page settles on the next page.
- expect(page(600, 0, 1)).toBe(2);
- expect(page(1950, 9000, 5)).toBe(5);
- });
-});
diff --git a/packages/core/src/motion/selectPage.ts b/packages/core/src/motion/selectPage.ts
deleted file mode 100644
index 26f76cb0fe..0000000000
--- a/packages/core/src/motion/selectPage.ts
+++ /dev/null
@@ -1,55 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-/**
- * @file selectPage.ts
- * @input A release (position, velocity), the page size and count, the
- * current page
- * @output Exports `selectPage`: the page a paging release settles on
- * @position UIScrollView paging (`isPagingEnabled`) on the release policy
- * (resolveSnapPoint.ts). Pure: no DOM, no React
- *
- * SYNC: When modified, update selectPage.test.ts.
- */
-
-import type {SnapSelection} from './projection';
-import {resolveSnapPoint} from './resolveSnapPoint';
-import {scroll} from './uikit/scroll';
-
-/**
- * UIScrollView paging (`isPagingEnabled`): the page a release settles on, at
- * most one page from `currentPage`, chosen by projecting the release with
- * the paging projection rate (uikit/scroll.ts; a GUESS until measured).
- * Pages are `pageSize` apart starting at 0.
- */
-export function selectPage({
- position,
- velocity,
- pageSize,
- pageCount,
- currentPage,
- rate = scroll.paging.projectionRate,
-}: {
- position: number;
- velocity: number;
- pageSize: number;
- pageCount: number;
- currentPage: number;
- rate?: number;
-}): SnapSelection {
- const points = Array.from(
- {length: Math.max(1, pageCount)},
- (_, i) => i * pageSize,
- );
- // The release policy (resolveSnapPoint.ts), with the paging rate as the
- // seconds of velocity it projects, no flick and one page per release.
- const {index, projected} = resolveSnapPoint({
- points,
- position,
- velocity,
- flickThreshold: Infinity,
- projection: {seconds: rate / (1 - rate) / 1000},
- fromIndex: currentPage,
- maxSteps: 1,
- });
- return {index, value: points[index], projected};
-}
diff --git a/packages/core/src/motion/uikit/paging.ts b/packages/core/src/motion/uikit/paging.ts
new file mode 100644
index 0000000000..7448fec409
--- /dev/null
+++ b/packages/core/src/motion/uikit/paging.ts
@@ -0,0 +1,162 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file paging.ts
+ * @input Nothing; data only
+ * @output Exports `paging`, the measured constants of a paging UIScrollView
+ * @position The paging domain of the UIKit constants table (motion/uikit). Only
+ * core reads it, so the `uikit` namespace does not re-export it
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/motion/MEASUREMENTS.md (measurement tasks)
+ * - /packages/core/src/motion/paging.ts and paging.test.ts
+ */
+
+export const paging = {
+ /**
+ * After the lift, one model moves the content: the settle onto the chosen
+ * page and the return from an overscroll. Each display frame runs floor(frame
+ * interval in ms) steps of 1 ms:
+ *
+ * v = (v + (target − x) · springPull) · friction; x += v (v: pt per step)
+ *
+ * A 60 Hz frame runs 16 steps, not 16.67. With these values, the model
+ * replays eight captured releases to 0.20 pt RMS. It replays five overscroll
+ * returns to 0.16–0.33 pt RMS (402 pt pages, iOS 26.2, 3× screen). Without
+ * the floor, the error is 1.0 pt RMS, with a systematic shape.
+ */
+ integrator: {
+ /**
+ * Velocity added per 1 ms step, per point of distance to the target page
+ * (pt per step²).
+ * @source measured: UIKit lab, iOS 26.2 simulator, Oct 23 2026.
+ * `_pagingSpringPull` reads the same on a 402 pt paging UIScrollView and
+ * on UIPageViewController's scroll view. It replays 8 captured settles to
+ * 0.20 pt RMS.
+ */
+ springPull: 0.000284858,
+ /**
+ * Velocity kept per step after the pull (`_pagingFriction`, equal to
+ * `_defaultPagingFriction`).
+ * @source measured: UIKit lab, iOS 26.2 simulator, Oct 23 2026. Both read
+ * the same on the two scroll views of `springPull`, and they replay with
+ * it.
+ */
+ friction: 0.970815,
+ /**
+ * Integration steps per second: floor(16.67 ms) = 16 steps per 60 Hz frame,
+ * and floor(8.33 ms) = 8 per 120 Hz frame, so 960.
+ * @source measured: UIKit lab, iOS 26.2 simulator, Oct 23 2026. In a 60 fps
+ * log of 8 releases at rest, floored stepping fits to 0.20 pt RMS.
+ * Unfloored stepping fits to 1.0 pt RMS.
+ */
+ stepsPerSecond: 960,
+ /**
+ * A settle ends exactly on the page once the remaining distance is below
+ * this many points and the step velocity is below `restSpeed`.
+ * @source measured: UIKit lab, iOS 26.2 simulator, Oct 23 2026. The
+ * captured settles jump the last 0.33 pt onto the page about 0.35 s after
+ * a release at rest.
+ */
+ restDistance: 0.5,
+ /**
+ * Step velocity (pt per step) below which a settle may end.
+ * @source GUESS — the captured settles end at about 0.04 pt per step;
+ * the threshold is not observable more finely at 60 fps
+ * @measure M-PG12
+ */
+ restSpeed: 0.05,
+ },
+ release: {
+ /**
+ * Released slower than `advanceSpeed`, the scroll view settles on the page
+ * nearest the content position: past half a page, the next one.
+ * @source measured: UIKit lab, iOS 26.2 simulator, Oct 23 2026. In releases
+ * at rest from page 1, content at 48.5 % of the page stays, and 57.5 %
+ * goes to the next page. On a second 402 pt pager, 45 % stays and 55 %
+ * advances.
+ */
+ commitFraction: 0.5,
+ /**
+ * Released at least this fast (pt/s), the scroll view pages in the
+ * direction of the velocity, from any content position. A flick from 6 % of
+ * the page advances. The speed is UIPanGestureRecognizer's velocity at the
+ * last movement, and it never decays. The scroll view's
+ * `_horizontalVelocity` equals it at every sample. A drag held still for
+ * 397 ms before the lift still pages at the speed it had.
+ * @source measured: UIKit lab, iOS 26.2 simulator, Oct 23 2026. Steady
+ * releases at 10, 25 and 40 % of a 402 pt page: 292.7, 295.3 and 298.6
+ * pt/s stay; 310.7, 316.4 and 329.9 advance. The result is the same at
+ * every position: a threshold, not a projection.
+ */
+ advanceSpeed: 300,
+ /**
+ * A settle velocity slower than this (pt/s) is zeroed, so the settle starts
+ * at rest. It is paging's own tuning on the one release velocity that every
+ * gesture reads.
+ * @source GUESS — the middle of the measured (200, 249] bracket. In the
+ * UIKit lab (iOS 26.2 simulator, Oct 23 2026),
+ * `scrollViewWillEndDragging` reads 0 for steady releases at 175 and 200
+ * pt/s. It reads 0.249 pt/ms for a release at 249 pt/s.
+ * @measure M-PG13
+ */
+ velocityFloor: 225,
+ /**
+ * Pages a release may travel from the page the drag started on, at any
+ * speed and drag distance.
+ * @source measured: UIKit lab, iOS 26.2 simulator, Oct 23 2026. A drag of
+ * 1.5 pages from page 1 lands on page 2 at release speeds of 0, 600 and
+ * 3000 pt/s.
+ */
+ maxPagesFromStart: 1,
+ },
+ /**
+ * A finger that lands on a settling pager does not stop it at once. The
+ * settle runs on for about this long, then the content holds under the
+ * finger. Lifted without a move, the content settles again on the nearest
+ * page.
+ * @source measured: UIKit lab, iOS 26.2 simulator, Oct 23 2026. After
+ * touch-downs 60 and 160 ms into a settle, the content moved on for 82.6
+ * and 87.5 ms (5 frames), then held.
+ */
+ catchStopMs: 85,
+ /**
+ * A horizontal pager's pan begins only for a drag within atan(1 ÷ this) of
+ * horizontal (26.6° for 2). A steeper drag goes to the vertical scroll around
+ * it. Between 26.6° and 45°, neither moves.
+ * @source measured: UIKit lab, iOS 26.2 simulator, Oct 23 2026. A scroll
+ * view's directional lock holds the major axis up to 25° and frees it from
+ * 30°. An inline calendar pager in a sheet pages at 20° from horizontal. At
+ * 35° and 45°, it moves neither itself nor the sheet, and it leaves 55° to
+ * the sheet.
+ */
+ panAxisRatio: 2,
+ animatedScroll: {
+ /**
+ * `setContentOffset(_:animated:)` duration. It is the same for one page and
+ * for five, as for a page control's tap.
+ * @source measured: UIKit lab, iOS 26.2 simulator, Oct 23 2026.
+ * `_contentOffsetAnimationDuration` reads 0.3, and five animated moves of
+ * 1 to 5 pages each last 0.30 s.
+ */
+ duration: 0.3,
+ /**
+ * Its curve is a sinusoidal ease-in-out: x = from + (to − from) · (1 − cos
+ * πu) ÷ 2, for u = t ÷ duration.
+ * @source measured: UIKit lab, iOS 26.2 simulator, Oct 23 2026. The five
+ * moves fit the sinusoid to 0.14–0.51 pt RMS, and a 2010 pt move fits to
+ * 0.20 pt. The curve easeInEaseOut (0.42, 0, 0.58, 1) misses by 7.7 pt.
+ */
+ curve: 'sineInOut',
+ },
+ /**
+ * Past the first or last page, the content follows the finger through the
+ * scroll view's rubber band (scroll.rubberBand.coefficient), with d = the
+ * page width. It returns on the integrator above.
+ * @source measured: UIKit lab, iOS 26.2 simulator, Oct 23 2026. A pan of 90
+ * pt past page 0 shows 42.7–45 pt, and 290 pt shows 114.3 pt. The formula
+ * gives 44.1 and 114.2, with c 0.55 and d 402. The return replays on the
+ * integrator to 0.16–0.33 pt RMS.
+ */
+ rubberBandDimension: 'pageWidth',
+} as const;
diff --git a/packages/core/src/motion/uikit/scroll.ts b/packages/core/src/motion/uikit/scroll.ts
index 7158a8d947..c2fc26ff26 100644
--- a/packages/core/src/motion/uikit/scroll.ts
+++ b/packages/core/src/motion/uikit/scroll.ts
@@ -4,8 +4,8 @@
* @file scroll.ts
* @input Nothing; data only
* @output Exports `scroll`, the UIScrollView constants: deceleration rates,
- * the rubber-band coefficient, the bounce-back spring, paging and the
- * content-touch delay
+ * the rubber-band coefficient, the bounce-back spring and the content-touch
+ * delay
* @position The scroll domain of the UIKit constants table (motion/uikit);
* read by the motion math and components
*
@@ -82,22 +82,6 @@ export const scroll = {
* @measure M-S3
*/
bounce: {duration: 0.5, bounce: 0},
- paging: {
- /**
- * Deceleration rate a paging release is projected with to pick the next
- * page.
- * @source GUESS — UIScrollView paging behaves like a fast scroll view;
- * the rate it uses internally is not documented
- * @measure M-PG1
- */
- projectionRate: 0.99,
- /**
- * The spring that carries a paging scroll view onto its page.
- * @source GUESS — SwiftUI `.smooth` default until measured
- * @measure M-PG1
- */
- snap: {duration: 0.5, bounce: 0},
- },
/**
* `delaysContentTouches`: how long a scroll view holds a touch-down from
* its content while it decides whether the touch is a scroll (no highlight
diff --git a/packages/core/src/motion/uikit/tableImports.test.ts b/packages/core/src/motion/uikit/tableImports.test.ts
index 97715084ab..65b1986f52 100644
--- a/packages/core/src/motion/uikit/tableImports.test.ts
+++ b/packages/core/src/motion/uikit/tableImports.test.ts
@@ -16,12 +16,16 @@ import {existsSync, readdirSync, readFileSync, statSync} from 'node:fs';
import {dirname, join, relative, resolve} from 'node:path';
import {describe, expect, it} from 'vitest';
-/** The tables every touch module may share: the animator and gestures read them. */
+/**
+ * The tables shared code may read. The animator and gestures read these, and
+ * the paging math reads paging.
+ */
const SHARED_TABLES = new Set([
'motion/uikit/gestures.ts',
// The long-press values: useLongPress and the menus' press model read them.
'motion/uikit/longPress.ts',
'motion/uikit/navigation.ts',
+ 'motion/uikit/paging.ts',
'motion/uikit/scroll.ts',
'motion/uikit/springs.ts',
'motion/uikit/timing.ts',
diff --git a/packages/core/src/motion/uikit/values.test.ts b/packages/core/src/motion/uikit/values.test.ts
index 467ffb6d40..aa58c72fe3 100644
--- a/packages/core/src/motion/uikit/values.test.ts
+++ b/packages/core/src/motion/uikit/values.test.ts
@@ -32,7 +32,6 @@ describe('UIKit constants table through the motion math', () => {
const springEntries: [string, SpringDescription][] = [
...Object.entries(springs),
['scroll.bounce', scroll.bounce],
- ['scroll.paging.snap', scroll.paging.snap],
];
it.each(springEntries)(