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.mdnew file mode 100644index 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.++@vjeuxdiff --git a/docs/specs/AST-094-touch-presentations/spec.md b/docs/specs/AST-094-touch-presentations/spec.mdindex 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 itsrest 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 atouch 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 aContextMenu 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 thecurrent velocity, and a release MUST hand its velocity to the spring thatfollows.+ 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 touchpresentation MUST play the exit its UIKit counterpart plays, on every touchplatform. 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 andstretch for the same travel; a mouse wheel scrolls its content and nevermoves 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 everypointer, 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 viewdiff --git a/docs/specs/components/Lightbox/Lightbox.spec.md b/docs/specs/components/Lightbox/Lightbox.spec.mdindex 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.mdindex 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 arenot Core Animation animations on iOS 26.2: UIKit writes presentationmodifiers 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 runsdiff --git a/packages/core/src/motion/README.md b/packages/core/src/motion/README.mdindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsdeleted file mode 100644index 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.tsdeleted file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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 highlightdiff --git a/packages/core/src/motion/uikit/tableImports.test.ts b/packages/core/src/motion/uikit/tableImports.test.tsindex 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.tsindex 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)(