From c7840845f20321a26b66827f132510664845f904 Mon Sep 17 00:00:00 2001
From: Cindy Zhang <cindyxz@meta.com>
Date: Sat, 24 Oct 2026 15:21:08 -0700
Subject: [PATCH 01/17] spec(AST-094): touch presentations feel native by
 default

Touch presentations get one native-feeling behavior by default on every
touch device, iOS and Android alike: measured values, compositor motion a
finger can catch, recognizer-tracked gestures with native arbitration, two
press profiles, and a Reduce Motion cross-fade. Touch motion is themeable,
with the measured values as theme defaults; gesture thresholds stay
internal. Size keys on the spec:AST-012 FR9 compact definition, a moved
default is restored by the caller's presentation choice (INV16, DEC-23),
and the record names the current claims it amends. Platform look and feel
(OQ3) and module-level experimental subpaths (OQ4) stay open.

Co-authored-by: vjeux <197597+vjeux@users.noreply.github.com>
---
 .../specs/AST-094-touch-presentations/spec.md | 397 ++++++++++++++++++
 1 file changed, 397 insertions(+)
 create mode 100644 docs/specs/AST-094-touch-presentations/spec.md

diff --git a/docs/specs/AST-094-touch-presentations/spec.md b/docs/specs/AST-094-touch-presentations/spec.md
new file mode 100644
index 0000000000000..469509af16807
--- /dev/null
+++ b/docs/specs/AST-094-touch-presentations/spec.md
@@ -0,0 +1,397 @@
+---
+schema_version: 4
+template_version: 2
+kind: system-spec
+id: spec:AST-094
+authority: draft
+archive_reason: null
+superseded_by: null
+approved_by: null
+approved_at: null
+phase: proposed
+owners: [vjeux]
+affects_architecture:
+  [
+    architecture:interaction-modality,
+    architecture:theme-tokens,
+    architecture:theme-authoring-contract,
+  ]
+affects_families: [family:buttons]
+affects_contributing: []
+affects_consumer_docs: []
+---
+
+# Touch presentations feel native system spec
+
+## Intent
+
+A person using an Astryx product on a phone or tablet gets controls, sheets,
+menus, lists and navigation with native-feeling touch behavior: measured
+physics, timings and gesture thresholds instead of desktop motion stretched to
+a finger. This behavior is the default on every touch device, iOS and Android
+alike, with no opt-in, and its motion keeps running at display rate while the
+page's JavaScript is busy.
+
+The behavior comes from one measured table. Its values are measured from UIKit
+on a named reference release, UIKit on iOS 26.2 today; each number names the
+release it was taken from, moving the reference to a newer release re-measures
+the table, and differences on older releases are noted, not targeted. Android
+touch devices get the same behavior. How touch behavior differs between the
+platforms is being explored, and the table records a separate value only where
+a measured, sourced difference exists.
+
+## Non-goals
+
+- Pointer (desktop) presentations. Their timing and easing stay with the
+  theme's duration and easing tokens (`architecture:theme-tokens`).
+- Platform-matched look and feel: glass versus material surfaces, glyphs and
+  chrome. This record governs behavior only (OQ3).
+- WebKit embedded in a native app and the native Swift package. This record
+  governs the web components themselves.
+- Scroll physics. Scrolling stays native on every platform: on iOS an overflow
+  area or the page is a UIKit scroll view already.
+- Which components get a touch presentation, and when. Each component's own
+  record owns its presentation.
+- Equivalent internal implementations remain valid when they satisfy this
+  contract. The modules, files and algorithms of the motion and gesture
+  foundations belong to their architecture records.
+
+## Requirements
+
+### Physics
+
+- **FR1 — Measured values, the same everywhere.** Every spring, duration,
+  deceleration rate, rubber-band coefficient, gesture threshold and haptic
+  moment a touch presentation uses MUST default to the measured native value
+  for that use (FR2), and every component that plays the same motion or
+  gesture MUST use the same value; a theme MAY override a motion role (FR4).
+  No component uses a value of its own where a measured value exists. The same
+  values apply on every touch platform; a platform gets a value of its own only
+  where a measured, sourced difference exists (FR2).
+- **FR2 — Every value has a source.** Each measured value MUST name its source next to it: Apple's documentation, a WWDC session, WebKit's own
+  source where WebKit states it matches UIKit, or a measurement of UIKit on
+  the iOS simulator naming the app, the iOS version, the method and the date.
+  A value without one of these MUST be labelled a guess and name the
+  measurement that will replace it. A decompilation of UIKit MAY aim a
+  measurement and MUST NOT be a source.
+- **FR3 — Native physics.** Springs MUST follow UIKit's spring model
+  (response and damping ratio, mass, stiffness and damping, and the release
+  velocity), with overdamping clamped to critical damping wherever UIKit
+  clamps it. A momentum coast MUST decay like a UIKit scroll view (0.998 per
+  millisecond, 0.99 for the fast rate), a drag past an edge MUST resist with
+  UIKit's rubber band `(1 − 1 ÷ (x·c ÷ d + 1))·d` with the coefficient its use
+  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.
+- **FR4 — Touch motion is themeable.** Every spring, duration and curve a
+  touch presentation plays MUST be a theme motion role, named by its table path
+  (`sheet.present`, `timing.curves.easeInOut`). The role's default value is
+  its table value, and a theme MAY override it through `motion`, at its root or
+  in an adaptation rule. A component MUST read touch motion through these roles
+  and MUST NOT play a literal. A theme value MUST reach the motion at its
+  start, without changing how the motion runs (FR5, FR6). Gesture thresholds,
+  the velocity filter, the timings that decide who gets a touch (the
+  content-touch delay, the scroll brake, momentum memory) and haptics are not
+  motion: they stay internal constants from the table and are not public
+  concepts (`spec:AST-002` FR3). This adds touch motion roles to the motion
+  configuration of `architecture:theme-authoring-contract` and to
+  `architecture:theme-tokens` beside the existing duration and easing tokens, whose rules are unchanged. It
+  amends `spec:AST-057` for touch presentations: Item's swipe springs and
+  durations become theme motion roles instead of constants in source, and its
+  swipe travel is a transform the recognizer writes (FR9) instead of a custom
+  property on the root (its FR2). It departs from the draft `design:motion` DR3
+  wherever the native motion settles with an overshoot or stretches with a
+  rubber band.
+
+### Motion
+
+- **FR5 — Motion runs on the compositor.** Every release and every
+  programmatic animation of a touch presentation MUST animate `transform`, the
+  individual `translate`, `scale` and `rotate` properties, or `opacity`
+  (a dialog's `::backdrop` included) through Web Animations that the browser
+  runs off the main thread,
+  and MUST keep advancing at display rate through a main-thread block. It MUST
+  NOT animate layout properties, and MUST NOT step a frame from script when the
+  compositor can run the curve.
+- **FR6 — Motion is interruptible.** A finger MUST be able to catch any
+  animation mid-flight at the value on screen. That value and its velocity
+  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.
+- **FR7 — Exits animate as the native counterpart's do.** A touch
+  presentation MUST play the exit its UIKit counterpart plays, on every touch
+  platform. A rule that turns exits off by default does not apply to touch presentations;
+  FR8 governs their reduced-motion form. Each overlay's own record states its
+  exit, since members own their animation (`family:overlay-dismissal` AV6).
+- **FR8 — Reduce Motion cross-fades.** When the person asks for reduced
+  motion (`prefers-reduced-motion: reduce`), a touch presentation MUST reach
+  each change of state by a cross-fade: it animates `opacity` only, with no
+  travel, no scale and no spring, over at most 200 ms
+  (`design:reduced-motion`). An entrance lands in place and fades in, an exit
+  fades out in place, and any other move fades through. A drag still follows
+  the finger while it is down; after the lift the presentation reaches its
+  committed state by the cross-fade. A core component MUST NOT keep its motion
+  under reduced motion (no `reducedMotion: 'keep'`). The cross-fade's duration
+  is a theme motion role whose default is at most 200 ms (FR4); a theme MAY
+  shorten it. This is iOS's Reduce Motion with Prefer Cross-Fade Transitions
+  on. `design:reduced-motion` owns the rule for every presentation, including
+  the pointer presentations this record leaves out, which change state at
+  once.
+
+### Gestures
+
+- **FR9 — A finger is tracked off the render path.** A drag MUST follow the
+  finger with one visual update per move, with no component render per move
+  and no layout read after the gesture begins.
+  Native scrolling MUST be used only where the component is a scroll view
+  (lists, scroll areas, the page). A component MAY track a finger with native
+  scroll snapping only with simulator evidence that it tracks through a
+  main-thread block, ends on the native release curve, ends correctly when the
+  finger lifts during a block, and lets a finger catch the content mid-flight.
+- **FR10 — A second finger never breaks the first.** A second finger MUST NOT
+  cancel or redirect a drag a recognizer has claimed. Page pinch-zoom MUST stay
+  the browser's whenever no pinch recognizer claims the fingers and no drag is
+  claimed (WCAG 1.4.4). A menu's press-tracking slide keeps
+  `module:DropdownMenu/useMenuPress` FR4: a second pointer or `pointercancel`
+  ends its gesture with nothing acting, which keeps the page zoomable over an
+  open menu.
+- **FR11 — Two press profiles.** Press feedback MUST follow one of two native
+  profiles. A control (UIControl) highlights on touch-down outside scroll
+  views, keeps tracking within its expanded bounds (70 pt), turns its highlight
+  off and on as the finger drags out and back, and activates on a lift inside.
+  A cell (a table or collection cell) highlights 150 ms after touch-down inside
+  a scroll view, drops the highlight when the scroll wins, and activates on a
+  lift inside it with no scroll. A control inside a scroll view (an overflow
+  area or the scrolling page) takes the same 150 ms delay before its highlight
+  and then follows its control profile; the 150 ms delay applies only inside
+  scroll views. A control whose own record keeps its press through a drag
+  keeps it: Slider's overlay stays on the dragged thumb (`design:user-states`
+  DR4). On every touch platform this amends
+  `design:user-states` DR1 (the pressed overlay during a hold) and DR3 (the
+  selected SegmentedControl item's held surface) for touch presentations, the
+  press treatment of `family:buttons`, and `module:DropdownMenu/useMenuPress`
+  FR6, whose rule that menu rows show no pressed paint under a finger gives way
+  to the cell profile for menu rows.
+- **FR12 — Long press and rubber band are per use.** A long press MUST use the
+  thresholds its UIKit counterpart uses: 0.5 s and 10 pt for a plain long
+  press, the measured values for context menus and menus. A rubber band MUST
+  use the coefficient its use measures.
+- **FR13 — One rule for the touch presentation.** Whether a component shows
+  its touch presentation MUST follow the same conditions in every component.
+  Touch behaviors key on a coarse primary pointer and are on by default there; layout keys on the available size through the one compact definition the
+  theme exports, the same on every platform (`spec:AST-012` FR9,
+  `architecture:public-component-api` INV14), and a component never restates
+  its values or keeps a parallel breakpoint table. A presentation asks for
+  exactly the conditions its own record names: one that depends on both (a
+  sheet instead of a popover) asks for both, and the date and time sheet, whose
+  record asks for a coarse pointer with no size condition (`spec:AST-043` FR1),
+  asks for the pointer only. No component answers these conditions differently
+  from another. A server render and the hydrating render produce the pointer
+  presentation, and the touch presentation applies after hydration
+  (`spec:AST-013` FR9).
+- **FR14 — Nested scrolling follows the native rule.** Who gets a drag that
+  starts inside a scroll area MUST be decided once, when the drag begins. If
+  the area sits at its edge and the drag moves toward that edge, the
+  surrounding surface (a sheet) takes the drag; otherwise the area keeps it for
+  the whole gesture and rubber-bands at its edge. The drag MUST NOT change
+  hands midway, in either direction. This amends `spec:AST-025` FR14 (scroll
+  chaining by default) for touch presentations on every touch platform.
+- **FR15 — Recognizers arbitrate like UIKit's.** Recognizers that see the
+  same touch sequence MUST be exclusive by default: the first to recognize
+  wins and the others fail, unless both allow simultaneous recognition. A
+  recognizer that requires another to fail MUST hold its recognition until
+  that one fails, and MUST fail if that one recognizes. When several recognize
+  on the same event, the innermost element's recognizer MUST win.
+- **FR16 — Gestures keep the event clock.** Recognizers MUST read time from the
+  input events' timestamps. Durations (a long press, the interval between
+  taps) MUST be deadlines on that clock, so a blocked main thread delays the
+  report and never the moment reported.
+- **FR17 — Native readings.** A recognizer's thresholds and readings MUST
+  follow UIKit's and come from the table. A pan begins at 10 pt of travel on
+  either axis, and its translation excludes that travel; its velocity is
+  UIKit's estimate, 0.2 × the newest event's instantaneous velocity + 0.8 ×
+  the previous event's, never decayed through a rest.
+- **FR18 — `touch-action` leaves the browser the rest.** An element with touch
+  recognizers MUST get a `touch-action` that leaves the browser exactly what
+  its recognizers do not use: the other axis for an axis-limited pan or swipe,
+  `manipulation` for taps and long presses, everything for a one-way pan or a
+  pan that shares its axis with native scrolling. `pinch-zoom` MUST stay
+  unless a pinch or rotation recognizer is attached.
+- **FR19 — Claims are made in time and only by an owner.** Recognizers attach
+  only under a coarse pointer; on a fine pointer no recognizer attaches and no
+  touch listener is registered (FR24). A recognizer that begins MUST claim its
+  touches by cancelling `touchmove` through a non-passive listener on its
+  element. A `touchmove` of a touch no recognizer owns MUST NOT be cancelled. A
+  recognizer that competes with native scrolling MUST decide within 10 px of
+  travel, before the browser commits to the scroll. Only an element with a
+  recognizer that must claim mid-gesture registers that blocking listener; an
+  element whose recognizers decide only at the lift keeps its `touchmove`
+  listener passive, and its `touchend` listener stays cancelable so the
+  gesture can cancel the click (FR21). Known limit: a native scroll that starts on an element with a
+  blocking listener waits for a free main thread in iOS Safari and Chromium.
+  That is never worse than UIKit, whose scrolling stops on a busy main thread,
+  and a passive listener, or one added at `touchstart`, would hand diagonal
+  drags to the scroll.
+- **FR20 — The browser can take a touch.** `pointercancel`, an uncancelable
+  `touchmove`, or a native scroll under the touch MUST count as the browser
+  taking the touch: possible recognizers that share it fail, active ones are
+  cancelled, and the view's press is cancelled without a release.
+- **FR21 — Clicks follow the gesture.** When a gesture takes a touch, its
+  `touchend` MUST be cancelled, and no click or compatibility mouse event
+  reaches the page. A click held for a recognizer that may still recognize (a
+  tap that a double tap may claim) MUST be replayed on its target if that
+  recognizer fails. Activation with `detail === 0` (keyboard, assistive
+  technology) MUST always pass. A tap MUST NOT wait for the browser's
+  double-tap delay.
+- **FR22 — The platform keeps its edge gestures.** iOS Safari's back swipe
+  from the screen edge and Android's system back gesture MUST stay the
+  browser's and the system's; a touch presentation never overrides them.
+
+### Haptics
+
+- **FR23 — Haptics where the native counterpart plays them.** A touch
+  presentation MUST play a haptic only at the moments its UIKit counterpart
+  does. In iOS Safari the only haptic a page can produce is a light impact from
+  a real tap landing on a `<label>` or a switch checkbox; a moment UIKit marks
+  mid-drag or after the lift has no haptic there, and the component records
+  that gap. `navigator.vibrate` stands in where the platform offers it.
+
+### Resources and compatibility
+
+- **FR24 — Touch work costs nothing where it is not used.** Under a fine
+  pointer, and while a touch presentation is disabled, no touch-only listener,
+  observer or timer is active. The number of `document`- or `window`-level
+  touch listeners MUST NOT grow with the number of component instances, a
+  repeated row or cell adds no touch observer of its own, and nothing
+  touch-related remains after the last instance unmounts
+  (`architecture:react-component-runtime` INV5, INV7).
+- **FR25 — A moved default keeps a way back.** Turning a touch presentation on
+  by default MUST NOT silently change a released default. Where it moves one,
+  such as Selector's `adaptive` presentation policy, the caller's
+  `presentation` choice restores the released surface and input mode
+  (`architecture:public-component-api` INV16, `spec:AST-017/DEC-23`), and the
+  change ships as a documented behavior change that names that prop
+  (`spec:AST-017` FR3). Thresholds and tuning values inside a touch mode, such
+  as a long press's delay, stay internal (`spec:AST-002` FR3); no prop exposes
+  them. This replaces `component:Selector` DEC-1's width-and-pointer query with
+  the FR13 rule for `adaptive`.
+
+### Platform support
+
+- Supported engines: Astryx's supported browsers (`spec:AST-013`) with touch
+  input, on iOS and Android. UIKit on the reference release is the parity
+  reference, not a support floor; an older iOS Safari gets the same behavior
+  wherever its engine supports it, and Android Chrome gets the same behavior.
+  This amends `spec:AST-013` FR3 with an explicit Android Chrome support row
+  for touch presentations.
+- Unsupported behavior: haptics outside the moments FR23 allows. Where an
+  engine cannot run a curve on its compositor, the animation still plays and
+  still ends on its committed state.
+- Browser evidence: the busy-main-thread proof and no layout or paint during
+  the animation in Chromium with phone emulation, the busy-main-thread proof
+  in WebKit, curves sampled by seeking the running animations, iOS simulator
+  recordings for every claim about the reference values, and real-device
+  evidence for every claim about iOS Safari and Android Chrome behavior
+  (`spec:AST-013` FR10).
+
+## Current-state impact
+
+- `architecture:theme-tokens` and `architecture:theme-authoring-contract`:
+  touch motion roles join the motion configuration, with the table's values as
+  their defaults; INV3 and the duration and easing tokens are unchanged (FR4).
+- `architecture:interaction-modality`: the touch-presentation conditions
+  (FR13) sit beside the shared modality state; its invariants are unchanged.
+- `architecture:react-component-runtime`: FR24 states the caller-visible
+  outcome of INV5 and INV7 for touch work; both are unchanged.
+- `family:buttons`: the control and cell press profiles (FR11).
+- Each overlay member's own record (Dialog, BottomSheet, Drawer, Popover, the
+  menus): its touch exit and its Reduce Motion cross-fade (FR7, FR8), since
+  members own their animation (`family:overlay-dismissal` AV6).
+- `spec:AST-057`: Item's swipe springs and durations become theme motion roles,
+  and its swipe travel is a recognizer-written transform (FR4, FR9).
+- `design:reduced-motion` owns the reduced-motion rule FR8 applies.
+- `component:Selector` DEC-1: `adaptive` resolves through the FR13 touch rule
+  (a coarse pointer and the `spec:AST-012` FR9 compact definition) instead of
+  its own width-and-pointer query, with `presentation` as the way back (FR25).
+- `module:DropdownMenu/useMenuPress` FR6: menu rows take the cell press
+  profile under a finger (FR11).
+- `design:user-states` DR1 and DR3, `spec:AST-025` FR14 and `spec:AST-013` FR3
+  each carry an amendment for touch presentations (FR11, FR14, Platform
+  support); `design:motion` DR3 and DR5 (draft) are departed from or met as
+  FR4 and FR8 state.
+- Consumer docs: none until a component ships its touch presentation; each
+  component documents its own, including the `presentation` value that keeps
+  the released surface (FR25).
+
+## Verification
+
+| Contract   | Verification                                                                                                                   | Representative states                                                                                            | Mutation or failure expectation                                                                                                                |
+| ---------- | ------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| 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                                                                      |
+| FR4        | Theme unit tests and a browser test of a themed spring                                                                         | no theme (table defaults); a theme writing a spring, a duration and a curve, at its root and in an adaptation    | a role that ignores the theme, a literal played in place of a role, or a default that differs from the table 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 layout read, a jump, or a lost velocity fails                                                                                                |
+| 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, 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 blocked page pinch, fails                                                                             |
+| FR11, FR12 | Press and long-press tests on synthetic streams with explicit timestamps                                                       | inside and outside a scroll view; drag out and back; a menu row under a finger                                   | the wrong profile's timing fails                                                                                                               |
+| FR13       | Resolver unit tests and a server-render test                                                                                   | coarse and fine pointer; narrow, wide and short; server render; hydrating render                                 | a component that answers the conditions differently, or a touch presentation in the server or hydrating render, fails                          |
+| FR14       | Browser tests of a sheet over a scrolled list                                                                                  | scrolled and at its top                                                                                          | a midway handoff fails                                                                                                                         |
+| FR15–FR17  | Recognizer unit tests on synthetic streams with explicit timestamps                                                            | exclusive, simultaneous, require-to-fail, nested; a blocked main thread; a pan at 10 pt per axis                 | a wrong winner, a late deadline, or a translation that keeps the hysteresis fails                                                              |
+| FR18–FR22  | Browser tests with real touch input                                                                                            | per-axis pans beside native scrolling, page zoom, cancelled touches, clicks after taps, keyboard activation      | a ghost click, a blocked scroll or zoom, or a cancelled unowned touchmove fails                                                                |
+| FR23       | Haptics tests on the recorded moments                                                                                          | tap, drag, lift                                                                                                  | a haptic outside a native moment fails                                                                                                         |
+| FR24       | Resource tests counting listeners, observers and timers                                                                        | fine pointer; coarse pointer enabled and disabled; many instances; unmount                                       | a touch listener on a fine pointer, a per-instance `document` or `window` listener, or a leak fails                                            |
+| FR25       | Component tests of each moved default and its `presentation` value                                                             | default; `presentation` set to the released surface                                                              | a moved default that `presentation` does not restore, or a public threshold, fails                                                             |
+| all        | iOS simulator: the UIKit reference capture and the same gesture in Safari; real iOS Safari and Android Chrome devices          | per component                                                                                                    | an unmatched curve or timing is a parity defect                                                                                                |
+
+## Decision log
+
+### DEC-1 — Touch presentations feel native by default
+
+**Reference:** `spec:AST-094/DEC-1`
+**Decider:** pending owner approval
+
+Every touch device gets one native-feeling touch behavior by default, without
+an opt-in, because the people using it already know that behavior from every
+other app on their phone. The behavior's values are measured from UIKit, not
+remembered: a number enters the table only with a citable source, and Android
+touch devices get the same values until a measured, sourced difference is
+recorded.
+
+The table supplies the defaults and a theme may retune any motion role (FR4):
+a product can soften a spring without forking a component, and the measured
+values stay the ones it starts from. Platform-matched look and feel is not part
+of this decision (OQ3).
+
+### DEC-2 — Recognizers track fingers; the compositor plays releases
+
+**Reference:** `spec:AST-094/DEC-2`
+**Decider:** pending owner approval
+
+On iOS, native scroll snapping keeps tracking through a main-thread block,
+but a finger that lifts during the block finishes on WebKit's own snap
+physics rather than UIKit's curve, a finger cannot catch the content
+mid-spring, and full-viewport hit testing breaks surfaces that leave the page
+usable around them. Tracking therefore runs in the recognizers, and every
+release runs as a compositor animation of the measured curve (FR5, FR9).
+
+## Open questions
+
+- **OQ1 — Scroll view bounce-back curve.** What curve brings a scroll view
+  back from an overscroll? It is not a single spring from rest; the rubber
+  band itself is settled. (`checkable`)
+- **OQ2 — Rotation threshold.** What rotation starts a rotation gesture? No
+  stored threshold is readable, and the simulator cannot script two-finger
+  rotation. (`checkable`)
+- **OQ3 — Platform-matched look and feel.** Should touch presentations match
+  each platform's visual conventions (glass or material surfaces, glyphs,
+  chrome)? This waits on an exploration of how iOS and Android differ; until
+  then this record sets no platform-split visual rule. (`owner decision`)
+- **OQ4 — Module-level experimental subpaths.** May the shared motion and
+  gesture modules publish experimental API through their own module-level
+  `/experimental` subpaths? `spec:AST-017` FR21 gives an experimental subpath
+  only to an owning component, and `spec:AST-002` FR18 asks a public primitive
+  for a current owning record. Options: (a) amend `spec:AST-017` FR21 to admit
+  module-level experimental subpaths with a current owning record; (b) expose
+  the modules only through an owning component's `/experimental` subpath.
+  (`owner decision`)

From 0c35c433ea445037c6c2b9e098ba4ff149ac28dc Mon Sep 17 00:00:00 2001
From: Christopher Chedeau <vjeuxx@gmail.com>
Date: Fri, 23 Oct 2026 19:57:22 -0700
Subject: [PATCH 02/17] chore(core): the UIKit constants table for touch
 presentations

Springs, scroll physics, timing curves, navigation values and gesture
thresholds for the touch presentations of core components, each with its
source (Apple documentation, a WWDC session, WebKit's UIKit-matched source,
or a measurement of UIKit on the iOS 26.2 simulator) or labelled a guess
with its measurement task. A test enforces the source rules on every domain
file, in their JSDoc and typed forms, and checks the list of simulator
measurements still owed.
---
 .changeset/uikit-constants-table.md           |   7 +
 packages/core/src/motion/MEASUREMENTS.md      | 267 ++++++++++++
 packages/core/src/motion/README.md            |  80 ++++
 .../core/src/motion/uikit/gestures.test.ts    |  71 ++++
 packages/core/src/motion/uikit/gestures.ts    | 392 ++++++++++++++++++
 packages/core/src/motion/uikit/index.ts       |  34 ++
 packages/core/src/motion/uikit/navigation.ts  |  73 ++++
 packages/core/src/motion/uikit/scroll.ts      | 117 ++++++
 packages/core/src/motion/uikit/springs.ts     | 327 +++++++++++++++
 packages/core/src/motion/uikit/timing.ts      | 144 +++++++
 packages/core/src/motion/uikit/uikit.test.ts  | 234 +++++++++++
 11 files changed, 1746 insertions(+)
 create mode 100644 .changeset/uikit-constants-table.md
 create mode 100644 packages/core/src/motion/MEASUREMENTS.md
 create mode 100644 packages/core/src/motion/README.md
 create mode 100644 packages/core/src/motion/uikit/gestures.test.ts
 create mode 100644 packages/core/src/motion/uikit/gestures.ts
 create mode 100644 packages/core/src/motion/uikit/index.ts
 create mode 100644 packages/core/src/motion/uikit/navigation.ts
 create mode 100644 packages/core/src/motion/uikit/scroll.ts
 create mode 100644 packages/core/src/motion/uikit/springs.ts
 create mode 100644 packages/core/src/motion/uikit/timing.ts
 create mode 100644 packages/core/src/motion/uikit/uikit.test.ts

diff --git a/.changeset/uikit-constants-table.md b/.changeset/uikit-constants-table.md
new file mode 100644
index 0000000000000..01fd41a182b0b
--- /dev/null
+++ b/.changeset/uikit-constants-table.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/core': patch
+---
+
+[chore] Internal: the UIKit constants table for touch presentations (springs, scroll physics, timing curves and navigation values), each value with its source and a checked list of the simulator measurements still owed. Not exported from the package entry point; no component reads it yet.
+
+@vjeux
diff --git a/packages/core/src/motion/MEASUREMENTS.md b/packages/core/src/motion/MEASUREMENTS.md
new file mode 100644
index 0000000000000..7e5600298e4d3
--- /dev/null
+++ b/packages/core/src/motion/MEASUREMENTS.md
@@ -0,0 +1,267 @@
+# Motion measurements
+
+The one list of UIKit reference captures the touch presentations need. Every
+`GUESS` or `webkit` value in `uikit/` names one of these IDs (`@measure`), and
+`uikit/uikit.test.ts` fails if a named ID is missing here. When a capture
+lands, its values replace the guesses in `uikit/` (tagged
+`@source measured: <app>, iOS <version>, <method>, <date>`).
+
+Run everything on the newest iOS simulator runtime (iOS 26.x, and 27.x when
+installed); rows marked † also on iOS 18 for the pre-glass delta. iPhone
+16-class device, 3× scale, real HID touches with logged timestamps.
+
+## Methods
+
+- **A, animation dump** (exact parameters): an instrumented UIKit app logs
+  every `CAAnimation` added to a layer (`-[CALayer addAnimation:forKey:]`):
+  view class, key, key path, class, from / to / by, additive, begin time,
+  duration, timing-function control points, and for `CASpringAnimation` mass,
+  stiffness, damping, initialVelocity, settlingDuration, allowsOverdamping.
+  Works for everything UIKit animates in process.
+- **B, recording** (ground truth on built-in apps): a 60 fps recording (120
+  where available), the moving edge tracked per frame into x(t), fitted to a
+  spring (response, damping ratio) or a curve by least squares and compared
+  with A.
+- **C, per-frame log**: a `CADisplayLink` logger writes time
+  (`CACurrentMediaTime()`), the touch stream (`UIWindow.sendEvent`),
+  `contentOffset` and the presentation frames / transforms / alphas of the
+  views under test, while a UI test drives drags of known velocity
+  (`press(forDuration:thenDragTo:withVelocity:thenHoldForDuration:)`).
+- **D, read**: print an SDK constant, a computed property or a private
+  style-provider value directly (harness or debugger).
+- **H, haptics log**: swizzle the trigger methods of `UIFeedbackGenerator` and
+  its subclasses (`impactOccurred`, `impactOccurredWithIntensity:`,
+  `selectionChanged`, `notificationOccurred:`, and private subclasses' methods)
+  and `AudioServicesPlaySystemSound*`; log class, style, timestamp. Record
+  audio.
+
+## Shared (foundation)
+
+| ID    | What                       | App and gesture                                                                                                                                       | Extract                                                                                                                | Method | Feeds                                                      |
+| ----- | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | ------ | ---------------------------------------------------------- |
+| M-S1  | Deceleration rates         | none                                                                                                                                                  | `UIScrollView.DecelerationRate.normal.rawValue`, `.fast.rawValue`                                                      | D      | `scroll.decelerationRate`                                  |
+| M-S2  | Momentum coast             | A long list (Contacts, or a probe table of 500 rows): flicks released at 1000, 2500, 5000 pt/s                                                        | contentOffset(t) from release to rest; decay constant; per-millisecond vs per-frame model; the speed at which it stops | C      | `decay.ts`                                                 |
+| M-S3  | Bounce-back spring         | Same list: drag 120 pt past the top, hold still, release; a flick into the top edge at 3000 pt/s                                                      | contentOffset(t) after release and after edge contact; spring response and damping ratio; velocity hand-off            | C      | `scroll.bounce`                                            |
+| M-S5  | Rubber band                | Same list on an 852 pt view: drag 100, 300, 600 pt past the top; a horizontal pager                                                                   | displayed overflow against finger overflow; confirm c = 0.55 and d = the view's size on the axis                       | C      | `scroll.rubberBand`                                        |
+| M-PG1 | Paging                     | Photos full-screen swipes; a probe paging scroll view                                                                                                 | page chosen per release position × velocity (thresholds; at most one page?); contentOffset(t) onto the page            | B, C   | `scroll.paging`                                            |
+| M-ST1 | Scroll to top              | Settings scrolled down 500, 2000, 8000 pt; tap the status bar                                                                                         | contentOffset(t); duration against distance; curve or spring fit                                                       | B, C   | `scroll.scrollToTopRate`                                   |
+| M-N1  | Navigation push            | Settings: tap General                                                                                                                                 | incoming leading edge x(t), outgoing x(t) (parallax fraction), dimming alpha(t); animation parameters                  | A, B   | `springs.navigationPush`                                   |
+| M-N2  | Navigation pop             | General: back button                                                                                                                                  | same as M-N1                                                                                                           | A, B   | `springs.navigationPop`                                    |
+| M-N3  | Interactive pop            | Settings ▸ General: edge swipe released at 40 % of the width at 600 pt/s (finishes) and at 30 % at rest (cancels)                                     | x(t) after release; spring parameters; the finish / cancel rule (position, velocity)                                   | A, B   | `springs.navigationInteractivePopFinish`                   |
+| M-A1  | Alert                      | Probe app: `UIAlertController(.alert)` presented and dismissed                                                                                        | scale(t), alpha(t) of the alert and the dimming view; animation parameters                                             | A      | `springs.alertPresent`, `.alertDismiss`                    |
+| M-AS1 | Action sheet and menu      | Probe app: `.actionSheet`; a button with a `UIMenu` as its primary action; Files: the … menu                                                          | scale, alpha, position (t) on open and close; animation parameters                                                     | A, B   | `springs.actionSheet*`, `.menu*`                           |
+| M-CM1 | Context menu               | Files: long-press an item; dismiss by tapping outside                                                                                                 | preview scale(t) on lift, backdrop blur and dim (t), menu scale(t); the preview's return on dismiss                    | A, B   | `springs.contextMenu*`                                     |
+| M-K1  | UIKit legacy spring        | Probe app: `UIView.animate(withDuration:usingSpringWithDamping:initialSpringVelocity:)`, durations 0.3, 0.5, 1 × ratios 0.5, 0.8, 1 × velocities 0, 2 | the `CASpringAnimation` UIKit attaches: mass, stiffness, damping, initialVelocity, duration, settlingDuration          | A      | `springFromUIKitDampingDuration`                           |
+| M-K2  | Default spring, keyboard   | Probe app: an animator with `UISpringTimingParameters()`; focus and blur a text field                                                                 | both springs' parameters and allowsOverdamping; the keyboard notification's duration and curve                         | A, D   | `springs.uikitDefault`, `.keyboard`, `timing.keyboard*`    |
+| M-CA1 | Settling duration          | none: `CASpringAnimation` mass 1, stiffness 100, damping 5, 10, 15, 20, 40 × initialVelocity 0, 5, −5 × allowsOverdamping on, off                     | `settlingDuration` of each (checks the critically damped and overdamped branches)                                      | D      | `settlingDuration`                                         |
+| M-T1  | Banner                     | A notification pushed to the simulator while an app is in the foreground                                                                              | banner y(t) in and out; time on screen                                                                                 | B      | `springs.banner`                                           |
+| M-RM1 | Reduced Motion             | Reduce Motion on, Prefer Cross-Fade Transitions on and off: Settings push and pop, an alert (sheets: M-SH13; controls: M-SW11, M-SL12, M-SG15)        | which transitions become cross-fades; alpha(t), duration and curve; what still moves                                   | B      | `timing.reducedMotionCrossFadeMs`, the animator's fallback |
+| M-NB1 | Navigation bar hide / show | none                                                                                                                                                  | `UINavigationController.hideShowBarDuration`                                                                           | D      | `timing.navigationBarHideShowMs`                           |
+
+Done (UIKit lab, iOS 26.2 simulator, Oct 23 2026; values in `uikit/` tagged
+`measured:`): M-S1, M-NB1, M-K2, M-CA1 (underdamped grid matched to the last
+digit; critically damped within 0.02 %), M-K1 (ratios 0.1–1 in 0.05 steps),
+M-N1, M-N2, M-N3, M-S2, M-S5, M-ST1, M-RM1; and the springs of M-SH07, M-SH08, M-SH09, M-A1, M-AS1 and
+M-CM1 (their non-spring values are the components' to record). Findings that
+shape the math: every spring UIKit attaches
+has `allowsOverdamping` off (clamped to critical) except
+`UIView.animate(springDuration:bounce:)`; with it on, Core Animation renders
+"overdamped" springs with the two exponentials' coefficients swapped and the
+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.
+
+## Gestures (UIKit gesture recognizers)
+
+Thresholds the gesture system reads (`uikit/gestures.ts`). Safari on iOS runs
+UIKit's own recognizers for tap-to-click, long press, double tap and the start
+of a page scroll, so many of these can be read off Safari itself.
+
+| ID    | Feeds                                           | Capture                                                                                                                                                                                              | Method |
+| ----- | ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ |
+| M-G01 | `UIKIT_GESTURES.tap.allowableMovement`          | Safari (UIKit tap -> click): on a touch-action:none box, HID touch down, move N px over 100 ms, lift; binary-search the largest N that still fires click.                                            | C      |
+| M-G02 | `UIKIT_GESTURES.tap.maximumIntervalBetweenTaps` | Safari with user-scalable=no (UIKit double-tap -> dblclick): two HID taps T ms apart; binary-search the largest T that fires dblclick.                                                               | C      |
+| M-G03 | `UIKIT_GESTURES.tap.allowableSeparation`        | Safari with user-scalable=no: two HID taps 150 ms apart, the second D px away; binary-search the largest D that fires dblclick.                                                                      | C      |
+| M-G04 | `UIKIT_GESTURES.tap.maximumTapDuration`         | Safari: HID hold on a <button> for 0.5, 1, 2, 4 s then lift; record which fire click.                                                                                                                | C      |
+| M-G05 | `UIKIT_GESTURES.pan.hysteresis`                 | Settings list (UIScrollView pan): slow HID drag at 20 px/s filmed at 60 fps; touch travel at the first frame the content moves.                                                                      | B, C   |
+| M-G06 | `UIKIT_GESTURES.swipe.minimumDistance`          | Needs a UIKit app that uses UISwipeGestureRecognizer (no built-in candidate known): HID swipes of increasing length at 600 px/s.                                                                     | C      |
+| M-G07 | `UIKIT_GESTURES.swipe.maximumDuration`          | Same rig as minimumDistance: 120 px swipes at decreasing speed; longest duration that still recognizes.                                                                                              | C      |
+| M-G08 | `UIKIT_GESTURES.swipe.maximumSecondaryMovement` | Same rig: 120 px swipes at increasing angles; largest angle that still recognizes.                                                                                                                   | C      |
+| M-G09 | `UIKIT_GESTURES.pinch.hysteresis`               | Photos (zoomable image): two HID touches spreading at 20 px/s filmed at 60 fps; span change at the first frame the image scales.                                                                     | B, C   |
+| M-G10 | `UIKIT_GESTURES.rotation.hysteresis`            | Maps: two touches rotating at 10 deg/s filmed at 60 fps; angle at the first frame the map turns. The simulator HID cannot rotate two fingers: a device run or an XCUITest rotate.                    | B, C   |
+| M-G11 | `UIKIT_GESTURES.screenEdgePan.edgeRegion`       | Settings > General (UINavigationController pop): HID drags inward starting at x = 5, 10 ... 40 pt; largest x that still pops.                                                                        | C      |
+| M-G12 | `UIKIT_GESTURES.control.trackingExpansion`      | Calculator (UIButton): HID press, drag away at 20 px/s filmed at 60 fps; distance from the frame at which the highlight turns off, then back on.                                                     | B, C   |
+| M-G13 | `UIKIT_GESTURES.scroll.contentEndHandoffSlop`   | A UIKit sheet (Maps place card at the medium detent) over a scrolled list: HID drag down from mid-list; finger travel between the list reaching its top and the sheet moving.                        | C      |
+| M-G14 | `UIKIT_GESTURES.velocity.horizon`               | Safari page scroll (UIScrollView): HID flings with known speed profiles; back out the release velocity from the coast distance (0.998/ms decay) and compare with this estimator on the same samples. | C      |
+| M-G15 | `UIKIT_GESTURES.velocity.maxSamples`            | Same comparison as horizon (M-G14).                                                                                                                                                                  | C      |
+| M-G16 | `UIKIT_GESTURES.velocity.assumeStopped`         | Safari page scroll: HID drag, pause P ms, lift; smallest P after which the page does not coast.                                                                                                      | C      |
+| M-G17 | `UIKIT_GESTURES.click.strayClickWindow`         | Not a parity value: confirm in Safari and Chromium that the click follows touchend within one frame.                                                                                                 | C      |
+| M-G18 | `HAPTIC_VIBRATION_PATTERNS` (every kind)        | On an Android device, compare against the platform HapticFeedbackConstants for the same moments.                                                                                                     | C      |
+| M-G19 | `UIKIT_GESTURES.press.momentumMemory`           | Safari page, hardest HID flick: time from the lift to the last scroll event.                                                                                                                         | C      |
+
+Done (UIKit lab, iOS 26.2 simulator, Oct 23 2026: the recognizers' ivars read
+in process, each confirmed with HID touches and the state log; values in
+`uikit/gestures.ts` tagged `measured:`): M-G01 to M-G09, M-G11 (the band
+only: simulator HID touches carry no edge flag, so an edge pan cannot begin)
+and M-G12. Findings that shape the code: the pan's hysteresis applies per
+axis and is left out of `translation(in:)`; the pinch measures its scale
+from the starting span moved by its hysteresis; the swipe is recognized
+during the motion; `velocity(in:)` is 0.2 × the newest event's
+instantaneous velocity + 0.8 × the previous one's (it reproduces every value
+UIKit reported on six recorded streams), does not decay through a rest and
+ignores the lift, which settles M-G14 to M-G16 for parity (the least-squares
+values remain for the non-UIKit estimator); a sheet over a scrolled list
+leaves the whole drag to the list (no mid-gesture handoff), which leaves
+M-G13 without a parity value.
+
+## Switch (UISwitch)
+
+Subject "switch S": the first switch in Settings ▸ Accessibility ▸ Display &
+Text Size (Bold Text row); a minimal host app holds a UISwitch on a plain view
+where a switch outside any scroll view is needed.
+
+Done (iOS 26.2 simulator, Oct 23 2026; in the switch's own table,
+`uikit/switch.ts`): M-SW02, M-SW03, M-SW04, M-SW05, M-SW06, M-SW09 (UISwitch
+makes no haptic call), M-SW11 (Reduce Motion: the lift stays, the stretch
+goes), M-SW16 (iOS 26.2). Partly: M-SW07 (a single tap only). Still open:
+M-SW17, and M-SW11's On/Off labels, Reduce Transparency and Bold Text.
+
+| ID     | Scene                                                                                                                                              | Gesture                                                                                                                                                                                           | Extract                                                                                                                                    | Method  |
+| ------ | -------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | ------- |
+| M-SW01 | † Display & Text Size; light, dark, Increase Contrast on and off                                                                                   | none (static, off and on)                                                                                                                                                                         | track w / h / radius, thumb w / h / inset, shadow profile, off / on colors                                                                 | B, D    |
+| M-SW02 | † switch S                                                                                                                                         | tap: down and up 50 ms apart at the thumb center                                                                                                                                                  | per frame for 600 ms: thumb edges, track center color (fit `thumbMove`; is the color a smoothstep over 488 ms?; does a quick tap stretch?) | A, B, C |
+| M-SW03 | † switch S; and the host-app switch outside any scroll view                                                                                        | down on the thumb, hold 1.0 s, release                                                                                                                                                            | per frame from down to +1.6 s: thumb edges (stretch, lift scale), track color; onset (0 / 150 / 200 ms); `thumbPress` fit                  | A, B, C |
+| M-SW04 | † switch S (off)                                                                                                                                   | hold 300 ms, drag right at 50 pt/s to 40 pt past the end, back to 40 pt before the start, release; b: press at 80 % of the width and drag right; c: quick 40 pt swipes without a hold             | finger x per event, thumb edges per frame, color: flip line(s), discrete vs following, hysteresis, commit rule, far-side offset 0.4 w      | C       |
+| M-SW05 | † switch S                                                                                                                                         | hold 300 ms, move straight down 30, 60, 100, 150 pt (separate runs), release; then flip right and continue 150 pt down                                                                            | final value per run: slide-off abort rule, tracking slop, does a flip survive leaving the bounds                                           | C       |
+| M-SW06 | † Display & Text Size list                                                                                                                         | a: quick swipe up starting on S; b: hold 300 ms on S then drag up 200 pt; c: fling the list, touch S while decelerating; d: quick horizontal swipe on S; e: hold 1 s on a row with a context menu | list offset per frame, S value, stretch frames: scroll hand-off, brake, horizontal capture, context menu vs tracking                       | C       |
+| M-SW07 | † switch S                                                                                                                                         | double tap 120 ms apart; tap, then re-press at +80 ms and hold                                                                                                                                    | thumb edges per frame: retarget and velocity continuity, re-grab from the presentation value                                               | B, C    |
+| M-SW08 | switch S                                                                                                                                           | hold the thumb with finger 1, tap / hold finger 2 elsewhere, drag finger 1 across                                                                                                                 | value, flips: second-finger rule                                                                                                           | C       |
+| M-SW09 | host app with a UISwitch and a web view holding `<input type=checkbox switch>`, its `<label>`, and a div whose click handler calls `label.click()` | tap, hold-release, drag flips, drag back, on both                                                                                                                                                 | haptic log per event, audio: kind and moments for UISwitch; Safari's rules on the rig's WebKit; sounds                                     | H       |
+| M-SW10 | Settings S with VoiceOver; Safari showing the Astryx switch story                                                                                  | swipe to focus, double-tap                                                                                                                                                                        | Accessibility Inspector label, value, traits, hint, actions; VoiceOver caption transcript; swipe stops for the Astryx row                  | D       |
+| M-SW11 | † switch S with On/Off Labels, Reduce Motion, Reduce Transparency, Bold Text (one at a time)                                                       | tap and hold as M-SW02 / M-SW03                                                                                                                                                                   | screenshots and per-frame traces: glyph geometry, Reduce Motion substitution, lens under Reduce Transparency                               | B, C    |
+| M-SW12 | host app forced right-to-left, or Settings in Hebrew                                                                                               | M-SW02 / M-SW03 / M-SW04, short                                                                                                                                                                   | mirrored edges: RTL stretch and flip                                                                                                       | B, C    |
+| M-SW13 | Settings at AX5 Dynamic Type                                                                                                                       | static                                                                                                                                                                                            | switch size, row layout                                                                                                                    | B       |
+| M-SW14 | host app with a UISwitch at the screen center                                                                                                      | taps at 2, 5, 10, 15, 20, 30 pt outside each edge; b: iPad pointer hover                                                                                                                          | which taps toggle: hit slop and UIControl tracking slop; hover visuals                                                                     | C       |
+| M-SW15 | Safari: a page with `<input type=checkbox switch>` in a tall scrolling page; the same page blocking script 600 ms right after a tap                | tap, hold, drag flips; a pan starting on the switch; a busy tap                                                                                                                                   | frames and page scroll offset: native switch look, press, scroll blocking, behavior under a frozen main thread                             | B       |
+| M-SW16 | switch S on iOS 26.x (and 27)                                                                                                                      | hold 1 s; tap; hold and drag slowly across; release mid-track                                                                                                                                     | per frame: lens bounds (w / h / scale, overflow beyond the track), translucency, does it follow the finger 1:1, the snap on release        | A, B, C |
+| M-SW17 | host app calling `setOn(true, animated: true)`                                                                                                     | programmatic                                                                                                                                                                                      | thumb edges per frame: is the programmatic animation the tap animation?                                                                    | A, C    |
+
+## Slider (UISlider)
+
+Lab app scenes: L1 a plain `UISlider` 0…1, 300 pt wide, centered, no scroller;
+L2 L1 in a vertical list cell; L3 L1 in a horizontal paging scroll view; L4
+`TrackConfiguration(numberOfTicks: 5)` with `allowsTickValuesOnly` true, L5
+false; L6 `neutralValue` 0.5; L7 `enabledRange` 0…0.75; L8 `.thumbless`; L9
+min / max images; L10 L1 forced right-to-left; L11 SwiftUI
+`Slider(value:in:0...100, step: 25)` and `step: 1`.
+
+| ID     | Scene                                                                                                        | Gesture                                                                                                                                                                                                                   | Extract                                                                                                                        | Method |
+| ------ | ------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | ------ |
+| M-SL01 | † L1, L9; Settings brightness                                                                                | none                                                                                                                                                                                                                      | `intrinsicContentSize`, `trackRect(forBounds:)`, `thumbRect(…)` at 0 / 0.5 / 1, thumb and track colors, shadow, disabled alpha | D, B   |
+| M-SL02 | L1                                                                                                           | touch-down at the thumb center + (dx, dy) on a 2 pt grid out to ±30 pt; release                                                                                                                                           | `isTracking` after down; the thumb hit insets                                                                                  | C, D   |
+| M-SL03 | † L1                                                                                                         | touch-down on the thumb, hold 800 ms, release, wait 800 ms                                                                                                                                                                | thumb width, height, scale and opacity per frame after down and after release: lift and release springs                        | A, C   |
+| M-SL04 | L1                                                                                                           | drags at 200 / 800 / 2000 pt/s over 150 pt; a sudden stop; a release while moving at 1500 pt/s                                                                                                                            | per frame: finger x, thumb center x, thumb width; value and events after touch-up: momentum, stretch, lag                      | A, C   |
+| M-SL05 | L1                                                                                                           | drag from the thumb at 0.9 to 80 pt past the max end, hold, release                                                                                                                                                       | thumb frame and track per frame: edge squash and over-drag mapping (rubber band?)                                              | A, C   |
+| M-SL06 | L8                                                                                                           | touch-down, drag, release                                                                                                                                                                                                 | track thickness per frame; when growth starts and ends                                                                         | A, C   |
+| M-SL07 | L4, L5, L6, L7, L11                                                                                          | slow (100 pt/s) and fast (1000 pt/s) drags across all ticks; a release between ticks                                                                                                                                      | thumb x vs finger per frame; `valueChanged` values and times; tick appearance: tick snapping rule and spring                   | A, C   |
+| M-SL08 | L1                                                                                                           | a: down 8 pt right of the thumb center, drag 60 pt; b: tap the track at 20 % and 80 %; c: during a drag, move 120 pt above the slider; d: re-grab 40 ms after `setValue(0.2, animated: true)`                             | finger − thumb per frame; `valueChanged` count and values; tracking while outside; re-grab offset                              | C      |
+| M-SL09 | L1                                                                                                           | `setValue(0.8, animated: true)` from 0.2                                                                                                                                                                                  | thumb x per frame: duration and curve of an animated value change                                                              | A, C   |
+| M-SL10 | L1, L4, L7                                                                                                   | drags into and out of min and max (re-enter 3×); slow and fast drags across ticks; a 50-tick fast sweep                                                                                                                   | haptic log with timestamps, audio: moments, kinds, re-arm, rate limit                                                          | H      |
+| M-SL11 | L2, L3, Settings ▸ Display & Brightness, Settings ▸ Accessibility ▸ Display & Text Size ▸ Larger Text        | from the thumb: quick horizontal swipe, quick vertical swipe, hold 300 ms then vertical, diagonals at 30° / 45° / 60°; from the track: vertical and horizontal swipes; in L3: horizontal from the thumb vs from the track | content offset per frame; thumb x vs finger for the first 150 ms; which recognizer wins: delay, pan hysteresis, parallel rule  | C      |
+| M-SL12 | L1, L4 under Reduce Motion, Reduce Transparency, Increase Contrast, Show Borders, AX5                        | M-SL03 and M-SL04 gestures                                                                                                                                                                                                | same traces and screenshots: accessibility substitutions                                                                       | B, C   |
+| M-SL13 | Accessibility Inspector on L1, L4; Safari on the probe page (ltr and rtl sliders); iPad keyboard and pointer | Increment ×3; hardware-keyboard arrows with Full Keyboard Access; pointer hover and click on the track                                                                                                                    | value string, traits, hint, value deltas (animated?); the RTL increment direction                                              | D      |
+| M-SL14 | Safari showing the slider stories, side by side with L1 / L2                                                 | the slider storyboards scripted identically                                                                                                                                                                               | paired 60 fps recordings (parity proof)                                                                                        | B      |
+
+## Segmented control (UISegmentedControl)
+
+Harness scenes (UIKit, no SwiftUI): S1 three equal text segments in a plain
+view; S2 the same in a vertical scroll view with tall content; S3 in a
+horizontal scroll view; S4 `apportionsSegmentWidthsByContent` with unequal
+labels; S5 `isMomentary`; S6 segment 1 disabled; S7 forced right-to-left; S8
+five icon segments; S9 a button setting `selectedSegmentIndex = 2` (plain and
+inside `UIView.animate`); S10 no initial selection. The harness logs
+`valueChanged` with `CACurrentMediaTime()`. Built-in fallbacks: Health's chart
+range control (in a scroll view), Calendar's New Event sheet, Safari's
+Bookmarks sheet.
+
+| ID     | Scene                                                                                                                                       | Gesture or action                                                                                                                                                                                                                                                                                                                                                                                 | Extract                                                                                                                                               | Method |
+| ------ | ------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | ------ |
+| M-SG00 | setup                                                                                                                                       | report the installed runtimes and devices                                                                                                                                                                                                                                                                                                                                                         | runtimes (iOS 27.x, 26.x, 18.x), an iPhone 6.1–6.3" class device, an iPad                                                                             | D      |
+| M-SG01 | † harness or debugger                                                                                                                       | read the iPhone style provider: selection scale and hiding scale factors, `mostlyInsideMargin`, indicator inset, corner radius, divider width, default heights, spacings, paddings, fonts and colors per state, the behavior flags; the class-level highlight / hidden selection scales and default height; the liquid lens spec defaults (lift / unlift springs, hang time, displacements, blur) | exact constants, no curve fitting                                                                                                                     | D      |
+| M-SG02 | S1, S5, S9, S10 with the animation dump                                                                                                     | a: tap seg0 → seg2; b: hold the selected segment 600 ms, lift; c: hold an unselected one 600 ms, lift; d: slow drag seg0 → seg2 over 1 s, hold, lift; e: tap seg2 then seg1 at +100 ms; f: momentary tap; g: no-selection pop-in; h: programmatic set, plain and animated                                                                                                                         | every animation's parameters: which properties animate (position, bounds, transform, opacity, shadow, label) and their springs                        | A      |
+| M-SG03 | S1, 120 fps if possible                                                                                                                     | tap seg2 (down 60 ms, no movement)                                                                                                                                                                                                                                                                                                                                                                | per frame 0–800 ms: thumb left / right x, scale, label weight per segment, highlight alpha under seg2, divider alpha (iOS 18)                         | B, C   |
+| M-SG04 | S1 vs S2 (Calendar vs Health fallback)                                                                                                      | hold unselected seg1 600 ms, lift; a 40 ms tap in S2                                                                                                                                                                                                                                                                                                                                              | highlight onset, color, fade in / out; slide start vs touch-up; `valueChanged` time: does the scroll view's touch delay apply?                        | B, C   |
+| M-SG05 | † S1 and S2                                                                                                                                 | hold the selected segment 600 ms, lift                                                                                                                                                                                                                                                                                                                                                            | thumb and label scale per frame; iOS 26 / 27 lens size, displacement, blur, glass per frame; hang time after the lift                                 | A, C   |
+| M-SG06 | S1, S4                                                                                                                                      | drag from selected seg0 to seg2 at 200 pt/s, hold 300 ms, lift; then a 1500 pt/s flick                                                                                                                                                                                                                                                                                                            | per frame: finger x, thumb x / width / scale, bold label, highlight; `valueChanged` timing: step vs free model, hysteresis, release target and spring | C      |
+| M-SG07 | S1                                                                                                                                          | drag the thumb 80 pt past the trailing edge and before the leading edge; drag to seg1 then 100 pt up and lift; 30 / 60 / 100 pt down                                                                                                                                                                                                                                                              | thumb at the ends (clamp or band); commit vs revert; the distance at which tracking counts as outside                                                 | C      |
+| M-SG08 | S1                                                                                                                                          | touch unselected seg1, drag to seg2, lift; touch seg1, drag 100 pt up, lift                                                                                                                                                                                                                                                                                                                       | which segment highlights during the drag; which gets selected                                                                                         | C      |
+| M-SG09 | S2, S3; an iOS 26 app with a navigation stack                                                                                               | S2: vertical 40 pt in 150 ms from seg1 and from the selected seg0, a 30° diagonal; S3: horizontal drag starting on the thumb vs on an unselected segment; a back-swipe from the control                                                                                                                                                                                                           | which recognizer wins; cancel visuals                                                                                                                 | C      |
+| M-SG10 | S1                                                                                                                                          | tap seg2, at +80 ms tap seg1; tap seg2, at +80 ms touch down on the moving thumb and hold 500 ms                                                                                                                                                                                                                                                                                                  | trajectory continuity; does the thumb stop under the finger (retarget, re-grab)                                                                       | B, C   |
+| M-SG11 | S1                                                                                                                                          | finger A holds seg0; finger B taps seg2; A drags while B taps                                                                                                                                                                                                                                                                                                                                     | ignored or not                                                                                                                                        | C      |
+| M-SG12 | harness with the haptics log                                                                                                                | tap; hold and lift the selected segment; drag across two segments; momentary tap                                                                                                                                                                                                                                                                                                                  | calls and timestamps relative to the touches; confirm no sound                                                                                        | H      |
+| M-SG13 | Accessibility Inspector (VoiceOver on a device if available)                                                                                | inspect S1, S5, S6, S8, and Safari showing the Astryx story                                                                                                                                                                                                                                                                                                                                       | label, value, traits, hint, frame, container type; spoken strings                                                                                     | D      |
+| M-SG14 | Larger Text: default, xxxL, AX1, AX3, AX5                                                                                                   | screenshots of S1, Health, Calendar; at AX sizes long-press a segment                                                                                                                                                                                                                                                                                                                             | font size and height per size; the large-text popover look, press duration, selection inside                                                          | B      |
+| M-SG15 | Bold Text; Increase Contrast; Reduce Transparency; Reduce Motion (+ Prefer Cross-Fade); iOS 27 glass at More Clear / More Tinted; dark mode | rest screenshots and M-SG03 tap frames                                                                                                                                                                                                                                                                                                                                                            | appearance deltas; the Reduce Motion substitute (slide vs fade, duration)                                                                             | B, C   |
+| M-SG16 | S7; Arabic system language for a built-in                                                                                                   | M-SG06 drag                                                                                                                                                                                                                                                                                                                                                                                       | mirrored order and drag                                                                                                                               | C      |
+| M-SG17 | S5 momentary                                                                                                                                | tap; hold 600 ms                                                                                                                                                                                                                                                                                                                                                                                  | highlight, thumb pop, hide scale and fade, timings                                                                                                    | A, C   |
+| M-SG18 | iPad S1 (touch; pointer if available)                                                                                                       | tap, hold, drag; hover                                                                                                                                                                                                                                                                                                                                                                            | differences from iPhone                                                                                                                               | B      |
+| M-SG19 | Safari showing the segmented stories vs S1                                                                                                  | the segmented storyboards side by side                                                                                                                                                                                                                                                                                                                                                            | synced recordings (parity proof)                                                                                                                      | B      |
+
+## Sheets (UISheetPresentationController)
+
+Probe app "SheetProbe" on an iPhone 16 Pro (iPad Pro 11" for M-SH11 / M-SH20 /
+M-SH21): a display-link logger of the sheet container's presentation frame and
+corner radius, the dimming view's alpha, the presenting view's transform and
+corner radius, the grabber frame; the animation dump at the start of each
+transition; the haptics log; drags driven with known velocity and the touch
+stream logged. Built-in apps are recorded too, to check that system sheets
+match the probe.
+
+| ID      | Scene                                                                                                                  | Gesture or action                                                                                                                   | Extract                                                                                                                                                 | Method  |
+| ------- | ---------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
+| M-SH01  | SheetProbe: detents `[.medium, .large]`, `[.large]`, a custom 0.25 · max                                               | present; read frames at rest                                                                                                        | sheet top y at each detent; `maximumDetentValue`; safe areas                                                                                            | C, D    |
+| M-SH01B | SheetProbe: content with a bottom-pinned toolbar                                                                       | drag medium → large slowly                                                                                                          | per frame: presented view height and toolbar y (relayout or translate?)                                                                                 | C       |
+| M-SH02  | SheetProbe and Maps (iOS 26)                                                                                           | rest at small / medium / large; slow drag between                                                                                   | corner radius, side and bottom inset, material per frame against height; iOS 18 baseline                                                                | B, C    |
+| M-SH02B | SheetProbe with `Detent.backgroundEffect` set and unset (26.1)                                                         | rest at each detent                                                                                                                 | effect per detent and the transition between                                                                                                            | B, C    |
+| M-SH03  | SheetProbe `prefersGrabberVisible`                                                                                     | rest; tap the grabber                                                                                                               | grabber frame, colors (light / dark / increased contrast), touch target (hit-test grid)                                                                 | C, D    |
+| M-SH04  | SheetProbe default and `largestUndimmedDetentIdentifier = .medium`; Notes' format sheet                                | drag medium → large and large → dismissed at 300 pt/s                                                                               | dimming color, alpha per frame against sheet y                                                                                                          | C       |
+| M-SH04B | SheetProbe at medium and large; the share sheet                                                                        | tap the dimmed area                                                                                                                 | dismisses or not                                                                                                                                        | C       |
+| M-SH05  | Contacts + (page sheet); SheetProbe `[.medium, .large]`                                                                | present; drag medium ⇄ large                                                                                                        | presenting view scale, translateY, corner radius per frame against sheet y                                                                              | B, C    |
+| M-SH06  | SheetProbe: a sheet presenting a sheet (both large; medium over large)                                                 | present the second; drag it down                                                                                                    | the covered sheet's transform per frame                                                                                                                 | C       |
+| M-SH07  | SheetProbe                                                                                                             | present and `dismiss(animated:)` at medium and large                                                                                | spring parameters (dump) and y per frame 0–800 ms                                                                                                       | A, C    |
+| M-SH08  | SheetProbe                                                                                                             | `animateChanges { selectedDetentIdentifier = … }` both ways                                                                         | spring parameters; the presenting view's recede timing                                                                                                  | A, C    |
+| M-SH09  | SheetProbe `[.medium, .large]`                                                                                         | drags released at 0, 200, 500, 1000, 2000, 4000 pt/s from 10 positions between and below the detents; a slow 1:1 drag in 4 pt steps | target per (position, velocity); release spring incl. initialVelocity; finger vs sheet (magnet?); dismiss / cancel boundary; minimum travel for a throw | A, C    |
+| M-SH09B | SheetProbe                                                                                                             | touch down 80 ms into a present, a detent change, a cancel                                                                          | sheet y at the touch frame vs before (grab from the presentation value)                                                                                 | C       |
+| M-SH09C | SheetProbe                                                                                                             | a second finger lands during a drag (still; moving apart)                                                                           | sheet behavior                                                                                                                                          | C       |
+| M-SH10  | SheetProbe at large                                                                                                    | drag up 50 … 600 pt slowly; release                                                                                                 | displacement against finger; fitted d for the rubber band; the return spring                                                                            | A, C    |
+| M-SH11  | SheetProbe `isModalInPresentation = true`                                                                              | drag down 50 … 600 pt; release slow and fast                                                                                        | the resistance curve; when `presentationControllerDidAttemptToDismiss` fires                                                                            | C       |
+| M-SH12  | SheetProbe text field at medium; Calendar new event                                                                    | focus, blur                                                                                                                         | sheet y per frame against the keyboard frame; the curve (notification curve 7, dump)                                                                    | A, C    |
+| M-SH12B | same                                                                                                                   | drag the sheet with the keyboard up                                                                                                 | does editing end? interactive keyboard?                                                                                                                 | C       |
+| M-SH13  | SheetProbe with Reduce Motion on                                                                                       | present, detent change, dismiss, drag release                                                                                       | the substitution (cross-fade, slide, duration)                                                                                                          | B, C    |
+| M-SH14  | SheetProbe `[.medium, .large]`, a long list at its top; again with `prefersScrollingExpandsWhenScrolledToEdge = false` | swipe up 400 pt in one gesture                                                                                                      | sheet travel vs content offset per frame (does scrolling continue in the same gesture?)                                                                 | C       |
+| M-SH15  | SheetProbe at large, list scrolled 300 pt                                                                              | one continuous 600 pt downward swipe                                                                                                | content offset, then sheet y, per frame                                                                                                                 | C       |
+| M-SH15B | SheetProbe with a horizontal collection view and long-pressable text                                                   | diagonal swipes at 20° / 45° / 70°; long-press then drag                                                                            | which recognizer wins                                                                                                                                   | C       |
+| M-SH16  | SheetProbe                                                                                                             | every transition above                                                                                                              | haptics log                                                                                                                                             | H       |
+| M-SH17  | SheetProbe with the Accessibility Inspector and VoiceOver                                                              | present; inspect the grabber; double-tap; swipe up / down; Z-scrub; at an undimmed detent, swipe past the sheet                     | label, traits, value, hint, custom actions, focus on present, escape result, reachability of content behind                                             | D       |
+| M-SH18  | SheetProbe with Reduce Transparency / Increase Contrast / Bold Text                                                    | rest at each detent                                                                                                                 | material and border changes                                                                                                                             | B       |
+| M-SH20  | Files or Mail on iPad portrait (overlay sidebar); SheetProbe split view                                                | edge-swipe to reveal; swipe to dismiss; tap the dimmed area                                                                         | sidebar x per frame, spring parameters, dim alpha, width                                                                                                | A, B, C |
+| M-SH20B | SheetProbe `UISplitViewController` with an inspector column, compact width                                             | show the inspector                                                                                                                  | presentation in compact width (sheet? detents?)                                                                                                         | B, C    |
+| M-SH21  | SheetProbe on iPad, iOS 27 `preferredPlacement` each case, RTL                                                         | present                                                                                                                             | placement geometry and motion                                                                                                                           | B, C    |
+| M-SH22  | SheetProbe iOS 26 `preferredTransition = .zoom` from a bar button                                                      | present, dismiss                                                                                                                    | morph geometry per frame                                                                                                                                | A, C    |
+
+## Context menu (UIContextMenuInteraction)
+
+Values the context menu reads from its own table (`uikit/contextMenu.ts`);
+its springs are `springs.contextMenuLift` and `springs.contextMenuDismiss`.
+
+Done (iOS 26.2 simulator, Oct 23 2026; in the context menu's table): M-CM4.
+Under Reduce Motion the pressed copy does not grow at all and only its shadow
+fades in, with Prefer Cross-Fade Transitions on or off.
+
+| ID    | What                            | App and gesture                                                                                                             | Extract                                                                                                                                                                                   | Method |
+| ----- | ------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ |
+| M-CM2 | Press feedback by size          | Probe app: context-menu interactions on views of several sizes (60 × 60, 200 × 120, 400 × 300 pt); long press               | the platter's target scale ramp (per second) before and after the commit, by size, and the spring its presentation follows                                                                | A, C   |
+| M-CM3 | Click-driver movement allowance | Probe app: long presses that drift N pt before the commit; binary search                                                    | the largest drift that still commits                                                                                                                                                      | C      |
+| M-CM4 | Reduce Motion press feedback    | Probe app with Reduce Motion on: long press, then dismiss                                                                   | press feedback, lift and dismiss animations under Reduce Motion                                                                                                                           | A, B   |
+| M-CM5 | Commit haptic stand-in          | An Android device: `navigator.vibrate` patterns against the platform's HapticFeedbackConstants for the context-click moment | the pattern that matches; not a UIKit parity value (as M-G18)                                                                                                                             | H      |
+| M-CM6 | Press thresholds                | Probe app: repeated long presses at random vsync phases                                                                     | from touch receipt and from the HID timestamp, the tick before and the tick at the press observer's began and at the click commit; the intersection pins the 150 ms and 400 ms thresholds | C      |
diff --git a/packages/core/src/motion/README.md b/packages/core/src/motion/README.md
new file mode 100644
index 0000000000000..d8bc91c74fa99
--- /dev/null
+++ b/packages/core/src/motion/README.md
@@ -0,0 +1,80 @@
+# Motion
+
+Internal motion foundation for the touch presentations of core components. It
+starts with the UIKit constants table: every spring, duration, deceleration
+rate, rubber-band constant, curve and gesture threshold a touch presentation
+uses, each with its source. Nothing here is exported from the package entry
+point; components import it by path.
+
+## Files
+
+| File                  | What it is                                                                                                              |
+| --------------------- | ----------------------------------------------------------------------------------------------------------------------- |
+| `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/timing.ts`     | Non-spring clocks and curves: press highlight, Core Animation's named curves, keyboard, Reduced Motion cross-fade.      |
+| `uikit/navigation.ts` | UINavigationController: push velocity, parallax, dimming, transition clock, interactive pop finish rule.                |
+| `uikit/gestures.ts`   | Gesture recognizer thresholds, the velocity filter and the haptic stand-ins, as typed entries the gesture system reads. |
+| `MEASUREMENTS.md`     | The UIKit reference captures each unconfirmed value still needs.                                                        |
+
+Component-specific values (a sheet's detents, a switch's geometry, a context
+menu's timeline) live in a domain file per component, `uikit/<component>.ts`,
+under the same rules.
+
+## Sources
+
+Every value in `uikit/` carries its source next to it, as a JSDoc tag on the
+entry:
+
+```
+/**
+ * What the value is, in UIKit's words.
+ * @source apple-docs https://developer.apple.com/documentation/…
+ */
+key: value,
+```
+
+Allowed source kinds:
+
+- `@source apple-docs <developer.apple.com URL>`
+- `@source wwdc <year>-<session> "<title>": <what it says>`
+- `@source webkit Source/<path> <what it says>` (Apple's engine, matched to
+  UIKit in its own comments; confirmed by a measurement)
+- `@source measured: <app>, iOS <version>, <method>, <date>`
+- `@source GUESS — <what it is based on>`
+
+A `GUESS` or `webkit` value also names the measurement that will confirm or
+replace it (`@measure M-…`, listed in MEASUREMENTS.md). An entry may carry
+several sources when different parts come from different places.
+`uikit/gestures.ts` carries the same information as typed fields that the
+gesture system reads at run time: `{value, unit, source}` with a source of one
+of the kinds above, or `{value, unit, guess, measure}` with a `measure` that
+starts with its MEASUREMENTS.md ID. `uikit/uikit.test.ts` enforces all of it on
+every domain file, in both forms: an unsourced value, an unknown kind, a guess
+without a task, or a task missing from MEASUREMENTS.md fails the build.
+
+Measurements come from the iOS simulator: built-in apps (Settings, Maps,
+Photos, Files, Contacts, Calendar, Reminders, Safari's own chrome) or a UIKit
+host app that reads the animations, recognizers and haptics UIKit attaches.
+Each names its iOS version; iOS 26.2 is the reference.
+
+### Adding a constant
+
+1. Find the source: Apple's documentation, a WWDC session, or a measurement on
+   the iOS simulator.
+2. Add the entry to the domain file it belongs to, in the vocabulary of its
+   source (a spring published as response and damping ratio stays
+   `{response, dampingRatio}`).
+3. Tag it with its `@source`. No source yet: write the best-founded `GUESS`,
+   say what it is based on, add a measurement task to MEASUREMENTS.md and tag
+   the entry with it.
+4. When a measurement lands, replace the value, tag it
+   `@source measured: …`, and drop the `@measure` tag.
+
+## Measurements
+
+[MEASUREMENTS.md](MEASUREMENTS.md) is the one list of UIKit reference captures:
+what each value still needs from the iOS simulator, the app and gesture to
+capture, the value to extract and the method. Every `@measure` ID in `uikit/`
+resolves there.
diff --git a/packages/core/src/motion/uikit/gestures.test.ts b/packages/core/src/motion/uikit/gestures.test.ts
new file mode 100644
index 0000000000000..c4ac3c7b54c64
--- /dev/null
+++ b/packages/core/src/motion/uikit/gestures.test.ts
@@ -0,0 +1,71 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file gestures.test.ts
+ * @input The gesture constants table
+ * @output Every value is sourced or is a guess that names its measurement;
+ *   the documented UIKit defaults keep their documented values
+ * @position Unit test of packages/core/src/motion/uikit/gestures.ts
+ */
+
+import {describe, expect, it} from 'vitest';
+import {
+  HAPTIC_FEEDBACK_KINDS,
+  HAPTIC_VIBRATION_PATTERNS,
+  isGuess,
+  UIKIT_GESTURES,
+  type GestureConstant,
+} from './gestures';
+
+function entries(): [string, GestureConstant<unknown>][] {
+  const result: [string, GestureConstant<unknown>][] = [];
+  for (const [group, values] of Object.entries(UIKIT_GESTURES)) {
+    for (const [name, constant] of Object.entries(values)) {
+      result.push([`${group}.${name}`, constant]);
+    }
+  }
+  for (const [kind, constant] of Object.entries(HAPTIC_VIBRATION_PATTERNS)) {
+    result.push([`haptics.${kind}`, constant]);
+  }
+  return result;
+}
+
+describe('UIKIT_GESTURES', () => {
+  it.each(entries())(
+    '%s carries a source or a measurement task',
+    (_, constant) => {
+      if (isGuess(constant)) {
+        expect(constant.guess.length).toBeGreaterThan(10);
+        expect(constant.measure).toMatch(/^M-G\d\d: .{10,}/);
+        expect('source' in constant).toBe(false);
+      } else {
+        expect(constant.source).toMatch(
+          /^(apple-docs https:\/\/developer\.apple\.com\/|wwdc \d{4}-\d+ |measured: )/,
+        );
+      }
+    },
+  );
+
+  it('keeps the documented and measured UIKit values', () => {
+    expect(UIKIT_GESTURES.longPress.minimumPressDuration.value).toBe(500);
+    expect(UIKIT_GESTURES.longPress.allowableMovement.value).toBe(10);
+    expect(UIKIT_GESTURES.tap.allowableMovement.value).toBe(45);
+    expect(UIKIT_GESTURES.tap.maximumIntervalBetweenTaps.value).toBe(350);
+    expect(UIKIT_GESTURES.pan.hysteresis.value).toBe(10);
+    expect(UIKIT_GESTURES.pinch.hysteresis.value).toBe(8);
+    expect(UIKIT_GESTURES.control.trackingExpansion.value).toBe(70);
+    expect(UIKIT_GESTURES.velocity.currentWeight.value).toBe(0.2);
+  });
+
+  it('keeps the pan decision within the distance WebKit claims a scroll at', () => {
+    // Mobile Safari's last cancelable touchmove of a slow drag is at 10 px; a
+    // pan that must cancel the native scroll decides by then.
+    expect(UIKIT_GESTURES.pan.hysteresis.value).toBeLessThanOrEqual(10);
+  });
+
+  it('has a vibration pattern for every feedback kind', () => {
+    for (const kind of HAPTIC_FEEDBACK_KINDS) {
+      expect(HAPTIC_VIBRATION_PATTERNS[kind].value.length).toBeGreaterThan(0);
+    }
+  });
+});
diff --git a/packages/core/src/motion/uikit/gestures.ts b/packages/core/src/motion/uikit/gestures.ts
new file mode 100644
index 0000000000000..cdca32009e3c7
--- /dev/null
+++ b/packages/core/src/motion/uikit/gestures.ts
@@ -0,0 +1,392 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file gestures.ts
+ * @input Nothing: plain data
+ * @output Exports UIKIT_GESTURES, the gesture thresholds the gesture system
+ *   (../../gestures) reads, each with where the number comes from, and the
+ *   GestureConstant type that carries a value and its source
+ * @position Gesture half of the UIKit constants table. Springs, scroll
+ *   physics and timing live beside it in this folder; no component carries a
+ *   gesture number of its own.
+ *
+ * Units are CSS pixels and milliseconds. On a phone with
+ * `width=device-width`, one CSS pixel is one UIKit point, so a UIKit distance
+ * in points is the same number here.
+ *
+ * Every entry is either SOURCED (Apple documentation, a WWDC session, or a
+ * measurement of a real UIKit app on the iOS simulator, named with the app,
+ * the iOS version and the method) or a GUESS. A guess says what it rests on
+ * and what to measure to replace it; `gestures.test.ts` fails if an entry
+ * carries neither. The table's shared rules hold here too (uikit.test.ts): a
+ * source starts with its kind (`apple-docs <URL>`, `wwdc <year>-<session>`,
+ * `webkit Source/…`, `measured: …`), and a guess's `measure` starts with
+ * the ID of its row in ../MEASUREMENTS.md. The press clocks are the same
+ * entries as `scroll.delaysContentTouchesMs` and `timing.press`, read from
+ * there. Safari on iOS runs UIKit's own recognizers for
+ * tap-to-click, long press, double tap and the start of a page scroll, so
+ * many guesses can be settled by measuring Safari itself.
+ *
+ * SYNC: When modified, update packages/core/src/gestures/README.md (the
+ * thresholds section) and packages/core/src/motion/uikit/gestures.test.ts.
+ */
+
+import {scroll} from './scroll';
+import {timing} from './timing';
+
+export type GestureConstantUnit =
+  'px' | 'ms' | 'px/s' | 'rad' | 'ratio' | 'count';
+
+interface GestureConstantBase<T> {
+  readonly value: T;
+  readonly unit: GestureConstantUnit;
+}
+
+/** A number with a citable origin. */
+export interface SourcedGestureConstant<
+  T = number,
+> extends GestureConstantBase<T> {
+  /** Documentation URL, WWDC session, or `measured: <app>, <iOS>, <method>`. */
+  readonly source: string;
+}
+
+/** A number nobody has measured yet. */
+export interface GuessedGestureConstant<
+  T = number,
+> extends GestureConstantBase<T> {
+  /** What the guess rests on. */
+  readonly guess: string;
+  /** The measurement that replaces it. */
+  readonly measure: string;
+}
+
+export type GestureConstant<T = number> =
+  SourcedGestureConstant<T> | GuessedGestureConstant<T>;
+
+/** Whether a constant still needs its measurement. */
+export function isGuess<T>(
+  constant: GestureConstant<T>,
+): constant is GuessedGestureConstant<T> {
+  return 'guess' in constant;
+}
+
+const APPLE = 'https://developer.apple.com/documentation/uikit';
+
+/**
+ * In-process reads and touch runs of fresh UIKit recognizers (private ivars
+ * read with key-value coding, every value confirmed with HID touches and the
+ * recognizer state log), iPhone 17 Pro simulator, iOS 26.2, Oct 2026.
+ */
+const UIKIT_LAB =
+  'measured: UIKit lab, iOS 26.2 simulator, ivar reads confirmed with HID touches';
+
+/**
+ * The repository's own measurement of the touch press model, recorded in
+ * packages/core/src/utils/pressGesture.ts: Settings and Contacts on an iPhone
+ * simulator running iOS 26.2, driven with real HID touches, filmed at 60 fps.
+ */
+const PRESS_MEASUREMENT =
+  'measured: Settings and Contacts, iOS 26.2 simulator, HID touches filmed at 60 fps (utils/pressGesture.ts)';
+
+/**
+ * Safari page scroll is a UIScrollView: the distance at which it claims a
+ * slow drag is where a press becomes a scroll, and the last moment a page
+ * can still cancel the scroll.
+ */
+const SAFARI_SCROLL_CLAIM =
+  'measured: Mobile Safari 26.2, iOS 26.2 simulator, slow HID drag on a scrollable page (1 pt steps): last cancelable touchmove at 10 px, pointercancel and the first uncancelable touchmove at 11 px';
+
+export const UIKIT_GESTURES = {
+  tap: {
+    /**
+     * How far each finger may travel from where it landed before a tap
+     * fails, as a distance.
+     */
+    allowableMovement: {
+      value: 45,
+      unit: 'px',
+      source: `${UIKIT_LAB}: UITapGestureRecognizer _allowableMovement 45; 44 pt taps, 46 pt fails, the same on the diagonal`,
+    },
+    /** Longest interval between one tap lifting and the next landing. */
+    maximumIntervalBetweenTaps: {
+      value: 350,
+      unit: 'ms',
+      source: `${UIKIT_LAB}: _maximumIntervalBetweenSuccessiveTaps 0.35 s; 330 ms double-taps, 370 ms does not`,
+    },
+    /** How far a later tap may land from the first one of the sequence. */
+    allowableSeparation: {
+      value: 45,
+      unit: 'px',
+      source: `${UIKIT_LAB}: _allowableSeparation is unbounded and the 45 pt movement rule applies between taps; 44 pt double-taps, 46 does not`,
+    },
+    /** Longest a finger may stay down and still tap. */
+    maximumTapDuration: {
+      value: 1500,
+      unit: 'ms',
+      source: `${UIKIT_LAB}: maximumTapDuration 1.5 s; a 1.4 s hold taps, 1.6 s does not`,
+    },
+  },
+  longPress: {
+    /** UILongPressGestureRecognizer.minimumPressDuration default. */
+    minimumPressDuration: {
+      value: 500,
+      unit: 'ms',
+      source: `apple-docs ${APPLE}/uilongpressgesturerecognizer/minimumpressduration; ${UIKIT_LAB}: _minimumPressDuration 0.5`,
+    },
+    /** UILongPressGestureRecognizer.allowableMovement default, a distance. */
+    allowableMovement: {
+      value: 10,
+      unit: 'px',
+      source: `apple-docs ${APPLE}/uilongpressgesturerecognizer/allowablemovement; ${UIKIT_LAB}: a (7, 7) drift begins, (7.2, 7.2) fails`,
+    },
+  },
+  pan: {
+    /**
+     * Travel before a pan begins, PER AXIS: |dx| or |dy| reaching it. The
+     * translation is reset when the pan begins, so the hysteresis is not
+     * part of it. Kept below the distance at which WebKit claims a drag for
+     * scrolling, so a pan that must cancel the native scroll still sees
+     * cancelable `touchmove`s.
+     */
+    hysteresis: {
+      value: 10,
+      unit: 'px',
+      source: `${UIKIT_LAB}: UIPanGestureRecognizer _hysteresis 10; x and y began at 10.0, a diagonal at (10.67, 10.67); translation(in:) is 0 at .began`,
+    },
+  },
+  swipe: {
+    /** Travel along the swipe direction before a swipe is recognized. */
+    minimumDistance: {
+      value: 50,
+      unit: 'px',
+      source: `${UIKIT_LAB}: UISwipeGestureRecognizer minimum primary movement 50; recognized during the motion; 40 pt does not`,
+    },
+    /** Longest a swipe may take before it fails. */
+    maximumDuration: {
+      value: 500,
+      unit: 'ms',
+      source: `${UIKIT_LAB}: UISwipeGestureRecognizer maximum duration 0.5 s`,
+    },
+    /** Travel across the swipe direction that fails it. */
+    maximumSecondaryMovement: {
+      value: 50,
+      unit: 'px',
+      source: `${UIKIT_LAB}: UISwipeGestureRecognizer maximum secondary movement 50`,
+    },
+    /**
+     * How the minimum movement relaxes over time. Read, not modelled: a
+     * 120 pt swipe over 0.8 s was recognized at 303 ms, below 50 pt of travel.
+     */
+    minimumMovementDecay: {
+      value: 0.06,
+      unit: 'ratio',
+      source: `${UIKIT_LAB}: UISwipeGestureRecognizer rateOfMinimumMovementDecay 0.06 (not modelled)`,
+    },
+  },
+  pinch: {
+    /**
+     * Change of the distance between two fingers before a pinch begins. The
+     * scale is then measured against the starting span moved by this much,
+     * so it does not jump.
+     */
+    hysteresis: {
+      value: 8,
+      unit: 'px',
+      source: `${UIKIT_LAB}: UIPinchGestureRecognizer _hysteresis 8; out from 120 began at 144 with scale 1.125 (= 144 / 128)`,
+    },
+  },
+  rotation: {
+    /** Rotation of the two-finger vector before a rotation begins. */
+    hysteresis: {
+      value: (5 * Math.PI) / 180,
+      unit: 'rad',
+      guess:
+        'UIRotationGestureRecognizer has no scalar threshold among its ivars; 5 degrees.',
+      measure:
+        'M-G10: The simulator HID cannot rotate two fingers: a device run (or an XCUITest rotate) logging the angle at .began.',
+    },
+  },
+  screenEdgePan: {
+    /** Width of the band at the screen edge a touch must land in. */
+    edgeRegion: {
+      value: 40.2,
+      unit: 'px',
+      source: `${UIKIT_LAB}: UIScreenEdgePanGestureRecognizer _edgeRegionSize 40.2 on a 402 pt wide screen (10 % of it); edge pans cannot begin from simulator HID`,
+    },
+    /** Travel before an edge pan begins. */
+    hysteresis: {
+      value: 15,
+      unit: 'px',
+      source: `${UIKIT_LAB}: the screen-edge pan hysteresis ivar 15`,
+    },
+  },
+  control: {
+    /**
+     * How far outside its bounds a UIControl keeps a press inside: a finger
+     * dragged out is still "inside" until it passes this margin.
+     */
+    trackingExpansion: {
+      value: 70,
+      unit: 'px',
+      source: `${UIKIT_LAB}: UIButton (.system) stays inside up to 70 pt out, touchDragExit at 71, touchDragEnter at 69 coming back; touchUpInside up to 70, touchUpOutside from 71`,
+    },
+  },
+  press: {
+    /** UIScrollView.delaysContentTouches: a touch in a scroller highlights after this. */
+    contentTouchDelay: {
+      value: scroll.delaysContentTouchesMs,
+      unit: 'ms',
+      source: PRESS_MEASUREMENT,
+    },
+    /** A tap shorter than the delay shows the highlight at the lift for this long. */
+    quickTapFlash: {
+      value: timing.press.flashMs,
+      unit: 'ms',
+      source: PRESS_MEASUREMENT,
+    },
+    /** Travel at which a press is a scroll, not a press. */
+    slop: {value: 10, unit: 'px', source: SAFARI_SCROLL_CLAIM},
+    /** A touch this soon after a finger-driven scroll moved is a brake, not a press. */
+    scrollBrake: {
+      value: timing.press.scrollBrakeMs,
+      unit: 'ms',
+      source: PRESS_MEASUREMENT,
+    },
+    /**
+     * How long after a finger was down a scroll can still be that finger's
+     * momentum (the brake only counts scrolls a finger drove).
+     */
+    momentumMemory: {
+      value: 3000,
+      unit: 'ms',
+      guess:
+        'The press model bound (utils/pressFeedback.ts): iOS momentum runs for a second or two after the lift.',
+      measure:
+        'M-G19: Safari page, hardest HID flick: time from the lift to the last scroll event.',
+    },
+  },
+  scroll: {
+    /**
+     * Travel past the point where a native scroll ran out of content before
+     * an opt-in `scrollHandoff` pan takes the rest of the gesture. UIKit
+     * itself never hands a drag over mid-gesture (a sheet over a scrolled
+     * list leaves the whole drag to the list), so this is not a parity value.
+     */
+    contentEndHandoffSlop: {
+      value: 4,
+      unit: 'px',
+      guess:
+        'The BottomSheet value (useSheetGestures.ts): enough to ignore a fling coming to rest on the last pixel.',
+      measure:
+        'M-G13: None for parity: UIKit decides sheet versus scroll when the drag begins (a sheet over a scrolled list leaves the whole drag to the list).',
+    },
+  },
+  velocity: {
+    /**
+     * UIPanGestureRecognizer.velocity(in:) is this times the newest event's
+     * instantaneous velocity plus the rest times the previous event's
+     * (instantaneous velocity: position change over timestamp change between
+     * consecutive events, the touch-down counting as the first). The lift
+     * does not update it, and a finger at rest sends no events, so a release
+     * after a pause reports the last moving value.
+     */
+    currentWeight: {
+      value: 0.2,
+      unit: 'ratio',
+      source: `${UIKIT_LAB}: fitted to all 69 velocity(in:) values of six HID streams (constant, accelerating, pauses before the lift) to 0.0 pt/s`,
+    },
+    /** For the least-squares alternative: samples older than this are ignored. */
+    horizon: {
+      value: 100,
+      unit: 'ms',
+      guess:
+        "Android's VelocityTracker and Flutter's fit the last 100 ms (least squares, degree 2); UIKit itself uses currentWeight.",
+      measure: 'M-G14: Not a parity value: UIKit uses the two-event filter.',
+    },
+    /** For the least-squares alternative: at most this many samples. */
+    maxSamples: {
+      value: 20,
+      unit: 'count',
+      guess: 'Android VelocityTracker and Flutter VelocityTracker keep 20.',
+      measure: 'M-G15: Not a parity value: UIKit uses the two-event filter.',
+    },
+    /**
+     * For the least-squares alternative: a gap this long between samples
+     * separates two motions.
+     */
+    assumeStopped: {
+      value: 40,
+      unit: 'ms',
+      guess: 'Android VelocityTracker and Flutter VelocityTracker use 40 ms.',
+      measure: 'M-G16: Not a parity value: UIKit uses the two-event filter.',
+    },
+  },
+  click: {
+    /**
+     * Longest the system waits for the browser's click after a touch it
+     * swallows. iOS and Chromium deliver it right after `touchend`; this only
+     * bounds a click that never comes.
+     */
+    strayClickWindow: {
+      value: 1000,
+      unit: 'ms',
+      guess: 'A safety bound, not a UIKit number.',
+      measure:
+        'M-G17: Not a parity value: confirm in Safari and Chromium that the click follows touchend within one frame.',
+    },
+  },
+} as const satisfies Record<string, Record<string, GestureConstant>>;
+
+/**
+ * The feedback kinds UIKit's generators offer: UISelectionFeedbackGenerator,
+ * UIImpactFeedbackGenerator (.light .medium .heavy .soft .rigid) and
+ * UINotificationFeedbackGenerator (.success .warning .error).
+ * https://developer.apple.com/documentation/uikit/uifeedbackgenerator
+ */
+export const HAPTIC_FEEDBACK_KINDS = [
+  'selection',
+  'impactLight',
+  'impactMedium',
+  'impactHeavy',
+  'impactSoft',
+  'impactRigid',
+  'notificationSuccess',
+  'notificationWarning',
+  'notificationError',
+] as const;
+
+export type HapticFeedbackKind = (typeof HAPTIC_FEEDBACK_KINDS)[number];
+
+/**
+ * `navigator.vibrate` patterns standing in for each kind where the platform
+ * has nothing better (Android browsers). Not UIKit numbers: a vibration motor
+ * cannot render a Taptic Engine waveform, so these only keep the relative
+ * strengths in order.
+ */
+export const HAPTIC_VIBRATION_PATTERNS: Record<
+  HapticFeedbackKind,
+  GestureConstant<ReadonlyArray<number>>
+> = {
+  selection: vibration([5]),
+  impactLight: vibration([8]),
+  impactMedium: vibration([12]),
+  impactHeavy: vibration([18]),
+  impactSoft: vibration([10]),
+  impactRigid: vibration([6]),
+  notificationSuccess: vibration([8, 60, 12]),
+  notificationWarning: vibration([12, 80, 12]),
+  notificationError: vibration([12, 50, 12, 50, 18]),
+};
+
+function vibration(
+  pattern: ReadonlyArray<number>,
+): GuessedGestureConstant<ReadonlyArray<number>> {
+  return {
+    value: pattern,
+    unit: 'ms',
+    guess:
+      'No UIKit equivalent exists for a vibration motor; durations only order the strengths.',
+    measure:
+      'M-G18: On an Android device, compare against the platform HapticFeedbackConstants for the same moments.',
+  };
+}
diff --git a/packages/core/src/motion/uikit/index.ts b/packages/core/src/motion/uikit/index.ts
new file mode 100644
index 0000000000000..2c454217cbb7f
--- /dev/null
+++ b/packages/core/src/motion/uikit/index.ts
@@ -0,0 +1,34 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file index.ts
+ * @input The domain files of the UIKit constants table
+ * @output Re-exports `springs`, `scroll`, `timing`, `navigation` and the
+ *   gesture thresholds (`UIKIT_GESTURES` and the haptic tables)
+ * @position Entry of the UIKit constants table (motion/uikit). Internal to
+ *   core: not exported from the package entry point
+ *
+ * THE table (law P1): every spring, duration, deceleration rate, rubber-band
+ * constant, timing curve and gesture threshold a touch presentation uses
+ * comes from here, with its source next to it. Components never carry their
+ * own numbers.
+ *
+ * SYNC: When a domain file is added, re-export it here and list it in
+ * /packages/core/src/motion/README.md.
+ */
+
+export {
+  HAPTIC_FEEDBACK_KINDS,
+  HAPTIC_VIBRATION_PATTERNS,
+  isGuess,
+  UIKIT_GESTURES,
+  type GestureConstant,
+  type GestureConstantUnit,
+  type GuessedGestureConstant,
+  type HapticFeedbackKind,
+  type SourcedGestureConstant,
+} from './gestures';
+export {navigation} from './navigation';
+export {scroll} from './scroll';
+export {springs} from './springs';
+export {timing} from './timing';
diff --git a/packages/core/src/motion/uikit/navigation.ts b/packages/core/src/motion/uikit/navigation.ts
new file mode 100644
index 0000000000000..62dd928f4cf9e
--- /dev/null
+++ b/packages/core/src/motion/uikit/navigation.ts
@@ -0,0 +1,73 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file navigation.ts
+ * @input Nothing; data only
+ * @output Exports `navigation`: UINavigationController's push / pop geometry,
+ *   starting velocity, dimming, transition clock and the interactive pop's
+ *   finish rule
+ * @position The navigation domain of the UIKit constants table
+ *   (motion/uikit); its springs are `springs.navigationPush`,
+ *   `springs.navigationPop`, `springs.navigationInteractivePopFinish` and
+ *   `springs.navigationBarElements`
+ *
+ * On iOS 26.2 UIKit moves the cards by writing their positions into Core
+ * Animation presentation modifiers every frame from the main thread; the
+ * values below are fitted to those writes. The web version runs the same
+ * curves on the compositor, which keeps them moving while the main thread is
+ * busy.
+ *
+ * Every leaf carries one or more `@source`; webkit and GUESS values also carry
+ * the `@measure` task that will confirm or replace them. uikit.test.ts
+ * enforces both.
+ *
+ * SYNC: When modified, update /packages/core/src/motion/MEASUREMENTS.md
+ */
+
+export const navigation = {
+  /**
+   * The push and pop springs start moving at this many travels per second
+   * (3527 pt/s on a 402 pt card), not from rest.
+   * @source measured: UIKit lab (injected host app), iOS 26.2 simulator,
+   *   iPhone 17 Pro, CAPresentationModifier (value, velocity) fit, Oct 23 2026
+   */
+  pushVelocity: 8.773,
+  /**
+   * Where the card underneath ends, as a fraction of the container width:
+   * it moves from 0 to −0.3 W while the incoming card moves from W to 0.
+   * @source measured: UIKit lab (injected host app), iOS 26.2 simulator,
+   *   iPhone 17 Pro, CAPresentationModifier values, Oct 23 2026
+   */
+  parallax: -0.3,
+  /**
+   * The dimming over the card underneath: black at this alpha, its opacity
+   * going 0 → 1 on the push spring.
+   * @source measured: UIKit lab (injected host app), iOS 26.2 simulator,
+   *   iPhone 17 Pro, _UIParallaxDimmingView read, Oct 23 2026
+   */
+  dimmingAlpha: 0.1,
+  /**
+   * The transition context's duration, in ms; it paces completion callbacks
+   * (a linear property animator), not the cards.
+   * @source measured: UIKit lab (injected host app), iOS 26.2 simulator,
+   *   iPhone 17 Pro, transitionDuration read, Oct 23 2026
+   */
+  transitionMs: 350,
+  /**
+   * The interactive pop finishes when progress + this × velocity passes
+   * `interactivePopFinishThreshold` (progress in widths, velocity in widths
+   * per second): seconds of projection.
+   * @source measured: UIKit lab (injected host app), iOS 26.2 simulator,
+   *   iPhone 17 Pro, the pop decision method hooked over 61 controlled
+   *   releases: the rule matches 58; the 3 misses all finished where it says
+   *   cancel, Oct 23 2026
+   */
+  interactivePopFinishProjection: 0.35,
+  /**
+   * The progress the projected release must pass to finish the pop (a still
+   * finger at 0.475 cancels).
+   * @source measured: UIKit lab (injected host app), iOS 26.2 simulator,
+   *   iPhone 17 Pro, the pop decision method over 61 releases, Oct 23 2026
+   */
+  interactivePopFinishThreshold: 0.5,
+} as const;
diff --git a/packages/core/src/motion/uikit/scroll.ts b/packages/core/src/motion/uikit/scroll.ts
new file mode 100644
index 0000000000000..af88c91058978
--- /dev/null
+++ b/packages/core/src/motion/uikit/scroll.ts
@@ -0,0 +1,117 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @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
+ * @position The scroll domain of the UIKit constants table (motion/uikit);
+ *   read by decay.ts, rubberBand.ts, projection.ts and components
+ *
+ * Every leaf carries one `@source` (apple-docs | wwdc | webkit | measured |
+ * GUESS); webkit and GUESS values also carry the `@measure` task that will
+ * confirm or replace them (listed in motion/README.md). sources.test.ts
+ * enforces both.
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/motion/MEASUREMENTS.md (measurement tasks)
+ */
+
+export const scroll = {
+  decelerationRate: {
+    /**
+     * Normal deceleration: the release velocity is multiplied by this every
+     * millisecond, as a continuous exponential (UIScrollView keeps ln r,
+     * −0.002002, and velocities in pt/ms; decay.ts). The scroll view's own
+     * target for a release (`scrollViewWillEndDragging`) is
+     * v · r ÷ (1 − r), within 1 %: WWDC18 803's projection function.
+     * @source apple-docs https://developer.apple.com/documentation/uikit/uiscrollview/decelerationrate-swift.struct/normal
+     *   (the constant, not its number)
+     * @source measured: UIKit lab (injected host app), iOS 26.2 simulator,
+     *   iPhone 17 Pro, rawValue read, Oct 23 2026 (also a new scroll view's
+     *   decelerationRate)
+     * @source measured: UIKit lab (injected host app), iOS 26.2 simulator,
+     *   iPhone 17 Pro, deceleration ivars read mid-coast
+     *   (`_decelerationFactor` 0.998, `_decelerationLnFactorV` −0.002002, the
+     *   velocity decaying 0.4343 over 400 ms) and willEndDragging targets,
+     *   Oct 23 2026
+     */
+    normal: 0.998,
+    /**
+     * Fast deceleration (`UIScrollView.DecelerationRate.fast`).
+     * @source apple-docs https://developer.apple.com/documentation/uikit/uiscrollview/decelerationrate-swift.struct/fast
+     *   (the constant, not its number)
+     * @source measured: UIKit lab (injected host app), iOS 26.2 simulator,
+     *   iPhone 17 Pro, rawValue read and `_decelerationFactor` 0.99 (ln
+     *   −0.01005) mid-coast, Oct 23 2026
+     */
+    fast: 0.99,
+  },
+  rubberBand: {
+    /**
+     * c in b = (1 − 1 ÷ (x·c ÷ d + 1))·d, d = the scroll view's size on the
+     * axis (rubberBand.ts), x = the finger's travel past the edge after the
+     * pan's 10 pt hysteresis.
+     * @source measured: UIKit lab (injected host app), iOS 26.2 simulator,
+     *   iPhone 17 Pro, UIScrollView offsets released 100 / 300 / 600 pt past
+     *   the edge of an 874 pt view: 47 / 135 / 236.67 against the formula's
+     *   46.85 / 134.9 / 236.6, Oct 23 2026
+     * @source measured: UIKit lab (injected host app), iOS 26.2 simulator,
+     *   iPhone 17 Pro, sheet drags hooked: UISheetPresentationController
+     *   passes `withRubberBandCoefficient: 0.55` on every drag, Oct 23 2026
+     */
+    coefficient: 0.55,
+  },
+  /**
+   * The spring that returns content released past an edge, and that catches
+   * a coast hitting an edge (its velocity handed to the spring).
+   * @source GUESS — critically damped as in I. Lobanov's UIScrollView
+   *   reimplementation (no oscillation at the bound); pace from SwiftUI's
+   *   `.smooth` default duration. Measured so far (iOS 26.2 simulator, Oct 23
+   *   2026): back to the edge in about 0.5 s with no overshoot, but no single
+   *   spring from rest fits releases 47, 135 and 237 pt past the edge, so
+   *   UIKit's bounce is not a plain spring; the model is still to fit
+   * @measure M-S3
+   */
+  bounce: {duration: 0.5, bounce: 0},
+  paging: {
+    /**
+     * Deceleration rate a paging release is projected with to pick the next
+     * page (projection.ts `selectPage`).
+     * @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
+   * flash on a quick scroll), in ms.
+   * @source wwdc 2014-235 "Advanced Scrollviews and Touch Handling
+   *   Techniques": the touch-delay recognizer UIScrollView uses runs "a
+   *   pretty short timer … Let's say .15 seconds" (presenter's example value)
+   * @source measured: Settings and Contacts, iOS 26.2, simulator driven with
+   *   real HID touches at 60 fps, recorded with the touch press model
+   *   (PRESS_ONSET_MS in packages/core/src/utils/pressGesture.ts, 2026-10-06)
+   */
+  delaysContentTouchesMs: 150,
+  /**
+   * Scroll-to-top after a status-bar tap: not a spring. The offset
+   * approaches the top as 1 − e^(−9.7 t) whatever the distance (done in about
+   * 1.6 s for 500, 2000 or 8000 pt), which is a decay at this per-millisecond
+   * rate (e^(−0.0097)) whose rest point is the top: `animator.decay` with a
+   * starting velocity of 9.7 × the distance per second.
+   * @source measured: UIKit lab (injected host app), iOS 26.2 simulator,
+   *   iPhone 17 Pro, setContentOffset log after status-bar taps (starts 85–95
+   *   ms after the tap), Oct 23 2026
+   */
+  scrollToTopRate: 0.99035,
+} as const;
diff --git a/packages/core/src/motion/uikit/springs.ts b/packages/core/src/motion/uikit/springs.ts
new file mode 100644
index 0000000000000..bfe545356578a
--- /dev/null
+++ b/packages/core/src/motion/uikit/springs.ts
@@ -0,0 +1,327 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file springs.ts
+ * @input Nothing; data only
+ * @output Exports `springs`, every UIKit / SwiftUI interaction spring the
+ *   touch presentations use, each in the vocabulary of its source
+ *   (SpringDescription: duration/bounce, response/dampingRatio or
+ *   mass/stiffness/damping; `toSpring` normalizes)
+ * @position The springs domain of the UIKit constants table (motion/uikit)
+ *
+ * Every leaf carries one or more `@source` (apple-docs | wwdc | webkit |
+ * measured | GUESS); webkit and GUESS values also carry the `@measure` task
+ * that will confirm or replace them (motion/README.md lists them all).
+ * sources.test.ts enforces both.
+ *
+ * Most interaction springs below are GUESSES today: UIKit does not document
+ * the springs of its own transitions, and the simulator measurements that
+ * will replace them (method in motion/README.md) have not run yet. Each
+ * guess starts from the nearest sourced spring and names it, so a component
+ * built on the table gets the right value the moment the measurement lands,
+ * without changing.
+ *
+ * Press highlight in/out are fades, not springs: see timing.ts.
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/motion/MEASUREMENTS.md (measurement tasks)
+ */
+
+/**
+ * UIKit's default spring (see `springs.uikitDefault` for its sources). The
+ * guesses below start from it: the system-driven transitions it is believed
+ * to drive until each is measured.
+ */
+const UIKIT_DEFAULT_SPRING = {mass: 3, stiffness: 1000, damping: 500} as const;
+
+/** Push and pop (see `springs.navigationPush`). */
+const NAVIGATION_SPRING = {response: 0.3, dampingRatio: 1} as const;
+
+/**
+ * A sheet's fast release and swipe dismissal (see `springs.sheetReleaseFast`):
+ * the presentation's pace at 80 % damping.
+ */
+const SHEET_RELEASE_FAST_SPRING = {
+  response: 0.3441442326,
+  dampingRatio: 0.8,
+} as const;
+
+/**
+ * Alerts and action sheets, presenting and dismissing (see
+ * `springs.alertPresent`): UIKit's legacy 0.404 s spring, critically damped.
+ */
+const ALERT_SPRING = {mass: 1, stiffness: 522.35, damping: 45.71} as const;
+
+/** Menus and context menus opening (see `springs.menuOpen`). */
+const MENU_OPEN_SPRING = {response: 0.32, dampingRatio: 0.8} as const;
+
+/** Menus and context menus closing (see `springs.menuClose`). */
+const MENU_CLOSE_SPRING = {response: 0.35, dampingRatio: 0.85} as const;
+
+export const springs = {
+  // ---------------------------------------------------------------------
+  // Sourced presets
+  // ---------------------------------------------------------------------
+
+  /**
+   * SwiftUI `.smooth`: no bounce. Also SwiftUI's `Spring()` and
+   * `.spring(duration:bounce:)` defaults.
+   * @source apple-docs https://developer.apple.com/documentation/swiftui/spring/smooth(duration:extrabounce:)
+   */
+  smooth: {duration: 0.5, bounce: 0},
+  /**
+   * SwiftUI `.snappy`: "small amount of bounce", base bounce 0.15.
+   * @source apple-docs https://developer.apple.com/documentation/swiftui/spring/snappy(duration:extrabounce:)
+   */
+  snappy: {duration: 0.5, bounce: 0.15},
+  /**
+   * SwiftUI `.bouncy`: base bounce 0.3.
+   * @source apple-docs https://developer.apple.com/documentation/swiftui/spring/bouncy(duration:extrabounce:)
+   */
+  bouncy: {duration: 0.5, bounce: 0.3},
+  /**
+   * SwiftUI `interactiveSpring()` defaults: for a value that tracks a finger.
+   * @source apple-docs https://developer.apple.com/documentation/swiftui/animation/interactivespring(response:dampingfraction:blendduration:)
+   */
+  interactive: {response: 0.15, dampingRatio: 0.86},
+  /**
+   * SwiftUI `Animation.default` since iOS 17 (what `withAnimation` uses).
+   * @source apple-docs https://developer.apple.com/documentation/swiftui/animation/default
+   */
+  swiftUIDefault: {response: 0.55, dampingRatio: 1},
+  /**
+   * SwiftUI `.spring(response:dampingFraction:blendDuration:)` defaults.
+   * @source apple-docs https://developer.apple.com/documentation/swiftui/animation/spring(response:dampingfraction:blendduration:)
+   */
+  swiftUISpring: {response: 0.5, dampingRatio: 0.825},
+  /**
+   * UIKit `UIView.animate(springDuration:bounce:…)` defaults (iOS 17).
+   * @source apple-docs https://developer.apple.com/documentation/uikit/uiview/animate(springduration:bounce:initialspringvelocity:delay:options:animations:completion:)
+   */
+  uikitSpringDuration: {duration: 0.5, bounce: 0},
+  /**
+   * UIKit's default spring, `UISpringTimingParameters()`: Apple documents
+   * its damping ratio as 4.56, which is exactly 500 ÷ (2·√(3·1000)).
+   * Overdamped on paper; Core Animation treats overdamping as critical
+   * unless told otherwise, which `toSpring` mirrors: in effect a critically
+   * damped spring with ω₀ = 18.26 rad/s (response 0.344 s) that settles in
+   * 0.506 s. The keyboard does not use it (see `keyboard`).
+   * @source apple-docs https://developer.apple.com/documentation/uikit/uispringtimingparameters/init() (damping ratio 4.56)
+   * @source measured: UIKit lab (injected host app), iOS 26.2 simulator,
+   *   iPhone 17 Pro, CAAnimation read, Oct 23 2026: UISpringTimingParameters()
+   *   is mass 3, stiffness 1000, damping 500; UIKit runs it for 0.505824 s
+   *   (clamped to critical) whatever duration the animator was given, and
+   *   `UIView.animate` with curve 7 outside the keyboard is this spring with
+   *   its duration forced to 0.5 s
+   */
+  uikitDefault: UIKIT_DEFAULT_SPRING,
+
+  // ---------------------------------------------------------------------
+  // Navigation (UINavigationController)
+  // ---------------------------------------------------------------------
+
+  /**
+   * Push (programmatic or a row tap): the incoming card slides in from the
+   * trailing edge, the outgoing card shifts by `navigation.parallax`. The
+   * spring does not start from rest: it starts at
+   * `navigation.pushVelocity` × the travel per second.
+   * @source measured: UIKit lab (injected host app), iOS 26.2 simulator,
+   *   iPhone 17 Pro, time-free fit of the (value, velocity) pairs UIKit
+   *   writes to the cards' CAPresentationModifiers every frame (rms 5e-4 of
+   *   the travel), Oct 23 2026
+   */
+  navigationPush: NAVIGATION_SPRING,
+  /**
+   * Pop (back button or programmatic): identical to the push.
+   * @source measured: UIKit lab (injected host app), iOS 26.2 simulator,
+   *   iPhone 17 Pro, CAPresentationModifier fit as for the push, Oct 23 2026
+   */
+  navigationPop: NAVIGATION_SPRING,
+  /**
+   * Interactive pop finishing or cancelling after the finger lifts, starting
+   * from the finger's velocity; which one is `navigation.interactivePop*`.
+   * @source measured: UIKit lab (injected host app), iOS 26.2 simulator,
+   *   iPhone 17 Pro, CAPresentationModifier fit over released swipes,
+   *   Oct 23 2026
+   */
+  navigationInteractivePopFinish: {response: 0.3, dampingRatio: 0.85},
+  /**
+   * Navigation bar elements (Liquid Glass) moving during a push or pop.
+   * @source measured: UIKit lab (injected host app), iOS 26.2 simulator,
+   *   iPhone 17 Pro, UIView.animate(springDuration: 0.6, bounce: 0,
+   *   .beginFromCurrentState) calls hooked during transitions, Oct 23 2026
+   */
+  navigationBarElements: {duration: 0.6, bounce: 0},
+
+  // ---------------------------------------------------------------------
+  // Sheets (UISheetPresentationController)
+  // ---------------------------------------------------------------------
+
+  /**
+   * Sheet presented programmatically: UIKit's default spring
+   * (`UIViewPropertyAnimator(duration: 0.4, timingParameters:
+   * UISpringTimingParameters())`), which renders critically damped at
+   * response 0.344 s; the same at the medium and large detents.
+   * @source measured: UIKit lab (injected host app), iOS 26.2 simulator,
+   *   iPhone 17 Pro, CAAnimation dump (mass 3, stiffness 1000, damping 500,
+   *   duration 0.5, allowsOverdamping off), Oct 23 2026
+   */
+  sheetPresent: UIKIT_DEFAULT_SPRING,
+  /**
+   * Sheet dismissed programmatically (Cancel / Done / a scrim tap).
+   * @source measured: UIKit lab (injected host app), iOS 26.2 simulator,
+   *   iPhone 17 Pro, CAAnimation dump, the same spring as the presentation,
+   *   Oct 23 2026
+   */
+  sheetDismiss: UIKIT_DEFAULT_SPRING,
+  /**
+   * Detent change (`animateChanges`) and the settle after a slow release
+   * (below the sheet's fast-release speed, which the sheet's own table
+   * records): critically damped at the same pace as the presentation.
+   * @source measured: UIKit lab (injected host app), iOS 26.2 simulator,
+   *   iPhone 17 Pro, `_UISpringParameters(dampingRatio: 1, response:
+   *   0.3441442326)` hooked, CASpringAnimation mass 1, stiffness 333.333,
+   *   damping 36.515, Oct 23 2026
+   */
+  sheetDetent: {response: 0.3441442326, dampingRatio: 1},
+  /**
+   * The settle after a fast release (from the sheet's fast-release speed
+   * on), toward a detent or out of the screen: same pace, 80 % damping;
+   * UIKit hands it the finger's velocity.
+   * @source measured: UIKit lab (injected host app), iOS 26.2 simulator,
+   *   iPhone 17 Pro, CASpringAnimation dump over 36 releases (mass 1,
+   *   stiffness 333.333, damping 29.212), Oct 23 2026
+   */
+  sheetReleaseFast: SHEET_RELEASE_FAST_SPRING,
+  /**
+   * Sheet dismissed by a swipe: the fast-release spring.
+   * @source measured: UIKit lab (injected host app), iOS 26.2 simulator,
+   *   iPhone 17 Pro, CASpringAnimation dump (300 pt swipe in 0.15 s:
+   *   stiffness 333.333, damping 29.212), Oct 23 2026
+   */
+  sheetDismissSwipe: SHEET_RELEASE_FAST_SPRING,
+
+  // ---------------------------------------------------------------------
+  // Alerts, action sheets, menus
+  // ---------------------------------------------------------------------
+
+  /**
+   * Alert (UIAlertController .alert) appearing: fades in and scales from
+   * 1.2 to 1, the dimming fading in alongside. UIKit asks
+   * `UIView.animate(withDuration: 0.404, usingSpringWithDamping: 600,
+   * initialSpringVelocity: 0)`; the damping clamps to critical, and the
+   * spring settles at 0.404 s.
+   * @source measured: UIKit lab (injected host app), iOS 26.2 simulator,
+   *   iPhone 17 Pro, UIView.animate hooked and CASpringAnimation dumped
+   *   (mass 1, stiffness 522.350, damping 45.710, duration 0.404),
+   *   Oct 23 2026
+   */
+  alertPresent: ALERT_SPRING,
+  /**
+   * Alert dismissing: the same spring, opacity only.
+   * @source measured: UIKit lab (injected host app), iOS 26.2 simulator,
+   *   iPhone 17 Pro, CASpringAnimation dump, Oct 23 2026
+   */
+  alertDismiss: ALERT_SPRING,
+  /**
+   * Action sheet (UIAlertController .actionSheet) appearing: identical to
+   * the alert.
+   * @source measured: UIKit lab (injected host app), iOS 26.2 simulator,
+   *   iPhone 17 Pro, CASpringAnimation dump, Oct 23 2026
+   */
+  actionSheetPresent: ALERT_SPRING,
+  /**
+   * Action sheet dismissing: identical to the alert.
+   * @source measured: UIKit lab (injected host app), iOS 26.2 simulator,
+   *   iPhone 17 Pro, CASpringAnimation dump, Oct 23 2026
+   */
+  actionSheetDismiss: ALERT_SPRING,
+  /**
+   * UIMenu (from a button) opening; UIKit drives it per frame and lets it
+   * track a finger still on the screen.
+   * @source measured: UIKit lab (injected host app), iOS 26.2 simulator,
+   *   iPhone 17 Pro, `_animateUsingSpringWithDampingRatio:response:tracking:`
+   *   hooked (0.8, 0.32, tracking), Oct 23 2026
+   */
+  menuOpen: MENU_OPEN_SPRING,
+  /**
+   * UIMenu closing (a tap outside).
+   * @source measured: UIKit lab (injected host app), iOS 26.2 simulator,
+   *   iPhone 17 Pro, the same hook (0.85, 0.35, not tracking), Oct 23 2026
+   */
+  menuClose: MENU_CLOSE_SPRING,
+  /**
+   * Context menu (UIContextMenuInteraction): the preview lifting once the
+   * long press commits.
+   * @source measured: UIKit lab (injected host app), iOS 26.2 simulator,
+   *   iPhone 17 Pro, the same hook (0.8, 0.32, tracking), Oct 23 2026
+   */
+  contextMenuLift: MENU_OPEN_SPRING,
+  /**
+   * Context menu dismissing (a tap outside).
+   * @source measured: UIKit lab (injected host app), iOS 26.2 simulator,
+   *   iPhone 17 Pro, the same hook (0.85, 0.35, not tracking), Oct 23 2026
+   */
+  contextMenuDismiss: MENU_CLOSE_SPRING,
+  /**
+   * Menus opening and closing under Reduce Motion: critically damped,
+   * slower, no overshoot.
+   * @source measured: UIKit lab (injected host app), iOS 26.2 simulator,
+   *   iPhone 17 Pro, `_animateUsingSpringWithDampingRatio:response:tracking:`
+   *   hooked with Reduce Motion on (1.0, 0.4), Oct 23 2026
+   */
+  menuReducedMotion: {response: 0.4, dampingRatio: 1},
+
+  // ---------------------------------------------------------------------
+  // Controls
+  // ---------------------------------------------------------------------
+
+  /**
+   * UISwitch thumb travelling between off and on.
+   * @source webkit Source/WebCore/rendering/cocoa/RenderThemeCocoa.mm
+   *   `thumbMoveSpring = SpringSolver(1.0, 438.649…, 31.4159…)`, "Values
+   *   chosen for consistency with UIKit" (= response 0.30 s, ratio 0.75);
+   *   its settling duration is WebKit's iOS switch duration 0.48801 s
+   *   (RenderThemeIOS.h)
+   * @measure M-SW02
+   */
+  switchThumbMove: {response: 0.3, dampingRatio: 0.75},
+  /**
+   * UISwitch thumb stretching while pressed and relaxing on release.
+   * @source webkit Source/WebCore/rendering/cocoa/RenderThemeCocoa.mm
+   *   `thumbPressSpring = SpringSolver(1.0, 322.272…, 31.2364…)`, "Values
+   *   chosen for consistency with UIKit" (= response 0.35 s, ratio 0.87);
+   *   settles in WebKit's held duration 0.50740 s (RenderThemeIOS.h)
+   * @measure M-SW03
+   */
+  switchThumbStretch: {response: 0.35, dampingRatio: 0.87},
+  /**
+   * UISegmentedControl selection thumb sliding to a new segment.
+   * @source GUESS — WebKit's UIKit-matched switch thumb spring, the nearest
+   *   sourced control thumb
+   * @measure M-SG02
+   * @measure M-SG03
+   */
+  segmentedThumb: {response: 0.3, dampingRatio: 0.75},
+
+  // ---------------------------------------------------------------------
+  // System
+  // ---------------------------------------------------------------------
+
+  /**
+   * Keyboard frame animation, show and hide alike: critically damped,
+   * response 0.2667 s. The notification reports curve 7 and 0.3833 s
+   * (`timing.keyboardNotificationMs`); Core Animation cuts the spring there.
+   * @source measured: UIKit lab (injected host app), iOS 26.2 simulator,
+   *   iPhone 17 Pro, CAAnimation read on the keyboard host and a
+   *   keyboardLayoutGuide-pinned view, Oct 23 2026
+   */
+  keyboard: {mass: 1, stiffness: 555.0265, damping: 47.118},
+  /**
+   * Banner / toast sliding in from the top edge (system notification
+   * banner as the reference).
+   * @source GUESS — UIKit's default spring
+   * @measure M-T1
+   */
+  banner: UIKIT_DEFAULT_SPRING,
+} as const;
diff --git a/packages/core/src/motion/uikit/timing.ts b/packages/core/src/motion/uikit/timing.ts
new file mode 100644
index 0000000000000..91e1c0509edc2
--- /dev/null
+++ b/packages/core/src/motion/uikit/timing.ts
@@ -0,0 +1,144 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file timing.ts
+ * @input Nothing; data only
+ * @output Exports `timing`: the non-spring clocks and curves UIKit uses
+ *   (press highlight onset, flash and fade, Core Animation's named Bézier
+ *   curves, the navigation bar hide/show duration, the keyboard
+ *   notification duration, the Reduced Motion cross-fade)
+ * @position The timing domain of the UIKit constants table (motion/uikit)
+ *
+ * Every leaf carries one or more `@source` (apple-docs | wwdc | webkit |
+ * measured | GUESS); webkit and GUESS values also carry the `@measure` task
+ * that will confirm or replace them (motion/README.md). sources.test.ts
+ * enforces both.
+ *
+ * Durations are in ms (the unit of pointer-event timestamps, which these
+ * clocks are compared against); curves are cubic-bézier control points
+ * [x1, y1, x2, y2].
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/motion/MEASUREMENTS.md (measurement tasks)
+ * - /packages/core/src/utils/pressGesture.ts (the press clocks are measured
+ *   there and must agree; uikit/uikit.test.ts checks it)
+ */
+
+export const timing = {
+  press: {
+    /**
+     * Highlight onset once a press is believed: none, the highlight is
+     * painted in the frame the touch is accepted (after
+     * `scroll.delaysContentTouchesMs` inside a scroller).
+     * @source measured: Settings and Contacts, iOS 26.2, simulator driven
+     *   with real HID touches at 60 fps (touch press model,
+     *   packages/core/src/utils/pressGesture.ts, 2026-10-06)
+     */
+    highlightInMs: 0,
+    /**
+     * A tap released before the onset delay still flashes the highlight at
+     * full strength for this long before fading.
+     * @source measured: Settings and Contacts, iOS 26.2, simulator driven
+     *   with real HID touches at 60 fps (PRESS_FLASH_MS,
+     *   packages/core/src/utils/pressGesture.ts, 2026-10-06)
+     */
+    flashMs: 100,
+    /**
+     * Highlight fade after release: UIKit's deselect cross-fade.
+     * @source measured: Settings and Contacts, iOS 26.2, simulator driven
+     *   with real HID touches at 60 fps (PRESS_FADE_MS / pressConsts.releaseMs,
+     *   packages/core/src/utils/pressGesture.ts, 2026-10-06)
+     */
+    highlightOutMs: 200,
+    /**
+     * A touch on a scroller that moved this recently brakes it instead of
+     * pressing.
+     * @source measured: Settings and Contacts, iOS 26.2, simulator driven
+     *   with real HID touches at 60 fps (PRESS_SCROLL_BRAKE_MS,
+     *   packages/core/src/utils/pressGesture.ts, 2026-10-06)
+     */
+    scrollBrakeMs: 150,
+    /**
+     * UIButton (filled configuration) release: the label cross-fade and the
+     * background color both run 0.25 s on `curves.easeInOut`.
+     * @source measured: UIKit lab (injected host app), iOS 26.2 simulator,
+     *   iPhone 17 Pro, CAAnimation read (CATransition fade and backgroundColor),
+     *   Oct 23 2026
+     */
+    buttonReleaseMs: 250,
+  },
+  curves: {
+    /**
+     * `CAMediaTimingFunctionName.default`: "the timing of … most system
+     * animations" that are not springs.
+     * @source apple-docs https://developer.apple.com/documentation/quartzcore/camediatimingfunctionname/default
+     * @source measured: UIKit lab (injected host app), iOS 26.2 simulator,
+     *   iPhone 17 Pro, CAMediaTimingFunction read from UIView.animate,
+     *   Oct 23 2026
+     */
+    caDefault: [0.25, 0.1, 0.25, 1],
+    /**
+     * `easeInEaseOut`; UIKit's default curve (`UIView.AnimationCurve
+     * .easeInOut`, "the default curve for most animations").
+     * @source apple-docs https://developer.apple.com/documentation/quartzcore/camediatimingfunctionname/easeineaseout
+     * @source measured: UIKit lab (injected host app), iOS 26.2 simulator,
+     *   iPhone 17 Pro, CAMediaTimingFunction read from UIView.animate,
+     *   Oct 23 2026
+     */
+    easeInOut: [0.42, 0, 0.58, 1],
+    /**
+     * `easeIn`.
+     * @source apple-docs https://developer.apple.com/documentation/quartzcore/camediatimingfunctionname/easein
+     * @source measured: UIKit lab (injected host app), iOS 26.2 simulator,
+     *   iPhone 17 Pro, CAMediaTimingFunction read from UIView.animate,
+     *   Oct 23 2026
+     */
+    easeIn: [0.42, 0, 1, 1],
+    /**
+     * `easeOut`.
+     * @source apple-docs https://developer.apple.com/documentation/quartzcore/camediatimingfunctionname/easeout
+     * @source measured: UIKit lab (injected host app), iOS 26.2 simulator,
+     *   iPhone 17 Pro, CAMediaTimingFunction read from UIView.animate,
+     *   Oct 23 2026
+     */
+    easeOut: [0, 0, 0.58, 1],
+  },
+  /**
+   * `UINavigationController.hideShowBarDuration`, in ms.
+   * @source apple-docs https://developer.apple.com/documentation/uikit/uinavigationcontroller/hideshowbarduration
+   *   (the constant, not its value)
+   * @source measured: UIKit lab (injected host app), iOS 26.2 simulator,
+   *   iPhone 17 Pro, read, Oct 23 2026
+   */
+  navigationBarHideShowMs: 200,
+  /**
+   * The duration the keyboard notifications report
+   * (UIKeyboardAnimationDurationUserInfoKey, with curve 7), show and hide
+   * alike, in ms. The frame follows `springs.keyboard`, cut at this time.
+   * @source measured: UIKit lab (injected host app), iOS 26.2 simulator,
+   *   iPhone 17 Pro, UIKeyboardWillShow / WillHide / WillChangeFrame read,
+   *   Oct 23 2026
+   */
+  keyboardNotificationMs: 383.3,
+  /**
+   * Core Animation's implicit animation duration
+   * (`CATransaction.animationDuration()`), in ms.
+   * @source measured: UIKit lab (injected host app), iOS 26.2 simulator,
+   *   iPhone 17 Pro, read, Oct 23 2026
+   */
+  implicitAnimationMs: 250,
+  /**
+   * Reduce Motion with Prefer Cross-Fade Transitions: a navigation push or pop
+   * becomes a cross-fade of this length on `curves.easeInOut` (the new view
+   * fades in while the old one fades out, with no travel), in ms. Sheets,
+   * full-screen modals and alerts fade on their own presentation spring
+   * instead.
+   * @source apple-docs https://developer.apple.com/documentation/uikit/uiaccessibility/preferscrossfadetransitions
+   *   (the setting)
+   * @source measured: UIKit lab (injected host app), iOS 26.2 simulator,
+   *   iPhone 17 Pro, CAAnimation dump with Reduce Motion and Prefer
+   *   Cross-Fade Transitions on (opacity CABasicAnimation 0.5 s,
+   *   (0.42, 0, 0.58, 1)), Oct 23 2026
+   */
+  reducedMotionCrossFadeMs: 500,
+} as const;
diff --git a/packages/core/src/motion/uikit/uikit.test.ts b/packages/core/src/motion/uikit/uikit.test.ts
new file mode 100644
index 0000000000000..500205516350e
--- /dev/null
+++ b/packages/core/src/motion/uikit/uikit.test.ts
@@ -0,0 +1,234 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file uikit.test.ts
+ * @input vitest, the UIKit constants table and its source text
+ * @output Enforces law P2 on the table: every leaf has a source of an
+ *   allowed kind, every guess and every WebKit value names its measurement
+ *   task, every task is listed in motion/MEASUREMENTS.md; checks the plain
+ *   values (ratios, rates, curves) and that the press clocks agree with the
+ *   touch press model they were measured for
+ * @position Testing; validates motion/uikit/*.ts without a browser
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import {describe, expect, it} from 'vitest';
+import {
+  PRESS_FADE_MS,
+  PRESS_FLASH_MS,
+  PRESS_ONSET_MS,
+  PRESS_SCROLL_BRAKE_MS,
+} from '../../utils/pressGesture';
+import {scroll, springs, timing} from '.';
+import {HAPTIC_VIBRATION_PATTERNS, UIKIT_GESTURES} from './gestures';
+
+// Domain files whose entries are typed constants ({value, unit, source} or
+// {value, unit, guess, measure}); the same rules are checked on the values.
+const TYPED_TABLE_FILES = ['gestures.ts'];
+// Every other domain file carries its sources as JSDoc tags: a new one is
+// enforced the moment it lands.
+const TABLE_FILES = fs
+  .readdirSync(__dirname)
+  .filter(
+    file =>
+      file.endsWith('.ts') &&
+      file !== 'index.ts' &&
+      !file.endsWith('.test.ts') &&
+      !TYPED_TABLE_FILES.includes(file),
+  )
+  .sort();
+const SOURCE_KINDS =
+  /^@source (apple-docs https:\/\/developer\.apple\.com\/|wwdc \d{4}-\d+ |webkit Source\/|measured: .*iOS \d|GUESS — )/;
+
+interface Leaf {
+  file: string;
+  key: string;
+  doc: string;
+}
+
+/**
+ * Every leaf of the exported table object with the JSDoc block right above
+ * it. A line ending in `{` opens a group (no source of its own); any other
+ * `key: value,` line is a leaf.
+ */
+function leavesOf(file: string): Leaf[] {
+  const text = fs.readFileSync(path.resolve(__dirname, file), 'utf8');
+  const lines = text.split('\n');
+  const start = lines.findIndex(line => /^export const \w+ = \{$/.test(line));
+  expect(start).toBeGreaterThan(-1);
+  const leaves: Leaf[] = [];
+  let doc = '';
+  let inDoc = false;
+  let groupLeafCount: number[] = [];
+  for (const line of lines.slice(start + 1)) {
+    const trimmed = line.trim();
+    if (trimmed.startsWith('/**')) {
+      inDoc = true;
+      doc = '';
+    }
+    if (inDoc) {
+      doc += trimmed.replace(/^\/?\*+\/?\s?/, '') + '\n';
+      if (trimmed.endsWith('*/')) {
+        inDoc = false;
+      }
+      continue;
+    }
+    if (trimmed === '' || trimmed.startsWith('//')) {
+      continue;
+    }
+    const group = /^(\w+): \{$/.exec(trimmed);
+    if (group) {
+      groupLeafCount.push(0);
+      doc = '';
+      continue;
+    }
+    if (/^\},?$/.test(trimmed)) {
+      const count = groupLeafCount.pop();
+      expect(count, `${file}: empty group`).toBeGreaterThan(0);
+      continue;
+    }
+    if (trimmed.startsWith('} as const')) {
+      break;
+    }
+    const leaf = /^(\w+): .+,$/.exec(trimmed);
+    expect(
+      leaf,
+      `${file}: unexpected line ${JSON.stringify(trimmed)}`,
+    ).not.toBeNull();
+    if (leaf) {
+      leaves.push({file, key: leaf[1], doc});
+      groupLeafCount = groupLeafCount.map(n => n + 1);
+    }
+    doc = '';
+  }
+  return leaves;
+}
+
+const MEASUREMENTS = fs.readFileSync(
+  path.resolve(__dirname, '../MEASUREMENTS.md'),
+  'utf8',
+);
+
+describe('UIKit constants table: every value is sourced (law P2)', () => {
+  const leaves = TABLE_FILES.flatMap(leavesOf);
+
+  it('finds the table entries', () => {
+    expect(TABLE_FILES).toEqual(
+      expect.arrayContaining([
+        'navigation.ts',
+        'scroll.ts',
+        'springs.ts',
+        'timing.ts',
+      ]),
+    );
+    expect(leaves.length).toBeGreaterThan(50);
+  });
+
+  for (const {file, key, doc} of leaves) {
+    it(`${file} › ${key}`, () => {
+      // Collapse each tag's continuation lines onto it.
+      const tags = doc
+        .split(/\n(?=@)/)
+        .map(tag => tag.replace(/\s*\n\s*/g, ' ').trim())
+        .filter(tag => tag.startsWith('@'));
+      const sources = tags.filter(tag => tag.startsWith('@source '));
+      expect(sources.length, `${key} has no @source`).toBeGreaterThan(0);
+      for (const source of sources) {
+        expect(source, `${key}: unknown source kind`).toMatch(SOURCE_KINDS);
+      }
+      const needsMeasurement = sources.some(source =>
+        /^@source (GUESS|webkit)/.test(source),
+      );
+      const measures = tags.filter(tag => tag.startsWith('@measure '));
+      if (needsMeasurement) {
+        expect(
+          measures.length,
+          `${key} is unconfirmed but names no @measure task`,
+        ).toBeGreaterThan(0);
+      }
+      for (const measure of measures) {
+        const id = /^@measure (M-[A-Z0-9]+)$/.exec(measure)?.[1];
+        expect(id, `${key}: malformed ${measure}`).toBeDefined();
+        expect(MEASUREMENTS, `${id} is not in motion/MEASUREMENTS.md`).toMatch(
+          new RegExp(`^\\| ${id} +\\|`, 'm'),
+        );
+      }
+    });
+  }
+});
+
+describe('UIKit constants table: typed domains follow the same rules', () => {
+  const constants: [
+    string,
+    {source?: string; guess?: string; measure?: string},
+  ][] = [
+    ...Object.entries(UIKIT_GESTURES).flatMap(([group, values]) =>
+      Object.entries(values).map(
+        ([name, constant]) =>
+          [`gestures.${group}.${name}`, constant] as [
+            string,
+            {source?: string; guess?: string; measure?: string},
+          ],
+      ),
+    ),
+    ...Object.entries(HAPTIC_VIBRATION_PATTERNS).map(
+      ([kind, constant]) =>
+        [`haptics.${kind}`, constant] as [
+          string,
+          {source?: string; guess?: string; measure?: string},
+        ],
+    ),
+  ];
+
+  it('finds the gesture constants', () => {
+    expect(constants.length).toBeGreaterThan(20);
+  });
+
+  it.each(constants)('%s', (name, constant) => {
+    if (constant.source != null) {
+      expect(`@source ${constant.source}`, name).toMatch(SOURCE_KINDS);
+    } else {
+      expect(
+        constant.guess,
+        `${name} has neither a source nor a guess`,
+      ).toBeTruthy();
+      const id = /^(M-[A-Z0-9]+): /.exec(constant.measure ?? '')?.[1];
+      expect(
+        id,
+        `${name}: measure must start with its MEASUREMENTS.md ID`,
+      ).toBeDefined();
+      expect(MEASUREMENTS, `${id} is not in motion/MEASUREMENTS.md`).toMatch(
+        new RegExp(`^\\| ${id} +\\|`, 'm'),
+      );
+    }
+  });
+});
+
+describe('UIKit constants table: values', () => {
+  it('UIKit\u2019s default spring has the documented damping ratio 4.56 before clamping', () => {
+    const {mass, stiffness, damping} = springs.uikitDefault;
+    expect(damping / (2 * Math.sqrt(stiffness * mass))).toBeCloseTo(4.56, 2);
+  });
+
+  it('deceleration rates are per-millisecond factors in (0, 1), fast below normal', () => {
+    expect(scroll.decelerationRate.fast).toBeLessThan(
+      scroll.decelerationRate.normal,
+    );
+    expect(scroll.decelerationRate.normal).toBeLessThan(1);
+  });
+
+  it('press clocks agree with the touch press model they were measured for', () => {
+    expect(scroll.delaysContentTouchesMs).toBe(PRESS_ONSET_MS);
+    expect(timing.press.flashMs).toBe(PRESS_FLASH_MS);
+    expect(timing.press.highlightOutMs).toBe(PRESS_FADE_MS);
+    expect(timing.press.scrollBrakeMs).toBe(PRESS_SCROLL_BRAKE_MS);
+  });
+
+  it('curves are valid cubic-bézier control points', () => {
+    for (const [x1, , x2] of Object.values(timing.curves)) {
+      expect(x1).toBeGreaterThanOrEqual(0);
+      expect(x2).toBeLessThanOrEqual(1);
+    }
+  });
+});

From 17c181b93f94f13b20b5e3f233765b55c8f1a34d Mon Sep 17 00:00:00 2001
From: Christopher Chedeau <vjeuxx@gmail.com>
Date: Fri, 23 Oct 2026 20:00:56 -0700
Subject: [PATCH 03/17] chore(core): UIKit's spring, decay, rubber-band and
 projection math

Pure functions for the touch presentations: a closed-form damped spring
with every Apple parameterization and Core Animation's settling duration,
a spring chasing a moving target, UIScrollView's coast, rubber band and
release projection. Tests hold them to an RK4 integration, WebKit's spring
solver, the WWDC conversion equations and values read from UIKit, and play
the constants table through them.
---
 .changeset/uikit-motion-math.md               |   7 +
 packages/core/src/motion/README.md            |  34 +-
 packages/core/src/motion/decay.test.ts        | 120 ++++
 packages/core/src/motion/decay.ts             | 126 ++++
 packages/core/src/motion/projection.test.ts   | 126 ++++
 packages/core/src/motion/projection.ts        | 146 ++++
 packages/core/src/motion/rubberBand.test.ts   |  88 +++
 packages/core/src/motion/rubberBand.ts        | 114 +++
 packages/core/src/motion/spring.test.ts       | 650 ++++++++++++++++++
 packages/core/src/motion/spring.ts            | 551 +++++++++++++++
 packages/core/src/motion/uikit/values.test.ts |  93 +++
 11 files changed, 2050 insertions(+), 5 deletions(-)
 create mode 100644 .changeset/uikit-motion-math.md
 create mode 100644 packages/core/src/motion/decay.test.ts
 create mode 100644 packages/core/src/motion/decay.ts
 create mode 100644 packages/core/src/motion/projection.test.ts
 create mode 100644 packages/core/src/motion/projection.ts
 create mode 100644 packages/core/src/motion/rubberBand.test.ts
 create mode 100644 packages/core/src/motion/rubberBand.ts
 create mode 100644 packages/core/src/motion/spring.test.ts
 create mode 100644 packages/core/src/motion/spring.ts
 create mode 100644 packages/core/src/motion/uikit/values.test.ts

diff --git a/.changeset/uikit-motion-math.md b/.changeset/uikit-motion-math.md
new file mode 100644
index 0000000000000..7af3d73a92a98
--- /dev/null
+++ b/.changeset/uikit-motion-math.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/core': patch
+---
+
+[chore] Internal: the spring, decay, rubber-band and projection math of UIKit for touch presentations, as pure functions checked against an independent integration and against values read from UIKit. Not exported from the package entry point; no component uses it yet.
+
+@vjeux
diff --git a/packages/core/src/motion/README.md b/packages/core/src/motion/README.md
index d8bc91c74fa99..0ca69112c7578 100644
--- a/packages/core/src/motion/README.md
+++ b/packages/core/src/motion/README.md
@@ -1,10 +1,11 @@
 # Motion
 
-Internal motion foundation for the touch presentations of core components. It
-starts with the UIKit constants table: every spring, duration, deceleration
-rate, rubber-band constant, curve and gesture threshold a touch presentation
-uses, each with its source. Nothing here is exported from the package entry
-point; components import it by path.
+Internal motion foundation for the touch presentations of core components:
+the UIKit constants table (every spring, duration, deceleration rate,
+rubber-band constant, curve and gesture threshold a touch presentation uses,
+each with its source) and the spring, decay, rubber-band and projection math
+UIKit uses. Nothing here is exported from the package entry point; components
+import it by path.
 
 ## Files
 
@@ -17,11 +18,34 @@ point; components import it by path.
 | `uikit/navigation.ts` | UINavigationController: push velocity, parallax, dimming, transition clock, interactive pop finish rule.                |
 | `uikit/gestures.ts`   | Gesture recognizer thresholds, the velocity filter and the haptic stand-ins, as typed entries the gesture system reads. |
 | `MEASUREMENTS.md`     | The UIKit reference captures each unconfirmed value still needs.                                                        |
+| `spring.ts`           | Closed-form damped spring, every Apple parameterization, settling duration, a spring chasing a moving target.           |
+| `decay.ts`            | UIScrollView's momentum coast.                                                                                          |
+| `rubberBand.ts`       | UIScrollView's resistance past an edge, and its inverse.                                                                |
+| `projection.ts`       | Release targets: the rest point nearest the projected coast; paging.                                                    |
 
 Component-specific values (a sheet's detents, a switch's geometry, a context
 menu's timeline) live in a domain file per component, `uikit/<component>.ts`,
 under the same rules.
 
+## Math
+
+`spring.ts` solves m·x″ + c·x′ + k·x = 0 in closed form in all three regimes:
+the model behind SwiftUI's `Spring`, `CASpringAnimation` and
+`UISpringTimingParameters`. A spring description stays in its source's
+vocabulary (mass, stiffness and damping; duration and bounce; response and
+damping ratio) and `toSpring` normalizes it, clamping overdamping to critical
+as Core Animation does for every spring UIKit attaches. The tests hold it to an
+independent fourth-order Runge-Kutta integration over a sweep of damping
+ratios, responses and release velocities; to a port of WebKit's own spring
+solver; to the WWDC23 "Animate with springs" conversion equations; and to
+values read from UIKit on the iOS 26.2 simulator: `settlingDuration` for a
+grid of springs and velocities, and the durations UIKit gives its spring APIs,
+which the settling formula reproduces to the last digit (underdamped) or within
+0.02 % (critically damped). `decay.ts` is held to a literal per-millisecond
+simulation of the deceleration rate and to WWDC18's projection function;
+`rubberBand.ts` to UIScrollView's overscroll measured on the simulator.
+`uikit/values.test.ts` plays the table's values through this math.
+
 ## Sources
 
 Every value in `uikit/` carries its source next to it, as a JSDoc tag on the
diff --git a/packages/core/src/motion/decay.test.ts b/packages/core/src/motion/decay.test.ts
new file mode 100644
index 0000000000000..41d5bee1b6eb3
--- /dev/null
+++ b/packages/core/src/motion/decay.test.ts
@@ -0,0 +1,120 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file decay.test.ts
+ * @input vitest, the decay model
+ * @output Checks the continuous coast against an independent per-millisecond
+ *   simulation of UIScrollView's deceleration, against WWDC18's projection,
+ *   and every derived time (settle, speed, reach)
+ * @position Testing; validates decay.ts without a browser
+ */
+
+import {describe, expect, it} from 'vitest';
+import {decayRestDistance, solveDecay} from './decay';
+import {projectDistance} from './projection';
+import {scroll} from './uikit/scroll';
+
+/**
+ * Independent reference: the deceleration rate applied literally, the
+ * velocity multiplied by the rate once per millisecond and integrated
+ * exactly over each millisecond step.
+ */
+function perMillisecond(
+  from: number,
+  velocity: number,
+  rate: number,
+  ms: number,
+) {
+  let x = from;
+  let v = velocity / 1000; // units per ms
+  const k = -Math.log(rate);
+  for (let i = 0; i < ms; i++) {
+    // Within one ms the speed falls from v to v·rate exponentially.
+    x += (v * (1 - rate)) / k;
+    v *= rate;
+  }
+  return {value: x, velocity: v * 1000};
+}
+
+describe('solveDecay', () => {
+  for (const rate of [
+    scroll.decelerationRate.normal,
+    scroll.decelerationRate.fast,
+  ]) {
+    for (const velocity of [-3000, -400, 150, 2500, 8000]) {
+      it(`matches a per-millisecond simulation (rate ${rate}, ${velocity} units/s)`, () => {
+        const coast = solveDecay({from: 100, velocity, rate});
+        for (const ms of [0, 1, 16, 100, 250, 600, 1500, 4000]) {
+          const reference = perMillisecond(100, velocity, rate, ms);
+          expect(coast.value(ms / 1000)).toBeCloseTo(reference.value, 6);
+          expect(coast.velocity(ms / 1000)).toBeCloseTo(reference.velocity, 6);
+        }
+      });
+    }
+  }
+
+  it('rests where the coast ends, 0.1 % past WWDC18\u2019s geometric projection', () => {
+    const coast = solveDecay({from: 0, velocity: 2000});
+    expect(coast.rest).toBeCloseTo(2000 / (-1000 * Math.log(0.998)), 9);
+    expect(coast.value(60)).toBeCloseTo(coast.rest, 6);
+    // −1 ÷ ln(0.998) = 499.5 ms against 0.998 ÷ 0.002 = 499 ms.
+    expect(coast.rest / projectDistance(2000)).toBeCloseTo(499.5 / 499, 3);
+    expect(decayRestDistance(2000)).toBeCloseTo(coast.rest, 9);
+  });
+
+  it('a fast rate stops sooner and shorter', () => {
+    const normal = solveDecay({from: 0, velocity: 2000});
+    const fast = solveDecay({
+      from: 0,
+      velocity: 2000,
+      rate: scroll.decelerationRate.fast,
+    });
+    expect(fast.rest).toBeLessThan(normal.rest);
+    expect(fast.settleTime(0.5)).toBeLessThan(normal.settleTime(0.5));
+  });
+
+  it('settleTime bounds every later distance to rest', () => {
+    const coast = solveDecay({from: 0, velocity: -5000});
+    for (const threshold of [5, 0.5, 0.01]) {
+      const settle = coast.settleTime(threshold);
+      expect(Math.abs(coast.value(settle) - coast.rest)).toBeCloseTo(
+        threshold,
+        9,
+      );
+      expect(Math.abs(coast.value(settle + 0.5) - coast.rest)).toBeLessThan(
+        threshold,
+      );
+    }
+    expect(solveDecay({from: 0, velocity: 0.1}).settleTime(0.5)).toBe(0);
+  });
+
+  it('timeToSpeed lands on the asked speed', () => {
+    const coast = solveDecay({from: 0, velocity: 3000});
+    const t = coast.timeToSpeed(100);
+    expect(coast.velocity(t)).toBeCloseTo(100, 9);
+    expect(coast.timeToSpeed(5000)).toBe(0);
+    expect(coast.timeToSpeed(0)).toBe(Infinity);
+  });
+
+  it('timeToReach finds the crossing, or null when the coast never gets there', () => {
+    const coast = solveDecay({from: 0, velocity: 2000});
+    const t = coast.timeToReach(400);
+    expect(t).not.toBeNull();
+    expect(coast.value(t ?? 0)).toBeCloseTo(400, 9);
+    expect(coast.timeToReach(-10)).toBeNull();
+    expect(coast.timeToReach(coast.rest)).toBeNull();
+    expect(coast.timeToReach(coast.rest + 1)).toBeNull();
+    const back = solveDecay({from: 0, velocity: -2000});
+    expect(back.value(back.timeToReach(-400) ?? 0)).toBeCloseTo(-400, 9);
+    expect(solveDecay({from: 3, velocity: 0}).timeToReach(3)).toBe(0);
+  });
+
+  it('rejects a rate outside (0, 1)', () => {
+    expect(() => solveDecay({from: 0, velocity: 1, rate: 1})).toThrow(
+      RangeError,
+    );
+    expect(() => solveDecay({from: 0, velocity: 1, rate: 0})).toThrow(
+      RangeError,
+    );
+  });
+});
diff --git a/packages/core/src/motion/decay.ts b/packages/core/src/motion/decay.ts
new file mode 100644
index 0000000000000..be005048d06da
--- /dev/null
+++ b/packages/core/src/motion/decay.ts
@@ -0,0 +1,126 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file decay.ts
+ * @input A release value, velocity and a UIScrollView deceleration rate
+ * @output Exports `solveDecay`, the closed-form momentum coast of a scroll
+ *   view after the finger lifts (value, velocity, rest point, settle time,
+ *   time to reach a value), and `decayRestDistance`
+ * @position Pure math under the motion animator; no DOM, no React
+ *
+ * UIScrollView's deceleration rate is a per-millisecond velocity factor: the
+ * speed is multiplied by the rate every millisecond (0.998 normal, 0.99 fast;
+ * see uikit/scroll.ts). As a continuous decay that is
+ *   v(t) = v₀·e^(−λt),  x(t) = x₀ + v₀·(1 − e^(−λt)) ÷ λ,  λ = −1000·ln(rate) /s
+ * and the coast ends at x₀ + v₀ ÷ λ. WWDC18 "Designing Fluid Interfaces"
+ * projects the same rest point with the geometric series v₀·rate ÷ (1 − rate)
+ * per millisecond (projection.ts), 0.1 % shorter at the normal rate (499.0
+ * against 499.5 ms of the release speed); the continuous form is the one
+ * that also gives the position and velocity at every instant, which the
+ * animator needs to grab a coasting surface mid-flight.
+ *
+ * Units: time in seconds, velocity in units per second.
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/motion/decay.test.ts
+ * - /packages/core/src/motion/README.md
+ */
+
+import {scroll} from './uikit/scroll';
+
+/** A coast released at `from` with `initialVelocity`. */
+export interface DecayCurve {
+  readonly from: number;
+  /** Units per second. */
+  readonly initialVelocity: number;
+  /** Per-millisecond velocity factor. */
+  readonly rate: number;
+  /** Where the coast comes to rest. */
+  readonly rest: number;
+  /** Value `t` seconds after release. */
+  value(t: number): number;
+  /** Velocity `t` seconds after release, units/s. */
+  velocity(t: number): number;
+  /** Seconds until the value is within `threshold` of `rest` for good. */
+  settleTime(threshold: number): number;
+  /** Seconds until the speed falls to `speed` units/s (0 if already slower). */
+  timeToSpeed(speed: number): number;
+  /**
+   * Seconds until the coast reaches `target`, or null when it never gets
+   * there (behind the release point, or at or past the rest point).
+   */
+  timeToReach(target: number): number | null;
+}
+
+function decayConstant(rate: number): number {
+  if (!(rate > 0 && rate < 1)) {
+    throw new RangeError(`decay: rate must be in (0, 1), got ${rate}`);
+  }
+  return -1000 * Math.log(rate);
+}
+
+/** How far a coast at `velocity` units/s travels before it stops. */
+export function decayRestDistance(
+  velocity: number,
+  rate: number = scroll.decelerationRate.normal,
+): number {
+  return velocity / decayConstant(rate);
+}
+
+/**
+ * The momentum coast UIScrollView performs after the finger lifts.
+ *
+ * @example
+ * ```
+ * const coast = solveDecay({from: 0, velocity: 2000});
+ * coast.rest; // ≈ 999 px
+ * coast.value(0.2); // px after 200 ms
+ * ```
+ */
+export function solveDecay({
+  from,
+  velocity: initialVelocity,
+  rate = scroll.decelerationRate.normal,
+}: {
+  from: number;
+  velocity: number;
+  rate?: number;
+}): DecayCurve {
+  const lambda = decayConstant(rate);
+  const rest = from + initialVelocity / lambda;
+  const speed0 = Math.abs(initialVelocity);
+  return {
+    from,
+    initialVelocity,
+    rate,
+    rest,
+    value: t => from + (initialVelocity * -Math.expm1(-lambda * t)) / lambda,
+    velocity: t => initialVelocity * Math.exp(-lambda * t),
+    settleTime: threshold => {
+      const remaining = speed0 / lambda;
+      if (!(threshold > 0)) {
+        return Infinity;
+      }
+      return remaining <= threshold
+        ? 0
+        : Math.log(remaining / threshold) / lambda;
+    },
+    timeToSpeed: speed =>
+      speed0 <= speed
+        ? 0
+        : speed > 0
+          ? Math.log(speed0 / speed) / lambda
+          : Infinity,
+    timeToReach: target => {
+      if (initialVelocity === 0) {
+        return target === from ? 0 : null;
+      }
+      // 1 − e^(−λt) = λ·(target − from) ÷ v₀
+      const fraction = (lambda * (target - from)) / initialVelocity;
+      if (fraction < 0 || fraction >= 1) {
+        return null;
+      }
+      return -Math.log1p(-fraction) / lambda;
+    },
+  };
+}
diff --git a/packages/core/src/motion/projection.test.ts b/packages/core/src/motion/projection.test.ts
new file mode 100644
index 0000000000000..9b933e0530e7d
--- /dev/null
+++ b/packages/core/src/motion/projection.test.ts
@@ -0,0 +1,126 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file projection.test.ts
+ * @input vitest, the projection functions
+ * @output Checks WWDC18's projection verbatim and the release-target rules
+ *   (nearest projected rest, step limits, paging)
+ * @position Testing; validates projection.ts without a browser
+ */
+
+import {describe, expect, it} from 'vitest';
+import {
+  project,
+  projectDistance,
+  selectPage,
+  selectSnapPoint,
+} from './projection';
+import {scroll} from './uikit/scroll';
+
+describe('projectDistance', () => {
+  it('is WWDC18\u2019s (v ÷ 1000)·r ÷ (1 − r)', () => {
+    for (const velocity of [-2500, -1, 0, 640, 3000]) {
+      for (const rate of [0.998, 0.99]) {
+        expect(projectDistance(velocity, rate)).toBeCloseTo(
+          ((velocity / 1000) * rate) / (1 - rate),
+          9,
+        );
+      }
+    }
+  });
+
+  it('projects 499 ms of the release speed at the normal rate (the sheet\u2019s prior art)', () => {
+    expect(projectDistance(1000)).toBeCloseTo(499, 9);
+    expect(projectDistance(1000, scroll.decelerationRate.fast)).toBeCloseTo(
+      99,
+      9,
+    );
+  });
+
+  it('a release at rest projects onto itself', () => {
+    expect(project(321, 0)).toBe(321);
+  });
+
+  it('rejects a rate outside (0, 1)', () => {
+    expect(() => projectDistance(10, 1)).toThrow(RangeError);
+  });
+});
+
+describe('selectSnapPoint', () => {
+  const detents = [0, 300, 600];
+
+  it('goes to the point nearest the projected rest, not the release point', () => {
+    // Released nearer 300, but thrown toward 600.
+    expect(selectSnapPoint(detents, {position: 320, velocity: 900}).value).toBe(
+      600,
+    );
+    // A slow release places.
+    expect(selectSnapPoint(detents, {position: 320, velocity: 20}).value).toBe(
+      300,
+    );
+    // Thrown the other way.
+    expect(
+      selectSnapPoint(detents, {position: 320, velocity: -900}).value,
+    ).toBe(0);
+  });
+
+  it('a projection past the ends lands on the end', () => {
+    expect(
+      selectSnapPoint(detents, {position: 580, velocity: 6000}).value,
+    ).toBe(600);
+    expect(
+      selectSnapPoint(detents, {position: 10, velocity: -6000}).index,
+    ).toBe(0);
+  });
+
+  it('reports the projection it chose from', () => {
+    const choice = selectSnapPoint(detents, {position: 100, velocity: 400});
+    expect(choice.projected).toBeCloseTo(100 + 0.4 * 499, 9);
+  });
+
+  it('limits the travel to maxSteps points from fromIndex', () => {
+    const pages = [0, 100, 200, 300, 400];
+    expect(selectSnapPoint(pages, {position: 110, velocity: 5000}).value).toBe(
+      400,
+    );
+    expect(
+      selectSnapPoint(pages, {
+        position: 110,
+        velocity: 5000,
+        fromIndex: 1,
+        maxSteps: 1,
+      }).value,
+    ).toBe(200);
+  });
+
+  it('breaks an exact tie toward the direction of travel', () => {
+    expect(
+      selectSnapPoint([0, 100], {position: 50, velocity: 0.0001, rate: 0.5})
+        .value,
+    ).toBe(100);
+    expect(
+      selectSnapPoint([0, 100], {position: 50, velocity: -0.0001, rate: 0.5})
+        .value,
+    ).toBe(0);
+  });
+
+  it('needs at least one point', () => {
+    expect(() => selectSnapPoint([], {position: 0, velocity: 0})).toThrow(
+      RangeError,
+    );
+  });
+});
+
+describe('selectPage', () => {
+  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/projection.ts b/packages/core/src/motion/projection.ts
new file mode 100644
index 0000000000000..c71003d4dc391
--- /dev/null
+++ b/packages/core/src/motion/projection.ts
@@ -0,0 +1,146 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file projection.ts
+ * @input A release position and velocity, candidate rest points
+ * @output Exports `projectDistance` / `project` (WWDC18's momentum
+ *   projection), `selectSnapPoint` (the release target UIKit-style) and
+ *   `selectPage` (paging: at most one page per release)
+ * @position Pure math; no DOM, no React
+ *
+ * WWDC18 "Designing Fluid Interfaces" (session 803): a thrown object goes to
+ * the endpoint nearest to where it WOULD coast if it were scrolled, not the
+ * endpoint nearest to where the finger let go. The talk's projection
+ * function, verbatim in units/s:
+ *
+ *   func project(initialVelocity: CGFloat, decelerationRate: CGFloat) -> CGFloat {
+ *     return (initialVelocity / 1000.0) * decelerationRate / (1.0 - decelerationRate)
+ *   }
+ *
+ * used with `UIScrollView.DecelerationRate.normal`. A slow release projects
+ * onto itself, so it places; a flick continues past the finger.
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/motion/projection.test.ts
+ * - /packages/core/src/motion/README.md
+ */
+
+import {scroll} from './uikit/scroll';
+
+/** Distance a surface released at `velocity` units/s coasts (WWDC18). */
+export function projectDistance(
+  velocity: number,
+  rate: number = scroll.decelerationRate.normal,
+): number {
+  if (!(rate > 0 && rate < 1)) {
+    throw new RangeError(`projection: rate must be in (0, 1), got ${rate}`);
+  }
+  return ((velocity / 1000) * rate) / (1 - rate);
+}
+
+/** Where a surface released at `position` with `velocity` would come to rest. */
+export function project(
+  position: number,
+  velocity: number,
+  rate: number = scroll.decelerationRate.normal,
+): number {
+  return position + projectDistance(velocity, rate);
+}
+
+export interface SnapSelection {
+  /** Index of the chosen point in the list passed in. */
+  readonly index: number;
+  /** The chosen point. */
+  readonly value: number;
+  /** The projected rest position the choice was made from. */
+  readonly projected: number;
+}
+
+/**
+ * The rest point a release goes to: the one nearest the projected rest
+ * position. `fromIndex` + `maxSteps` limit how many points away from the
+ * starting one a single release may travel (by index order; pass points
+ * sorted along the axis). Ties go to the point in the direction of travel.
+ *
+ * @example
+ * ```
+ * // A sheet with detents at 0, 300 and 600 px, released at 320 px moving
+ * // 900 px/s toward 600: projected ≈ 769 → 600.
+ * selectSnapPoint([0, 300, 600], {position: 320, velocity: 900});
+ * ```
+ */
+export function selectSnapPoint(
+  points: ReadonlyArray<number>,
+  {
+    position,
+    velocity,
+    rate = scroll.decelerationRate.normal,
+    fromIndex,
+    maxSteps,
+  }: {
+    position: number;
+    velocity: number;
+    rate?: number;
+    fromIndex?: number;
+    maxSteps?: number;
+  },
+): SnapSelection {
+  if (points.length === 0) {
+    throw new RangeError(
+      'projection: selectSnapPoint needs at least one point',
+    );
+  }
+  const projected = project(position, velocity, rate);
+  let lo = 0;
+  let hi = points.length - 1;
+  if (fromIndex != null && maxSteps != null) {
+    lo = Math.max(lo, fromIndex - maxSteps);
+    hi = Math.min(hi, fromIndex + maxSteps);
+  }
+  let best = lo;
+  let bestDistance = Infinity;
+  for (let i = lo; i <= hi; i++) {
+    const distance = Math.abs(points[i] - projected);
+    const isTie = Math.abs(distance - bestDistance) < 1e-9;
+    const isAhead = Math.sign(points[i] - points[best]) === Math.sign(velocity);
+    if (distance < bestDistance - 1e-9 || (isTie && isAhead)) {
+      best = i;
+      bestDistance = distance;
+    }
+  }
+  return {index: best, value: points[best], projected};
+}
+
+/**
+ * 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,
+  );
+  return selectSnapPoint(points, {
+    position,
+    velocity,
+    rate,
+    fromIndex: currentPage,
+    maxSteps: 1,
+  });
+}
diff --git a/packages/core/src/motion/rubberBand.test.ts b/packages/core/src/motion/rubberBand.test.ts
new file mode 100644
index 0000000000000..3328d94eab608
--- /dev/null
+++ b/packages/core/src/motion/rubberBand.test.ts
@@ -0,0 +1,88 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file rubberBand.test.ts
+ * @input vitest, the rubber-band functions
+ * @output Checks the formula against a published device measurement of
+ *   UIScrollView, its slope, inverse and clamp round trips
+ * @position Testing; validates rubberBand.ts without a browser
+ */
+
+import {describe, expect, it} from 'vitest';
+import {
+  rubberBand,
+  rubberBandClamp,
+  rubberBandInverse,
+  rubberBandSlope,
+  rubberBandUnclamp,
+} from './rubberBand';
+
+describe('rubberBand', () => {
+  it('reproduces the published UIScrollView measurement (812 pt view)', () => {
+    // Finger 500 / 1000 / 1500 pt past the edge displayed 205 / 328 / 409 pt
+    // (I. Lobanov, "How UIScrollView works").
+    expect(Math.abs(rubberBand(500, 812) - 205)).toBeLessThan(0.5);
+    expect(Math.abs(rubberBand(1000, 812) - 328)).toBeLessThan(0.5);
+    expect(Math.abs(rubberBand(1500, 812) - 409)).toBeLessThan(0.5);
+  });
+
+  it('is (1 − 1 ÷ (x·c ÷ d + 1))·d with c = 0.55', () => {
+    for (const x of [0, 1, 10, 80, 300, 2000]) {
+      expect(rubberBand(x, 600)).toBeCloseTo(
+        (1 - 1 / ((x * 0.55) / 600 + 1)) * 600,
+        9,
+      );
+    }
+    expect(rubberBand(100, 600, 0.3)).toBeCloseTo(
+      (1 - 1 / ((100 * 0.3) / 600 + 1)) * 600,
+      9,
+    );
+  });
+
+  it('keeps the sign, never reaches the dimension, starts at slope c', () => {
+    expect(rubberBand(-120, 700)).toBeCloseTo(-rubberBand(120, 700), 12);
+    expect(rubberBand(1e9, 700)).toBeLessThan(700);
+    expect(rubberBandSlope(0, 700)).toBeCloseTo(0.55, 12);
+    for (const x of [0, 50, 400, 3000]) {
+      const h = 1e-4;
+      const numeric =
+        (rubberBand(x + h, 700) - rubberBand(x - h, 700)) / (2 * h);
+      expect(rubberBandSlope(x, 700)).toBeCloseTo(numeric, 6);
+    }
+  });
+
+  it('inverts exactly', () => {
+    for (const x of [-900, -40, 0, 3, 75, 640, 5000]) {
+      expect(rubberBandInverse(rubberBand(x, 812), 812)).toBeCloseTo(x, 6);
+    }
+    expect(rubberBandInverse(812, 812)).toBe(Infinity);
+    expect(rubberBandInverse(-900, 812)).toBe(-Infinity);
+  });
+
+  it('a degenerate dimension bands nothing', () => {
+    expect(rubberBand(50, 0)).toBe(0);
+    expect(rubberBandInverse(50, 0)).toBe(0);
+    expect(rubberBandSlope(50, 0)).toBe(0);
+  });
+});
+
+describe('rubberBandClamp', () => {
+  it('passes values inside the range through and bands past either edge', () => {
+    expect(rubberBandClamp(120, 0, 500, 800)).toBe(120);
+    expect(rubberBandClamp(-100, 0, 500, 800)).toBeCloseTo(
+      rubberBand(-100, 800),
+      12,
+    );
+    expect(rubberBandClamp(650, 0, 500, 800)).toBeCloseTo(
+      500 + rubberBand(150, 800),
+      12,
+    );
+  });
+
+  it('round-trips through rubberBandUnclamp (a grab mid-bounce resumes in place)', () => {
+    for (const raw of [-600, -12, 0, 250, 500, 510, 1400]) {
+      const shown = rubberBandClamp(raw, 0, 500, 800);
+      expect(rubberBandUnclamp(shown, 0, 500, 800)).toBeCloseTo(raw, 6);
+    }
+  });
+});
diff --git a/packages/core/src/motion/rubberBand.ts b/packages/core/src/motion/rubberBand.ts
new file mode 100644
index 0000000000000..e7faa517a1173
--- /dev/null
+++ b/packages/core/src/motion/rubberBand.ts
@@ -0,0 +1,114 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file rubberBand.ts
+ * @input An overflow past an edge, the scroll view's dimension and UIKit's
+ *   rubber-band coefficient
+ * @output Exports `rubberBand` (finger overflow → displayed overflow), its
+ *   inverse, its slope, and the clamp/unclamp pair over a [min, max] range
+ * @position Pure math; no DOM, no React
+ *
+ * UIScrollView resists a drag past its content edge with
+ *   b = (1 − 1 ÷ (x·c ÷ d + 1))·d
+ * where x is how far the finger has gone past the edge, d the scroll view's
+ * size on that axis and c = 0.55 (uikit/scroll.ts records the sources). The
+ * displayed overflow b approaches d but never reaches it, and its slope at
+ * the edge is c: the first points of overflow move at 55 % of the finger.
+ *
+ * The inverse matters for M2 (grab anything mid-flight): a finger that lands
+ * on content still bouncing back has to resume the drag from the finger
+ * position that would produce the overflow on screen, or the content jumps.
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/motion/rubberBand.test.ts
+ * - /packages/core/src/motion/README.md
+ */
+
+import {scroll} from './uikit/scroll';
+
+/**
+ * Displayed overflow for a finger `overflow` past the edge (signed: the sign
+ * is kept). `dimension` is the scroll view's size on the axis.
+ */
+export function rubberBand(
+  overflow: number,
+  dimension: number,
+  coefficient: number = scroll.rubberBand.coefficient,
+): number {
+  if (!(dimension > 0)) {
+    return 0;
+  }
+  const x = Math.abs(overflow);
+  const banded = (1 - 1 / ((x * coefficient) / dimension + 1)) * dimension;
+  return overflow < 0 ? -banded : banded;
+}
+
+/** The finger overflow that displays `displayed`; ±Infinity at ±dimension. */
+export function rubberBandInverse(
+  displayed: number,
+  dimension: number,
+  coefficient: number = scroll.rubberBand.coefficient,
+): number {
+  if (!(dimension > 0)) {
+    return 0;
+  }
+  const b = Math.abs(displayed);
+  if (b >= dimension) {
+    return displayed < 0 ? -Infinity : Infinity;
+  }
+  const x = ((dimension / coefficient) * b) / (dimension - b);
+  return displayed < 0 ? -x : x;
+}
+
+/**
+ * d(displayed) ÷ d(finger) at a finger overflow: what a finger velocity
+ * becomes on screen while banding (c at the edge, falling toward 0).
+ */
+export function rubberBandSlope(
+  overflow: number,
+  dimension: number,
+  coefficient: number = scroll.rubberBand.coefficient,
+): number {
+  if (!(dimension > 0)) {
+    return 0;
+  }
+  const u = (Math.abs(overflow) * coefficient) / dimension + 1;
+  return coefficient / (u * u);
+}
+
+/**
+ * The displayed value for a raw (finger-driven) `value` constrained to
+ * [min, max]: unchanged inside, rubber-banded past either edge.
+ */
+export function rubberBandClamp(
+  value: number,
+  min: number,
+  max: number,
+  dimension: number,
+  coefficient: number = scroll.rubberBand.coefficient,
+): number {
+  if (value < min) {
+    return min + rubberBand(value - min, dimension, coefficient);
+  }
+  if (value > max) {
+    return max + rubberBand(value - max, dimension, coefficient);
+  }
+  return value;
+}
+
+/** Inverse of `rubberBandClamp`: the raw value that displays `displayed`. */
+export function rubberBandUnclamp(
+  displayed: number,
+  min: number,
+  max: number,
+  dimension: number,
+  coefficient: number = scroll.rubberBand.coefficient,
+): number {
+  if (displayed < min) {
+    return min + rubberBandInverse(displayed - min, dimension, coefficient);
+  }
+  if (displayed > max) {
+    return max + rubberBandInverse(displayed - max, dimension, coefficient);
+  }
+  return displayed;
+}
diff --git a/packages/core/src/motion/spring.test.ts b/packages/core/src/motion/spring.test.ts
new file mode 100644
index 0000000000000..e770107b77dda
--- /dev/null
+++ b/packages/core/src/motion/spring.test.ts
@@ -0,0 +1,650 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file spring.test.ts
+ * @input vitest, the spring model
+ * @output Checks the closed-form spring against an independent RK4
+ *   integration of the ODE across damping regimes, every conversion against
+ *   Apple's published equations, and the settling duration against every
+ *   published reference value
+ * @position Testing; validates spring.ts without a browser
+ */
+
+import {describe, expect, it} from 'vitest';
+import {
+  absoluteVelocity,
+  dampingRatioOf,
+  durationBounceOf,
+  relativeVelocity,
+  responseDampingOf,
+  responseOf,
+  settlingDuration,
+  solveSpring,
+  solveSpringTowardRamp,
+  springFromDurationBounce,
+  springFromPhysics,
+  springFromResponse,
+  springFromUIKitDampingDuration,
+  type Spring,
+} from './spring';
+
+/**
+ * Independent reference: classic fourth-order Runge-Kutta on
+ * m·x″ + c·x′ + k·(x − to) = 0. Shares nothing with the closed form.
+ */
+function rk4(
+  spring: Spring,
+  from: number,
+  to: number,
+  velocity: number,
+  until: number,
+  dt = 1e-4,
+): {t: number; value: number; velocity: number}[] {
+  const {mass: m, stiffness: k, damping: c} = spring;
+  const accel = (x: number, v: number) => (-k * (x - to) - c * v) / m;
+  let x = from;
+  let v = velocity;
+  const out = [{t: 0, value: x, velocity: v}];
+  const steps = Math.round(until / dt);
+  for (let i = 1; i <= steps; i++) {
+    const k1x = v;
+    const k1v = accel(x, v);
+    const k2x = v + (dt / 2) * k1v;
+    const k2v = accel(x + (dt / 2) * k1x, v + (dt / 2) * k1v);
+    const k3x = v + (dt / 2) * k2v;
+    const k3v = accel(x + (dt / 2) * k2x, v + (dt / 2) * k2v);
+    const k4x = v + dt * k3v;
+    const k4v = accel(x + dt * k3x, v + dt * k3v);
+    x += (dt / 6) * (k1x + 2 * k2x + 2 * k3x + k4x);
+    v += (dt / 6) * (k1v + 2 * k2v + 2 * k3v + k4v);
+    if (i % 100 === 0) {
+      out.push({t: i * dt, value: x, velocity: v});
+    }
+  }
+  return out;
+}
+
+const RATIOS = [
+  0, 0.05, 0.3, 0.5, 0.75, 0.9, 0.99, 0.999999, 1, 1.000001, 1.2, 2, 5,
+];
+const RESPONSES = [0.15, 0.35, 0.5, 1];
+const RELEASES = [
+  {from: 0, to: 1, velocity: 0},
+  {from: 0, to: 300, velocity: 0},
+  {from: 300, to: 0, velocity: -2500},
+  {from: -120, to: 80, velocity: 4000},
+  // Zero displacement, all velocity: the case UIKit's relative velocity
+  // cannot express.
+  {from: 50, to: 50, velocity: 1800},
+];
+
+describe('solveSpring matches an RK4 integration of the ODE', () => {
+  for (const dampingRatio of RATIOS) {
+    for (const response of RESPONSES) {
+      it(`ζ=${dampingRatio}, response=${response}s`, () => {
+        // springFromResponse keeps overdamping, so every regime is covered.
+        const spring = springFromResponse({response, dampingRatio});
+        for (const release of RELEASES) {
+          const curve = solveSpring(spring, release);
+          const scale = Math.max(
+            1,
+            Math.abs(release.from - release.to),
+            Math.abs(release.velocity) * response,
+          );
+          for (const sample of rk4(
+            spring,
+            release.from,
+            release.to,
+            release.velocity,
+            1.5,
+          )) {
+            expect(Math.abs(curve.value(sample.t) - sample.value)).toBeLessThan(
+              1e-6 * scale,
+            );
+            expect(
+              Math.abs(curve.velocity(sample.t) - sample.velocity),
+            ).toBeLessThan((1e-6 * scale * 2 * Math.PI) / response);
+          }
+        }
+      });
+    }
+  }
+});
+
+describe('solveSpring', () => {
+  it('agrees with WebKit\u2019s SpringSolver (an independent port of its code)', () => {
+    // Source/WebCore/platform/graphics/SpringSolver.h, verbatim in
+    // structure: unit move, initial velocity positive toward the target.
+    const webkitSolve = (
+      m: number,
+      k: number,
+      c: number,
+      v0: number,
+      t: number,
+    ) => {
+      const w0 = Math.sqrt(k / m);
+      const zeta = c / (2 * Math.sqrt(k * m));
+      let x: number;
+      if (zeta < 1) {
+        const wd = w0 * Math.sqrt(1 - zeta * zeta);
+        const b = (zeta * w0 + -v0) / wd;
+        x =
+          Math.exp(-t * zeta * w0) * (Math.cos(wd * t) + b * Math.sin(wd * t));
+      } else {
+        x = (1 + (-v0 + w0) * t) * Math.exp(-t * w0);
+      }
+      return 1 - x;
+    };
+    const cases = [
+      [1, 438.64908449286042, 31.415926535897931, 0],
+      [1, 322.27279677026473, 31.2364069556928, 0],
+      [1, 100, 5, 0],
+      [1, 100, 20, 0],
+      [2, 300, 12, 4],
+      [1, 250, 31.6227766016838, -3],
+    ];
+    for (const [m, k, c, v0] of cases) {
+      const curve = solveSpring(
+        springFromPhysics({mass: m, stiffness: k, damping: c}),
+        {
+          from: 0,
+          to: 1,
+          velocity: v0,
+        },
+      );
+      for (let t = 0; t <= 1.5; t += 0.01) {
+        expect(curve.value(t)).toBeCloseTo(webkitSolve(m, k, c, v0, t), 6);
+      }
+    }
+  });
+
+  it('starts at the release value and velocity in every regime', () => {
+    for (const dampingRatio of RATIOS) {
+      const curve = solveSpring(
+        springFromResponse({response: 0.4, dampingRatio}),
+        {
+          from: 10,
+          to: 250,
+          velocity: -700,
+        },
+      );
+      expect(curve.value(0)).toBeCloseTo(10, 9);
+      expect(curve.velocity(0)).toBeCloseTo(-700, 6);
+    }
+  });
+
+  it('is continuous across critical damping', () => {
+    const release = {from: 0, to: 300, velocity: 1200};
+    const critical = solveSpring(
+      springFromResponse({response: 0.5, dampingRatio: 1}),
+      release,
+    );
+    for (const dampingRatio of [1 - 1e-5, 1 - 1e-7, 1 + 1e-7, 1 + 1e-5]) {
+      const near = solveSpring(
+        springFromResponse({response: 0.5, dampingRatio}),
+        release,
+      );
+      for (let t = 0; t <= 1.5; t += 0.01) {
+        expect(Math.abs(near.value(t) - critical.value(t))).toBeLessThan(0.01);
+      }
+    }
+  });
+
+  it('comes to rest at the target', () => {
+    for (const dampingRatio of RATIOS.filter(r => r > 0)) {
+      const curve = solveSpring(
+        springFromResponse({response: 0.3, dampingRatio}),
+        {from: 0, to: 100},
+      );
+      const settle = curve.settleTime(0.01);
+      expect(Math.abs(curve.value(settle + 5) - 100)).toBeLessThan(0.01);
+    }
+  });
+
+  it('settleTime bounds every later displacement (property sweep)', () => {
+    for (const dampingRatio of RATIOS.filter(r => r > 0)) {
+      for (const response of RESPONSES) {
+        for (const release of RELEASES) {
+          const curve = solveSpring(
+            springFromResponse({response, dampingRatio}),
+            release,
+          );
+          for (const threshold of [1, 0.1, 0.001]) {
+            const settle = curve.settleTime(threshold);
+            expect(Number.isFinite(settle)).toBe(true);
+            for (let i = 0; i <= 400; i++) {
+              const t = settle + (i / 400) * 3 * response;
+              expect(Math.abs(curve.value(t) - release.to)).toBeLessThanOrEqual(
+                threshold * (1 + 1e-9),
+              );
+            }
+          }
+        }
+      }
+    }
+  });
+
+  it('settleTime is 0 when already settled, Infinity when undamped and displaced', () => {
+    const spring = springFromResponse({response: 0.4, dampingRatio: 0.8});
+    expect(solveSpring(spring, {from: 5, to: 5}).settleTime(0.5)).toBe(0);
+    expect(solveSpring(spring, {from: 5.1, to: 5}).settleTime(0.5)).toBe(0);
+    const undamped = springFromResponse({response: 0.4, dampingRatio: 0});
+    expect(solveSpring(undamped, {from: 0, to: 1}).settleTime(0.001)).toBe(
+      Infinity,
+    );
+  });
+
+  it('an undamped spring oscillates with the response as its period (WWDC23: bounce 1 is a cosine)', () => {
+    const curve = solveSpring(
+      springFromDurationBounce({duration: 0.5, bounce: 1}),
+      {from: 0, to: 1},
+    );
+    for (let t = 0; t <= 2; t += 0.05) {
+      expect(curve.value(t)).toBeCloseTo(
+        1 - Math.cos((2 * Math.PI * t) / 0.5),
+        9,
+      );
+    }
+  });
+});
+
+describe('solveSpringTowardRamp (a target moving at constant speed)', () => {
+  /** RK4 on m·x″ + c·x′ + k·(x − (target + slope·t)) = 0. */
+  function rk4Ramp(
+    spring: Spring,
+    {
+      from,
+      velocity,
+      target,
+      slope,
+    }: {from: number; velocity: number; target: number; slope: number},
+    until: number,
+    dt = 1e-4,
+  ): {t: number; value: number; velocity: number}[] {
+    const {mass: m, stiffness: k, damping: c} = spring;
+    const accel = (time: number, x: number, v: number) =>
+      (-k * (x - (target + slope * time)) - c * v) / m;
+    let x = from;
+    let v = velocity;
+    const out = [{t: 0, value: x, velocity: v}];
+    const steps = Math.round(until / dt);
+    for (let i = 1; i <= steps; i++) {
+      const time = (i - 1) * dt;
+      const k1x = v;
+      const k1v = accel(time, x, v);
+      const k2x = v + (dt / 2) * k1v;
+      const k2v = accel(time + dt / 2, x + (dt / 2) * k1x, v + (dt / 2) * k1v);
+      const k3x = v + (dt / 2) * k2v;
+      const k3v = accel(time + dt / 2, x + (dt / 2) * k2x, v + (dt / 2) * k2v);
+      const k4x = v + dt * k3v;
+      const k4v = accel(time + dt, x + dt * k3x, v + dt * k3v);
+      x += (dt / 6) * (k1x + 2 * k2x + 2 * k3x + k4x);
+      v += (dt / 6) * (k1v + 2 * k2v + 2 * k3v + k4v);
+      if (i % 100 === 0) {
+        out.push({t: i * dt, value: x, velocity: v});
+      }
+    }
+    return out;
+  }
+
+  it.each([
+    {
+      name: 'underdamped',
+      spring: springFromResponse({response: 0.32, dampingRatio: 0.8}),
+      slope: 0.16,
+    },
+    {
+      name: 'critically damped',
+      spring: springFromResponse({response: 0.3, dampingRatio: 1}),
+      slope: -40,
+    },
+    {
+      name: 'overdamped',
+      spring: springFromPhysics({
+        stiffness: 100,
+        damping: 40,
+        allowOverdamping: true,
+      }),
+      slope: 250,
+    },
+  ])('matches an RK4 integration ($name)', ({spring, slope}) => {
+    const start = {from: 1, velocity: 0.5, target: 1.02, slope};
+    const curve = solveSpringTowardRamp(spring, start);
+    const scale = Math.max(1, Math.abs(slope));
+    for (const sample of rk4Ramp(spring, start, 1.5)) {
+      expect(Math.abs(curve.value(sample.t) - sample.value)).toBeLessThan(
+        1e-7 * scale,
+      );
+      expect(Math.abs(curve.velocity(sample.t) - sample.velocity)).toBeLessThan(
+        1e-6 * scale,
+      );
+    }
+  });
+
+  it('starts where it is told and settles lag behind, at the target\u2019s speed', () => {
+    const spring = springFromResponse({response: 0.3, dampingRatio: 1});
+    const curve = solveSpringTowardRamp(spring, {
+      from: 0,
+      velocity: 2,
+      target: 0,
+      slope: 10,
+    });
+    expect(curve.value(0)).toBeCloseTo(0, 12);
+    expect(curve.velocity(0)).toBeCloseTo(2, 12);
+    expect(curve.lag).toBeCloseTo((spring.damping * 10) / spring.stiffness, 12);
+    expect(curve.value(5) - (10 * 5 - curve.lag)).toBeCloseTo(0, 6);
+    expect(curve.velocity(5)).toBeCloseTo(10, 6);
+  });
+
+  it('with no slope it is the ordinary spring', () => {
+    const spring = springFromResponse({response: 0.35, dampingRatio: 0.85});
+    const ramp = solveSpringTowardRamp(spring, {
+      from: 0,
+      velocity: 3,
+      target: 1,
+      slope: 0,
+    });
+    const plain = solveSpring(spring, {from: 0, to: 1, velocity: 3});
+    for (let t = 0; t <= 1; t += 0.05) {
+      expect(ramp.value(t)).toBeCloseTo(plain.value(t), 12);
+      expect(ramp.velocity(t)).toBeCloseTo(plain.velocity(t), 12);
+    }
+  });
+});
+
+describe('conversions', () => {
+  it('(duration, bounce) follows the WWDC23 equations', () => {
+    // stiffness = (2π ÷ duration)², damping = (1 − bounce) × 4π ÷ duration.
+    const bouncy = springFromDurationBounce({duration: 0.5, bounce: 0.3});
+    expect(bouncy.mass).toBe(1);
+    expect(bouncy.stiffness).toBeCloseTo(((2 * Math.PI) / 0.5) ** 2, 9);
+    expect(bouncy.damping).toBeCloseTo((0.7 * 4 * Math.PI) / 0.5, 9);
+    // damping = 4π ÷ (duration × (1 + bounce)) for negative bounce.
+    const flattened = springFromDurationBounce({duration: 0.4, bounce: -0.5});
+    expect(flattened.damping).toBeCloseTo((4 * Math.PI) / (0.4 * 0.5), 9);
+    expect(dampingRatioOf(flattened)).toBeCloseTo(2, 9);
+  });
+
+  it('round-trips (duration, bounce) over the whole range', () => {
+    for (const duration of [0.15, 0.3, 0.5, 0.75, 1.2]) {
+      for (const bounce of [-0.9, -0.5, -0.1, 0, 0.15, 0.3, 0.6, 0.95, 1]) {
+        const back = durationBounceOf(
+          springFromDurationBounce({duration, bounce}),
+        );
+        expect(back.duration).toBeCloseTo(duration, 9);
+        expect(back.bounce).toBeCloseTo(bounce, 9);
+      }
+    }
+  });
+
+  it('SwiftUI presets map to their damping ratios (smooth 0, snappy 0.15, bouncy 0.3)', () => {
+    expect(
+      dampingRatioOf(springFromDurationBounce({duration: 0.5, bounce: 0})),
+    ).toBeCloseTo(1, 12);
+    expect(
+      dampingRatioOf(springFromDurationBounce({duration: 0.5, bounce: 0.15})),
+    ).toBeCloseTo(0.85, 12);
+    expect(
+      dampingRatioOf(springFromDurationBounce({duration: 0.5, bounce: 0.3})),
+    ).toBeCloseTo(0.7, 12);
+  });
+
+  it('(response, dampingRatio) reproduces WebKit\u2019s UIKit-matched switch springs exactly', () => {
+    // Source/WebCore/rendering/cocoa/RenderThemeCocoa.mm:
+    // SpringSolver(1.0, 438.64908449286042, 31.415926535897931, 0.0) and
+    // SpringSolver(1.0, 322.27279677026473, 31.2364069556928, 0.0).
+    const move = springFromResponse({response: 0.3, dampingRatio: 0.75});
+    expect(move.stiffness).toBeCloseTo(438.64908449286042, 9);
+    expect(move.damping).toBeCloseTo(31.415926535897931, 9);
+    const press = springFromResponse({response: 0.35, dampingRatio: 0.87});
+    expect(press.stiffness).toBeCloseTo(322.27279677026473, 9);
+    expect(press.damping).toBeCloseTo(31.2364069556928, 9);
+  });
+
+  it('round-trips (response, dampingRatio) and physics', () => {
+    const spring = springFromPhysics({mass: 2, stiffness: 300, damping: 20});
+    const {response, dampingRatio} = responseDampingOf(spring);
+    expect(response).toBeCloseTo((2 * Math.PI) / Math.sqrt(150), 12);
+    expect(dampingRatio).toBeCloseTo(20 / (2 * Math.sqrt(600)), 12);
+    // A different mass with the same ω₀ and ζ is the same motion.
+    const unit = springFromResponse({response, dampingRatio});
+    const a = solveSpring(spring, {from: 0, to: 1, velocity: 3});
+    const b = solveSpring(unit, {from: 0, to: 1, velocity: 3});
+    for (let t = 0; t < 1; t += 0.05) {
+      expect(a.value(t)).toBeCloseTo(b.value(t), 9);
+    }
+    expect(responseOf(unit)).toBeCloseTo(response, 12);
+  });
+
+  it('treats an overdamped physics spring as critical unless allowed (SwiftUI, UIKit)', () => {
+    const clamped = springFromPhysics({stiffness: 100, damping: 50});
+    expect(dampingRatioOf(clamped)).toBeCloseTo(1, 12);
+    const kept = springFromPhysics({
+      stiffness: 100,
+      damping: 50,
+      allowOverdamping: true,
+    });
+    expect(dampingRatioOf(kept)).toBeCloseTo(2.5, 12);
+  });
+
+  it('rejects impossible parameters', () => {
+    expect(() => springFromDurationBounce({duration: 0, bounce: 0})).toThrow(
+      RangeError,
+    );
+    expect(() => springFromResponse({response: -1, dampingRatio: 1})).toThrow(
+      RangeError,
+    );
+    expect(() => springFromPhysics({stiffness: 100, damping: -1})).toThrow(
+      RangeError,
+    );
+    expect(() =>
+      springFromPhysics({mass: 0, stiffness: 100, damping: 1}),
+    ).toThrow(RangeError);
+  });
+
+  it('relative velocity follows UIKit\u2019s documented example', () => {
+    // "if the total animation distance is 200 points and you want the start
+    // of the animation to match a view velocity of 100 pt/s, use 0.5"
+    expect(relativeVelocity(100, 0, 200)).toBe(0.5);
+    expect(absoluteVelocity(0.5, 0, 200)).toBe(100);
+    expect(relativeVelocity(-100, 300, 100)).toBe(0.5);
+  });
+});
+
+describe('settlingDuration (CASpringAnimation semantics)', () => {
+  it('matches Apple\u2019s CASpringAnimation documentation example', () => {
+    // mass 1, stiffness 100: damping 5 → "approximately 2.85 seconds";
+    // damping 15 → "just over 1 second".
+    const loose = settlingDuration(
+      springFromPhysics({stiffness: 100, damping: 5}),
+    );
+    expect(loose).toBeGreaterThan(2.845);
+    expect(loose).toBeLessThan(2.865);
+    const tight = settlingDuration(
+      springFromPhysics({stiffness: 100, damping: 15}),
+    );
+    expect(tight).toBeGreaterThan(1);
+    expect(tight).toBeLessThan(1.05);
+  });
+
+  it('matches WebKit\u2019s iOS switch durations, the settling durations of its springs', () => {
+    // Source/WebCore/rendering/ios/RenderThemeIOS.h:
+    // switchAnimationVisuallyOnDuration 0.4880138408543766_s,
+    // switchAnimationHeldDuration 0.5073965509413827_s.
+    expect(
+      settlingDuration(springFromResponse({response: 0.3, dampingRatio: 0.75})),
+    ).toBeCloseTo(0.4880138408543766, 9);
+    expect(
+      settlingDuration(
+        springFromResponse({response: 0.35, dampingRatio: 0.87}),
+      ),
+    ).toBeCloseTo(0.5073965509413827, 9);
+  });
+
+  it('is shorter for a stiffer or a better-damped spring, as documented', () => {
+    const base = settlingDuration(
+      springFromPhysics({stiffness: 100, damping: 10}),
+    );
+    expect(
+      settlingDuration(springFromPhysics({stiffness: 200, damping: 10})),
+    ).toBeLessThan(base);
+    expect(
+      settlingDuration(springFromPhysics({stiffness: 100, damping: 15})),
+    ).toBeLessThan(base);
+    expect(
+      settlingDuration(
+        springFromPhysics({mass: 2, stiffness: 100, damping: 10}),
+      ),
+    ).toBeGreaterThan(base);
+  });
+
+  it('a critically damped unit move settles at (1 + u)·e^(−u) = ε', () => {
+    const spring = springFromResponse({response: 0.5, dampingRatio: 1});
+    const omega = (2 * Math.PI) / 0.5;
+    const u = settlingDuration(spring) * omega;
+    expect((1 + u) * Math.exp(-u)).toBeCloseTo(0.001, 9);
+  });
+
+  it('accounts for the initial velocity', () => {
+    const spring = springFromResponse({response: 0.5, dampingRatio: 0.8});
+    const still = settlingDuration(spring);
+    // Moving away from the target, or toward it hard enough to overshoot
+    // further, settles later; a velocity close to the spring's own natural
+    // start (here ζ·ω₀ ≈ 10 distances/s) shrinks the oscillation instead.
+    expect(settlingDuration(spring, {initialVelocity: -8})).toBeGreaterThan(
+      still,
+    );
+    expect(settlingDuration(spring, {initialVelocity: 40})).toBeGreaterThan(
+      still,
+    );
+    expect(settlingDuration(spring, {initialVelocity: 8})).toBeLessThan(still);
+  });
+});
+
+// Read from UIKit on the iOS 26.2 simulator (UIKit lab, injected host app,
+// iPhone 17 Pro, Oct 23 2026): CASpringAnimation.settlingDuration for mass 1,
+// stiffness 100, and the duration UIKit gives UIView.animate(springDuration:
+// bounce:initialSpringVelocity:).
+const CA_SETTLING = [
+  {damping: 5, velocity: 0, settling: 2.854974609888761},
+  {damping: 5, velocity: 5, settling: 2.854974609888761},
+  {damping: 5, velocity: -5, settling: 2.992531378997136},
+  {damping: 10, velocity: 0, settling: 1.4727003346780927},
+  {damping: 10, velocity: 5, settling: 1.3815510557964277},
+  {damping: 10, velocity: -5, settling: 1.5350814063145797},
+  {damping: 15, velocity: 0, settling: 1.0220937981854987},
+  {damping: 15, velocity: 5, settling: 0.9637816892907282},
+  {damping: 15, velocity: -5, settling: 1.0625267085113923},
+];
+const UIKIT_SPRING_DURATION = [
+  {duration: 0.3, bounce: 0, velocity: 0, uikit: 0.4409405178437803},
+  {duration: 0.3, bounce: 0, velocity: 2, uikit: 0.43617534275714415},
+  {duration: 0.3, bounce: 0.15, velocity: 0, uikit: 0.4419904194536484},
+  {duration: 0.3, bounce: 0.15, velocity: 2, uikit: 0.4379526271453696},
+  {duration: 0.3, bounce: 0.3, velocity: 0, uikit: 0.5177731699046524},
+  {duration: 0.5, bounce: 0, velocity: 0, uikit: 0.734900863},
+  {duration: 0.5, bounce: 0.15, velocity: 0, uikit: 0.736650699089414},
+  {duration: 0.5, bounce: 0.3, velocity: 2, uikit: 0.8493819071116907},
+  {duration: 1, bounce: 0, velocity: 0, uikit: 1.469801726},
+  {duration: 1, bounce: 0, velocity: 2, uikit: 1.410252226},
+  {duration: 1, bounce: 0.15, velocity: 2, uikit: 1.4240715395795775},
+  {duration: 1, bounce: 0.3, velocity: 0, uikit: 1.725910566348841},
+];
+
+describe('settlingDuration against values read from UIKit', () => {
+  it.each(CA_SETTLING)(
+    'CASpringAnimation(stiffness 100, damping $damping, v $velocity).settlingDuration',
+    ({damping, velocity, settling}) => {
+      const spring = springFromPhysics({stiffness: 100, damping});
+      expect(settlingDuration(spring, {initialVelocity: velocity})).toBeCloseTo(
+        settling,
+        12,
+      );
+    },
+  );
+
+  it.each(UIKIT_SPRING_DURATION)(
+    'UIView.animate(springDuration: $duration, bounce: $bounce, v $velocity) runs $uikit s',
+    ({duration, bounce, velocity, uikit}) => {
+      const spring = springFromDurationBounce({duration, bounce});
+      const mine = settlingDuration(spring, {initialVelocity: velocity});
+      if (bounce > 0) {
+        expect(mine).toBeCloseTo(uikit, 12);
+      } else {
+        // Critically damped: UIKit stops 0.0016 later in ω₀·t.
+        expect(Math.abs(mine - uikit) / uikit).toBeLessThan(3e-4);
+      }
+    },
+  );
+
+  it('UIKit’s default spring runs 0.505824 s: overdamping clamped to critical', () => {
+    const spring = springFromPhysics({mass: 3, stiffness: 1000, damping: 500});
+    expect(dampingRatioOf(spring)).toBeCloseTo(1, 12);
+    expect(
+      Math.abs(settlingDuration(spring) - 0.505824) / 0.505824,
+    ).toBeLessThan(3e-4);
+  });
+});
+
+describe('springFromUIKitDampingDuration (legacy damping/duration API)', () => {
+  // Read from UIKit (same capture): UIView.animate(withDuration: D,
+  // usingSpringWithDamping: ζ, initialSpringVelocity: 0) → mass 1 and these.
+  it.each([
+    {duration: 0.3, dampingRatio: 0.5, stiffness: 1796.883, damping: 42.3897},
+    {duration: 0.3, dampingRatio: 0.8, stiffness: 898.86, damping: 47.9696},
+    {duration: 0.3, dampingRatio: 1, stiffness: 947.288, damping: 61.5561},
+    {duration: 0.5, dampingRatio: 0.5, stiffness: 646.878, damping: 25.4338},
+    {duration: 0.5, dampingRatio: 0.8, stiffness: 323.589, damping: 28.7817},
+    {duration: 0.5, dampingRatio: 1, stiffness: 341.024, damping: 36.9337},
+    {duration: 1, dampingRatio: 0.5, stiffness: 161.72, damping: 12.7169},
+    {duration: 1, dampingRatio: 0.8, stiffness: 80.897, damping: 14.3909},
+    {duration: 1, dampingRatio: 1, stiffness: 85.256, damping: 18.4668},
+  ])(
+    'D $duration, ζ $dampingRatio → stiffness $stiffness',
+    ({duration, dampingRatio, stiffness, damping}) => {
+      const spring = springFromUIKitDampingDuration({duration, dampingRatio});
+      expect(spring.mass).toBe(1);
+      expect(Math.abs(spring.stiffness - stiffness) / stiffness).toBeLessThan(
+        1e-4,
+      );
+      expect(Math.abs(spring.damping - damping) / damping).toBeLessThan(1e-4);
+    },
+  );
+
+  it('at ζ 1 the derived spring settles exactly at the duration', () => {
+    const spring = springFromUIKitDampingDuration({
+      duration: 0.4,
+      dampingRatio: 1,
+    });
+    expect(settlingDuration(spring)).toBeCloseTo(0.4, 3);
+  });
+
+  it.each([
+    {dampingRatio: 0.1, omega: 46.1019536228216},
+    {dampingRatio: 0.3, omega: 19.1698},
+    {dampingRatio: 0.65, omega: 10.3869},
+    {dampingRatio: 0.95, omega: 8.4425},
+  ])(
+    'reproduces the wide read at D 1, ζ $dampingRatio',
+    ({dampingRatio, omega}) => {
+      const spring = springFromUIKitDampingDuration({
+        duration: 1,
+        dampingRatio,
+      });
+      expect(Math.sqrt(spring.stiffness)).toBeCloseTo(omega, 3);
+    },
+  );
+
+  it('interpolates between the measured ratios', () => {
+    const a = springFromUIKitDampingDuration({duration: 1, dampingRatio: 0.6});
+    const b = springFromUIKitDampingDuration({
+      duration: 1,
+      dampingRatio: 0.625,
+    });
+    const c = springFromUIKitDampingDuration({duration: 1, dampingRatio: 0.65});
+    expect(Math.sqrt(b.stiffness)).toBeCloseTo(
+      (Math.sqrt(a.stiffness) + Math.sqrt(c.stiffness)) / 2,
+      9,
+    );
+  });
+});
diff --git a/packages/core/src/motion/spring.ts b/packages/core/src/motion/spring.ts
new file mode 100644
index 0000000000000..bfd5fa91c9bf8
--- /dev/null
+++ b/packages/core/src/motion/spring.ts
@@ -0,0 +1,551 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file spring.ts
+ * @input Spring parameters in any of the four vocabularies Apple uses
+ * @output Exports the `Spring` model, conversions between SwiftUI
+ *   (duration, bounce), SwiftUI/WWDC (response, damping ratio),
+ *   CASpringAnimation (mass, stiffness, damping) and UIKit's legacy
+ *   `usingSpringWithDamping:initialSpringVelocity:` parameters, the closed-form
+ *   solution of the spring (`solveSpring`) and of a spring chasing a target
+ *   that moves at a constant speed (`solveSpringTowardRamp`), and
+ *   `settlingDuration`
+ * @position Pure math under the motion animator; no DOM, no React
+ *
+ * One model, the damped harmonic oscillator m·x″ + c·x′ + k·x = 0, solved in
+ * closed form for its three regimes (under-, critically and over-damped). It
+ * is the model behind SwiftUI's `Spring`, `CASpringAnimation` and UIKit's
+ * spring timing parameters, so a curve computed here is the curve UIKit
+ * computes for the same parameters.
+ *
+ * Units: time in seconds, velocity in units per second (the units of the
+ * animated value: px for a translation, 1 for a scale or an opacity), the
+ * same units SwiftUI and Core Animation use.
+ *
+ * Conversions, with their sources:
+ * - (duration, bounce) → (mass, stiffness, damping): the three equations of
+ *   WWDC23 "Animate with springs" (session 10158):
+ *     mass = 1, stiffness = (2π ÷ duration)²,
+ *     damping = (1 − bounce) × 4π ÷ duration          for bounce ≥ 0,
+ *     damping = 4π ÷ (duration × (1 + bounce))        for bounce < 0.
+ * - (response, dampingRatio) → physics: WWDC18 "Designing Fluid Interfaces"
+ *   (session 803) defines the response as the period of the undamped spring,
+ *   so ω₀ = 2π ÷ response; damping ratio ζ = c ÷ (2·√(k·m)) as stated in
+ *   https://developer.apple.com/documentation/uikit/uispringtimingparameters/init(mass:stiffness:damping:initialvelocity:)
+ * - UIKit's relative initial velocity: "A value of 1 corresponds to the total
+ *   animation distance traversed in one second"
+ *   (https://developer.apple.com/documentation/uikit/uiview/animate(withduration:delay:usingspringwithdamping:initialspringvelocity:options:animations:completion:)).
+ *
+ * Settling duration follows UIKit's own duration solver: the time after which
+ * the displacement from the target, for a unit move, stays below ε = 0.001
+ * (the epsilon SwiftUI documents for `Spring.settlingDuration`). Underdamped,
+ * it is the closed-form time at which the decaying envelope |A| + |B| of
+ * A·cos + B·sin falls to ε; critically damped and overdamped, the root of the
+ * envelope found numerically. Read from UIKit on the iOS 26.2 simulator, the
+ * underdamped values match to the last digit (`CASpringAnimation`
+ * `settlingDuration` for every stiffness/damping/velocity in the grid, and the
+ * duration UIKit gives `UIView.animate(springDuration:bounce:)`); critically
+ * damped ones land within 0.02 % of the duration UIKit picks (it stops 0.0016
+ * later in ω₀·t). Core Animation's `settlingDuration` PROPERTY additionally
+ * rounds critically damped and overdamped springs up to the next 0.1 s; that
+ * rounding is not modeled. Nor is Core Animation's overdamped rendering: with
+ * `allowsOverdamping` on (only `UIView.animate(springDuration:bounce:)` with a
+ * negative bounce turns it on) Core Animation swaps the two exponentials'
+ * coefficients and flips the initial velocity's sign, so its "overdamped"
+ * curve overshoots (stiffness 100, damping 40: 104.5 % at 200 ms); every other
+ * UIKit spring has it off and is clamped to critical, as `springFromPhysics`
+ * does. The bound also reproduces Apple's
+ * CASpringAnimation documentation example (stiffness 100, damping 5 →
+ * "approximately 2.85 seconds"; damping 15 → "just over 1 second") and
+ * WebKit's iOS switch durations, the settling durations of its UIKit-matched
+ * springs (0.4880138408543766 s and 0.5073965509413827 s in
+ * Source/WebCore/rendering/ios/RenderThemeIOS.h). See spring.test.ts.
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/motion/spring.test.ts
+ * - /packages/core/src/motion/README.md
+ */
+
+const TAU = 2 * Math.PI;
+
+/**
+ * A spring, in Core Animation's physical vocabulary. Every other way of
+ * describing a spring converts to this one.
+ */
+export interface Spring {
+  /** Mass m of the attached object (`CASpringAnimation.mass`). */
+  readonly mass: number;
+  /** Stiffness k (`CASpringAnimation.stiffness`). */
+  readonly stiffness: number;
+  /** Viscous damping coefficient c (`CASpringAnimation.damping`). */
+  readonly damping: number;
+}
+
+/** SwiftUI's two-parameter description: `Spring(duration:bounce:)`. */
+export interface DurationBounce {
+  /**
+   * Perceptual duration in seconds: the period of the undamped spring, "the
+   * pace of the spring".
+   */
+  readonly duration: number;
+  /**
+   * 0 is critically damped (no overshoot), up to 1 (undamped oscillation);
+   * negative values, down to −1, are overdamped ("flattened") springs.
+   */
+  readonly bounce: number;
+}
+
+/** WWDC18's design-friendly description: response and damping ratio. */
+export interface ResponseDamping {
+  /** Period of the undamped spring in seconds. */
+  readonly response: number;
+  /**
+   * Damping as a fraction of critical damping (SwiftUI's `dampingFraction`):
+   * 1 settles without overshoot, values toward 0 oscillate longer.
+   */
+  readonly dampingRatio: number;
+}
+
+function assertPositiveFinite(name: string, value: number): void {
+  if (!(Number.isFinite(value) && value > 0)) {
+    throw new RangeError(
+      `spring: ${name} must be a positive number, got ${value}`,
+    );
+  }
+}
+
+/**
+ * SwiftUI's `Spring(duration:bounce:)` and UIKit's
+ * `UIView.animate(springDuration:bounce:…)`: the WWDC23 equations. Bounce is
+ * clamped to SwiftUI's documented range (−1, 1].
+ *
+ * @example
+ * ```
+ * springFromDurationBounce({duration: 0.5, bounce: 0}); // SwiftUI .smooth
+ * ```
+ */
+export function springFromDurationBounce({
+  duration,
+  bounce,
+}: DurationBounce): Spring {
+  assertPositiveFinite('duration', duration);
+  if (!Number.isFinite(bounce)) {
+    throw new RangeError(`spring: bounce must be finite, got ${bounce}`);
+  }
+  // −1 itself would be infinite damping.
+  const b = Math.min(1, Math.max(-0.999999, bounce));
+  const stiffness = (TAU / duration) ** 2;
+  const damping =
+    b >= 0 ? ((1 - b) * 2 * TAU) / duration : (2 * TAU) / (duration * (1 + b));
+  return {mass: 1, stiffness, damping};
+}
+
+/**
+ * SwiftUI's `Spring(response:dampingRatio:)` and
+ * `Animation.spring(response:dampingFraction:)`. Overdamping (ratio > 1) is
+ * kept, as SwiftUI keeps it for this initializer.
+ */
+export function springFromResponse({
+  response,
+  dampingRatio,
+}: ResponseDamping): Spring {
+  assertPositiveFinite('response', response);
+  if (!(Number.isFinite(dampingRatio) && dampingRatio >= 0)) {
+    throw new RangeError(
+      `spring: dampingRatio must be ≥ 0, got ${dampingRatio}`,
+    );
+  }
+  const omega = TAU / response;
+  return {mass: 1, stiffness: omega * omega, damping: 2 * dampingRatio * omega};
+}
+
+/**
+ * `CASpringAnimation` / `UISpringTimingParameters(mass:stiffness:damping:)`
+ * / SwiftUI `Spring(mass:stiffness:damping:allowOverDamping:)`. Like SwiftUI,
+ * an overdamped spring is treated as critically damped unless
+ * `allowOverdamping` is set: "a value of false specifies that such cases
+ * should instead be treated as critically damped".
+ */
+export function springFromPhysics({
+  mass = 1,
+  stiffness,
+  damping,
+  allowOverdamping = false,
+}: {
+  mass?: number;
+  stiffness: number;
+  damping: number;
+  allowOverdamping?: boolean;
+}): Spring {
+  assertPositiveFinite('mass', mass);
+  assertPositiveFinite('stiffness', stiffness);
+  if (!(Number.isFinite(damping) && damping >= 0)) {
+    throw new RangeError(`spring: damping must be ≥ 0, got ${damping}`);
+  }
+  const critical = 2 * Math.sqrt(stiffness * mass);
+  return {
+    mass,
+    stiffness,
+    damping: allowOverdamping ? damping : Math.min(damping, critical),
+  };
+}
+
+/** Undamped angular frequency ω₀ = √(k/m), rad/s. */
+export function naturalFrequency(spring: Spring): number {
+  return Math.sqrt(spring.stiffness / spring.mass);
+}
+
+/** Damping ratio ζ = c / (2·√(k·m)). */
+export function dampingRatioOf(spring: Spring): number {
+  return spring.damping / (2 * Math.sqrt(spring.stiffness * spring.mass));
+}
+
+/** Response (period of the undamped spring), seconds. */
+export function responseOf(spring: Spring): number {
+  return TAU / naturalFrequency(spring);
+}
+
+/** The spring as SwiftUI's (duration, bounce), inverting the WWDC23 equations. */
+export function durationBounceOf(spring: Spring): DurationBounce {
+  const zeta = dampingRatioOf(spring);
+  return {
+    duration: responseOf(spring),
+    bounce: zeta <= 1 ? 1 - zeta : 1 / zeta - 1,
+  };
+}
+
+/** The spring as (response, dampingRatio). */
+export function responseDampingOf(spring: Spring): ResponseDamping {
+  return {response: responseOf(spring), dampingRatio: dampingRatioOf(spring)};
+}
+
+/**
+ * A spring in any of the vocabularies the constants table uses: physical
+ * (mass, stiffness, damping), SwiftUI (duration, bounce) or WWDC18
+ * (response, dampingRatio). Tables keep the vocabulary of their source so a
+ * value reads exactly as it was published.
+ */
+export type SpringDescription =
+  | {
+      readonly mass?: number;
+      readonly stiffness: number;
+      readonly damping: number;
+    }
+  | DurationBounce
+  | ResponseDamping;
+
+/**
+ * Normalizes a description to the physical `Spring`. A physical description
+ * gets `springFromPhysics`' treatment: overdamping is clamped to critical, as
+ * SwiftUI and Core Animation do by default.
+ */
+export function toSpring(description: SpringDescription): Spring {
+  if ('stiffness' in description) {
+    return springFromPhysics(description);
+  }
+  if ('bounce' in description) {
+    return springFromDurationBounce(description);
+  }
+  return springFromResponse(description);
+}
+
+/**
+ * UIKit's relative initial spring velocity for a move from `from` to `to`
+ * at `velocity` units/s: 1 means the whole distance in one second. Undefined
+ * (±Infinity) when `from === to`; animate in absolute units instead
+ * (`solveSpring` takes an absolute velocity).
+ */
+export function relativeVelocity(
+  velocity: number,
+  from: number,
+  to: number,
+): number {
+  return velocity / (to - from);
+}
+
+/** Inverse of `relativeVelocity`: absolute units/s. */
+export function absoluteVelocity(
+  relative: number,
+  from: number,
+  to: number,
+): number {
+  return relative * (to - from);
+}
+
+/** A spring released from a value with a velocity, heading for a target. */
+export interface SpringCurve {
+  readonly spring: Spring;
+  readonly from: number;
+  readonly to: number;
+  /** Initial velocity, units/s. */
+  readonly initialVelocity: number;
+  /** Value at `t` seconds after release. */
+  value(t: number): number;
+  /** Velocity at `t` seconds after release, units/s. */
+  velocity(t: number): number;
+  /**
+   * The time after which |value(t) − to| stays below `threshold` (in the
+   * value's own units) for good: the envelope bound used by
+   * `settlingDuration`, applied in absolute units. 0 when already within.
+   * Infinity for an undamped spring that is displaced or moving.
+   */
+  settleTime(threshold: number): number;
+}
+
+// |ζ − 1| below this is solved as critically damped: the under/overdamped
+// forms lose precision as ωd or the root gap goes to zero, and the critical
+// form differs from them by O(|ζ − 1|) there.
+const CRITICAL_TOLERANCE = 1e-6;
+
+/**
+ * Closed-form solution of the spring released at `from` with
+ * `initialVelocity` (units/s), heading for `to`.
+ *
+ * @example
+ * ```
+ * const curve = solveSpring(springFromDurationBounce({duration: 0.5, bounce: 0}), {from: 0, to: 300});
+ * curve.value(0.1); // px after 100 ms
+ * ```
+ */
+export function solveSpring(
+  spring: Spring,
+  {
+    from,
+    to,
+    velocity: initialVelocity = 0,
+  }: {from: number; to: number; velocity?: number},
+): SpringCurve {
+  const omega0 = naturalFrequency(spring);
+  const zeta = dampingRatioOf(spring);
+  // Displacement from the target; the ODE is solved for x(t) = value − to.
+  const x0 = from - to;
+  const v0 = initialVelocity;
+  let displacement: (t: number) => number;
+  let speed: (t: number) => number;
+  let envelope: (t: number) => number;
+  // Where the envelope peaks (critically damped only; elsewhere 0).
+  let envelopePeak = 0;
+
+  if (zeta < 1 - CRITICAL_TOLERANCE) {
+    const decay = zeta * omega0;
+    const omegaD = omega0 * Math.sqrt(1 - zeta * zeta);
+    const a = x0;
+    const b = (v0 + decay * x0) / omegaD;
+    const bv = (decay * v0 + omega0 * omega0 * x0) / omegaD;
+    displacement = t =>
+      Math.exp(-decay * t) *
+      (a * Math.cos(omegaD * t) + b * Math.sin(omegaD * t));
+    speed = t =>
+      Math.exp(-decay * t) *
+      (v0 * Math.cos(omegaD * t) - bv * Math.sin(omegaD * t));
+    const amplitude = Math.abs(a) + Math.abs(b);
+    envelope = t => amplitude * Math.exp(-decay * t);
+  } else if (zeta <= 1 + CRITICAL_TOLERANCE) {
+    const b = v0 + omega0 * x0;
+    displacement = t => (x0 + b * t) * Math.exp(-omega0 * t);
+    speed = t => (v0 - omega0 * b * t) * Math.exp(-omega0 * t);
+    const absA = Math.abs(x0);
+    const absB = Math.abs(b);
+    envelope = t => (absA + absB * t) * Math.exp(-omega0 * t);
+    // (|A| + |B|·t)·e^(−ω₀t) rises until t = 1/ω₀ − |A|/|B|, then decays.
+    envelopePeak = absB > 0 ? Math.max(0, 1 / omega0 - absA / absB) : 0;
+  } else {
+    const root = omega0 * Math.sqrt(zeta * zeta - 1);
+    const r1 = -zeta * omega0 + root; // slow root
+    const r2 = -zeta * omega0 - root; // fast root
+    const c1 = (v0 - r2 * x0) / (r1 - r2);
+    const c2 = x0 - c1;
+    displacement = t => c1 * Math.exp(r1 * t) + c2 * Math.exp(r2 * t);
+    speed = t => r1 * c1 * Math.exp(r1 * t) + r2 * c2 * Math.exp(r2 * t);
+    const absC1 = Math.abs(c1);
+    const absC2 = Math.abs(c2);
+    envelope = t => absC1 * Math.exp(r1 * t) + absC2 * Math.exp(r2 * t);
+  }
+
+  const settleTime = (threshold: number): number => {
+    if (!(threshold > 0)) {
+      return Infinity;
+    }
+    if (zeta === 0) {
+      return x0 === 0 && v0 === 0 ? 0 : Infinity;
+    }
+    const start = envelopePeak;
+    if (envelope(start) <= threshold) {
+      // `start` is where the bound peaks (0 when it only decays), so the
+      // bound is within the threshold everywhere.
+      return 0;
+    }
+    if (zeta < 1 - CRITICAL_TOLERANCE) {
+      // Closed form: amplitude · e^(−ζω₀t) = threshold.
+      const amplitude = envelope(0);
+      return Math.log(amplitude / threshold) / (zeta * omega0);
+    }
+    // Monotone decreasing after `start`: bracket, then bisect.
+    let lo = start;
+    let hi = Math.max(start, 1 / omega0);
+    while (envelope(hi) > threshold) {
+      lo = hi;
+      hi *= 2;
+      if (hi > 1e6) {
+        return Infinity;
+      }
+    }
+    for (let i = 0; i < 100 && hi - lo > 1e-12; i++) {
+      const mid = (lo + hi) / 2;
+      if (envelope(mid) > threshold) {
+        lo = mid;
+      } else {
+        hi = mid;
+      }
+    }
+    return hi;
+  };
+
+  return {
+    spring,
+    from,
+    to,
+    initialVelocity,
+    value: t => to + displacement(t),
+    velocity: t => speed(t),
+    settleTime,
+  };
+}
+
+/** A spring chasing a target that moves at a constant speed. */
+export interface SpringRampCurve {
+  readonly spring: Spring;
+  /** Value at `t` seconds after the start. */
+  value(t: number): number;
+  /** Velocity at `t` seconds after the start, units/s. */
+  velocity(t: number): number;
+  /**
+   * How far behind the moving target the spring settles: c·slope ÷ k
+   * (it then moves at the target's speed).
+   */
+  readonly lag: number;
+}
+
+/**
+ * A spring whose target moves at a constant speed, `target + slope · t`: the
+ * "tracking" springs UIKit drives per frame (a press that keeps deepening, a
+ * lift that follows the finger). Closed form: the spring settles `lag` behind
+ * the moving target, and what is left is a free spring around that point,
+ * solved by `solveSpring`. Chain pieces (a new slope, a fixed target) by
+ * starting each from the previous piece's value and velocity.
+ */
+export function solveSpringTowardRamp(
+  spring: Spring,
+  {
+    from,
+    velocity: initialVelocity = 0,
+    target,
+    slope,
+  }: {from: number; velocity?: number; target: number; slope: number},
+): SpringRampCurve {
+  const lag = (spring.damping * slope) / spring.stiffness;
+  // x(t) = target + slope·t − lag + h(t), with h a free spring around 0.
+  const free = solveSpring(spring, {
+    from: from - target + lag,
+    to: 0,
+    velocity: initialVelocity - slope,
+  });
+  return {
+    spring,
+    lag,
+    value: t => target + slope * t - lag + free.value(t),
+    velocity: t => slope + free.velocity(t),
+  };
+}
+
+/** Core Animation's settling epsilon (documented for SwiftUI's Spring). */
+export const SETTLING_EPSILON = 0.001;
+
+/**
+ * `CASpringAnimation.settlingDuration` / SwiftUI `Spring.settlingDuration`:
+ * seconds until a unit move (target 1) stays within `epsilon` of its target.
+ * `initialVelocity` is UIKit's relative velocity (distance fractions per
+ * second, positive toward the target), 0 by default as in SwiftUI.
+ */
+export function settlingDuration(
+  spring: Spring,
+  {
+    initialVelocity = 0,
+    epsilon = SETTLING_EPSILON,
+  }: {initialVelocity?: number; epsilon?: number} = {},
+): number {
+  return solveSpring(spring, {
+    from: 0,
+    to: 1,
+    velocity: initialVelocity,
+  }).settleTime(epsilon);
+}
+
+/**
+ * ω₀ · duration that UIKit's legacy spring derivation lands on, by damping
+ * ratio, for a release at rest. Read from UIKit
+ * (`UIView.animate(withDuration: 1, usingSpringWithDamping: ζ,
+ * initialSpringVelocity: 0)`; `UIViewPropertyAnimator(duration:dampingRatio:)`
+ * gives identical springs, and ω₀ scales as 1 ÷ duration): measured: UIKit
+ * lab (injected host app), iOS 26.2 sim iPhone 17 Pro, CAAnimation read,
+ * Oct 23 2026.
+ */
+const UIKIT_LEGACY_OMEGA_DURATION: ReadonlyArray<readonly [number, number]> = [
+  [0.1, 46.102],
+  [0.15, 33.4801],
+  [0.2, 26.5936],
+  [0.25, 22.2149],
+  [0.3, 19.1698],
+  [0.35, 16.9236],
+  [0.4, 15.1966],
+  [0.45, 13.8275],
+  [0.5, 12.7169],
+  [0.55, 11.8001],
+  [0.6, 11.0335],
+  [0.65, 10.3869],
+  [0.7, 9.8396],
+  [0.75, 9.3779],
+  [0.8, 8.9943],
+  [0.85, 8.6897],
+  [0.9, 8.4808],
+  [0.95, 8.4425],
+  [1, 9.2334],
+];
+
+/**
+ * UIKit's legacy `animate(withDuration:delay:usingSpringWithDamping:
+ * initialSpringVelocity:…)`: the caller fixes the total duration and the
+ * damping ratio, and UIKit derives the spring: mass 1, the given damping
+ * ratio, and ω₀ = c(ζ) ÷ duration with c read from UIKit every 0.05 of ζ from
+ * 0.1 to 1 (at ζ 1 the spring settles exactly at the duration). The animation
+ * is cut at the duration.
+ *
+ * GUESS between the measured ratios (linear interpolation, within 0.05 of a
+ * read) and below 0.1 (extrapolated as c ∝ 1 ÷ ζ). A non-zero initial
+ * velocity shifts UIKit's root slightly, and at low ratios makes its solver
+ * jump to a far smaller one (ζ 0.1, velocity 1 → ω₀·D 9.74); neither is
+ * modeled. Measurement task M-K1.
+ */
+export function springFromUIKitDampingDuration({
+  duration,
+  dampingRatio,
+}: {
+  duration: number;
+  dampingRatio: number;
+}): Spring {
+  assertPositiveFinite('duration', duration);
+  // UIKit's ratio is clamped to (0, 1]: it has no overdamped springs.
+  const zeta = Math.min(1, Math.max(1e-3, dampingRatio));
+  const table = UIKIT_LEGACY_OMEGA_DURATION;
+  let c = (table[0][1] * table[0][0]) / zeta;
+  for (let i = 0; i + 1 < table.length; i++) {
+    const [z0, c0] = table[i];
+    const [z1, c1] = table[i + 1];
+    if (zeta >= z0 && zeta <= z1) {
+      c = c0 + ((c1 - c0) * (zeta - z0)) / (z1 - z0);
+      break;
+    }
+  }
+  const omega0 = c / duration;
+  return {mass: 1, stiffness: omega0 * omega0, damping: 2 * zeta * omega0};
+}
diff --git a/packages/core/src/motion/uikit/values.test.ts b/packages/core/src/motion/uikit/values.test.ts
new file mode 100644
index 0000000000000..eea2c7f149fc4
--- /dev/null
+++ b/packages/core/src/motion/uikit/values.test.ts
@@ -0,0 +1,93 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file values.test.ts
+ * @input vitest, the UIKit constants table and the motion math
+ * @output Checks the table's values through the math that plays them: every
+ *   spring is valid and settles; the alert spring is UIKit's legacy
+ *   derivation; a sheet's detent and presentation springs render alike;
+ *   scroll-to-top and the rubber band reproduce what UIKit was measured doing
+ * @position Testing; the source rules are uikit.test.ts
+ */
+
+import {describe, expect, it} from 'vitest';
+import {solveDecay} from '../decay';
+import {rubberBand} from '../rubberBand';
+import {
+  naturalFrequency,
+  settlingDuration,
+  springFromUIKitDampingDuration,
+  toSpring,
+  type SpringDescription,
+} from '../spring';
+import {scroll, springs} from '.';
+
+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)(
+    '%s is a valid spring that settles',
+    (_, description) => {
+      const spring = toSpring(description);
+      const settle = settlingDuration(spring);
+      expect(settle).toBeGreaterThan(0.05);
+      expect(settle).toBeLessThan(2);
+    },
+  );
+
+  it('the alert spring is UIKit\u2019s legacy derivation at 0.404 s, critically damped', () => {
+    // UIKit asks for damping 600 (clamped to 1) over 0.404 s; the measured
+    // grid predicts the spring Core Animation was handed.
+    const derived = springFromUIKitDampingDuration({
+      duration: 0.404,
+      dampingRatio: 1,
+    });
+    expect(derived.stiffness).toBeCloseTo(springs.alertPresent.stiffness, 1);
+    expect(derived.damping).toBeCloseTo(springs.alertPresent.damping, 2);
+  });
+
+  it('a sheet\u2019s detent spring is its presentation spring as rendered (critical, same pace)', () => {
+    // Core Animation clamps UIKit\u2019s default spring to critical damping.
+    expect(naturalFrequency(toSpring(springs.sheetDetent))).toBeCloseTo(
+      naturalFrequency(toSpring(springs.sheetPresent)),
+      6,
+    );
+  });
+
+  it('scroll-to-top as a decay lands on the top along the measured curve', () => {
+    // 2000 pt from the top: remaining distance every ~50 ms after the start.
+    const measured = [1257, 768, 475, 296, 186, 118];
+    const coast = solveDecay({
+      from: 0,
+      velocity: 9.7 * 2000,
+      rate: scroll.scrollToTopRate,
+    });
+    expect(coast.rest).toBeCloseTo(2000, -1);
+    measured.forEach((remaining, i) => {
+      expect(
+        Math.abs(2000 - coast.value((i + 1) * 0.05) - remaining),
+      ).toBeLessThan(30);
+    });
+  });
+
+  it('the rubber band reproduces UIScrollView\u2019s released overscroll', () => {
+    // Finger 100 / 300 / 600 pt past the edge of an 874 pt view, minus the
+    // pan\u2019s 10 pt hysteresis.
+    const cases: [number, number][] = [
+      [90, 47],
+      [290, 135],
+      [590, 236.67],
+    ];
+    for (const [overflow, shown] of cases) {
+      expect(
+        Math.abs(
+          rubberBand(overflow, 874, scroll.rubberBand.coefficient) - shown,
+        ),
+      ).toBeLessThan(0.5);
+    }
+  });
+});

From 6bd2851c46853b321a6ac9ad0f89d0c96933cf60 Mon Sep 17 00:00:00 2001
From: Christopher Chedeau <vjeuxx@gmail.com>
Date: Sat, 24 Oct 2026 14:35:16 -0700
Subject: [PATCH 04/17] chore(core): the constants table names only what
 exists, and dates every measurement

Review fixes: the table headers point at uikit.test.ts and MEASUREMENTS.md
(not a sources.test.ts or the README); the springs header says how many
springs are guesses (two) instead of most; gestures.ts no longer names the
gesture system that arrives later; MEASUREMENTS.md keeps the switch and
context-menu captures open until their tables land; the switch springs say
they are WebKit's iOS 18 values, not UIKit's frames. Every measured source
now carries its date, and uikit.test.ts refuses one without.
---
 packages/core/src/motion/MEASUREMENTS.md     | 18 ++++++++------
 packages/core/src/motion/uikit/gestures.ts   | 13 +++++-----
 packages/core/src/motion/uikit/scroll.ts     |  4 +--
 packages/core/src/motion/uikit/springs.ts    | 26 ++++++++++----------
 packages/core/src/motion/uikit/timing.ts     |  2 +-
 packages/core/src/motion/uikit/uikit.test.ts | 14 +++++++++++
 6 files changed, 47 insertions(+), 30 deletions(-)

diff --git a/packages/core/src/motion/MEASUREMENTS.md b/packages/core/src/motion/MEASUREMENTS.md
index 7e5600298e4d3..4f53b0c9f2060 100644
--- a/packages/core/src/motion/MEASUREMENTS.md
+++ b/packages/core/src/motion/MEASUREMENTS.md
@@ -120,11 +120,13 @@ Subject "switch S": the first switch in Settings ▸ Accessibility ▸ Display &
 Text Size (Bold Text row); a minimal host app holds a UISwitch on a plain view
 where a switch outside any scroll view is needed.
 
-Done (iOS 26.2 simulator, Oct 23 2026; in the switch's own table,
-`uikit/switch.ts`): M-SW02, M-SW03, M-SW04, M-SW05, M-SW06, M-SW09 (UISwitch
+Captured (iOS 26.2 simulator, Oct 23 2026), with their values landing in the
+switch's own table: M-SW02, M-SW03, M-SW04, M-SW05, M-SW06, M-SW09 (UISwitch
 makes no haptic call), M-SW11 (Reduce Motion: the lift stays, the stretch
-goes), M-SW16 (iOS 26.2). Partly: M-SW07 (a single tap only). Still open:
-M-SW17, and M-SW11's On/Off labels, Reduce Transparency and Bold Text.
+goes), M-SW16 (iOS 26.2). Until that table lands they stay open here, and
+`springs.switchThumbMove` and `switchThumbStretch` keep WebKit's values.
+Partly: M-SW07 (a single tap only). Still open: M-SW17, and M-SW11's On/Off
+labels, Reduce Transparency and Bold Text.
 
 | ID     | Scene                                                                                                                                              | Gesture                                                                                                                                                                                           | Extract                                                                                                                                    | Method  |
 | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | ------- |
@@ -251,10 +253,12 @@ match the probe.
 
 ## Context menu (UIContextMenuInteraction)
 
-Values the context menu reads from its own table (`uikit/contextMenu.ts`);
-its springs are `springs.contextMenuLift` and `springs.contextMenuDismiss`.
+Values the context menu reads from its own table, which lands with the
+context menu; its springs are `springs.contextMenuLift` and
+`springs.contextMenuDismiss`.
 
-Done (iOS 26.2 simulator, Oct 23 2026; in the context menu's table): M-CM4.
+Captured (iOS 26.2 simulator, Oct 23 2026; the values land with the context
+menu's table): M-CM4.
 Under Reduce Motion the pressed copy does not grow at all and only its shadow
 fades in, with Prefer Cross-Fade Transitions on or off.
 
diff --git a/packages/core/src/motion/uikit/gestures.ts b/packages/core/src/motion/uikit/gestures.ts
index cdca32009e3c7..53725fa515032 100644
--- a/packages/core/src/motion/uikit/gestures.ts
+++ b/packages/core/src/motion/uikit/gestures.ts
@@ -3,8 +3,8 @@
 /**
  * @file gestures.ts
  * @input Nothing: plain data
- * @output Exports UIKIT_GESTURES, the gesture thresholds the gesture system
- *   (../../gestures) reads, each with where the number comes from, and the
+ * @output Exports UIKIT_GESTURES, the gesture thresholds gesture recognizers
+ *   read, each with where the number comes from, and the
  *   GestureConstant type that carries a value and its source
  * @position Gesture half of the UIKit constants table. Springs, scroll
  *   physics and timing live beside it in this folder; no component carries a
@@ -27,8 +27,7 @@
  * tap-to-click, long press, double tap and the start of a page scroll, so
  * many guesses can be settled by measuring Safari itself.
  *
- * SYNC: When modified, update packages/core/src/gestures/README.md (the
- * thresholds section) and packages/core/src/motion/uikit/gestures.test.ts.
+ * SYNC: When modified, update packages/core/src/motion/uikit/gestures.test.ts.
  */
 
 import {scroll} from './scroll';
@@ -78,7 +77,7 @@ const APPLE = 'https://developer.apple.com/documentation/uikit';
  * recognizer state log), iPhone 17 Pro simulator, iOS 26.2, Oct 2026.
  */
 const UIKIT_LAB =
-  'measured: UIKit lab, iOS 26.2 simulator, ivar reads confirmed with HID touches';
+  'measured: UIKit lab, iOS 26.2 simulator, ivar reads confirmed with HID touches, Oct 23 2026';
 
 /**
  * The repository's own measurement of the touch press model, recorded in
@@ -86,7 +85,7 @@ const UIKIT_LAB =
  * simulator running iOS 26.2, driven with real HID touches, filmed at 60 fps.
  */
 const PRESS_MEASUREMENT =
-  'measured: Settings and Contacts, iOS 26.2 simulator, HID touches filmed at 60 fps (utils/pressGesture.ts)';
+  'measured: Settings and Contacts, iOS 26.2 simulator, HID touches filmed at 60 fps (utils/pressGesture.ts), Oct 6 2026';
 
 /**
  * Safari page scroll is a UIScrollView: the distance at which it claims a
@@ -94,7 +93,7 @@ const PRESS_MEASUREMENT =
  * can still cancel the scroll.
  */
 const SAFARI_SCROLL_CLAIM =
-  'measured: Mobile Safari 26.2, iOS 26.2 simulator, slow HID drag on a scrollable page (1 pt steps): last cancelable touchmove at 10 px, pointercancel and the first uncancelable touchmove at 11 px';
+  'measured: Mobile Safari 26.2, iOS 26.2 simulator, slow HID drag on a scrollable page (1 pt steps): last cancelable touchmove at 10 px, pointercancel and the first uncancelable touchmove at 11 px, Oct 23 2026';
 
 export const UIKIT_GESTURES = {
   tap: {
diff --git a/packages/core/src/motion/uikit/scroll.ts b/packages/core/src/motion/uikit/scroll.ts
index af88c91058978..dddd637fc2425 100644
--- a/packages/core/src/motion/uikit/scroll.ts
+++ b/packages/core/src/motion/uikit/scroll.ts
@@ -7,11 +7,11 @@
  *   the rubber-band coefficient, the bounce-back spring, paging and the
  *   content-touch delay
  * @position The scroll domain of the UIKit constants table (motion/uikit);
- *   read by decay.ts, rubberBand.ts, projection.ts and components
+ *   read by the motion math and components
  *
  * Every leaf carries one `@source` (apple-docs | wwdc | webkit | measured |
  * GUESS); webkit and GUESS values also carry the `@measure` task that will
- * confirm or replace them (listed in motion/README.md). sources.test.ts
+ * confirm or replace them (listed in MEASUREMENTS.md). uikit.test.ts
  * enforces both.
  *
  * SYNC: When modified, update:
diff --git a/packages/core/src/motion/uikit/springs.ts b/packages/core/src/motion/uikit/springs.ts
index bfe545356578a..11f42993cf2a0 100644
--- a/packages/core/src/motion/uikit/springs.ts
+++ b/packages/core/src/motion/uikit/springs.ts
@@ -11,15 +11,14 @@
  *
  * Every leaf carries one or more `@source` (apple-docs | wwdc | webkit |
  * measured | GUESS); webkit and GUESS values also carry the `@measure` task
- * that will confirm or replace them (motion/README.md lists them all).
- * sources.test.ts enforces both.
+ * that will confirm or replace them (MEASUREMENTS.md lists them all).
+ * uikit.test.ts enforces both.
  *
- * Most interaction springs below are GUESSES today: UIKit does not document
- * the springs of its own transitions, and the simulator measurements that
- * will replace them (method in motion/README.md) have not run yet. Each
- * guess starts from the nearest sourced spring and names it, so a component
- * built on the table gets the right value the moment the measurement lands,
- * without changing.
+ * Most springs are measured on iOS 26.2 or documented by Apple; two are still
+ * GUESSES (`segmentedThumb`, `banner`) and two come from WebKit
+ * (`switchThumbMove`, `switchThumbStretch`). A guess starts from the
+ * nearest sourced spring and names it, so a component built on the table
+ * gets the right value the moment its measurement lands, without changing.
  *
  * Press highlight in/out are fades, not springs: see timing.ts.
  *
@@ -28,9 +27,8 @@
  */
 
 /**
- * UIKit's default spring (see `springs.uikitDefault` for its sources). The
- * guesses below start from it: the system-driven transitions it is believed
- * to drive until each is measured.
+ * UIKit's default spring (see `springs.uikitDefault` for its sources), shared
+ * by the system transitions measured to run on it.
  */
 const UIKIT_DEFAULT_SPRING = {mass: 3, stiffness: 1000, damping: 500} as const;
 
@@ -282,7 +280,8 @@ export const springs = {
    *   `thumbMoveSpring = SpringSolver(1.0, 438.649…, 31.4159…)`, "Values
    *   chosen for consistency with UIKit" (= response 0.30 s, ratio 0.75);
    *   its settling duration is WebKit's iOS switch duration 0.48801 s
-   *   (RenderThemeIOS.h)
+   *   (RenderThemeIOS.h). These are WebKit's iOS 18 values: UIKit's own
+   *   switch frames differ, and a switch reads its measured table instead.
    * @measure M-SW02
    */
   switchThumbMove: {response: 0.3, dampingRatio: 0.75},
@@ -291,7 +290,8 @@ export const springs = {
    * @source webkit Source/WebCore/rendering/cocoa/RenderThemeCocoa.mm
    *   `thumbPressSpring = SpringSolver(1.0, 322.272…, 31.2364…)`, "Values
    *   chosen for consistency with UIKit" (= response 0.35 s, ratio 0.87);
-   *   settles in WebKit's held duration 0.50740 s (RenderThemeIOS.h)
+   *   settles in WebKit's held duration 0.50740 s (RenderThemeIOS.h). As
+   *   for `switchThumbMove`, UIKit's own frames differ.
    * @measure M-SW03
    */
   switchThumbStretch: {response: 0.35, dampingRatio: 0.87},
diff --git a/packages/core/src/motion/uikit/timing.ts b/packages/core/src/motion/uikit/timing.ts
index 91e1c0509edc2..35aac388e600c 100644
--- a/packages/core/src/motion/uikit/timing.ts
+++ b/packages/core/src/motion/uikit/timing.ts
@@ -11,7 +11,7 @@
  *
  * Every leaf carries one or more `@source` (apple-docs | wwdc | webkit |
  * measured | GUESS); webkit and GUESS values also carry the `@measure` task
- * that will confirm or replace them (motion/README.md). sources.test.ts
+ * that will confirm or replace them (MEASUREMENTS.md). uikit.test.ts
  * enforces both.
  *
  * Durations are in ms (the unit of pointer-event timestamps, which these
diff --git a/packages/core/src/motion/uikit/uikit.test.ts b/packages/core/src/motion/uikit/uikit.test.ts
index 500205516350e..aabfcc1c910cd 100644
--- a/packages/core/src/motion/uikit/uikit.test.ts
+++ b/packages/core/src/motion/uikit/uikit.test.ts
@@ -38,6 +38,9 @@ const TABLE_FILES = fs
       !TYPED_TABLE_FILES.includes(file),
   )
   .sort();
+/** A measurement names its subject, the iOS version it ran on and its date. */
+const MEASURED =
+  /^@source measured: .*iOS \d.*(\b20\d\d-\d\d-\d\d\b|\b(Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec)[a-z]* \d{1,2},? 20\d\d\b)/;
 const SOURCE_KINDS =
   /^@source (apple-docs https:\/\/developer\.apple\.com\/|wwdc \d{4}-\d+ |webkit Source\/|measured: .*iOS \d|GUESS — )/;
 
@@ -136,6 +139,11 @@ describe('UIKit constants table: every value is sourced (law P2)', () => {
       expect(sources.length, `${key} has no @source`).toBeGreaterThan(0);
       for (const source of sources) {
         expect(source, `${key}: unknown source kind`).toMatch(SOURCE_KINDS);
+        if (source.startsWith('@source measured: ')) {
+          expect(source, `${key}: a measurement needs its date`).toMatch(
+            MEASURED,
+          );
+        }
       }
       const needsMeasurement = sources.some(source =>
         /^@source (GUESS|webkit)/.test(source),
@@ -188,6 +196,12 @@ describe('UIKit constants table: typed domains follow the same rules', () => {
   it.each(constants)('%s', (name, constant) => {
     if (constant.source != null) {
       expect(`@source ${constant.source}`, name).toMatch(SOURCE_KINDS);
+      if (constant.source.startsWith('measured: ')) {
+        expect(
+          `@source ${constant.source}`,
+          `${name}: a measurement needs its date`,
+        ).toMatch(MEASURED);
+      }
     } else {
       expect(
         constant.guess,

From 76be49335d8020d184bb83fd99c6801aa945409b Mon Sep 17 00:00:00 2001
From: Christopher Chedeau <vjeuxx@gmail.com>
Date: Sat, 24 Oct 2026 14:39:08 -0700
Subject: [PATCH 05/17] fix(core): paging past the last page lands on a real
 page

selectSnapPoint built its search window from fromIndex unclamped, so a stale
current page past the end gave an empty window and value undefined. The
index is clamped to the points first.
---
 packages/core/src/motion/projection.test.ts | 13 +++++++++++++
 packages/core/src/motion/projection.ts      |  6 ++++--
 2 files changed, 17 insertions(+), 2 deletions(-)

diff --git a/packages/core/src/motion/projection.test.ts b/packages/core/src/motion/projection.test.ts
index 9b933e0530e7d..21bdae9f96c31 100644
--- a/packages/core/src/motion/projection.test.ts
+++ b/packages/core/src/motion/projection.test.ts
@@ -112,6 +112,19 @@ describe('selectSnapPoint', () => {
 });
 
 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})
diff --git a/packages/core/src/motion/projection.ts b/packages/core/src/motion/projection.ts
index c71003d4dc391..8f0d0c8b920c0 100644
--- a/packages/core/src/motion/projection.ts
+++ b/packages/core/src/motion/projection.ts
@@ -94,8 +94,10 @@ export function selectSnapPoint(
   let lo = 0;
   let hi = points.length - 1;
   if (fromIndex != null && maxSteps != null) {
-    lo = Math.max(lo, fromIndex - maxSteps);
-    hi = Math.min(hi, fromIndex + maxSteps);
+    // A stale index past either end counts from the nearest real point.
+    const from = Math.min(Math.max(fromIndex, 0), points.length - 1);
+    lo = Math.max(lo, from - maxSteps);
+    hi = Math.min(hi, from + maxSteps);
   }
   let best = lo;
   let bestDistance = Infinity;

From 7fd8edfd9fb811acfea75e571eccdcb3270ea4fe Mon Sep 17 00:00:00 2001
From: Christopher Chedeau <vjeuxx@gmail.com>
Date: Fri, 23 Oct 2026 21:18:56 -0700
Subject: [PATCH 06/17] chore(core): swipe actions' UIKit values and release
 rule

---
 .changeset/uikit-swipe-actions-values.md      |   7 +
 packages/core/src/Item/swipeRelease.test.ts   | 190 ++++++++++++++++++
 packages/core/src/Item/swipeRelease.ts        |  85 ++++++++
 packages/core/src/motion/MEASUREMENTS.md      |  16 ++
 packages/core/src/motion/README.md            |  27 +--
 .../core/src/motion/uikit/swipeActions.ts     | 135 +++++++++++++
 6 files changed, 447 insertions(+), 13 deletions(-)
 create mode 100644 .changeset/uikit-swipe-actions-values.md
 create mode 100644 packages/core/src/Item/swipeRelease.test.ts
 create mode 100644 packages/core/src/Item/swipeRelease.ts
 create mode 100644 packages/core/src/motion/uikit/swipeActions.ts

diff --git a/.changeset/uikit-swipe-actions-values.md b/.changeset/uikit-swipe-actions-values.md
new file mode 100644
index 0000000000000..29fd82a3fd37b
--- /dev/null
+++ b/.changeset/uikit-swipe-actions-values.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/core': patch
+---
+
+[chore] Internal: the UIKit values of a swipe-action row (the swipe threshold, the spring the row follows the finger and settles with, the touch claim distance the web needs) and the release rule that picks closed, open or fire (a fast release goes the way it moves, a slow one by where it is, and only a release past the commit point fires), checked against 50 releases read from UIKit. Not exported from the package entry point.
+
+@vjeux
diff --git a/packages/core/src/Item/swipeRelease.test.ts b/packages/core/src/Item/swipeRelease.test.ts
new file mode 100644
index 0000000000000..982808917bbdb
--- /dev/null
+++ b/packages/core/src/Item/swipeRelease.test.ts
@@ -0,0 +1,190 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file swipeRelease.test.ts
+ * @input vitest; swipeRelease.ts and the UIKit constants table
+ * @output The release rule against the UIKit lab's releases; the commit
+ *   point and the resistance past it; the swipe spring is the one UIKit
+ *   reported
+ * @position Unit tests of packages/core/src/Item/swipeRelease.ts
+ */
+
+import {describe, expect, it} from 'vitest';
+import {
+  dampingRatioOf,
+  naturalFrequency,
+  settlingDuration,
+  toSpring,
+} from '../motion/spring';
+import {swipeActions} from '../motion/uikit/swipeActions';
+import {commitPoint, resistedTravel, resolveRelease} from './swipeRelease';
+
+describe('resolveRelease', () => {
+  // The UIKit lab's releases (batch 10a: plain table, 402 pt rows, two
+  // trailing actions, a 156.67 pt open width; the full-swipe point far beyond
+  // them), as the swipe pan reported them when the finger lifted: the
+  // swipe's travel (past the 25 pt the pan needs to begin; negative when the
+  // finger came back past where it began) and its velocity in pt/s, positive
+  // toward open. A scripted "closing" release can still be opening when it
+  // lifts (the 36 pt one at +458), so the reported values are the inputs.
+  const OPEN_WIDTH = 156.67;
+  const FAR = 373;
+  const RELEASES: [travel: number, velocity: number, lands: string][] = [
+    [35, -19, 'closed'],
+    [65, 490, 'open'],
+    [125, 1506, 'open'],
+    [5, -492, 'closed'],
+    [-55, -1532, 'closed'],
+    [95, -16, 'open'],
+    [125, 478, 'open'],
+    [185, 1565, 'open'],
+    [65, -468, 'closed'],
+    // [115, +135]: closed. Scripted as a 1500 pt/s closing flick, it lifted
+    // with the pan reporting a slow opening one: the one release of the 51
+    // neither this rule nor projection explains.
+    [-67, -2545, 'closed'],
+    [-47.7, -1025, 'closed'],
+    [-3, -256, 'closed'],
+    [12.3, -22, 'closed'],
+    [30.3, 293, 'open'],
+    [64, 1058, 'open'],
+    [132.3, 1983, 'open'],
+    [-67, -2060, 'closed'],
+    [-10, -1087, 'closed'],
+    [35.7, 458, 'open'],
+    [50, -18, 'closed'],
+    [63, 286, 'open'],
+    [93, 1372, 'open'],
+    [170, 2031, 'open'],
+    [1.7, -2168, 'closed'],
+    [27.3, -996, 'closed'],
+    [69.3, -287, 'closed'],
+    [87.7, -5, 'open'],
+    [100.3, 148, 'open'],
+    [147.3, 1271, 'open'],
+    [190.3, 608, 'open'],
+    [39.3, -2052, 'closed'],
+    [65, -983, 'closed'],
+    [107, -308, 'closed'],
+    [125, -18, 'open'],
+    [143, 347, 'open'],
+    [185, 948, 'open'],
+    [245, 2082, 'open'],
+    [42.3, -1975, 'closed'],
+    [102.7, -991, 'closed'],
+    [144.3, -283, 'closed'],
+    [162.3, -19, 'open'],
+    [180.3, 271, 'open'],
+    [222.7, 1002, 'open'],
+    [282.3, 1971, 'open'],
+  ];
+
+  it.each(RELEASES)(
+    'lands where UIKit did: %s pt of swipe at %s pt/s → %s',
+    (travel, velocity, lands) => {
+      expect(
+        resolveRelease({
+          behavior: 'reveal',
+          commitAt: FAR,
+          openWidth: OPEN_WIDTH,
+          travel: Math.max(0, travel),
+          velocity,
+        }),
+      ).toBe(lands);
+    },
+  );
+
+  it('goes the way a release moves from about 50 pt/s, and by where it is below that (batches 38c, 38d)', () => {
+    // 204.67 pt open width, released at 0.7 of it: past half. The speeds
+    // are the pan's at its end, as UIKit read them.
+    const base = {
+      behavior: 'reveal' as const,
+      commitAt: 325,
+      openWidth: 204.67,
+      travel: 143,
+    };
+    for (const velocity of [-19.9, -21.2, -35.7, -40.7, 0, 56.1]) {
+      expect(resolveRelease({...base, velocity})).toBe('open');
+    }
+    for (const velocity of [-56.1, -56.5, -68.5, -105, -200, -308]) {
+      expect(resolveRelease({...base, velocity})).toBe('closed');
+    }
+  });
+
+  it('closes a release past the open width that is moving back, as UIKit did (batch 38)', () => {
+    // 204.67 pt open width; released about 300 pt out while coming back at
+    // 300 pt/s: UIKit closed the row, though it would coast to rest past half
+    // the open width.
+    expect(
+      resolveRelease({
+        behavior: 'reveal',
+        commitAt: 325,
+        openWidth: 204.67,
+        travel: 305,
+        velocity: -300,
+      }),
+    ).toBe('closed');
+    // The same release at rest, or still opening, stays open.
+    for (const velocity of [0, 300]) {
+      expect(
+        resolveRelease({
+          behavior: 'reveal',
+          commitAt: 325,
+          openWidth: 204.67,
+          travel: 305,
+          velocity,
+        }),
+      ).toBe('open');
+    }
+  });
+
+  it('fires under reveal on a release past the commit point, whatever the velocity, and never on a flick short of it', () => {
+    const base = {behavior: 'reveal' as const, commitAt: 192, openWidth: 144};
+    expect(resolveRelease({...base, travel: 192, velocity: 0})).toBe('perform');
+    expect(resolveRelease({...base, travel: 200, velocity: -2000})).toBe(
+      'perform',
+    );
+    expect(resolveRelease({...base, travel: 44, velocity: 3000})).toBe('open');
+    expect(resolveRelease({...base, travel: 191, velocity: 3000})).toBe('open');
+  });
+
+  it('fires under commit only past the commit point, and never rests', () => {
+    const base = {behavior: 'commit' as const, commitAt: 150, openWidth: 72};
+    expect(resolveRelease({...base, travel: 150, velocity: 0})).toBe('perform');
+    expect(resolveRelease({...base, travel: 160, velocity: -1000})).toBe(
+      'perform',
+    );
+    expect(resolveRelease({...base, travel: 100, velocity: 0})).toBe('closed');
+    expect(resolveRelease({...base, travel: 40, velocity: 3000})).toBe(
+      'closed',
+    );
+  });
+});
+
+describe('commitPoint and resistedTravel', () => {
+  it('commits past the panel, or past the fraction of the row when that is further', () => {
+    expect(commitPoint(72, 300)).toBe(150);
+    expect(commitPoint(144, 300)).toBe(192);
+  });
+
+  it('follows the finger up to the commit point and resists past it', () => {
+    expect(resistedTravel(150, 150)).toBe(150);
+    expect(resistedTravel(250, 150)).toBeCloseTo(
+      150 + 100 * swipeActions.overdragResistance,
+      10,
+    );
+  });
+});
+
+describe('the swipe spring', () => {
+  it('is the one UIKit reported: critically damped at 10 rad/s, settling in 0.9235 s', () => {
+    for (const description of [swipeActions.tracking, swipeActions.settle]) {
+      const spring = toSpring(description);
+      expect(dampingRatioOf(spring)).toBeCloseTo(1, 10);
+      expect(naturalFrequency(spring)).toBeCloseTo(10, 10);
+      // UIKit's settlingDuration for it, within the 0.02 % the solver's
+      // critically damped branch is documented to land.
+      expect(settlingDuration(spring)).toBeCloseTo(0.9235, 3);
+    }
+  });
+});
diff --git a/packages/core/src/Item/swipeRelease.ts b/packages/core/src/Item/swipeRelease.ts
new file mode 100644
index 0000000000000..c6e364d9005af
--- /dev/null
+++ b/packages/core/src/Item/swipeRelease.ts
@@ -0,0 +1,85 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file swipeRelease.ts
+ * @input The UIKit constants table (motion/uikit/swipeActions.ts)
+ * @output Exports resolveRelease (where a swipe-action release lands: closed,
+ *   open, or the outermost entry fires), commitPoint and resistedTravel
+ * @position Pure pieces of Item's swipe actions, beside useSwipeAction;
+ *   tested by swipeRelease.test.ts against the UIKit lab's releases
+ *
+ * A UIKit list row decides a release by its speed first. A release at
+ * `releaseVelocity` or faster goes the way it moves: it opens the row when
+ * it opens and closes it when it closes, from anywhere short of the commit
+ * point. A slower one goes by where it is, against `openFraction` of the
+ * open width. So a flick opens the row even from a short drag and closes it
+ * from anywhere, and a flick never fires an action: only a release past the
+ * commit point does. Travel and velocity here are logical: measured toward
+ * the side being uncovered, whatever the writing direction.
+ */
+
+import {swipeActions} from '../motion/uikit/swipeActions';
+
+/** What a swipe does (Item's `swipeBehavior`). */
+export type SwipeReleaseBehavior = 'reveal' | 'commit';
+
+/** Where a release lands. */
+export type SwipeRelease = 'closed' | 'open' | 'perform';
+
+/**
+ * Where a release lands. `travel` (px, ≥ 0) and `velocity` (px/s) are
+ * logical: positive toward the side being uncovered. A release past the
+ * commit point fires the outermost entry, whatever its velocity; under
+ * `commit` nothing else fires and nothing rests. Under `reveal` a release at
+ * `releaseVelocity` or faster opens the row if it is opening and closes it if
+ * it is closing; a slower one opens it past `openFraction` of its open width
+ * and closes it short of that.
+ */
+export function resolveRelease({
+  travel,
+  velocity,
+  openWidth,
+  commitAt,
+  behavior,
+}: {
+  travel: number;
+  velocity: number;
+  openWidth: number;
+  commitAt: number;
+  behavior: SwipeReleaseBehavior;
+}): SwipeRelease {
+  if (travel >= commitAt) {
+    return 'perform';
+  }
+  if (behavior === 'commit') {
+    return 'closed';
+  }
+  if (velocity >= swipeActions.releaseVelocity) {
+    return 'open';
+  }
+  if (velocity <= -swipeActions.releaseVelocity) {
+    return 'closed';
+  }
+  return travel >= swipeActions.openFraction * openWidth ? 'open' : 'closed';
+}
+
+/**
+ * The commit point: `commitPastPanel` past the open width, or
+ * `commitFraction` of the row when that is further.
+ */
+export function commitPoint(openWidth: number, rowWidth: number): number {
+  return Math.max(
+    openWidth + swipeActions.commitPastPanel,
+    rowWidth * swipeActions.commitFraction,
+  );
+}
+
+/**
+ * The row's travel for the finger's: one for one up to the commit point,
+ * `overdragResistance` per pixel past it.
+ */
+export function resistedTravel(raw: number, commitAt: number): number {
+  return raw <= commitAt
+    ? raw
+    : commitAt + (raw - commitAt) * swipeActions.overdragResistance;
+}
diff --git a/packages/core/src/motion/MEASUREMENTS.md b/packages/core/src/motion/MEASUREMENTS.md
index 4f53b0c9f2060..d8e8b68f50c4a 100644
--- a/packages/core/src/motion/MEASUREMENTS.md
+++ b/packages/core/src/motion/MEASUREMENTS.md
@@ -269,3 +269,19 @@ fades in, with Prefer Cross-Fade Transitions on or off.
 | M-CM4 | Reduce Motion press feedback    | Probe app with Reduce Motion on: long press, then dismiss                                                                   | press feedback, lift and dismiss animations under Reduce Motion                                                                                                                           | A, B   |
 | M-CM5 | Commit haptic stand-in          | An Android device: `navigator.vibrate` patterns against the platform's HapticFeedbackConstants for the context-click moment | the pattern that matches; not a UIKit parity value (as M-G18)                                                                                                                             | H      |
 | M-CM6 | Press thresholds                | Probe app: repeated long presses at random vsync phases                                                                     | from touch receipt and from the HID timestamp, the tick before and the tick at the press observer's began and at the click commit; the intersection pins the 150 ms and 400 ms thresholds | C      |
+
+## Swipe actions (UIContextualAction)
+
+UIKit lab host app: a plain `UITableView` (402 and 375 pt wide, 60 pt rows)
+with one, two and three trailing `UIContextualAction`s (the last one
+`.destructive`) and one leading `.normal` action; drags driven with known
+velocity, the touch stream, the swipe handler's tracking and move calls and
+every animator and `CAAnimation` logged.
+
+| ID     | Value                                             | Gesture                                                                                                                                | Extract                                                                                                                    | Method |
+| ------ | ------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | ------ |
+| M-SA01 | `swipeActions.openFraction`                       | swipes released at rest at 0.3, 0.35, 0.4, 0.45, 0.5, 0.55 × the open width (past the 25 pt threshold)                                 | open or closed per release: the fraction                                                                                   | C      |
+| M-SA02 | `swipeActions.commitPastPanel`, `.commitFraction` | slow drag out past the full-swipe point and back; releases at rest and at ±1000 pt/s around it; 1, 2, 3 actions; 375, 402, 440 pt wide | the offsets where the primary action expands and collapses; perform or not per release; `confirmationThreshold`            | C, D   |
+| M-SA03 | `swipeActions.overdragResistance`                 | drag to the row width + 200 pt at 100 pt/s, with `performsFirstActionWithFullSwipe` on and off                                         | the row's offset against the finger's, per frame; `-[UISwipeOccurrence _extraOffsetForOffset:withDirection:]` over a sweep | C, D   |
+| M-SA04 | `swipeActions.slideOutOvershoot`                  | full swipe released past the confirmation point, `.normal` and `.destructive`                                                          | the row's position per frame until the action runs and the row returns or is removed; when the handler runs                | A, C   |
+| M-SA05 | `swipeActions.releaseVelocity`                    | releases past half the open width closing at 42, 44, 46, 48, 50, 52 and 54 pt/s (the pan's velocity at its end)                        | open or closed per release: the slowest closing speed that closes the row                                                  | C      |
diff --git a/packages/core/src/motion/README.md b/packages/core/src/motion/README.md
index 0ca69112c7578..a693394ef1e1b 100644
--- a/packages/core/src/motion/README.md
+++ b/packages/core/src/motion/README.md
@@ -9,19 +9,20 @@ import it by path.
 
 ## Files
 
-| File                  | What it is                                                                                                              |
-| --------------------- | ----------------------------------------------------------------------------------------------------------------------- |
-| `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/timing.ts`     | Non-spring clocks and curves: press highlight, Core Animation's named curves, keyboard, Reduced Motion cross-fade.      |
-| `uikit/navigation.ts` | UINavigationController: push velocity, parallax, dimming, transition clock, interactive pop finish rule.                |
-| `uikit/gestures.ts`   | Gesture recognizer thresholds, the velocity filter and the haptic stand-ins, as typed entries the gesture system reads. |
-| `MEASUREMENTS.md`     | The UIKit reference captures each unconfirmed value still needs.                                                        |
-| `spring.ts`           | Closed-form damped spring, every Apple parameterization, settling duration, a spring chasing a moving target.           |
-| `decay.ts`            | UIScrollView's momentum coast.                                                                                          |
-| `rubberBand.ts`       | UIScrollView's resistance past an edge, and its inverse.                                                                |
-| `projection.ts`       | Release targets: the rest point nearest the projected coast; paging.                                                    |
+| File                    | What it is                                                                                                              |
+| ----------------------- | ----------------------------------------------------------------------------------------------------------------------- |
+| `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/timing.ts`       | Non-spring clocks and curves: press highlight, Core Animation's named curves, keyboard, Reduced Motion cross-fade.      |
+| `uikit/navigation.ts`   | UINavigationController: push velocity, parallax, dimming, transition clock, interactive pop finish rule.                |
+| `uikit/swipeActions.ts` | Swipe actions on a list row: the claim and swipe thresholds, the tracking and settle spring, the release rule.          |
+| `uikit/gestures.ts`     | Gesture recognizer thresholds, the velocity filter and the haptic stand-ins, as typed entries the gesture system reads. |
+| `MEASUREMENTS.md`       | The UIKit reference captures each unconfirmed value still needs.                                                        |
+| `spring.ts`             | Closed-form damped spring, every Apple parameterization, settling duration, a spring chasing a moving target.           |
+| `decay.ts`              | UIScrollView's momentum coast.                                                                                          |
+| `rubberBand.ts`         | UIScrollView's resistance past an edge, and its inverse.                                                                |
+| `projection.ts`         | Release targets: the rest point nearest the projected coast; paging.                                                    |
 
 Component-specific values (a sheet's detents, a switch's geometry, a context
 menu's timeline) live in a domain file per component, `uikit/<component>.ts`,
diff --git a/packages/core/src/motion/uikit/swipeActions.ts b/packages/core/src/motion/uikit/swipeActions.ts
new file mode 100644
index 0000000000000..e05f05c62d0ce
--- /dev/null
+++ b/packages/core/src/motion/uikit/swipeActions.ts
@@ -0,0 +1,135 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file swipeActions.ts
+ * @input Nothing; data only
+ * @output Exports `swipeActions`: the swipe-action row's gesture thresholds
+ *   (the web's claim and UIKit's swipe), its tracking and settle springs, and
+ *   the speed and position that pick where a release lands
+ * @position The swipe-actions domain of the UIKit constants table
+ *   (motion/uikit): `UIContextualAction` / `UISwipeActionsConfiguration` rows
+ *   of a table or collection list
+ *
+ * Measured on a UIKit host app (plain `UITableView`, 402 pt rows, two
+ * trailing actions, iOS 26.2). Lengths are in pt (CSS px), springs in the
+ * vocabulary UIKit was read in (`toSpring` normalizes).
+ *
+ * Every leaf carries one or more `@source`; GUESS values also carry the
+ * `@measure` task that will confirm or replace them. uikit.test.ts enforces
+ * both.
+ *
+ * Reduce Motion is not a value here. UIKit keeps both springs under it (lab,
+ * iOS 26.2 simulator, iPhone 17 Pro, Reduce Motion on: the same
+ * `UISpringTimingParameters(mass: 2, stiffness: 200, damping: 100)` animators
+ * on tracking and release, and the full swipe still performs, Oct 23 2026),
+ * but `design:reduced-motion` governs Astryx: what a release starts
+ * cross-fades (DR2), and a core component keeps no motion under it (DR4).
+ *
+ * SYNC: When modified, update /packages/core/src/motion/MEASUREMENTS.md
+ */
+
+export const swipeActions = {
+  /**
+   * Sideways travel at which the row claims the touch from the browser, NOT
+   * a UIKit value: on the web a scrolling ancestor takes the touch at about
+   * 10 px unless the page cancels `touchmove` before that, so the row claims
+   * at 8 px and its swipe still begins at `hysteresis`. In between the touch
+   * moves neither the row nor the page.
+   * @source measured: Mobile Safari, iOS 26.2 simulator, iPhone 17 Pro, the
+   *   touch stream against WebKit's scroll commit on a scrollable element
+   *   (the last cancelable `touchmove` at 10 px; cancelling every `touchmove`
+   *   from 8 px keeps the page still for the whole gesture), Oct 23 2026
+   */
+  claim: 8,
+  /**
+   * Finger travel before the swipe begins. The travel up to that point is
+   * not part of the swipe: the row starts from where it was, it never jumps
+   * by the threshold.
+   * @source measured: UIKit lab (injected host app), iOS 26.2 simulator,
+   *   iPhone 17 Pro, `_UISwipeActionPanGestureRecognizer` `_hysteresis` ivar
+   *   read (25) and a 1 pt step drag: began at exactly 25 pt of travel with
+   *   a translation of 0, Oct 23 2026
+   */
+  hysteresis: 25,
+  /**
+   * The spring the row follows the finger with. Each move starts a new
+   * spring toward the finger's offset, from the row's presentation value and
+   * velocity, so the row trails a moving finger and catches up when it
+   * stops. Overdamped on paper; Core Animation renders it critically damped
+   * (allowsOverdamping off), ω₀ = 10 rad/s, which `toSpring` mirrors.
+   * @source measured: UIKit lab (injected host app), iOS 26.2 simulator,
+   *   iPhone 17 Pro, `UIViewPropertyAnimator` with
+   *   `UISpringTimingParameters(mass: 2, stiffness: 200, damping: 100)`
+   *   read on every tracking update, seeded with the presentation velocity,
+   *   settlingDuration 0.9235 s, Oct 23 2026
+   */
+  tracking: {mass: 2, stiffness: 200, damping: 100},
+  /**
+   * The settle after the finger lifts, to open, to closed or out: the same
+   * spring, seeded with the row's presentation velocity (the tracking
+   * spring's), not with the finger's.
+   * @source measured: UIKit lab (injected host app), iOS 26.2 simulator,
+   *   iPhone 17 Pro, the release animator read: mass 2, stiffness 200,
+   *   damping 100, rendered critically damped; a 1000 pt/s closing flick
+   *   seeded it with the presentation velocity (initialVelocity 2.88), not
+   *   the finger's, Oct 23 2026
+   */
+  settle: {mass: 2, stiffness: 200, damping: 100},
+  /**
+   * Where a slow release lands (one slower than `releaseVelocity`): past
+   * this fraction of the open width the row opens, short of it the row
+   * closes.
+   * @source measured: UIKit lab (injected host app), iOS 26.2 simulator,
+   *   iPhone 17 Pro, releases at rest: 0.32 × the 156.67 pt open width
+   *   closed and 0.56 opened (batch 10a), Oct 23 2026
+   * @source GUESS — the fraction inside the measured 0.32 to 0.56 bracket
+   * @measure M-SA01
+   */
+  openFraction: 0.5,
+  /**
+   * A release this fast goes the way it moves: it opens the row when it
+   * opens and closes it when it closes, from anywhere short of the commit
+   * point. A flick therefore never fires an action. The speed is the swipe
+   * pan's velocity when the finger lifts, which UIKit never decays: a lift
+   * after a pause carries the last moving speed.
+   * @source measured: UIKit lab (injected host app), iOS 26.2 simulator,
+   *   iPhone 17 Pro, the swipe pan's velocity read at its end: released past
+   *   half the open width while closing at 19.9, 21.2, 35.7 and 40.7 pt/s
+   *   the row opened, and at 56.1, 56.5, 68.5, 105, 200 and 308 pt/s it
+   *   closed (batch 38d); of 51 releases every one at 283 pt/s or more went
+   *   its way (batch 10a), Oct 23 2026
+   * @source GUESS — the speed inside the measured 40.7 to 56.1 pt/s bracket
+   * @measure M-SA05
+   */
+  releaseVelocity: 48,
+  /**
+   * Past the open width, how far beyond the panel the row must be dragged
+   * for a release to fire the outermost action (`commitPastPanel`), unless
+   * `commitFraction` of the row is further.
+   * @source GUESS — the threshold Astryx used before the UIKit lab; UIKit's
+   *   confirmation threshold (the table width − 29 pt on iOS 26.2) replaces
+   *   it with the full-swipe expansion
+   * @measure M-SA02
+   */
+  commitPastPanel: 48,
+  /**
+   * See `commitPastPanel`.
+   * @source GUESS — the threshold Astryx used before the UIKit lab
+   * @measure M-SA02
+   */
+  commitFraction: 0.5,
+  /**
+   * Past the commit point the row moves this much per point of finger
+   * travel.
+   * @source GUESS — the resistance Astryx used before the UIKit lab
+   * @measure M-SA03
+   */
+  overdragResistance: 0.35,
+  /**
+   * How far past the row's edge the row travels when an action fires and
+   * the row goes out.
+   * @source GUESS — the distance Astryx used before the UIKit lab
+   * @measure M-SA04
+   */
+  slideOutOvershoot: 24,
+} as const;

From e7df427651e28222cd27d9e6ee456755ce5a5d3f Mon Sep 17 00:00:00 2001
From: Christopher Chedeau <vjeuxx@gmail.com>
Date: Sun, 25 Oct 2026 07:37:35 -0700
Subject: [PATCH 07/17] perf(core): the gesture table's sources move to JSDoc,
 out of the bundle

UIKIT_GESTURES shipped each value's provenance as runtime strings
({value, unit, source} or {value, unit, guess, measure}): 69% of the minified
module, carried by every page that reads a gesture threshold, and read by
nothing at run time. Its entries now carry their sources as JSDoc tags
(@source, @measure), like every other domain of the table, and ship only
{value, unit}. Values and units are unchanged; isGuess and the sourced and
guessed constant types go, since no value carries a guess any more.

The haptic stand-ins share one guess, stated once above
HAPTIC_VIBRATION_PATTERNS, and the patterns are plain literals, so a bundle
that never plays a haptic drops them. uikit.test.ts checks gestures.ts in the
JSDoc form, fails a table value named source, guess or measure, and checks
the haptic block; gestures.test.ts checks that each constant ships only its
value and unit.

Production bundle, minified and gzipped: UIKIT_GESTURES alone 5,794 B /
2,397 B -> 1,746 B / 785 B (scroll and timing included); a Carousel built on
the gesture system 63,389 -> 61,489 B gzip; the gesture host alone 16,320 ->
14,434 B gzip.
---
 packages/core/src/motion/README.md            |  13 +-
 .../core/src/motion/uikit/gestures.test.ts    |  31 +-
 packages/core/src/motion/uikit/gestures.ts    | 462 ++++++++----------
 packages/core/src/motion/uikit/index.ts       |   3 -
 packages/core/src/motion/uikit/uikit.test.ts  | 156 +++---
 5 files changed, 293 insertions(+), 372 deletions(-)

diff --git a/packages/core/src/motion/README.md b/packages/core/src/motion/README.md
index d8bc91c74fa99..cf1202e4c0bd3 100644
--- a/packages/core/src/motion/README.md
+++ b/packages/core/src/motion/README.md
@@ -15,7 +15,7 @@ point; components import it by path.
 | `uikit/scroll.ts`     | UIScrollView: deceleration rates, rubber band, bounce-back spring, paging, `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/navigation.ts` | UINavigationController: push velocity, parallax, dimming, transition clock, interactive pop finish rule.                |
-| `uikit/gestures.ts`   | Gesture recognizer thresholds, the velocity filter and the haptic stand-ins, as typed entries the gesture system reads. |
+| `uikit/gestures.ts`   | Gesture recognizer thresholds, the velocity filter and haptic stand-ins, as `{value, unit}` entries (sources in JSDoc). |
 | `MEASUREMENTS.md`     | The UIKit reference captures each unconfirmed value still needs.                                                        |
 
 Component-specific values (a sheet's detents, a switch's geometry, a context
@@ -47,12 +47,11 @@ Allowed source kinds:
 A `GUESS` or `webkit` value also names the measurement that will confirm or
 replace it (`@measure M-…`, listed in MEASUREMENTS.md). An entry may carry
 several sources when different parts come from different places.
-`uikit/gestures.ts` carries the same information as typed fields that the
-gesture system reads at run time: `{value, unit, source}` with a source of one
-of the kinds above, or `{value, unit, guess, measure}` with a `measure` that
-starts with its MEASUREMENTS.md ID. `uikit/uikit.test.ts` enforces all of it on
-every domain file, in both forms: an unsourced value, an unknown kind, a guess
-without a task, or a task missing from MEASUREMENTS.md fails the build.
+The sources are documentation and stay out of the bundle: no value carries
+them, `uikit/gestures.ts` included (its entries ship only `{value, unit}`).
+`uikit/uikit.test.ts` enforces all of it on every domain file: an unsourced
+value, an unknown kind, a guess without a task, a task missing from
+MEASUREMENTS.md, or a source in a value fails the build.
 
 Measurements come from the iOS simulator: built-in apps (Settings, Maps,
 Photos, Files, Contacts, Calendar, Reminders, Safari's own chrome) or a UIKit
diff --git a/packages/core/src/motion/uikit/gestures.test.ts b/packages/core/src/motion/uikit/gestures.test.ts
index c4ac3c7b54c64..cb64b5a3abae1 100644
--- a/packages/core/src/motion/uikit/gestures.test.ts
+++ b/packages/core/src/motion/uikit/gestures.test.ts
@@ -3,8 +3,9 @@
 /**
  * @file gestures.test.ts
  * @input The gesture constants table
- * @output Every value is sourced or is a guess that names its measurement;
- *   the documented UIKit defaults keep their documented values
+ * @output Every constant ships only its value and unit (its sources are
+ *   JSDoc, checked by uikit.test.ts); the documented UIKit defaults keep
+ *   their documented values
  * @position Unit test of packages/core/src/motion/uikit/gestures.ts
  */
 
@@ -12,7 +13,6 @@ import {describe, expect, it} from 'vitest';
 import {
   HAPTIC_FEEDBACK_KINDS,
   HAPTIC_VIBRATION_PATTERNS,
-  isGuess,
   UIKIT_GESTURES,
   type GestureConstant,
 } from './gestures';
@@ -31,20 +31,17 @@ function entries(): [string, GestureConstant<unknown>][] {
 }
 
 describe('UIKIT_GESTURES', () => {
-  it.each(entries())(
-    '%s carries a source or a measurement task',
-    (_, constant) => {
-      if (isGuess(constant)) {
-        expect(constant.guess.length).toBeGreaterThan(10);
-        expect(constant.measure).toMatch(/^M-G\d\d: .{10,}/);
-        expect('source' in constant).toBe(false);
-      } else {
-        expect(constant.source).toMatch(
-          /^(apple-docs https:\/\/developer\.apple\.com\/|wwdc \d{4}-\d+ |measured: )/,
-        );
-      }
-    },
-  );
+  it.each(entries())('%s ships only its value and unit', (_, constant) => {
+    // Its sources are JSDoc (uikit.test.ts): a source in the value would ship
+    // in every bundle that reads it.
+    expect(Object.keys(constant).sort()).toEqual(['unit', 'value']);
+    const values = Array.isArray(constant.value)
+      ? constant.value
+      : [constant.value];
+    for (const value of values) {
+      expect(Number.isFinite(value)).toBe(true);
+    }
+  });
 
   it('keeps the documented and measured UIKit values', () => {
     expect(UIKIT_GESTURES.longPress.minimumPressDuration.value).toBe(500);
diff --git a/packages/core/src/motion/uikit/gestures.ts b/packages/core/src/motion/uikit/gestures.ts
index 53725fa515032..283f7c96f46a2 100644
--- a/packages/core/src/motion/uikit/gestures.ts
+++ b/packages/core/src/motion/uikit/gestures.ts
@@ -4,8 +4,7 @@
  * @file gestures.ts
  * @input Nothing: plain data
  * @output Exports UIKIT_GESTURES, the gesture thresholds gesture recognizers
- *   read, each with where the number comes from, and the
- *   GestureConstant type that carries a value and its source
+ *   read, and the GestureConstant type: a value and its unit
  * @position Gesture half of the UIKit constants table. Springs, scroll
  *   physics and timing live beside it in this folder; no component carries a
  *   gesture number of its own.
@@ -14,18 +13,26 @@
  * `width=device-width`, one CSS pixel is one UIKit point, so a UIKit distance
  * in points is the same number here.
  *
- * Every entry is either SOURCED (Apple documentation, a WWDC session, or a
- * measurement of a real UIKit app on the iOS simulator, named with the app,
- * the iOS version and the method) or a GUESS. A guess says what it rests on
- * and what to measure to replace it; `gestures.test.ts` fails if an entry
- * carries neither. The table's shared rules hold here too (uikit.test.ts): a
- * source starts with its kind (`apple-docs <URL>`, `wwdc <year>-<session>`,
- * `webkit Source/…`, `measured: …`), and a guess's `measure` starts with
- * the ID of its row in ../MEASUREMENTS.md. The press clocks are the same
- * entries as `scroll.delaysContentTouchesMs` and `timing.press`, read from
- * there. Safari on iOS runs UIKit's own recognizers for
- * tap-to-click, long press, double tap and the start of a page scroll, so
- * many guesses can be settled by measuring Safari itself.
+ * Every leaf carries one or more `@source` (apple-docs | wwdc | webkit |
+ * measured | GUESS); webkit and GUESS values also carry the `@measure` task
+ * that will confirm or replace them (MEASUREMENTS.md lists them all).
+ * uikit.test.ts enforces both. Only the value and its unit ship: where a
+ * number comes from stays in its JSDoc, out of the bundle. The press clocks
+ * are the same entries as `scroll.delaysContentTouchesMs` and
+ * `timing.press`, read from there. Safari on iOS runs UIKit's own
+ * recognizers for tap-to-click, long press, double tap and the start of a
+ * page scroll, so many guesses can be settled by measuring Safari itself.
+ *
+ * The measurements the sources name:
+ * - UIKit lab: in-process reads and touch runs of fresh UIKit recognizers
+ *   (private ivars read with key-value coding, every value confirmed with HID
+ *   touches and the recognizer state log), iPhone 17 Pro simulator, iOS 26.2.
+ * - Settings and Contacts: the repository's own measurement of the touch
+ *   press model, recorded in packages/core/src/utils/pressGesture.ts, driven
+ *   with real HID touches and filmed at 60 fps.
+ * - Mobile Safari: Safari page scroll is a UIScrollView; the distance at which
+ *   it claims a slow drag is where a press becomes a scroll, and the last
+ *   moment a page can still cancel the scroll.
  *
  * SYNC: When modified, update packages/core/src/motion/uikit/gestures.test.ts.
  */
@@ -36,108 +43,66 @@ import {timing} from './timing';
 export type GestureConstantUnit =
   'px' | 'ms' | 'px/s' | 'rad' | 'ratio' | 'count';
 
-interface GestureConstantBase<T> {
+/**
+ * A gesture number and its unit. Where the number comes from is in the
+ * entry's JSDoc (`@source`, `@measure`), not in the value.
+ */
+export interface GestureConstant<T = number> {
   readonly value: T;
   readonly unit: GestureConstantUnit;
 }
 
-/** A number with a citable origin. */
-export interface SourcedGestureConstant<
-  T = number,
-> extends GestureConstantBase<T> {
-  /** Documentation URL, WWDC session, or `measured: <app>, <iOS>, <method>`. */
-  readonly source: string;
-}
-
-/** A number nobody has measured yet. */
-export interface GuessedGestureConstant<
-  T = number,
-> extends GestureConstantBase<T> {
-  /** What the guess rests on. */
-  readonly guess: string;
-  /** The measurement that replaces it. */
-  readonly measure: string;
-}
-
-export type GestureConstant<T = number> =
-  SourcedGestureConstant<T> | GuessedGestureConstant<T>;
-
-/** Whether a constant still needs its measurement. */
-export function isGuess<T>(
-  constant: GestureConstant<T>,
-): constant is GuessedGestureConstant<T> {
-  return 'guess' in constant;
-}
-
-const APPLE = 'https://developer.apple.com/documentation/uikit';
-
-/**
- * In-process reads and touch runs of fresh UIKit recognizers (private ivars
- * read with key-value coding, every value confirmed with HID touches and the
- * recognizer state log), iPhone 17 Pro simulator, iOS 26.2, Oct 2026.
- */
-const UIKIT_LAB =
-  'measured: UIKit lab, iOS 26.2 simulator, ivar reads confirmed with HID touches, Oct 23 2026';
-
-/**
- * The repository's own measurement of the touch press model, recorded in
- * packages/core/src/utils/pressGesture.ts: Settings and Contacts on an iPhone
- * simulator running iOS 26.2, driven with real HID touches, filmed at 60 fps.
- */
-const PRESS_MEASUREMENT =
-  'measured: Settings and Contacts, iOS 26.2 simulator, HID touches filmed at 60 fps (utils/pressGesture.ts), Oct 6 2026';
-
-/**
- * Safari page scroll is a UIScrollView: the distance at which it claims a
- * slow drag is where a press becomes a scroll, and the last moment a page
- * can still cancel the scroll.
- */
-const SAFARI_SCROLL_CLAIM =
-  'measured: Mobile Safari 26.2, iOS 26.2 simulator, slow HID drag on a scrollable page (1 pt steps): last cancelable touchmove at 10 px, pointercancel and the first uncancelable touchmove at 11 px, Oct 23 2026';
-
 export const UIKIT_GESTURES = {
   tap: {
     /**
      * How far each finger may travel from where it landed before a tap
      * fails, as a distance.
+     * @source measured: UIKit lab, iOS 26.2 simulator, ivar reads confirmed
+     *   with HID touches, Oct 23 2026: UITapGestureRecognizer
+     *   _allowableMovement 45; 44 pt taps, 46 pt fails, the same on the
+     *   diagonal
+     */
+    allowableMovement: {value: 45, unit: 'px'},
+    /**
+     * Longest interval between one tap lifting and the next landing.
+     * @source measured: UIKit lab, iOS 26.2 simulator, ivar reads confirmed
+     *   with HID touches, Oct 23 2026: _maximumIntervalBetweenSuccessiveTaps
+     *   0.35 s; 330 ms double-taps, 370 ms does not
+     */
+    maximumIntervalBetweenTaps: {value: 350, unit: 'ms'},
+    /**
+     * How far a later tap may land from the first one of the sequence.
+     * @source measured: UIKit lab, iOS 26.2 simulator, ivar reads confirmed
+     *   with HID touches, Oct 23 2026: _allowableSeparation is unbounded and
+     *   the 45 pt movement rule applies between taps; 44 pt double-taps, 46
+     *   does not
      */
-    allowableMovement: {
-      value: 45,
-      unit: 'px',
-      source: `${UIKIT_LAB}: UITapGestureRecognizer _allowableMovement 45; 44 pt taps, 46 pt fails, the same on the diagonal`,
-    },
-    /** Longest interval between one tap lifting and the next landing. */
-    maximumIntervalBetweenTaps: {
-      value: 350,
-      unit: 'ms',
-      source: `${UIKIT_LAB}: _maximumIntervalBetweenSuccessiveTaps 0.35 s; 330 ms double-taps, 370 ms does not`,
-    },
-    /** How far a later tap may land from the first one of the sequence. */
-    allowableSeparation: {
-      value: 45,
-      unit: 'px',
-      source: `${UIKIT_LAB}: _allowableSeparation is unbounded and the 45 pt movement rule applies between taps; 44 pt double-taps, 46 does not`,
-    },
-    /** Longest a finger may stay down and still tap. */
-    maximumTapDuration: {
-      value: 1500,
-      unit: 'ms',
-      source: `${UIKIT_LAB}: maximumTapDuration 1.5 s; a 1.4 s hold taps, 1.6 s does not`,
-    },
+    allowableSeparation: {value: 45, unit: 'px'},
+    /**
+     * Longest a finger may stay down and still tap.
+     * @source measured: UIKit lab, iOS 26.2 simulator, ivar reads confirmed
+     *   with HID touches, Oct 23 2026: maximumTapDuration 1.5 s; a 1.4 s hold
+     *   taps, 1.6 s does not
+     */
+    maximumTapDuration: {value: 1500, unit: 'ms'},
   },
   longPress: {
-    /** UILongPressGestureRecognizer.minimumPressDuration default. */
-    minimumPressDuration: {
-      value: 500,
-      unit: 'ms',
-      source: `apple-docs ${APPLE}/uilongpressgesturerecognizer/minimumpressduration; ${UIKIT_LAB}: _minimumPressDuration 0.5`,
-    },
-    /** UILongPressGestureRecognizer.allowableMovement default, a distance. */
-    allowableMovement: {
-      value: 10,
-      unit: 'px',
-      source: `apple-docs ${APPLE}/uilongpressgesturerecognizer/allowablemovement; ${UIKIT_LAB}: a (7, 7) drift begins, (7.2, 7.2) fails`,
-    },
+    /**
+     * UILongPressGestureRecognizer.minimumPressDuration default.
+     * @source apple-docs
+     *   https://developer.apple.com/documentation/uikit/uilongpressgesturerecognizer/minimumpressduration
+     * @source measured: UIKit lab, iOS 26.2 simulator, ivar reads confirmed
+     *   with HID touches, Oct 23 2026: _minimumPressDuration 0.5
+     */
+    minimumPressDuration: {value: 500, unit: 'ms'},
+    /**
+     * UILongPressGestureRecognizer.allowableMovement default, a distance.
+     * @source apple-docs
+     *   https://developer.apple.com/documentation/uikit/uilongpressgesturerecognizer/allowablemovement
+     * @source measured: UIKit lab, iOS 26.2 simulator, ivar reads confirmed
+     *   with HID touches, Oct 23 2026: a (7, 7) drift begins, (7.2, 7.2) fails
+     */
+    allowableMovement: {value: 10, unit: 'px'},
   },
   pan: {
     /**
@@ -146,123 +111,130 @@ export const UIKIT_GESTURES = {
      * part of it. Kept below the distance at which WebKit claims a drag for
      * scrolling, so a pan that must cancel the native scroll still sees
      * cancelable `touchmove`s.
+     * @source measured: UIKit lab, iOS 26.2 simulator, ivar reads confirmed
+     *   with HID touches, Oct 23 2026: UIPanGestureRecognizer _hysteresis 10; x
+     *   and y began at 10.0, a diagonal at (10.67, 10.67); translation(in:) is
+     *   0 at .began
      */
-    hysteresis: {
-      value: 10,
-      unit: 'px',
-      source: `${UIKIT_LAB}: UIPanGestureRecognizer _hysteresis 10; x and y began at 10.0, a diagonal at (10.67, 10.67); translation(in:) is 0 at .began`,
-    },
+    hysteresis: {value: 10, unit: 'px'},
   },
   swipe: {
-    /** Travel along the swipe direction before a swipe is recognized. */
-    minimumDistance: {
-      value: 50,
-      unit: 'px',
-      source: `${UIKIT_LAB}: UISwipeGestureRecognizer minimum primary movement 50; recognized during the motion; 40 pt does not`,
-    },
-    /** Longest a swipe may take before it fails. */
-    maximumDuration: {
-      value: 500,
-      unit: 'ms',
-      source: `${UIKIT_LAB}: UISwipeGestureRecognizer maximum duration 0.5 s`,
-    },
-    /** Travel across the swipe direction that fails it. */
-    maximumSecondaryMovement: {
-      value: 50,
-      unit: 'px',
-      source: `${UIKIT_LAB}: UISwipeGestureRecognizer maximum secondary movement 50`,
-    },
+    /**
+     * Travel along the swipe direction before a swipe is recognized.
+     * @source measured: UIKit lab, iOS 26.2 simulator, ivar reads confirmed
+     *   with HID touches, Oct 23 2026: UISwipeGestureRecognizer minimum primary
+     *   movement 50; recognized during the motion; 40 pt does not
+     */
+    minimumDistance: {value: 50, unit: 'px'},
+    /**
+     * Longest a swipe may take before it fails.
+     * @source measured: UIKit lab, iOS 26.2 simulator, ivar reads confirmed
+     *   with HID touches, Oct 23 2026: UISwipeGestureRecognizer maximum
+     *   duration 0.5 s
+     */
+    maximumDuration: {value: 500, unit: 'ms'},
+    /**
+     * Travel across the swipe direction that fails it.
+     * @source measured: UIKit lab, iOS 26.2 simulator, ivar reads confirmed
+     *   with HID touches, Oct 23 2026: UISwipeGestureRecognizer maximum
+     *   secondary movement 50
+     */
+    maximumSecondaryMovement: {value: 50, unit: 'px'},
     /**
      * How the minimum movement relaxes over time. Read, not modelled: a
      * 120 pt swipe over 0.8 s was recognized at 303 ms, below 50 pt of travel.
+     * @source measured: UIKit lab, iOS 26.2 simulator, ivar reads confirmed
+     *   with HID touches, Oct 23 2026: UISwipeGestureRecognizer
+     *   rateOfMinimumMovementDecay 0.06 (not modelled)
      */
-    minimumMovementDecay: {
-      value: 0.06,
-      unit: 'ratio',
-      source: `${UIKIT_LAB}: UISwipeGestureRecognizer rateOfMinimumMovementDecay 0.06 (not modelled)`,
-    },
+    minimumMovementDecay: {value: 0.06, unit: 'ratio'},
   },
   pinch: {
     /**
      * Change of the distance between two fingers before a pinch begins. The
      * scale is then measured against the starting span moved by this much,
      * so it does not jump.
+     * @source measured: UIKit lab, iOS 26.2 simulator, ivar reads confirmed
+     *   with HID touches, Oct 23 2026: UIPinchGestureRecognizer _hysteresis 8;
+     *   out from 120 began at 144 with scale 1.125 (= 144 / 128)
      */
-    hysteresis: {
-      value: 8,
-      unit: 'px',
-      source: `${UIKIT_LAB}: UIPinchGestureRecognizer _hysteresis 8; out from 120 began at 144 with scale 1.125 (= 144 / 128)`,
-    },
+    hysteresis: {value: 8, unit: 'px'},
   },
   rotation: {
-    /** Rotation of the two-finger vector before a rotation begins. */
-    hysteresis: {
-      value: (5 * Math.PI) / 180,
-      unit: 'rad',
-      guess:
-        'UIRotationGestureRecognizer has no scalar threshold among its ivars; 5 degrees.',
-      measure:
-        'M-G10: The simulator HID cannot rotate two fingers: a device run (or an XCUITest rotate) logging the angle at .began.',
-    },
+    /**
+     * Rotation of the two-finger vector before a rotation begins.
+     * @source GUESS — UIRotationGestureRecognizer has no scalar threshold among
+     *   its ivars; 5 degrees. The simulator HID cannot rotate two fingers: a
+     *   device run (or an XCUITest rotate) logging the angle at .began.
+     * @measure M-G10
+     */
+    hysteresis: {value: (5 * Math.PI) / 180, unit: 'rad'},
   },
   screenEdgePan: {
-    /** Width of the band at the screen edge a touch must land in. */
-    edgeRegion: {
-      value: 40.2,
-      unit: 'px',
-      source: `${UIKIT_LAB}: UIScreenEdgePanGestureRecognizer _edgeRegionSize 40.2 on a 402 pt wide screen (10 % of it); edge pans cannot begin from simulator HID`,
-    },
-    /** Travel before an edge pan begins. */
-    hysteresis: {
-      value: 15,
-      unit: 'px',
-      source: `${UIKIT_LAB}: the screen-edge pan hysteresis ivar 15`,
-    },
+    /**
+     * Width of the band at the screen edge a touch must land in.
+     * @source measured: UIKit lab, iOS 26.2 simulator, ivar reads confirmed
+     *   with HID touches, Oct 23 2026: UIScreenEdgePanGestureRecognizer
+     *   _edgeRegionSize 40.2 on a 402 pt wide screen (10 % of it); edge pans
+     *   cannot begin from simulator HID
+     */
+    edgeRegion: {value: 40.2, unit: 'px'},
+    /**
+     * Travel before an edge pan begins.
+     * @source measured: UIKit lab, iOS 26.2 simulator, ivar reads confirmed
+     *   with HID touches, Oct 23 2026: the screen-edge pan hysteresis ivar 15
+     */
+    hysteresis: {value: 15, unit: 'px'},
   },
   control: {
     /**
      * How far outside its bounds a UIControl keeps a press inside: a finger
      * dragged out is still "inside" until it passes this margin.
+     * @source measured: UIKit lab, iOS 26.2 simulator, ivar reads confirmed
+     *   with HID touches, Oct 23 2026: UIButton (.system) stays inside up to 70
+     *   pt out, touchDragExit at 71, touchDragEnter at 69 coming back;
+     *   touchUpInside up to 70, touchUpOutside from 71
      */
-    trackingExpansion: {
-      value: 70,
-      unit: 'px',
-      source: `${UIKIT_LAB}: UIButton (.system) stays inside up to 70 pt out, touchDragExit at 71, touchDragEnter at 69 coming back; touchUpInside up to 70, touchUpOutside from 71`,
-    },
+    trackingExpansion: {value: 70, unit: 'px'},
   },
   press: {
-    /** UIScrollView.delaysContentTouches: a touch in a scroller highlights after this. */
-    contentTouchDelay: {
-      value: scroll.delaysContentTouchesMs,
-      unit: 'ms',
-      source: PRESS_MEASUREMENT,
-    },
-    /** A tap shorter than the delay shows the highlight at the lift for this long. */
-    quickTapFlash: {
-      value: timing.press.flashMs,
-      unit: 'ms',
-      source: PRESS_MEASUREMENT,
-    },
-    /** Travel at which a press is a scroll, not a press. */
-    slop: {value: 10, unit: 'px', source: SAFARI_SCROLL_CLAIM},
-    /** A touch this soon after a finger-driven scroll moved is a brake, not a press. */
-    scrollBrake: {
-      value: timing.press.scrollBrakeMs,
-      unit: 'ms',
-      source: PRESS_MEASUREMENT,
-    },
+    /**
+     * UIScrollView.delaysContentTouches: a touch in a scroller highlights after
+     * this.
+     * @source measured: Settings and Contacts, iOS 26.2 simulator, HID touches
+     *   filmed at 60 fps (utils/pressGesture.ts), Oct 6 2026
+     */
+    contentTouchDelay: {value: scroll.delaysContentTouchesMs, unit: 'ms'},
+    /**
+     * A tap shorter than the delay shows the highlight at the lift for this
+     * long.
+     * @source measured: Settings and Contacts, iOS 26.2 simulator, HID touches
+     *   filmed at 60 fps (utils/pressGesture.ts), Oct 6 2026
+     */
+    quickTapFlash: {value: timing.press.flashMs, unit: 'ms'},
+    /**
+     * Travel at which a press is a scroll, not a press.
+     * @source measured: Mobile Safari 26.2, iOS 26.2 simulator, slow HID drag
+     *   on a scrollable page (1 pt steps): last cancelable touchmove at 10 px,
+     *   pointercancel and the first uncancelable touchmove at 11 px, Oct 23
+     *   2026
+     */
+    slop: {value: 10, unit: 'px'},
+    /**
+     * A touch this soon after a finger-driven scroll moved is a brake, not a
+     * press.
+     * @source measured: Settings and Contacts, iOS 26.2 simulator, HID touches
+     *   filmed at 60 fps (utils/pressGesture.ts), Oct 6 2026
+     */
+    scrollBrake: {value: timing.press.scrollBrakeMs, unit: 'ms'},
     /**
      * How long after a finger was down a scroll can still be that finger's
      * momentum (the brake only counts scrolls a finger drove).
+     * @source GUESS — The press model bound (utils/pressFeedback.ts): iOS
+     *   momentum runs for a second or two after the lift.
+     * @measure M-G19
      */
-    momentumMemory: {
-      value: 3000,
-      unit: 'ms',
-      guess:
-        'The press model bound (utils/pressFeedback.ts): iOS momentum runs for a second or two after the lift.',
-      measure:
-        'M-G19: Safari page, hardest HID flick: time from the lift to the last scroll event.',
-    },
+    momentumMemory: {value: 3000, unit: 'ms'},
   },
   scroll: {
     /**
@@ -270,15 +242,13 @@ export const UIKIT_GESTURES = {
      * an opt-in `scrollHandoff` pan takes the rest of the gesture. UIKit
      * itself never hands a drag over mid-gesture (a sheet over a scrolled
      * list leaves the whole drag to the list), so this is not a parity value.
+     * @source GUESS — The BottomSheet value (useSheetGestures.ts): enough to
+     *   ignore a fling coming to rest on the last pixel. None for parity: UIKit
+     *   decides sheet versus scroll when the drag begins (a sheet over a
+     *   scrolled list leaves the whole drag to the list).
+     * @measure M-G13
      */
-    contentEndHandoffSlop: {
-      value: 4,
-      unit: 'px',
-      guess:
-        'The BottomSheet value (useSheetGestures.ts): enough to ignore a fling coming to rest on the last pixel.',
-      measure:
-        'M-G13: None for parity: UIKit decides sheet versus scroll when the drag begins (a sheet over a scrolled list leaves the whole drag to the list).',
-    },
+    contentEndHandoffSlop: {value: 4, unit: 'px'},
   },
   velocity: {
     /**
@@ -288,51 +258,45 @@ export const UIKIT_GESTURES = {
      * consecutive events, the touch-down counting as the first). The lift
      * does not update it, and a finger at rest sends no events, so a release
      * after a pause reports the last moving value.
+     * @source measured: UIKit lab, iOS 26.2 simulator, ivar reads confirmed
+     *   with HID touches, Oct 23 2026: fitted to all 69 velocity(in:) values of
+     *   six HID streams (constant, accelerating, pauses before the lift) to 0.0
+     *   pt/s
+     */
+    currentWeight: {value: 0.2, unit: 'ratio'},
+    /**
+     * For the least-squares alternative: samples older than this are ignored.
+     * @source GUESS — Android's VelocityTracker and Flutter's fit the last 100
+     *   ms (least squares, degree 2); UIKit itself uses currentWeight. Not a
+     *   parity value: UIKit uses the two-event filter.
+     * @measure M-G14
      */
-    currentWeight: {
-      value: 0.2,
-      unit: 'ratio',
-      source: `${UIKIT_LAB}: fitted to all 69 velocity(in:) values of six HID streams (constant, accelerating, pauses before the lift) to 0.0 pt/s`,
-    },
-    /** For the least-squares alternative: samples older than this are ignored. */
-    horizon: {
-      value: 100,
-      unit: 'ms',
-      guess:
-        "Android's VelocityTracker and Flutter's fit the last 100 ms (least squares, degree 2); UIKit itself uses currentWeight.",
-      measure: 'M-G14: Not a parity value: UIKit uses the two-event filter.',
-    },
-    /** For the least-squares alternative: at most this many samples. */
-    maxSamples: {
-      value: 20,
-      unit: 'count',
-      guess: 'Android VelocityTracker and Flutter VelocityTracker keep 20.',
-      measure: 'M-G15: Not a parity value: UIKit uses the two-event filter.',
-    },
+    horizon: {value: 100, unit: 'ms'},
+    /**
+     * For the least-squares alternative: at most this many samples.
+     * @source GUESS — Android VelocityTracker and Flutter VelocityTracker keep
+     *   20. Not a parity value: UIKit uses the two-event filter.
+     * @measure M-G15
+     */
+    maxSamples: {value: 20, unit: 'count'},
     /**
      * For the least-squares alternative: a gap this long between samples
      * separates two motions.
+     * @source GUESS — Android VelocityTracker and Flutter VelocityTracker use
+     *   40 ms. Not a parity value: UIKit uses the two-event filter.
+     * @measure M-G16
      */
-    assumeStopped: {
-      value: 40,
-      unit: 'ms',
-      guess: 'Android VelocityTracker and Flutter VelocityTracker use 40 ms.',
-      measure: 'M-G16: Not a parity value: UIKit uses the two-event filter.',
-    },
+    assumeStopped: {value: 40, unit: 'ms'},
   },
   click: {
     /**
      * Longest the system waits for the browser's click after a touch it
      * swallows. iOS and Chromium deliver it right after `touchend`; this only
      * bounds a click that never comes.
+     * @source GUESS — A safety bound, not a UIKit number.
+     * @measure M-G17
      */
-    strayClickWindow: {
-      value: 1000,
-      unit: 'ms',
-      guess: 'A safety bound, not a UIKit number.',
-      measure:
-        'M-G17: Not a parity value: confirm in Safari and Chromium that the click follows touchend within one frame.',
-    },
+    strayClickWindow: {value: 1000, unit: 'ms'},
   },
 } as const satisfies Record<string, Record<string, GestureConstant>>;
 
@@ -361,31 +325,21 @@ export type HapticFeedbackKind = (typeof HAPTIC_FEEDBACK_KINDS)[number];
  * has nothing better (Android browsers). Not UIKit numbers: a vibration motor
  * cannot render a Taptic Engine waveform, so these only keep the relative
  * strengths in order.
+ * @source GUESS — No UIKit equivalent exists for a vibration motor;
+ *   durations only order the strengths.
+ * @measure M-G18
  */
 export const HAPTIC_VIBRATION_PATTERNS: Record<
   HapticFeedbackKind,
   GestureConstant<ReadonlyArray<number>>
 > = {
-  selection: vibration([5]),
-  impactLight: vibration([8]),
-  impactMedium: vibration([12]),
-  impactHeavy: vibration([18]),
-  impactSoft: vibration([10]),
-  impactRigid: vibration([6]),
-  notificationSuccess: vibration([8, 60, 12]),
-  notificationWarning: vibration([12, 80, 12]),
-  notificationError: vibration([12, 50, 12, 50, 18]),
+  selection: {value: [5], unit: 'ms'},
+  impactLight: {value: [8], unit: 'ms'},
+  impactMedium: {value: [12], unit: 'ms'},
+  impactHeavy: {value: [18], unit: 'ms'},
+  impactSoft: {value: [10], unit: 'ms'},
+  impactRigid: {value: [6], unit: 'ms'},
+  notificationSuccess: {value: [8, 60, 12], unit: 'ms'},
+  notificationWarning: {value: [12, 80, 12], unit: 'ms'},
+  notificationError: {value: [12, 50, 12, 50, 18], unit: 'ms'},
 };
-
-function vibration(
-  pattern: ReadonlyArray<number>,
-): GuessedGestureConstant<ReadonlyArray<number>> {
-  return {
-    value: pattern,
-    unit: 'ms',
-    guess:
-      'No UIKit equivalent exists for a vibration motor; durations only order the strengths.',
-    measure:
-      'M-G18: On an Android device, compare against the platform HapticFeedbackConstants for the same moments.',
-  };
-}
diff --git a/packages/core/src/motion/uikit/index.ts b/packages/core/src/motion/uikit/index.ts
index 2c454217cbb7f..eeb12390c27b4 100644
--- a/packages/core/src/motion/uikit/index.ts
+++ b/packages/core/src/motion/uikit/index.ts
@@ -20,13 +20,10 @@
 export {
   HAPTIC_FEEDBACK_KINDS,
   HAPTIC_VIBRATION_PATTERNS,
-  isGuess,
   UIKIT_GESTURES,
   type GestureConstant,
   type GestureConstantUnit,
-  type GuessedGestureConstant,
   type HapticFeedbackKind,
-  type SourcedGestureConstant,
 } from './gestures';
 export {navigation} from './navigation';
 export {scroll} from './scroll';
diff --git a/packages/core/src/motion/uikit/uikit.test.ts b/packages/core/src/motion/uikit/uikit.test.ts
index aabfcc1c910cd..28d913b22d305 100644
--- a/packages/core/src/motion/uikit/uikit.test.ts
+++ b/packages/core/src/motion/uikit/uikit.test.ts
@@ -5,9 +5,9 @@
  * @input vitest, the UIKit constants table and its source text
  * @output Enforces law P2 on the table: every leaf has a source of an
  *   allowed kind, every guess and every WebKit value names its measurement
- *   task, every task is listed in motion/MEASUREMENTS.md; checks the plain
- *   values (ratios, rates, curves) and that the press clocks agree with the
- *   touch press model they were measured for
+ *   task, every task is listed in motion/MEASUREMENTS.md, and no value ships
+ *   its source; checks the plain values (ratios, rates, curves) and that the
+ *   press clocks agree with the touch press model they were measured for
  * @position Testing; validates motion/uikit/*.ts without a browser
  */
 
@@ -21,13 +21,11 @@ import {
   PRESS_SCROLL_BRAKE_MS,
 } from '../../utils/pressGesture';
 import {scroll, springs, timing} from '.';
-import {HAPTIC_VIBRATION_PATTERNS, UIKIT_GESTURES} from './gestures';
 
-// Domain files whose entries are typed constants ({value, unit, source} or
-// {value, unit, guess, measure}); the same rules are checked on the values.
-const TYPED_TABLE_FILES = ['gestures.ts'];
-// Every other domain file carries its sources as JSDoc tags: a new one is
-// enforced the moment it lands.
+// Modules in this folder that hold no table of their own (none yet).
+const NON_TABLE_FILES: string[] = [];
+// Every domain file carries its sources as JSDoc tags: a new one is enforced
+// the moment it lands.
 const TABLE_FILES = fs
   .readdirSync(__dirname)
   .filter(
@@ -35,9 +33,12 @@ const TABLE_FILES = fs
       file.endsWith('.ts') &&
       file !== 'index.ts' &&
       !file.endsWith('.test.ts') &&
-      !TYPED_TABLE_FILES.includes(file),
+      !NON_TABLE_FILES.includes(file),
   )
   .sort();
+// Where a number comes from is documentation: a value that carried it would
+// ship it in every bundle that reads the value.
+const PROVENANCE_KEYS = new Set(['source', 'guess', 'measure']);
 /** A measurement names its subject, the iOS version it ran on and its date. */
 const MEASURED =
   /^@source measured: .*iOS \d.*(\b20\d\d-\d\d-\d\d\b|\b(Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec)[a-z]* \d{1,2},? 20\d\d\b)/;
@@ -119,6 +120,7 @@ describe('UIKit constants table: every value is sourced (law P2)', () => {
   it('finds the table entries', () => {
     expect(TABLE_FILES).toEqual(
       expect.arrayContaining([
+        'gestures.ts',
         'navigation.ts',
         'scroll.ts',
         'springs.ts',
@@ -130,94 +132,66 @@ describe('UIKit constants table: every value is sourced (law P2)', () => {
 
   for (const {file, key, doc} of leaves) {
     it(`${file} › ${key}`, () => {
-      // Collapse each tag's continuation lines onto it.
-      const tags = doc
-        .split(/\n(?=@)/)
-        .map(tag => tag.replace(/\s*\n\s*/g, ' ').trim())
-        .filter(tag => tag.startsWith('@'));
-      const sources = tags.filter(tag => tag.startsWith('@source '));
-      expect(sources.length, `${key} has no @source`).toBeGreaterThan(0);
-      for (const source of sources) {
-        expect(source, `${key}: unknown source kind`).toMatch(SOURCE_KINDS);
-        if (source.startsWith('@source measured: ')) {
-          expect(source, `${key}: a measurement needs its date`).toMatch(
-            MEASURED,
-          );
-        }
-      }
-      const needsMeasurement = sources.some(source =>
-        /^@source (GUESS|webkit)/.test(source),
-      );
-      const measures = tags.filter(tag => tag.startsWith('@measure '));
-      if (needsMeasurement) {
-        expect(
-          measures.length,
-          `${key} is unconfirmed but names no @measure task`,
-        ).toBeGreaterThan(0);
-      }
-      for (const measure of measures) {
-        const id = /^@measure (M-[A-Z0-9]+)$/.exec(measure)?.[1];
-        expect(id, `${key}: malformed ${measure}`).toBeDefined();
-        expect(MEASUREMENTS, `${id} is not in motion/MEASUREMENTS.md`).toMatch(
-          new RegExp(`^\\| ${id} +\\|`, 'm'),
-        );
-      }
+      expect(
+        PROVENANCE_KEYS.has(key),
+        `${file} › ${key}: a source belongs in the JSDoc, not in the value`,
+      ).toBe(false);
+      expectSourced(key, doc);
     });
   }
 });
 
-describe('UIKit constants table: typed domains follow the same rules', () => {
-  const constants: [
-    string,
-    {source?: string; guess?: string; measure?: string},
-  ][] = [
-    ...Object.entries(UIKIT_GESTURES).flatMap(([group, values]) =>
-      Object.entries(values).map(
-        ([name, constant]) =>
-          [`gestures.${group}.${name}`, constant] as [
-            string,
-            {source?: string; guess?: string; measure?: string},
-          ],
-      ),
-    ),
-    ...Object.entries(HAPTIC_VIBRATION_PATTERNS).map(
-      ([kind, constant]) =>
-        [`haptics.${kind}`, constant] as [
-          string,
-          {source?: string; guess?: string; measure?: string},
-        ],
-    ),
-  ];
-
-  it('finds the gesture constants', () => {
-    expect(constants.length).toBeGreaterThan(20);
+describe('UIKit constants table: blocks sourced as a whole', () => {
+  it('gestures.ts › HAPTIC_VIBRATION_PATTERNS', () => {
+    // Every pattern rests on the same guess, stated once above the object.
+    const text = fs.readFileSync(
+      path.resolve(__dirname, 'gestures.ts'),
+      'utf8',
+    );
+    const end = text.indexOf('export const HAPTIC_VIBRATION_PATTERNS');
+    expect(end).toBeGreaterThan(-1);
+    const block = text.slice(text.lastIndexOf('/**', end), end);
+    const doc = block
+      .split('\n')
+      .map(line => line.trim().replace(/^\/?\*+\/?\s?/, ''))
+      .join('\n');
+    expectSourced('HAPTIC_VIBRATION_PATTERNS', doc);
   });
+});
 
-  it.each(constants)('%s', (name, constant) => {
-    if (constant.source != null) {
-      expect(`@source ${constant.source}`, name).toMatch(SOURCE_KINDS);
-      if (constant.source.startsWith('measured: ')) {
-        expect(
-          `@source ${constant.source}`,
-          `${name}: a measurement needs its date`,
-        ).toMatch(MEASURED);
-      }
-    } else {
-      expect(
-        constant.guess,
-        `${name} has neither a source nor a guess`,
-      ).toBeTruthy();
-      const id = /^(M-[A-Z0-9]+): /.exec(constant.measure ?? '')?.[1];
-      expect(
-        id,
-        `${name}: measure must start with its MEASUREMENTS.md ID`,
-      ).toBeDefined();
-      expect(MEASUREMENTS, `${id} is not in motion/MEASUREMENTS.md`).toMatch(
-        new RegExp(`^\\| ${id} +\\|`, 'm'),
-      );
+/** The JSDoc rules every sourced value follows. */
+function expectSourced(key: string, doc: string) {
+  // Collapse each tag's continuation lines onto it.
+  const tags = doc
+    .split(/\n(?=@)/)
+    .map(tag => tag.replace(/\s*\n\s*/g, ' ').trim())
+    .filter(tag => tag.startsWith('@'));
+  const sources = tags.filter(tag => tag.startsWith('@source '));
+  expect(sources.length, `${key} has no @source`).toBeGreaterThan(0);
+  for (const source of sources) {
+    expect(source, `${key}: unknown source kind`).toMatch(SOURCE_KINDS);
+    if (source.startsWith('@source measured: ')) {
+      expect(source, `${key}: a measurement needs its date`).toMatch(MEASURED);
     }
-  });
-});
+  }
+  const needsMeasurement = sources.some(source =>
+    /^@source (GUESS|webkit)/.test(source),
+  );
+  const measures = tags.filter(tag => tag.startsWith('@measure '));
+  if (needsMeasurement) {
+    expect(
+      measures.length,
+      `${key} is unconfirmed but names no @measure task`,
+    ).toBeGreaterThan(0);
+  }
+  for (const measure of measures) {
+    const id = /^@measure (M-[A-Z0-9]+)$/.exec(measure)?.[1];
+    expect(id, `${key}: malformed ${measure}`).toBeDefined();
+    expect(MEASUREMENTS, `${id} is not in motion/MEASUREMENTS.md`).toMatch(
+      new RegExp(`^\\| ${id} +\\|`, 'm'),
+    );
+  }
+}
 
 describe('UIKit constants table: values', () => {
   it('UIKit\u2019s default spring has the documented damping ratio 4.56 before clamping', () => {

From 439dcc3dc5b94db4c0b832e7aa2df59475458142 Mon Sep 17 00:00:00 2001
From: Christopher Chedeau <vjeuxx@gmail.com>
Date: Sun, 25 Oct 2026 07:37:35 -0700
Subject: [PATCH 08/17] docs(spec): the draft AST-094 copy leaves this stack

The touch-presentations record is revised in its own pull request; this
stack keeps no copy of it.
---
 .../specs/AST-094-touch-presentations/spec.md | 397 ------------------
 1 file changed, 397 deletions(-)
 delete mode 100644 docs/specs/AST-094-touch-presentations/spec.md

diff --git a/docs/specs/AST-094-touch-presentations/spec.md b/docs/specs/AST-094-touch-presentations/spec.md
deleted file mode 100644
index 469509af16807..0000000000000
--- a/docs/specs/AST-094-touch-presentations/spec.md
+++ /dev/null
@@ -1,397 +0,0 @@
----
-schema_version: 4
-template_version: 2
-kind: system-spec
-id: spec:AST-094
-authority: draft
-archive_reason: null
-superseded_by: null
-approved_by: null
-approved_at: null
-phase: proposed
-owners: [vjeux]
-affects_architecture:
-  [
-    architecture:interaction-modality,
-    architecture:theme-tokens,
-    architecture:theme-authoring-contract,
-  ]
-affects_families: [family:buttons]
-affects_contributing: []
-affects_consumer_docs: []
----
-
-# Touch presentations feel native system spec
-
-## Intent
-
-A person using an Astryx product on a phone or tablet gets controls, sheets,
-menus, lists and navigation with native-feeling touch behavior: measured
-physics, timings and gesture thresholds instead of desktop motion stretched to
-a finger. This behavior is the default on every touch device, iOS and Android
-alike, with no opt-in, and its motion keeps running at display rate while the
-page's JavaScript is busy.
-
-The behavior comes from one measured table. Its values are measured from UIKit
-on a named reference release, UIKit on iOS 26.2 today; each number names the
-release it was taken from, moving the reference to a newer release re-measures
-the table, and differences on older releases are noted, not targeted. Android
-touch devices get the same behavior. How touch behavior differs between the
-platforms is being explored, and the table records a separate value only where
-a measured, sourced difference exists.
-
-## Non-goals
-
-- Pointer (desktop) presentations. Their timing and easing stay with the
-  theme's duration and easing tokens (`architecture:theme-tokens`).
-- Platform-matched look and feel: glass versus material surfaces, glyphs and
-  chrome. This record governs behavior only (OQ3).
-- WebKit embedded in a native app and the native Swift package. This record
-  governs the web components themselves.
-- Scroll physics. Scrolling stays native on every platform: on iOS an overflow
-  area or the page is a UIKit scroll view already.
-- Which components get a touch presentation, and when. Each component's own
-  record owns its presentation.
-- Equivalent internal implementations remain valid when they satisfy this
-  contract. The modules, files and algorithms of the motion and gesture
-  foundations belong to their architecture records.
-
-## Requirements
-
-### Physics
-
-- **FR1 — Measured values, the same everywhere.** Every spring, duration,
-  deceleration rate, rubber-band coefficient, gesture threshold and haptic
-  moment a touch presentation uses MUST default to the measured native value
-  for that use (FR2), and every component that plays the same motion or
-  gesture MUST use the same value; a theme MAY override a motion role (FR4).
-  No component uses a value of its own where a measured value exists. The same
-  values apply on every touch platform; a platform gets a value of its own only
-  where a measured, sourced difference exists (FR2).
-- **FR2 — Every value has a source.** Each measured value MUST name its source next to it: Apple's documentation, a WWDC session, WebKit's own
-  source where WebKit states it matches UIKit, or a measurement of UIKit on
-  the iOS simulator naming the app, the iOS version, the method and the date.
-  A value without one of these MUST be labelled a guess and name the
-  measurement that will replace it. A decompilation of UIKit MAY aim a
-  measurement and MUST NOT be a source.
-- **FR3 — Native physics.** Springs MUST follow UIKit's spring model
-  (response and damping ratio, mass, stiffness and damping, and the release
-  velocity), with overdamping clamped to critical damping wherever UIKit
-  clamps it. A momentum coast MUST decay like a UIKit scroll view (0.998 per
-  millisecond, 0.99 for the fast rate), a drag past an edge MUST resist with
-  UIKit's rubber band `(1 − 1 ÷ (x·c ÷ d + 1))·d` with the coefficient its use
-  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.
-- **FR4 — Touch motion is themeable.** Every spring, duration and curve a
-  touch presentation plays MUST be a theme motion role, named by its table path
-  (`sheet.present`, `timing.curves.easeInOut`). The role's default value is
-  its table value, and a theme MAY override it through `motion`, at its root or
-  in an adaptation rule. A component MUST read touch motion through these roles
-  and MUST NOT play a literal. A theme value MUST reach the motion at its
-  start, without changing how the motion runs (FR5, FR6). Gesture thresholds,
-  the velocity filter, the timings that decide who gets a touch (the
-  content-touch delay, the scroll brake, momentum memory) and haptics are not
-  motion: they stay internal constants from the table and are not public
-  concepts (`spec:AST-002` FR3). This adds touch motion roles to the motion
-  configuration of `architecture:theme-authoring-contract` and to
-  `architecture:theme-tokens` beside the existing duration and easing tokens, whose rules are unchanged. It
-  amends `spec:AST-057` for touch presentations: Item's swipe springs and
-  durations become theme motion roles instead of constants in source, and its
-  swipe travel is a transform the recognizer writes (FR9) instead of a custom
-  property on the root (its FR2). It departs from the draft `design:motion` DR3
-  wherever the native motion settles with an overshoot or stretches with a
-  rubber band.
-
-### Motion
-
-- **FR5 — Motion runs on the compositor.** Every release and every
-  programmatic animation of a touch presentation MUST animate `transform`, the
-  individual `translate`, `scale` and `rotate` properties, or `opacity`
-  (a dialog's `::backdrop` included) through Web Animations that the browser
-  runs off the main thread,
-  and MUST keep advancing at display rate through a main-thread block. It MUST
-  NOT animate layout properties, and MUST NOT step a frame from script when the
-  compositor can run the curve.
-- **FR6 — Motion is interruptible.** A finger MUST be able to catch any
-  animation mid-flight at the value on screen. That value and its velocity
-  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.
-- **FR7 — Exits animate as the native counterpart's do.** A touch
-  presentation MUST play the exit its UIKit counterpart plays, on every touch
-  platform. A rule that turns exits off by default does not apply to touch presentations;
-  FR8 governs their reduced-motion form. Each overlay's own record states its
-  exit, since members own their animation (`family:overlay-dismissal` AV6).
-- **FR8 — Reduce Motion cross-fades.** When the person asks for reduced
-  motion (`prefers-reduced-motion: reduce`), a touch presentation MUST reach
-  each change of state by a cross-fade: it animates `opacity` only, with no
-  travel, no scale and no spring, over at most 200 ms
-  (`design:reduced-motion`). An entrance lands in place and fades in, an exit
-  fades out in place, and any other move fades through. A drag still follows
-  the finger while it is down; after the lift the presentation reaches its
-  committed state by the cross-fade. A core component MUST NOT keep its motion
-  under reduced motion (no `reducedMotion: 'keep'`). The cross-fade's duration
-  is a theme motion role whose default is at most 200 ms (FR4); a theme MAY
-  shorten it. This is iOS's Reduce Motion with Prefer Cross-Fade Transitions
-  on. `design:reduced-motion` owns the rule for every presentation, including
-  the pointer presentations this record leaves out, which change state at
-  once.
-
-### Gestures
-
-- **FR9 — A finger is tracked off the render path.** A drag MUST follow the
-  finger with one visual update per move, with no component render per move
-  and no layout read after the gesture begins.
-  Native scrolling MUST be used only where the component is a scroll view
-  (lists, scroll areas, the page). A component MAY track a finger with native
-  scroll snapping only with simulator evidence that it tracks through a
-  main-thread block, ends on the native release curve, ends correctly when the
-  finger lifts during a block, and lets a finger catch the content mid-flight.
-- **FR10 — A second finger never breaks the first.** A second finger MUST NOT
-  cancel or redirect a drag a recognizer has claimed. Page pinch-zoom MUST stay
-  the browser's whenever no pinch recognizer claims the fingers and no drag is
-  claimed (WCAG 1.4.4). A menu's press-tracking slide keeps
-  `module:DropdownMenu/useMenuPress` FR4: a second pointer or `pointercancel`
-  ends its gesture with nothing acting, which keeps the page zoomable over an
-  open menu.
-- **FR11 — Two press profiles.** Press feedback MUST follow one of two native
-  profiles. A control (UIControl) highlights on touch-down outside scroll
-  views, keeps tracking within its expanded bounds (70 pt), turns its highlight
-  off and on as the finger drags out and back, and activates on a lift inside.
-  A cell (a table or collection cell) highlights 150 ms after touch-down inside
-  a scroll view, drops the highlight when the scroll wins, and activates on a
-  lift inside it with no scroll. A control inside a scroll view (an overflow
-  area or the scrolling page) takes the same 150 ms delay before its highlight
-  and then follows its control profile; the 150 ms delay applies only inside
-  scroll views. A control whose own record keeps its press through a drag
-  keeps it: Slider's overlay stays on the dragged thumb (`design:user-states`
-  DR4). On every touch platform this amends
-  `design:user-states` DR1 (the pressed overlay during a hold) and DR3 (the
-  selected SegmentedControl item's held surface) for touch presentations, the
-  press treatment of `family:buttons`, and `module:DropdownMenu/useMenuPress`
-  FR6, whose rule that menu rows show no pressed paint under a finger gives way
-  to the cell profile for menu rows.
-- **FR12 — Long press and rubber band are per use.** A long press MUST use the
-  thresholds its UIKit counterpart uses: 0.5 s and 10 pt for a plain long
-  press, the measured values for context menus and menus. A rubber band MUST
-  use the coefficient its use measures.
-- **FR13 — One rule for the touch presentation.** Whether a component shows
-  its touch presentation MUST follow the same conditions in every component.
-  Touch behaviors key on a coarse primary pointer and are on by default there; layout keys on the available size through the one compact definition the
-  theme exports, the same on every platform (`spec:AST-012` FR9,
-  `architecture:public-component-api` INV14), and a component never restates
-  its values or keeps a parallel breakpoint table. A presentation asks for
-  exactly the conditions its own record names: one that depends on both (a
-  sheet instead of a popover) asks for both, and the date and time sheet, whose
-  record asks for a coarse pointer with no size condition (`spec:AST-043` FR1),
-  asks for the pointer only. No component answers these conditions differently
-  from another. A server render and the hydrating render produce the pointer
-  presentation, and the touch presentation applies after hydration
-  (`spec:AST-013` FR9).
-- **FR14 — Nested scrolling follows the native rule.** Who gets a drag that
-  starts inside a scroll area MUST be decided once, when the drag begins. If
-  the area sits at its edge and the drag moves toward that edge, the
-  surrounding surface (a sheet) takes the drag; otherwise the area keeps it for
-  the whole gesture and rubber-bands at its edge. The drag MUST NOT change
-  hands midway, in either direction. This amends `spec:AST-025` FR14 (scroll
-  chaining by default) for touch presentations on every touch platform.
-- **FR15 — Recognizers arbitrate like UIKit's.** Recognizers that see the
-  same touch sequence MUST be exclusive by default: the first to recognize
-  wins and the others fail, unless both allow simultaneous recognition. A
-  recognizer that requires another to fail MUST hold its recognition until
-  that one fails, and MUST fail if that one recognizes. When several recognize
-  on the same event, the innermost element's recognizer MUST win.
-- **FR16 — Gestures keep the event clock.** Recognizers MUST read time from the
-  input events' timestamps. Durations (a long press, the interval between
-  taps) MUST be deadlines on that clock, so a blocked main thread delays the
-  report and never the moment reported.
-- **FR17 — Native readings.** A recognizer's thresholds and readings MUST
-  follow UIKit's and come from the table. A pan begins at 10 pt of travel on
-  either axis, and its translation excludes that travel; its velocity is
-  UIKit's estimate, 0.2 × the newest event's instantaneous velocity + 0.8 ×
-  the previous event's, never decayed through a rest.
-- **FR18 — `touch-action` leaves the browser the rest.** An element with touch
-  recognizers MUST get a `touch-action` that leaves the browser exactly what
-  its recognizers do not use: the other axis for an axis-limited pan or swipe,
-  `manipulation` for taps and long presses, everything for a one-way pan or a
-  pan that shares its axis with native scrolling. `pinch-zoom` MUST stay
-  unless a pinch or rotation recognizer is attached.
-- **FR19 — Claims are made in time and only by an owner.** Recognizers attach
-  only under a coarse pointer; on a fine pointer no recognizer attaches and no
-  touch listener is registered (FR24). A recognizer that begins MUST claim its
-  touches by cancelling `touchmove` through a non-passive listener on its
-  element. A `touchmove` of a touch no recognizer owns MUST NOT be cancelled. A
-  recognizer that competes with native scrolling MUST decide within 10 px of
-  travel, before the browser commits to the scroll. Only an element with a
-  recognizer that must claim mid-gesture registers that blocking listener; an
-  element whose recognizers decide only at the lift keeps its `touchmove`
-  listener passive, and its `touchend` listener stays cancelable so the
-  gesture can cancel the click (FR21). Known limit: a native scroll that starts on an element with a
-  blocking listener waits for a free main thread in iOS Safari and Chromium.
-  That is never worse than UIKit, whose scrolling stops on a busy main thread,
-  and a passive listener, or one added at `touchstart`, would hand diagonal
-  drags to the scroll.
-- **FR20 — The browser can take a touch.** `pointercancel`, an uncancelable
-  `touchmove`, or a native scroll under the touch MUST count as the browser
-  taking the touch: possible recognizers that share it fail, active ones are
-  cancelled, and the view's press is cancelled without a release.
-- **FR21 — Clicks follow the gesture.** When a gesture takes a touch, its
-  `touchend` MUST be cancelled, and no click or compatibility mouse event
-  reaches the page. A click held for a recognizer that may still recognize (a
-  tap that a double tap may claim) MUST be replayed on its target if that
-  recognizer fails. Activation with `detail === 0` (keyboard, assistive
-  technology) MUST always pass. A tap MUST NOT wait for the browser's
-  double-tap delay.
-- **FR22 — The platform keeps its edge gestures.** iOS Safari's back swipe
-  from the screen edge and Android's system back gesture MUST stay the
-  browser's and the system's; a touch presentation never overrides them.
-
-### Haptics
-
-- **FR23 — Haptics where the native counterpart plays them.** A touch
-  presentation MUST play a haptic only at the moments its UIKit counterpart
-  does. In iOS Safari the only haptic a page can produce is a light impact from
-  a real tap landing on a `<label>` or a switch checkbox; a moment UIKit marks
-  mid-drag or after the lift has no haptic there, and the component records
-  that gap. `navigator.vibrate` stands in where the platform offers it.
-
-### Resources and compatibility
-
-- **FR24 — Touch work costs nothing where it is not used.** Under a fine
-  pointer, and while a touch presentation is disabled, no touch-only listener,
-  observer or timer is active. The number of `document`- or `window`-level
-  touch listeners MUST NOT grow with the number of component instances, a
-  repeated row or cell adds no touch observer of its own, and nothing
-  touch-related remains after the last instance unmounts
-  (`architecture:react-component-runtime` INV5, INV7).
-- **FR25 — A moved default keeps a way back.** Turning a touch presentation on
-  by default MUST NOT silently change a released default. Where it moves one,
-  such as Selector's `adaptive` presentation policy, the caller's
-  `presentation` choice restores the released surface and input mode
-  (`architecture:public-component-api` INV16, `spec:AST-017/DEC-23`), and the
-  change ships as a documented behavior change that names that prop
-  (`spec:AST-017` FR3). Thresholds and tuning values inside a touch mode, such
-  as a long press's delay, stay internal (`spec:AST-002` FR3); no prop exposes
-  them. This replaces `component:Selector` DEC-1's width-and-pointer query with
-  the FR13 rule for `adaptive`.
-
-### Platform support
-
-- Supported engines: Astryx's supported browsers (`spec:AST-013`) with touch
-  input, on iOS and Android. UIKit on the reference release is the parity
-  reference, not a support floor; an older iOS Safari gets the same behavior
-  wherever its engine supports it, and Android Chrome gets the same behavior.
-  This amends `spec:AST-013` FR3 with an explicit Android Chrome support row
-  for touch presentations.
-- Unsupported behavior: haptics outside the moments FR23 allows. Where an
-  engine cannot run a curve on its compositor, the animation still plays and
-  still ends on its committed state.
-- Browser evidence: the busy-main-thread proof and no layout or paint during
-  the animation in Chromium with phone emulation, the busy-main-thread proof
-  in WebKit, curves sampled by seeking the running animations, iOS simulator
-  recordings for every claim about the reference values, and real-device
-  evidence for every claim about iOS Safari and Android Chrome behavior
-  (`spec:AST-013` FR10).
-
-## Current-state impact
-
-- `architecture:theme-tokens` and `architecture:theme-authoring-contract`:
-  touch motion roles join the motion configuration, with the table's values as
-  their defaults; INV3 and the duration and easing tokens are unchanged (FR4).
-- `architecture:interaction-modality`: the touch-presentation conditions
-  (FR13) sit beside the shared modality state; its invariants are unchanged.
-- `architecture:react-component-runtime`: FR24 states the caller-visible
-  outcome of INV5 and INV7 for touch work; both are unchanged.
-- `family:buttons`: the control and cell press profiles (FR11).
-- Each overlay member's own record (Dialog, BottomSheet, Drawer, Popover, the
-  menus): its touch exit and its Reduce Motion cross-fade (FR7, FR8), since
-  members own their animation (`family:overlay-dismissal` AV6).
-- `spec:AST-057`: Item's swipe springs and durations become theme motion roles,
-  and its swipe travel is a recognizer-written transform (FR4, FR9).
-- `design:reduced-motion` owns the reduced-motion rule FR8 applies.
-- `component:Selector` DEC-1: `adaptive` resolves through the FR13 touch rule
-  (a coarse pointer and the `spec:AST-012` FR9 compact definition) instead of
-  its own width-and-pointer query, with `presentation` as the way back (FR25).
-- `module:DropdownMenu/useMenuPress` FR6: menu rows take the cell press
-  profile under a finger (FR11).
-- `design:user-states` DR1 and DR3, `spec:AST-025` FR14 and `spec:AST-013` FR3
-  each carry an amendment for touch presentations (FR11, FR14, Platform
-  support); `design:motion` DR3 and DR5 (draft) are departed from or met as
-  FR4 and FR8 state.
-- Consumer docs: none until a component ships its touch presentation; each
-  component documents its own, including the `presentation` value that keeps
-  the released surface (FR25).
-
-## Verification
-
-| Contract   | Verification                                                                                                                   | Representative states                                                                                            | Mutation or failure expectation                                                                                                                |
-| ---------- | ------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
-| 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                                                                      |
-| FR4        | Theme unit tests and a browser test of a themed spring                                                                         | no theme (table defaults); a theme writing a spring, a duration and a curve, at its root and in an adaptation    | a role that ignores the theme, a literal played in place of a role, or a default that differs from the table 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 layout read, a jump, or a lost velocity fails                                                                                                |
-| 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, 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 blocked page pinch, fails                                                                             |
-| FR11, FR12 | Press and long-press tests on synthetic streams with explicit timestamps                                                       | inside and outside a scroll view; drag out and back; a menu row under a finger                                   | the wrong profile's timing fails                                                                                                               |
-| FR13       | Resolver unit tests and a server-render test                                                                                   | coarse and fine pointer; narrow, wide and short; server render; hydrating render                                 | a component that answers the conditions differently, or a touch presentation in the server or hydrating render, fails                          |
-| FR14       | Browser tests of a sheet over a scrolled list                                                                                  | scrolled and at its top                                                                                          | a midway handoff fails                                                                                                                         |
-| FR15–FR17  | Recognizer unit tests on synthetic streams with explicit timestamps                                                            | exclusive, simultaneous, require-to-fail, nested; a blocked main thread; a pan at 10 pt per axis                 | a wrong winner, a late deadline, or a translation that keeps the hysteresis fails                                                              |
-| FR18–FR22  | Browser tests with real touch input                                                                                            | per-axis pans beside native scrolling, page zoom, cancelled touches, clicks after taps, keyboard activation      | a ghost click, a blocked scroll or zoom, or a cancelled unowned touchmove fails                                                                |
-| FR23       | Haptics tests on the recorded moments                                                                                          | tap, drag, lift                                                                                                  | a haptic outside a native moment fails                                                                                                         |
-| FR24       | Resource tests counting listeners, observers and timers                                                                        | fine pointer; coarse pointer enabled and disabled; many instances; unmount                                       | a touch listener on a fine pointer, a per-instance `document` or `window` listener, or a leak fails                                            |
-| FR25       | Component tests of each moved default and its `presentation` value                                                             | default; `presentation` set to the released surface                                                              | a moved default that `presentation` does not restore, or a public threshold, fails                                                             |
-| all        | iOS simulator: the UIKit reference capture and the same gesture in Safari; real iOS Safari and Android Chrome devices          | per component                                                                                                    | an unmatched curve or timing is a parity defect                                                                                                |
-
-## Decision log
-
-### DEC-1 — Touch presentations feel native by default
-
-**Reference:** `spec:AST-094/DEC-1`
-**Decider:** pending owner approval
-
-Every touch device gets one native-feeling touch behavior by default, without
-an opt-in, because the people using it already know that behavior from every
-other app on their phone. The behavior's values are measured from UIKit, not
-remembered: a number enters the table only with a citable source, and Android
-touch devices get the same values until a measured, sourced difference is
-recorded.
-
-The table supplies the defaults and a theme may retune any motion role (FR4):
-a product can soften a spring without forking a component, and the measured
-values stay the ones it starts from. Platform-matched look and feel is not part
-of this decision (OQ3).
-
-### DEC-2 — Recognizers track fingers; the compositor plays releases
-
-**Reference:** `spec:AST-094/DEC-2`
-**Decider:** pending owner approval
-
-On iOS, native scroll snapping keeps tracking through a main-thread block,
-but a finger that lifts during the block finishes on WebKit's own snap
-physics rather than UIKit's curve, a finger cannot catch the content
-mid-spring, and full-viewport hit testing breaks surfaces that leave the page
-usable around them. Tracking therefore runs in the recognizers, and every
-release runs as a compositor animation of the measured curve (FR5, FR9).
-
-## Open questions
-
-- **OQ1 — Scroll view bounce-back curve.** What curve brings a scroll view
-  back from an overscroll? It is not a single spring from rest; the rubber
-  band itself is settled. (`checkable`)
-- **OQ2 — Rotation threshold.** What rotation starts a rotation gesture? No
-  stored threshold is readable, and the simulator cannot script two-finger
-  rotation. (`checkable`)
-- **OQ3 — Platform-matched look and feel.** Should touch presentations match
-  each platform's visual conventions (glass or material surfaces, glyphs,
-  chrome)? This waits on an exploration of how iOS and Android differ; until
-  then this record sets no platform-split visual rule. (`owner decision`)
-- **OQ4 — Module-level experimental subpaths.** May the shared motion and
-  gesture modules publish experimental API through their own module-level
-  `/experimental` subpaths? `spec:AST-017` FR21 gives an experimental subpath
-  only to an owning component, and `spec:AST-002` FR18 asks a public primitive
-  for a current owning record. Options: (a) amend `spec:AST-017` FR21 to admit
-  module-level experimental subpaths with a current owning record; (b) expose
-  the modules only through an owning component's `/experimental` subpath.
-  (`owner decision`)

From bbbcb60b8a15e353c79241d9e675d136a0ccc4b0 Mon Sep 17 00:00:00 2001
From: Christopher Chedeau <vjeuxx@gmail.com>
Date: Sun, 25 Oct 2026 12:11:21 -0700
Subject: [PATCH 09/17] refactor(core): the platform presets are named for
 their use

spec:AST-094 FR4 names every touch motion role for its use. The 13 platform
presets in the constants table keep their values and sources and take those
names: springs smooth, snappy, bouncy, interactive, uikitDefault,
uikitSpringDuration, swiftUIDefault and swiftUISpring become settle,
quickChange, emphasis, fingerTracking, viewChange, timedChange, stateChange
and directChange; timing.implicitAnimationMs becomes stateChangeMs; and the
curves caDefault, easeInOut, easeIn and easeOut become viewChange, move, exit
and entrance. The source names stay in each entry's JSDoc.

A test pins the use names, their values, and the absence of the source
names.
---
 packages/core/src/motion/MEASUREMENTS.md     |  2 +-
 packages/core/src/motion/uikit/springs.ts    | 18 ++++-----
 packages/core/src/motion/uikit/timing.ts     | 14 +++----
 packages/core/src/motion/uikit/uikit.test.ts | 39 +++++++++++++++++++-
 4 files changed, 55 insertions(+), 18 deletions(-)

diff --git a/packages/core/src/motion/MEASUREMENTS.md b/packages/core/src/motion/MEASUREMENTS.md
index 4f53b0c9f2060..16dceb1f2f7ae 100644
--- a/packages/core/src/motion/MEASUREMENTS.md
+++ b/packages/core/src/motion/MEASUREMENTS.md
@@ -52,7 +52,7 @@ installed); rows marked † also on iOS 18 for the pre-glass delta. iPhone
 | M-AS1 | Action sheet and menu      | Probe app: `.actionSheet`; a button with a `UIMenu` as its primary action; Files: the … menu                                                          | scale, alpha, position (t) on open and close; animation parameters                                                     | A, B   | `springs.actionSheet*`, `.menu*`                           |
 | M-CM1 | Context menu               | Files: long-press an item; dismiss by tapping outside                                                                                                 | preview scale(t) on lift, backdrop blur and dim (t), menu scale(t); the preview's return on dismiss                    | A, B   | `springs.contextMenu*`                                     |
 | M-K1  | UIKit legacy spring        | Probe app: `UIView.animate(withDuration:usingSpringWithDamping:initialSpringVelocity:)`, durations 0.3, 0.5, 1 × ratios 0.5, 0.8, 1 × velocities 0, 2 | the `CASpringAnimation` UIKit attaches: mass, stiffness, damping, initialVelocity, duration, settlingDuration          | A      | `springFromUIKitDampingDuration`                           |
-| M-K2  | Default spring, keyboard   | Probe app: an animator with `UISpringTimingParameters()`; focus and blur a text field                                                                 | both springs' parameters and allowsOverdamping; the keyboard notification's duration and curve                         | A, D   | `springs.uikitDefault`, `.keyboard`, `timing.keyboard*`    |
+| M-K2  | Default spring, keyboard   | Probe app: an animator with `UISpringTimingParameters()`; focus and blur a text field                                                                 | both springs' parameters and allowsOverdamping; the keyboard notification's duration and curve                         | A, D   | `springs.viewChange`, `.keyboard`, `timing.keyboard*`      |
 | M-CA1 | Settling duration          | none: `CASpringAnimation` mass 1, stiffness 100, damping 5, 10, 15, 20, 40 × initialVelocity 0, 5, −5 × allowsOverdamping on, off                     | `settlingDuration` of each (checks the critically damped and overdamped branches)                                      | D      | `settlingDuration`                                         |
 | M-T1  | Banner                     | A notification pushed to the simulator while an app is in the foreground                                                                              | banner y(t) in and out; time on screen                                                                                 | B      | `springs.banner`                                           |
 | M-RM1 | Reduced Motion             | Reduce Motion on, Prefer Cross-Fade Transitions on and off: Settings push and pop, an alert (sheets: M-SH13; controls: M-SW11, M-SL12, M-SG15)        | which transitions become cross-fades; alpha(t), duration and curve; what still moves                                   | B      | `timing.reducedMotionCrossFadeMs`, the animator's fallback |
diff --git a/packages/core/src/motion/uikit/springs.ts b/packages/core/src/motion/uikit/springs.ts
index 11f42993cf2a0..4af3e96472d8a 100644
--- a/packages/core/src/motion/uikit/springs.ts
+++ b/packages/core/src/motion/uikit/springs.ts
@@ -27,7 +27,7 @@
  */
 
 /**
- * UIKit's default spring (see `springs.uikitDefault` for its sources), shared
+ * UIKit's default spring (see `springs.viewChange` for its sources), shared
  * by the system transitions measured to run on it.
  */
 const UIKIT_DEFAULT_SPRING = {mass: 3, stiffness: 1000, damping: 500} as const;
@@ -66,37 +66,37 @@ export const springs = {
    * `.spring(duration:bounce:)` defaults.
    * @source apple-docs https://developer.apple.com/documentation/swiftui/spring/smooth(duration:extrabounce:)
    */
-  smooth: {duration: 0.5, bounce: 0},
+  settle: {duration: 0.5, bounce: 0},
   /**
    * SwiftUI `.snappy`: "small amount of bounce", base bounce 0.15.
    * @source apple-docs https://developer.apple.com/documentation/swiftui/spring/snappy(duration:extrabounce:)
    */
-  snappy: {duration: 0.5, bounce: 0.15},
+  quickChange: {duration: 0.5, bounce: 0.15},
   /**
    * SwiftUI `.bouncy`: base bounce 0.3.
    * @source apple-docs https://developer.apple.com/documentation/swiftui/spring/bouncy(duration:extrabounce:)
    */
-  bouncy: {duration: 0.5, bounce: 0.3},
+  emphasis: {duration: 0.5, bounce: 0.3},
   /**
    * SwiftUI `interactiveSpring()` defaults: for a value that tracks a finger.
    * @source apple-docs https://developer.apple.com/documentation/swiftui/animation/interactivespring(response:dampingfraction:blendduration:)
    */
-  interactive: {response: 0.15, dampingRatio: 0.86},
+  fingerTracking: {response: 0.15, dampingRatio: 0.86},
   /**
    * SwiftUI `Animation.default` since iOS 17 (what `withAnimation` uses).
    * @source apple-docs https://developer.apple.com/documentation/swiftui/animation/default
    */
-  swiftUIDefault: {response: 0.55, dampingRatio: 1},
+  stateChange: {response: 0.55, dampingRatio: 1},
   /**
    * SwiftUI `.spring(response:dampingFraction:blendDuration:)` defaults.
    * @source apple-docs https://developer.apple.com/documentation/swiftui/animation/spring(response:dampingfraction:blendduration:)
    */
-  swiftUISpring: {response: 0.5, dampingRatio: 0.825},
+  directChange: {response: 0.5, dampingRatio: 0.825},
   /**
    * UIKit `UIView.animate(springDuration:bounce:…)` defaults (iOS 17).
    * @source apple-docs https://developer.apple.com/documentation/uikit/uiview/animate(springduration:bounce:initialspringvelocity:delay:options:animations:completion:)
    */
-  uikitSpringDuration: {duration: 0.5, bounce: 0},
+  timedChange: {duration: 0.5, bounce: 0},
   /**
    * UIKit's default spring, `UISpringTimingParameters()`: Apple documents
    * its damping ratio as 4.56, which is exactly 500 ÷ (2·√(3·1000)).
@@ -112,7 +112,7 @@ export const springs = {
    *   `UIView.animate` with curve 7 outside the keyboard is this spring with
    *   its duration forced to 0.5 s
    */
-  uikitDefault: UIKIT_DEFAULT_SPRING,
+  viewChange: UIKIT_DEFAULT_SPRING,
 
   // ---------------------------------------------------------------------
   // Navigation (UINavigationController)
diff --git a/packages/core/src/motion/uikit/timing.ts b/packages/core/src/motion/uikit/timing.ts
index 35aac388e600c..89f492a5c1f17 100644
--- a/packages/core/src/motion/uikit/timing.ts
+++ b/packages/core/src/motion/uikit/timing.ts
@@ -60,7 +60,7 @@ export const timing = {
     scrollBrakeMs: 150,
     /**
      * UIButton (filled configuration) release: the label cross-fade and the
-     * background color both run 0.25 s on `curves.easeInOut`.
+     * background color both run 0.25 s on `curves.move`.
      * @source measured: UIKit lab (injected host app), iOS 26.2 simulator,
      *   iPhone 17 Pro, CAAnimation read (CATransition fade and backgroundColor),
      *   Oct 23 2026
@@ -76,7 +76,7 @@ export const timing = {
      *   iPhone 17 Pro, CAMediaTimingFunction read from UIView.animate,
      *   Oct 23 2026
      */
-    caDefault: [0.25, 0.1, 0.25, 1],
+    viewChange: [0.25, 0.1, 0.25, 1],
     /**
      * `easeInEaseOut`; UIKit's default curve (`UIView.AnimationCurve
      * .easeInOut`, "the default curve for most animations").
@@ -85,7 +85,7 @@ export const timing = {
      *   iPhone 17 Pro, CAMediaTimingFunction read from UIView.animate,
      *   Oct 23 2026
      */
-    easeInOut: [0.42, 0, 0.58, 1],
+    move: [0.42, 0, 0.58, 1],
     /**
      * `easeIn`.
      * @source apple-docs https://developer.apple.com/documentation/quartzcore/camediatimingfunctionname/easein
@@ -93,7 +93,7 @@ export const timing = {
      *   iPhone 17 Pro, CAMediaTimingFunction read from UIView.animate,
      *   Oct 23 2026
      */
-    easeIn: [0.42, 0, 1, 1],
+    exit: [0.42, 0, 1, 1],
     /**
      * `easeOut`.
      * @source apple-docs https://developer.apple.com/documentation/quartzcore/camediatimingfunctionname/easeout
@@ -101,7 +101,7 @@ export const timing = {
      *   iPhone 17 Pro, CAMediaTimingFunction read from UIView.animate,
      *   Oct 23 2026
      */
-    easeOut: [0, 0, 0.58, 1],
+    entrance: [0, 0, 0.58, 1],
   },
   /**
    * `UINavigationController.hideShowBarDuration`, in ms.
@@ -126,10 +126,10 @@ export const timing = {
    * @source measured: UIKit lab (injected host app), iOS 26.2 simulator,
    *   iPhone 17 Pro, read, Oct 23 2026
    */
-  implicitAnimationMs: 250,
+  stateChangeMs: 250,
   /**
    * Reduce Motion with Prefer Cross-Fade Transitions: a navigation push or pop
-   * becomes a cross-fade of this length on `curves.easeInOut` (the new view
+   * becomes a cross-fade of this length on `curves.move` (the new view
    * fades in while the old one fades out, with no travel), in ms. Sheets,
    * full-screen modals and alerts fade on their own presentation spring
    * instead.
diff --git a/packages/core/src/motion/uikit/uikit.test.ts b/packages/core/src/motion/uikit/uikit.test.ts
index 28d913b22d305..4246c8e6ab212 100644
--- a/packages/core/src/motion/uikit/uikit.test.ts
+++ b/packages/core/src/motion/uikit/uikit.test.ts
@@ -194,8 +194,45 @@ function expectSourced(key: string, doc: string) {
 }
 
 describe('UIKit constants table: values', () => {
+  it('names each platform preset for its use, not its source', () => {
+    // spec AST-094 FR4: a role is named for its use; the source stays in the
+    // JSDoc (SwiftUI .smooth, UISpringTimingParameters(), Core Animation's
+    // default curve).
+    expect(springs).toMatchObject({
+      fingerTracking: {response: 0.15, dampingRatio: 0.86},
+      emphasis: {duration: 0.5, bounce: 0.3},
+      settle: {duration: 0.5, bounce: 0},
+      quickChange: {duration: 0.5, bounce: 0.15},
+      viewChange: {mass: 3, stiffness: 1000, damping: 500},
+      timedChange: {duration: 0.5, bounce: 0},
+      stateChange: {response: 0.55, dampingRatio: 1},
+      directChange: {response: 0.5, dampingRatio: 0.825},
+    });
+    expect(timing.stateChangeMs).toBe(250);
+    expect(timing.curves).toEqual({
+      viewChange: [0.25, 0.1, 0.25, 1],
+      move: [0.42, 0, 0.58, 1],
+      exit: [0.42, 0, 1, 1],
+      entrance: [0, 0, 0.58, 1],
+    });
+    const sourceNames = [
+      'smooth',
+      'snappy',
+      'bouncy',
+      'interactive',
+      'uikitDefault',
+      'uikitSpringDuration',
+      'swiftUIDefault',
+      'swiftUISpring',
+    ];
+    for (const name of sourceNames) {
+      expect(springs).not.toHaveProperty(name);
+    }
+    expect(timing).not.toHaveProperty('implicitAnimationMs');
+  });
+
   it('UIKit\u2019s default spring has the documented damping ratio 4.56 before clamping', () => {
-    const {mass, stiffness, damping} = springs.uikitDefault;
+    const {mass, stiffness, damping} = springs.viewChange;
     expect(damping / (2 * Math.sqrt(stiffness * mass))).toBeCloseTo(4.56, 2);
   });
 

From 03f66c39685cf80efbed7752bb80cbfa42374f12 Mon Sep 17 00:00:00 2001
From: Cindy Zhang <cindyxz@meta.com>
Date: Sun, 25 Oct 2026 13:54:29 -0700
Subject: [PATCH 10/17] fix(core): the UIKit table keeps only what a touch
 presentation plays, and its press clocks import alone

- gestures.ts imports the press clocks by name (DELAYS_CONTENT_TOUCHES_MS,
  press), so reading one threshold no longer bundles the scroll and timing
  tables (component-style-authoring INV6).
- Drops the least-squares velocity rows (AST-100 FR2: one release filter) and
  scroll.contentEndHandoffSlop (AST-094 FR14), with their measurement tasks.
- Marks timing.reducedMotionCrossFadeMs and springs.menuReducedMotion as
  reference readings a touch presentation does not play (AST-094 FR8).
- uikit.test.ts checks every exported table group and rejects a provenance key
  in any value; the README and JSDoc stop citing code and rules that do not
  exist (decay.ts, toSpring, law P1/P2) and say components read touch motion
  from the theme's roles (AST-094 FR4).
---
 packages/core/src/motion/MEASUREMENTS.md     | 12 +--
 packages/core/src/motion/README.md           |  4 +-
 packages/core/src/motion/uikit/gestures.ts   | 52 ++---------
 packages/core/src/motion/uikit/index.ts      |  2 +-
 packages/core/src/motion/uikit/scroll.ts     |  9 +-
 packages/core/src/motion/uikit/springs.ts    |  8 +-
 packages/core/src/motion/uikit/timing.ts     | 95 +++++++++++---------
 packages/core/src/motion/uikit/uikit.test.ts | 36 +++++++-
 8 files changed, 112 insertions(+), 106 deletions(-)

diff --git a/packages/core/src/motion/MEASUREMENTS.md b/packages/core/src/motion/MEASUREMENTS.md
index 16dceb1f2f7ae..97d91ef34c3dd 100644
--- a/packages/core/src/motion/MEASUREMENTS.md
+++ b/packages/core/src/motion/MEASUREMENTS.md
@@ -91,10 +91,6 @@ of a page scroll, so many of these can be read off Safari itself.
 | M-G10 | `UIKIT_GESTURES.rotation.hysteresis`            | Maps: two touches rotating at 10 deg/s filmed at 60 fps; angle at the first frame the map turns. The simulator HID cannot rotate two fingers: a device run or an XCUITest rotate.                    | B, C   |
 | M-G11 | `UIKIT_GESTURES.screenEdgePan.edgeRegion`       | Settings > General (UINavigationController pop): HID drags inward starting at x = 5, 10 ... 40 pt; largest x that still pops.                                                                        | C      |
 | M-G12 | `UIKIT_GESTURES.control.trackingExpansion`      | Calculator (UIButton): HID press, drag away at 20 px/s filmed at 60 fps; distance from the frame at which the highlight turns off, then back on.                                                     | B, C   |
-| M-G13 | `UIKIT_GESTURES.scroll.contentEndHandoffSlop`   | A UIKit sheet (Maps place card at the medium detent) over a scrolled list: HID drag down from mid-list; finger travel between the list reaching its top and the sheet moving.                        | C      |
-| M-G14 | `UIKIT_GESTURES.velocity.horizon`               | Safari page scroll (UIScrollView): HID flings with known speed profiles; back out the release velocity from the coast distance (0.998/ms decay) and compare with this estimator on the same samples. | C      |
-| M-G15 | `UIKIT_GESTURES.velocity.maxSamples`            | Same comparison as horizon (M-G14).                                                                                                                                                                  | C      |
-| M-G16 | `UIKIT_GESTURES.velocity.assumeStopped`         | Safari page scroll: HID drag, pause P ms, lift; smallest P after which the page does not coast.                                                                                                      | C      |
 | M-G17 | `UIKIT_GESTURES.click.strayClickWindow`         | Not a parity value: confirm in Safari and Chromium that the click follows touchend within one frame.                                                                                                 | C      |
 | M-G18 | `HAPTIC_VIBRATION_PATTERNS` (every kind)        | On an Android device, compare against the platform HapticFeedbackConstants for the same moments.                                                                                                     | C      |
 | M-G19 | `UIKIT_GESTURES.press.momentumMemory`           | Safari page, hardest HID flick: time from the lift to the last scroll event.                                                                                                                         | C      |
@@ -109,10 +105,10 @@ from the starting span moved by its hysteresis; the swipe is recognized
 during the motion; `velocity(in:)` is 0.2 × the newest event's
 instantaneous velocity + 0.8 × the previous one's (it reproduces every value
 UIKit reported on six recorded streams), does not decay through a rest and
-ignores the lift, which settles M-G14 to M-G16 for parity (the least-squares
-values remain for the non-UIKit estimator); a sheet over a scrolled list
-leaves the whole drag to the list (no mid-gesture handoff), which leaves
-M-G13 without a parity value.
+ignores the lift: the table keeps that one filter and no least-squares
+estimator (`spec:AST-100` FR2); a sheet over a scrolled list leaves the whole
+drag to the list (no mid-gesture handoff), so the table carries no handoff
+slop (`spec:AST-094` FR14).
 
 ## Switch (UISwitch)
 
diff --git a/packages/core/src/motion/README.md b/packages/core/src/motion/README.md
index cf1202e4c0bd3..eee925f2d8f11 100644
--- a/packages/core/src/motion/README.md
+++ b/packages/core/src/motion/README.md
@@ -4,7 +4,9 @@ Internal motion foundation for the touch presentations of core components. It
 starts with the UIKit constants table: every spring, duration, deceleration
 rate, rubber-band constant, curve and gesture threshold a touch presentation
 uses, each with its source. Nothing here is exported from the package entry
-point; components import it by path.
+point. Core's motion and gesture modules read it by path; components take
+touch motion from the theme's motion roles (`spec:AST-094` FR4), not from
+this table.
 
 ## Files
 
diff --git a/packages/core/src/motion/uikit/gestures.ts b/packages/core/src/motion/uikit/gestures.ts
index 283f7c96f46a2..77243930dab67 100644
--- a/packages/core/src/motion/uikit/gestures.ts
+++ b/packages/core/src/motion/uikit/gestures.ts
@@ -18,8 +18,9 @@
  * that will confirm or replace them (MEASUREMENTS.md lists them all).
  * uikit.test.ts enforces both. Only the value and its unit ship: where a
  * number comes from stays in its JSDoc, out of the bundle. The press clocks
- * are the same entries as `scroll.delaysContentTouchesMs` and
- * `timing.press`, read from there. Safari on iOS runs UIKit's own
+ * are the same entries as `DELAYS_CONTENT_TOUCHES_MS` (`scroll.delaysContentTouchesMs`)
+ * and `press` (`timing.press`), imported by name so reading one threshold
+ * does not bundle the scroll and timing tables. Safari on iOS runs UIKit's own
  * recognizers for tap-to-click, long press, double tap and the start of a
  * page scroll, so many guesses can be settled by measuring Safari itself.
  *
@@ -37,8 +38,8 @@
  * SYNC: When modified, update packages/core/src/motion/uikit/gestures.test.ts.
  */
 
-import {scroll} from './scroll';
-import {timing} from './timing';
+import {DELAYS_CONTENT_TOUCHES_MS} from './scroll';
+import {press} from './timing';
 
 export type GestureConstantUnit =
   'px' | 'ms' | 'px/s' | 'rad' | 'ratio' | 'count';
@@ -204,14 +205,14 @@ export const UIKIT_GESTURES = {
      * @source measured: Settings and Contacts, iOS 26.2 simulator, HID touches
      *   filmed at 60 fps (utils/pressGesture.ts), Oct 6 2026
      */
-    contentTouchDelay: {value: scroll.delaysContentTouchesMs, unit: 'ms'},
+    contentTouchDelay: {value: DELAYS_CONTENT_TOUCHES_MS, unit: 'ms'},
     /**
      * A tap shorter than the delay shows the highlight at the lift for this
      * long.
      * @source measured: Settings and Contacts, iOS 26.2 simulator, HID touches
      *   filmed at 60 fps (utils/pressGesture.ts), Oct 6 2026
      */
-    quickTapFlash: {value: timing.press.flashMs, unit: 'ms'},
+    quickTapFlash: {value: press.flashMs, unit: 'ms'},
     /**
      * Travel at which a press is a scroll, not a press.
      * @source measured: Mobile Safari 26.2, iOS 26.2 simulator, slow HID drag
@@ -226,7 +227,7 @@ export const UIKIT_GESTURES = {
      * @source measured: Settings and Contacts, iOS 26.2 simulator, HID touches
      *   filmed at 60 fps (utils/pressGesture.ts), Oct 6 2026
      */
-    scrollBrake: {value: timing.press.scrollBrakeMs, unit: 'ms'},
+    scrollBrake: {value: press.scrollBrakeMs, unit: 'ms'},
     /**
      * How long after a finger was down a scroll can still be that finger's
      * momentum (the brake only counts scrolls a finger drove).
@@ -236,20 +237,6 @@ export const UIKIT_GESTURES = {
      */
     momentumMemory: {value: 3000, unit: 'ms'},
   },
-  scroll: {
-    /**
-     * Travel past the point where a native scroll ran out of content before
-     * an opt-in `scrollHandoff` pan takes the rest of the gesture. UIKit
-     * itself never hands a drag over mid-gesture (a sheet over a scrolled
-     * list leaves the whole drag to the list), so this is not a parity value.
-     * @source GUESS — The BottomSheet value (useSheetGestures.ts): enough to
-     *   ignore a fling coming to rest on the last pixel. None for parity: UIKit
-     *   decides sheet versus scroll when the drag begins (a sheet over a
-     *   scrolled list leaves the whole drag to the list).
-     * @measure M-G13
-     */
-    contentEndHandoffSlop: {value: 4, unit: 'px'},
-  },
   velocity: {
     /**
      * UIPanGestureRecognizer.velocity(in:) is this times the newest event's
@@ -264,29 +251,6 @@ export const UIKIT_GESTURES = {
      *   pt/s
      */
     currentWeight: {value: 0.2, unit: 'ratio'},
-    /**
-     * For the least-squares alternative: samples older than this are ignored.
-     * @source GUESS — Android's VelocityTracker and Flutter's fit the last 100
-     *   ms (least squares, degree 2); UIKit itself uses currentWeight. Not a
-     *   parity value: UIKit uses the two-event filter.
-     * @measure M-G14
-     */
-    horizon: {value: 100, unit: 'ms'},
-    /**
-     * For the least-squares alternative: at most this many samples.
-     * @source GUESS — Android VelocityTracker and Flutter VelocityTracker keep
-     *   20. Not a parity value: UIKit uses the two-event filter.
-     * @measure M-G15
-     */
-    maxSamples: {value: 20, unit: 'count'},
-    /**
-     * For the least-squares alternative: a gap this long between samples
-     * separates two motions.
-     * @source GUESS — Android VelocityTracker and Flutter VelocityTracker use
-     *   40 ms. Not a parity value: UIKit uses the two-event filter.
-     * @measure M-G16
-     */
-    assumeStopped: {value: 40, unit: 'ms'},
   },
   click: {
     /**
diff --git a/packages/core/src/motion/uikit/index.ts b/packages/core/src/motion/uikit/index.ts
index eeb12390c27b4..7f107844497f5 100644
--- a/packages/core/src/motion/uikit/index.ts
+++ b/packages/core/src/motion/uikit/index.ts
@@ -8,7 +8,7 @@
  * @position Entry of the UIKit constants table (motion/uikit). Internal to
  *   core: not exported from the package entry point
  *
- * THE table (law P1): every spring, duration, deceleration rate, rubber-band
+ * THE table (`spec:AST-094` FR1, FR2): every spring, duration, deceleration rate, rubber-band
  * constant, timing curve and gesture threshold a touch presentation uses
  * comes from here, with its source next to it. Components never carry their
  * own numbers.
diff --git a/packages/core/src/motion/uikit/scroll.ts b/packages/core/src/motion/uikit/scroll.ts
index dddd637fc2425..75cb365e16523 100644
--- a/packages/core/src/motion/uikit/scroll.ts
+++ b/packages/core/src/motion/uikit/scroll.ts
@@ -18,12 +18,17 @@
  * - /packages/core/src/motion/MEASUREMENTS.md (measurement tasks)
  */
 
+// The value of `scroll.delaysContentTouchesMs` (sourced there), its own
+// export so the press clocks read it without the rest of the table
+// (`architecture:component-style-authoring` INV6).
+export const DELAYS_CONTENT_TOUCHES_MS = 150;
+
 export const scroll = {
   decelerationRate: {
     /**
      * Normal deceleration: the release velocity is multiplied by this every
      * millisecond, as a continuous exponential (UIScrollView keeps ln r,
-     * −0.002002, and velocities in pt/ms; decay.ts). The scroll view's own
+     * −0.002002, and velocities in pt/ms). The scroll view's own
      * target for a release (`scrollViewWillEndDragging`) is
      * v · r ÷ (1 − r), within 1 %: WWDC18 803's projection function.
      * @source apple-docs https://developer.apple.com/documentation/uikit/uiscrollview/decelerationrate-swift.struct/normal
@@ -102,7 +107,7 @@ export const scroll = {
    *   real HID touches at 60 fps, recorded with the touch press model
    *   (PRESS_ONSET_MS in packages/core/src/utils/pressGesture.ts, 2026-10-06)
    */
-  delaysContentTouchesMs: 150,
+  delaysContentTouchesMs: DELAYS_CONTENT_TOUCHES_MS,
   /**
    * Scroll-to-top after a status-bar tap: not a spring. The offset
    * approaches the top as 1 − e^(−9.7 t) whatever the distance (done in about
diff --git a/packages/core/src/motion/uikit/springs.ts b/packages/core/src/motion/uikit/springs.ts
index 4af3e96472d8a..569d345c14d44 100644
--- a/packages/core/src/motion/uikit/springs.ts
+++ b/packages/core/src/motion/uikit/springs.ts
@@ -6,7 +6,7 @@
  * @output Exports `springs`, every UIKit / SwiftUI interaction spring the
  *   touch presentations use, each in the vocabulary of its source
  *   (SpringDescription: duration/bounce, response/dampingRatio or
- *   mass/stiffness/damping; `toSpring` normalizes)
+ *   mass/stiffness/damping; a reader normalizes them to one form)
  * @position The springs domain of the UIKit constants table (motion/uikit)
  *
  * Every leaf carries one or more `@source` (apple-docs | wwdc | webkit |
@@ -101,7 +101,7 @@ export const springs = {
    * UIKit's default spring, `UISpringTimingParameters()`: Apple documents
    * its damping ratio as 4.56, which is exactly 500 ÷ (2·√(3·1000)).
    * Overdamped on paper; Core Animation treats overdamping as critical
-   * unless told otherwise, which `toSpring` mirrors: in effect a critically
+   * unless told otherwise, so in effect it is a critically
    * damped spring with ω₀ = 18.26 rad/s (response 0.344 s) that settles in
    * 0.506 s. The keyboard does not use it (see `keyboard`).
    * @source apple-docs https://developer.apple.com/documentation/uikit/uispringtimingparameters/init() (damping ratio 4.56)
@@ -263,7 +263,9 @@ export const springs = {
   contextMenuDismiss: MENU_CLOSE_SPRING,
   /**
    * Menus opening and closing under Reduce Motion: critically damped,
-   * slower, no overshoot.
+   * slower, no overshoot. A reference reading only: under reduced motion a
+   * touch presentation follows `design:reduced-motion` DR2 and DR4, not this
+   * spring (`spec:AST-094` FR8).
    * @source measured: UIKit lab (injected host app), iOS 26.2 simulator,
    *   iPhone 17 Pro, `_animateUsingSpringWithDampingRatio:response:tracking:`
    *   hooked with Reduce Motion on (1.0, 0.4), Oct 23 2026
diff --git a/packages/core/src/motion/uikit/timing.ts b/packages/core/src/motion/uikit/timing.ts
index 89f492a5c1f17..c3c4c461d716e 100644
--- a/packages/core/src/motion/uikit/timing.ts
+++ b/packages/core/src/motion/uikit/timing.ts
@@ -24,49 +24,56 @@
  *   there and must agree; uikit/uikit.test.ts checks it)
  */
 
+/**
+ * The touch press clocks, its own export so a reader of one clock does not
+ * bundle the rest of the table (`architecture:component-style-authoring`
+ * INV6).
+ */
+export const press = {
+  /**
+   * Highlight onset once a press is believed: none, the highlight is
+   * painted in the frame the touch is accepted (after
+   * `scroll.delaysContentTouchesMs` inside a scroller).
+   * @source measured: Settings and Contacts, iOS 26.2, simulator driven
+   *   with real HID touches at 60 fps (touch press model,
+   *   packages/core/src/utils/pressGesture.ts, 2026-10-06)
+   */
+  highlightInMs: 0,
+  /**
+   * A tap released before the onset delay still flashes the highlight at
+   * full strength for this long before fading.
+   * @source measured: Settings and Contacts, iOS 26.2, simulator driven
+   *   with real HID touches at 60 fps (PRESS_FLASH_MS,
+   *   packages/core/src/utils/pressGesture.ts, 2026-10-06)
+   */
+  flashMs: 100,
+  /**
+   * Highlight fade after release: UIKit's deselect cross-fade.
+   * @source measured: Settings and Contacts, iOS 26.2, simulator driven
+   *   with real HID touches at 60 fps (PRESS_FADE_MS / pressConsts.releaseMs,
+   *   packages/core/src/utils/pressGesture.ts, 2026-10-06)
+   */
+  highlightOutMs: 200,
+  /**
+   * A touch on a scroller that moved this recently brakes it instead of
+   * pressing.
+   * @source measured: Settings and Contacts, iOS 26.2, simulator driven
+   *   with real HID touches at 60 fps (PRESS_SCROLL_BRAKE_MS,
+   *   packages/core/src/utils/pressGesture.ts, 2026-10-06)
+   */
+  scrollBrakeMs: 150,
+  /**
+   * UIButton (filled configuration) release: the label cross-fade and the
+   * background color both run 0.25 s on `curves.move`.
+   * @source measured: UIKit lab (injected host app), iOS 26.2 simulator,
+   *   iPhone 17 Pro, CAAnimation read (CATransition fade and backgroundColor),
+   *   Oct 23 2026
+   */
+  buttonReleaseMs: 250,
+} as const;
+
 export const timing = {
-  press: {
-    /**
-     * Highlight onset once a press is believed: none, the highlight is
-     * painted in the frame the touch is accepted (after
-     * `scroll.delaysContentTouchesMs` inside a scroller).
-     * @source measured: Settings and Contacts, iOS 26.2, simulator driven
-     *   with real HID touches at 60 fps (touch press model,
-     *   packages/core/src/utils/pressGesture.ts, 2026-10-06)
-     */
-    highlightInMs: 0,
-    /**
-     * A tap released before the onset delay still flashes the highlight at
-     * full strength for this long before fading.
-     * @source measured: Settings and Contacts, iOS 26.2, simulator driven
-     *   with real HID touches at 60 fps (PRESS_FLASH_MS,
-     *   packages/core/src/utils/pressGesture.ts, 2026-10-06)
-     */
-    flashMs: 100,
-    /**
-     * Highlight fade after release: UIKit's deselect cross-fade.
-     * @source measured: Settings and Contacts, iOS 26.2, simulator driven
-     *   with real HID touches at 60 fps (PRESS_FADE_MS / pressConsts.releaseMs,
-     *   packages/core/src/utils/pressGesture.ts, 2026-10-06)
-     */
-    highlightOutMs: 200,
-    /**
-     * A touch on a scroller that moved this recently brakes it instead of
-     * pressing.
-     * @source measured: Settings and Contacts, iOS 26.2, simulator driven
-     *   with real HID touches at 60 fps (PRESS_SCROLL_BRAKE_MS,
-     *   packages/core/src/utils/pressGesture.ts, 2026-10-06)
-     */
-    scrollBrakeMs: 150,
-    /**
-     * UIButton (filled configuration) release: the label cross-fade and the
-     * background color both run 0.25 s on `curves.move`.
-     * @source measured: UIKit lab (injected host app), iOS 26.2 simulator,
-     *   iPhone 17 Pro, CAAnimation read (CATransition fade and backgroundColor),
-     *   Oct 23 2026
-     */
-    buttonReleaseMs: 250,
-  },
+  press,
   curves: {
     /**
      * `CAMediaTimingFunctionName.default`: "the timing of … most system
@@ -132,7 +139,9 @@ export const timing = {
    * becomes a cross-fade of this length on `curves.move` (the new view
    * fades in while the old one fades out, with no travel), in ms. Sheets,
    * full-screen modals and alerts fade on their own presentation spring
-   * instead.
+   * instead. A reference reading only: under reduced motion a touch
+   * presentation follows `design:reduced-motion` DR2 and DR4, not this clock
+   * (`spec:AST-094` FR8).
    * @source apple-docs https://developer.apple.com/documentation/uikit/uiaccessibility/preferscrossfadetransitions
    *   (the setting)
    * @source measured: UIKit lab (injected host app), iOS 26.2 simulator,
diff --git a/packages/core/src/motion/uikit/uikit.test.ts b/packages/core/src/motion/uikit/uikit.test.ts
index 4246c8e6ab212..3ac1607fdd289 100644
--- a/packages/core/src/motion/uikit/uikit.test.ts
+++ b/packages/core/src/motion/uikit/uikit.test.ts
@@ -3,7 +3,7 @@
 /**
  * @file uikit.test.ts
  * @input vitest, the UIKit constants table and its source text
- * @output Enforces law P2 on the table: every leaf has a source of an
+ * @output Enforces `spec:AST-094` FR2 on the table: every leaf has a source of an
  *   allowed kind, every guess and every WebKit value names its measurement
  *   task, every task is listed in motion/MEASUREMENTS.md, and no value ships
  *   its source; checks the plain values (ratios, rates, curves) and that the
@@ -59,8 +59,16 @@ interface Leaf {
 function leavesOf(file: string): Leaf[] {
   const text = fs.readFileSync(path.resolve(__dirname, file), 'utf8');
   const lines = text.split('\n');
-  const start = lines.findIndex(line => /^export const \w+ = \{$/.test(line));
-  expect(start).toBeGreaterThan(-1);
+  // Every exported table object: a domain may export a group of its own
+  // (the press clocks) so a reader takes that group alone.
+  const starts = lines.flatMap((line, index) =>
+    /^export const \w+ = \{$/.test(line) ? [index] : [],
+  );
+  expect(starts.length).toBeGreaterThan(0);
+  return starts.flatMap(start => leavesFrom(file, lines, start));
+}
+
+function leavesFrom(file: string, lines: string[], start: number): Leaf[] {
   const leaves: Leaf[] = [];
   let doc = '';
   let inDoc = false;
@@ -95,6 +103,12 @@ function leavesOf(file: string): Leaf[] {
     if (trimmed.startsWith('} as const')) {
       break;
     }
+    // A group exported on its own and read back by name (`press,`): its
+    // leaves are checked where it is declared.
+    if (/^\w+,$/.test(trimmed)) {
+      doc = '';
+      continue;
+    }
     const leaf = /^(\w+): .+,$/.exec(trimmed);
     expect(
       leaf,
@@ -114,7 +128,7 @@ const MEASUREMENTS = fs.readFileSync(
   'utf8',
 );
 
-describe('UIKit constants table: every value is sourced (law P2)', () => {
+describe('UIKit constants table: every value is sourced (AST-094 FR2)', () => {
   const leaves = TABLE_FILES.flatMap(leavesOf);
 
   it('finds the table entries', () => {
@@ -141,6 +155,20 @@ describe('UIKit constants table: every value is sourced (law P2)', () => {
   }
 });
 
+describe('UIKit constants table: no source in a value', () => {
+  // Where a value comes from stays in its JSDoc, out of the bundle: no
+  // domain file writes a provenance key in code, at any depth.
+  for (const file of TABLE_FILES) {
+    it(file, () => {
+      const code = fs
+        .readFileSync(path.resolve(__dirname, file), 'utf8')
+        .replace(/\/\*[\s\S]*?\*\//g, '')
+        .replace(/\/\/.*$/gm, '');
+      expect(code).not.toMatch(/\b(source|guess|measure)\s*:/);
+    });
+  }
+});
+
 describe('UIKit constants table: blocks sourced as a whole', () => {
   it('gestures.ts › HAPTIC_VIBRATION_PATTERNS', () => {
     // Every pattern rests on the same guess, stated once above the object.

From eded944593d477b2aa0130a71f9b40191e7385fe Mon Sep 17 00:00:00 2001
From: Cindy Zhang <cindyxz@meta.com>
Date: Sun, 25 Oct 2026 14:13:18 -0700
Subject: [PATCH 11/17] style(core): MEASUREMENTS.md table widths after the
 dropped rows

---
 packages/core/src/motion/MEASUREMENTS.md | 34 ++++++++++++------------
 1 file changed, 17 insertions(+), 17 deletions(-)

diff --git a/packages/core/src/motion/MEASUREMENTS.md b/packages/core/src/motion/MEASUREMENTS.md
index 97d91ef34c3dd..51896a86f16dc 100644
--- a/packages/core/src/motion/MEASUREMENTS.md
+++ b/packages/core/src/motion/MEASUREMENTS.md
@@ -77,23 +77,23 @@ Thresholds the gesture system reads (`uikit/gestures.ts`). Safari on iOS runs
 UIKit's own recognizers for tap-to-click, long press, double tap and the start
 of a page scroll, so many of these can be read off Safari itself.
 
-| ID    | Feeds                                           | Capture                                                                                                                                                                                              | Method |
-| ----- | ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ |
-| M-G01 | `UIKIT_GESTURES.tap.allowableMovement`          | Safari (UIKit tap -> click): on a touch-action:none box, HID touch down, move N px over 100 ms, lift; binary-search the largest N that still fires click.                                            | C      |
-| M-G02 | `UIKIT_GESTURES.tap.maximumIntervalBetweenTaps` | Safari with user-scalable=no (UIKit double-tap -> dblclick): two HID taps T ms apart; binary-search the largest T that fires dblclick.                                                               | C      |
-| M-G03 | `UIKIT_GESTURES.tap.allowableSeparation`        | Safari with user-scalable=no: two HID taps 150 ms apart, the second D px away; binary-search the largest D that fires dblclick.                                                                      | C      |
-| M-G04 | `UIKIT_GESTURES.tap.maximumTapDuration`         | Safari: HID hold on a <button> for 0.5, 1, 2, 4 s then lift; record which fire click.                                                                                                                | C      |
-| M-G05 | `UIKIT_GESTURES.pan.hysteresis`                 | Settings list (UIScrollView pan): slow HID drag at 20 px/s filmed at 60 fps; touch travel at the first frame the content moves.                                                                      | B, C   |
-| M-G06 | `UIKIT_GESTURES.swipe.minimumDistance`          | Needs a UIKit app that uses UISwipeGestureRecognizer (no built-in candidate known): HID swipes of increasing length at 600 px/s.                                                                     | C      |
-| M-G07 | `UIKIT_GESTURES.swipe.maximumDuration`          | Same rig as minimumDistance: 120 px swipes at decreasing speed; longest duration that still recognizes.                                                                                              | C      |
-| M-G08 | `UIKIT_GESTURES.swipe.maximumSecondaryMovement` | Same rig: 120 px swipes at increasing angles; largest angle that still recognizes.                                                                                                                   | C      |
-| M-G09 | `UIKIT_GESTURES.pinch.hysteresis`               | Photos (zoomable image): two HID touches spreading at 20 px/s filmed at 60 fps; span change at the first frame the image scales.                                                                     | B, C   |
-| M-G10 | `UIKIT_GESTURES.rotation.hysteresis`            | Maps: two touches rotating at 10 deg/s filmed at 60 fps; angle at the first frame the map turns. The simulator HID cannot rotate two fingers: a device run or an XCUITest rotate.                    | B, C   |
-| M-G11 | `UIKIT_GESTURES.screenEdgePan.edgeRegion`       | Settings > General (UINavigationController pop): HID drags inward starting at x = 5, 10 ... 40 pt; largest x that still pops.                                                                        | C      |
-| M-G12 | `UIKIT_GESTURES.control.trackingExpansion`      | Calculator (UIButton): HID press, drag away at 20 px/s filmed at 60 fps; distance from the frame at which the highlight turns off, then back on.                                                     | B, C   |
-| M-G17 | `UIKIT_GESTURES.click.strayClickWindow`         | Not a parity value: confirm in Safari and Chromium that the click follows touchend within one frame.                                                                                                 | C      |
-| M-G18 | `HAPTIC_VIBRATION_PATTERNS` (every kind)        | On an Android device, compare against the platform HapticFeedbackConstants for the same moments.                                                                                                     | C      |
-| M-G19 | `UIKIT_GESTURES.press.momentumMemory`           | Safari page, hardest HID flick: time from the lift to the last scroll event.                                                                                                                         | C      |
+| ID    | Feeds                                           | Capture                                                                                                                                                                           | Method |
+| ----- | ----------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ |
+| M-G01 | `UIKIT_GESTURES.tap.allowableMovement`          | Safari (UIKit tap -> click): on a touch-action:none box, HID touch down, move N px over 100 ms, lift; binary-search the largest N that still fires click.                         | C      |
+| M-G02 | `UIKIT_GESTURES.tap.maximumIntervalBetweenTaps` | Safari with user-scalable=no (UIKit double-tap -> dblclick): two HID taps T ms apart; binary-search the largest T that fires dblclick.                                            | C      |
+| M-G03 | `UIKIT_GESTURES.tap.allowableSeparation`        | Safari with user-scalable=no: two HID taps 150 ms apart, the second D px away; binary-search the largest D that fires dblclick.                                                   | C      |
+| M-G04 | `UIKIT_GESTURES.tap.maximumTapDuration`         | Safari: HID hold on a <button> for 0.5, 1, 2, 4 s then lift; record which fire click.                                                                                             | C      |
+| M-G05 | `UIKIT_GESTURES.pan.hysteresis`                 | Settings list (UIScrollView pan): slow HID drag at 20 px/s filmed at 60 fps; touch travel at the first frame the content moves.                                                   | B, C   |
+| M-G06 | `UIKIT_GESTURES.swipe.minimumDistance`          | Needs a UIKit app that uses UISwipeGestureRecognizer (no built-in candidate known): HID swipes of increasing length at 600 px/s.                                                  | C      |
+| M-G07 | `UIKIT_GESTURES.swipe.maximumDuration`          | Same rig as minimumDistance: 120 px swipes at decreasing speed; longest duration that still recognizes.                                                                           | C      |
+| M-G08 | `UIKIT_GESTURES.swipe.maximumSecondaryMovement` | Same rig: 120 px swipes at increasing angles; largest angle that still recognizes.                                                                                                | C      |
+| M-G09 | `UIKIT_GESTURES.pinch.hysteresis`               | Photos (zoomable image): two HID touches spreading at 20 px/s filmed at 60 fps; span change at the first frame the image scales.                                                  | B, C   |
+| M-G10 | `UIKIT_GESTURES.rotation.hysteresis`            | Maps: two touches rotating at 10 deg/s filmed at 60 fps; angle at the first frame the map turns. The simulator HID cannot rotate two fingers: a device run or an XCUITest rotate. | B, C   |
+| M-G11 | `UIKIT_GESTURES.screenEdgePan.edgeRegion`       | Settings > General (UINavigationController pop): HID drags inward starting at x = 5, 10 ... 40 pt; largest x that still pops.                                                     | C      |
+| M-G12 | `UIKIT_GESTURES.control.trackingExpansion`      | Calculator (UIButton): HID press, drag away at 20 px/s filmed at 60 fps; distance from the frame at which the highlight turns off, then back on.                                  | B, C   |
+| M-G17 | `UIKIT_GESTURES.click.strayClickWindow`         | Not a parity value: confirm in Safari and Chromium that the click follows touchend within one frame.                                                                              | C      |
+| M-G18 | `HAPTIC_VIBRATION_PATTERNS` (every kind)        | On an Android device, compare against the platform HapticFeedbackConstants for the same moments.                                                                                  | C      |
+| M-G19 | `UIKIT_GESTURES.press.momentumMemory`           | Safari page, hardest HID flick: time from the lift to the last scroll event.                                                                                                      | C      |
 
 Done (UIKit lab, iOS 26.2 simulator, Oct 23 2026: the recognizers' ivars read
 in process, each confirmed with HID touches and the state log; values in

From f9d0900b0c9d4daf17fe14e5c2ddf7be5548f58e Mon Sep 17 00:00:00 2001
From: Christopher Chedeau <vjeuxx@gmail.com>
Date: Sun, 25 Oct 2026 14:19:55 -0700
Subject: [PATCH 12/17] feat(core): the press release's curve is a press value

press.highlightOutCurve is the highlight fade's curve after release, beside
highlightOutMs: cubic-bezier(0, 0, 0.2, 1), the release curve the touch
press model ships with. It is a guess until M-PR1 reads the timing function
Core Animation attaches to the deselect fade.
---
 packages/core/src/motion/MEASUREMENTS.md | 1 +
 packages/core/src/motion/uikit/timing.ts | 9 +++++++++
 2 files changed, 10 insertions(+)

diff --git a/packages/core/src/motion/MEASUREMENTS.md b/packages/core/src/motion/MEASUREMENTS.md
index 51896a86f16dc..181b4bf2238ea 100644
--- a/packages/core/src/motion/MEASUREMENTS.md
+++ b/packages/core/src/motion/MEASUREMENTS.md
@@ -56,6 +56,7 @@ installed); rows marked † also on iOS 18 for the pre-glass delta. iPhone
 | M-CA1 | Settling duration          | none: `CASpringAnimation` mass 1, stiffness 100, damping 5, 10, 15, 20, 40 × initialVelocity 0, 5, −5 × allowsOverdamping on, off                     | `settlingDuration` of each (checks the critically damped and overdamped branches)                                      | D      | `settlingDuration`                                         |
 | M-T1  | Banner                     | A notification pushed to the simulator while an app is in the foreground                                                                              | banner y(t) in and out; time on screen                                                                                 | B      | `springs.banner`                                           |
 | M-RM1 | Reduced Motion             | Reduce Motion on, Prefer Cross-Fade Transitions on and off: Settings push and pop, an alert (sheets: M-SH13; controls: M-SW11, M-SL12, M-SG15)        | which transitions become cross-fades; alpha(t), duration and curve; what still moves                                   | B      | `timing.reducedMotionCrossFadeMs`, the animator's fallback |
+| M-PR1 | Press release curve        | Settings and Contacts: a row tapped and released (the deselect cross-fade)                                                                            | the timing function Core Animation attaches to the deselect fade (control points)                                      | A      | `timing.press.highlightOutCurve`                           |
 | M-NB1 | Navigation bar hide / show | none                                                                                                                                                  | `UINavigationController.hideShowBarDuration`                                                                           | D      | `timing.navigationBarHideShowMs`                           |
 
 Done (UIKit lab, iOS 26.2 simulator, Oct 23 2026; values in `uikit/` tagged
diff --git a/packages/core/src/motion/uikit/timing.ts b/packages/core/src/motion/uikit/timing.ts
index c3c4c461d716e..8ce8079df076c 100644
--- a/packages/core/src/motion/uikit/timing.ts
+++ b/packages/core/src/motion/uikit/timing.ts
@@ -54,6 +54,15 @@ export const press = {
    *   packages/core/src/utils/pressGesture.ts, 2026-10-06)
    */
   highlightOutMs: 200,
+  /**
+   * The highlight fade's curve after release: an ease-out that spends the
+   * whole clock fading (strength about 0.2 at the midpoint).
+   * @source GUESS — the release curve the touch press model ships with
+   *   (`RELEASE_EASE`, packages/core/src/utils/interactionOverlay.stylex.ts),
+   *   chosen to read as UIKit's deselect cross-fade, not read from UIKit
+   * @measure M-PR1
+   */
+  highlightOutCurve: [0, 0, 0.2, 1],
   /**
    * A touch on a scroller that moved this recently brakes it instead of
    * pressing.

From 9db9315e40425659a87d760515c39cb144ffbf7d Mon Sep 17 00:00:00 2001
From: Christopher Chedeau <vjeuxx@gmail.com>
Date: Sun, 25 Oct 2026 14:29:26 -0700
Subject: [PATCH 13/17] docs(core): the velocity weight says a rested finger
 releases at 0

UIKit's two-event filter keeps the last moving value after a pause; the
note now says so as UIKit's behavior and that Astryx's release reads 0 once
the finger has rested (spec:AST-100 FR2), so the table no longer reads as
Astryx's rule.
---
 packages/core/src/motion/uikit/gestures.ts | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/packages/core/src/motion/uikit/gestures.ts b/packages/core/src/motion/uikit/gestures.ts
index 77243930dab67..b7c0718b4bfa3 100644
--- a/packages/core/src/motion/uikit/gestures.ts
+++ b/packages/core/src/motion/uikit/gestures.ts
@@ -243,8 +243,9 @@ export const UIKIT_GESTURES = {
      * instantaneous velocity plus the rest times the previous event's
      * (instantaneous velocity: position change over timestamp change between
      * consecutive events, the touch-down counting as the first). The lift
-     * does not update it, and a finger at rest sends no events, so a release
-     * after a pause reports the last moving value.
+     * does not update it, and a finger at rest sends no events, so UIKit
+     * reports the last moving value after a pause; Astryx's release reads 0
+     * once the finger has rested (`spec:AST-100` FR2).
      * @source measured: UIKit lab, iOS 26.2 simulator, ivar reads confirmed
      *   with HID touches, Oct 23 2026: fitted to all 69 velocity(in:) values of
      *   six HID streams (constant, accelerating, pauses before the lift) to 0.0

From 7e36bcd12c154bfb6f4d5471d1a58c08c2b11d1b Mon Sep 17 00:00:00 2001
From: Cindy Zhang <cindyxz@meta.com>
Date: Sun, 25 Oct 2026 14:58:05 -0700
Subject: [PATCH 14/17] fix(core): the table's notes point at what exists, and
 the press entries are pinned to the press model

- MEASUREMENTS.md: M-RM1 feeds a reference reading (AST-094 FR8), and M-K1
  and M-CA1 feed springs.ts rather than functions that do not exist yet.
- scroll.ts drops its references to rubberBand.ts, projection.ts and
  animator.decay.
- gestures.test.ts pins press.slop and press.momentumMemory to PRESS_SLOP_PX
  and PRESS_GESTURE_MEMORY_MS: one value per use.
---
 packages/core/src/motion/MEASUREMENTS.md      | 40 +++++++++----------
 .../core/src/motion/uikit/gestures.test.ts    | 11 +++++
 packages/core/src/motion/uikit/scroll.ts      |  6 +--
 3 files changed, 34 insertions(+), 23 deletions(-)

diff --git a/packages/core/src/motion/MEASUREMENTS.md b/packages/core/src/motion/MEASUREMENTS.md
index 51896a86f16dc..91dcb9339f087 100644
--- a/packages/core/src/motion/MEASUREMENTS.md
+++ b/packages/core/src/motion/MEASUREMENTS.md
@@ -37,26 +37,26 @@ installed); rows marked † also on iOS 18 for the pre-glass delta. iPhone
 
 ## Shared (foundation)
 
-| ID    | What                       | App and gesture                                                                                                                                       | Extract                                                                                                                | Method | Feeds                                                      |
-| ----- | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | ------ | ---------------------------------------------------------- |
-| M-S1  | Deceleration rates         | none                                                                                                                                                  | `UIScrollView.DecelerationRate.normal.rawValue`, `.fast.rawValue`                                                      | D      | `scroll.decelerationRate`                                  |
-| M-S2  | Momentum coast             | A long list (Contacts, or a probe table of 500 rows): flicks released at 1000, 2500, 5000 pt/s                                                        | contentOffset(t) from release to rest; decay constant; per-millisecond vs per-frame model; the speed at which it stops | C      | `decay.ts`                                                 |
-| M-S3  | Bounce-back spring         | Same list: drag 120 pt past the top, hold still, release; a flick into the top edge at 3000 pt/s                                                      | contentOffset(t) after release and after edge contact; spring response and damping ratio; velocity hand-off            | C      | `scroll.bounce`                                            |
-| M-S5  | Rubber band                | Same list on an 852 pt view: drag 100, 300, 600 pt past the top; a horizontal pager                                                                   | displayed overflow against finger overflow; confirm c = 0.55 and d = the view's size on the axis                       | C      | `scroll.rubberBand`                                        |
-| M-PG1 | Paging                     | Photos full-screen swipes; a probe paging scroll view                                                                                                 | page chosen per release position × velocity (thresholds; at most one page?); contentOffset(t) onto the page            | B, C   | `scroll.paging`                                            |
-| M-ST1 | Scroll to top              | Settings scrolled down 500, 2000, 8000 pt; tap the status bar                                                                                         | contentOffset(t); duration against distance; curve or spring fit                                                       | B, C   | `scroll.scrollToTopRate`                                   |
-| M-N1  | Navigation push            | Settings: tap General                                                                                                                                 | incoming leading edge x(t), outgoing x(t) (parallax fraction), dimming alpha(t); animation parameters                  | A, B   | `springs.navigationPush`                                   |
-| M-N2  | Navigation pop             | General: back button                                                                                                                                  | same as M-N1                                                                                                           | A, B   | `springs.navigationPop`                                    |
-| M-N3  | Interactive pop            | Settings ▸ General: edge swipe released at 40 % of the width at 600 pt/s (finishes) and at 30 % at rest (cancels)                                     | x(t) after release; spring parameters; the finish / cancel rule (position, velocity)                                   | A, B   | `springs.navigationInteractivePopFinish`                   |
-| M-A1  | Alert                      | Probe app: `UIAlertController(.alert)` presented and dismissed                                                                                        | scale(t), alpha(t) of the alert and the dimming view; animation parameters                                             | A      | `springs.alertPresent`, `.alertDismiss`                    |
-| M-AS1 | Action sheet and menu      | Probe app: `.actionSheet`; a button with a `UIMenu` as its primary action; Files: the … menu                                                          | scale, alpha, position (t) on open and close; animation parameters                                                     | A, B   | `springs.actionSheet*`, `.menu*`                           |
-| M-CM1 | Context menu               | Files: long-press an item; dismiss by tapping outside                                                                                                 | preview scale(t) on lift, backdrop blur and dim (t), menu scale(t); the preview's return on dismiss                    | A, B   | `springs.contextMenu*`                                     |
-| M-K1  | UIKit legacy spring        | Probe app: `UIView.animate(withDuration:usingSpringWithDamping:initialSpringVelocity:)`, durations 0.3, 0.5, 1 × ratios 0.5, 0.8, 1 × velocities 0, 2 | the `CASpringAnimation` UIKit attaches: mass, stiffness, damping, initialVelocity, duration, settlingDuration          | A      | `springFromUIKitDampingDuration`                           |
-| M-K2  | Default spring, keyboard   | Probe app: an animator with `UISpringTimingParameters()`; focus and blur a text field                                                                 | both springs' parameters and allowsOverdamping; the keyboard notification's duration and curve                         | A, D   | `springs.viewChange`, `.keyboard`, `timing.keyboard*`      |
-| M-CA1 | Settling duration          | none: `CASpringAnimation` mass 1, stiffness 100, damping 5, 10, 15, 20, 40 × initialVelocity 0, 5, −5 × allowsOverdamping on, off                     | `settlingDuration` of each (checks the critically damped and overdamped branches)                                      | D      | `settlingDuration`                                         |
-| M-T1  | Banner                     | A notification pushed to the simulator while an app is in the foreground                                                                              | banner y(t) in and out; time on screen                                                                                 | B      | `springs.banner`                                           |
-| M-RM1 | Reduced Motion             | Reduce Motion on, Prefer Cross-Fade Transitions on and off: Settings push and pop, an alert (sheets: M-SH13; controls: M-SW11, M-SL12, M-SG15)        | which transitions become cross-fades; alpha(t), duration and curve; what still moves                                   | B      | `timing.reducedMotionCrossFadeMs`, the animator's fallback |
-| M-NB1 | Navigation bar hide / show | none                                                                                                                                                  | `UINavigationController.hideShowBarDuration`                                                                           | D      | `timing.navigationBarHideShowMs`                           |
+| ID    | What                       | App and gesture                                                                                                                                       | Extract                                                                                                                | Method | Feeds                                                                                   |
+| ----- | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | ------ | --------------------------------------------------------------------------------------- |
+| M-S1  | Deceleration rates         | none                                                                                                                                                  | `UIScrollView.DecelerationRate.normal.rawValue`, `.fast.rawValue`                                                      | D      | `scroll.decelerationRate`                                                               |
+| M-S2  | Momentum coast             | A long list (Contacts, or a probe table of 500 rows): flicks released at 1000, 2500, 5000 pt/s                                                        | contentOffset(t) from release to rest; decay constant; per-millisecond vs per-frame model; the speed at which it stops | C      | `decay.ts`                                                                              |
+| M-S3  | Bounce-back spring         | Same list: drag 120 pt past the top, hold still, release; a flick into the top edge at 3000 pt/s                                                      | contentOffset(t) after release and after edge contact; spring response and damping ratio; velocity hand-off            | C      | `scroll.bounce`                                                                         |
+| M-S5  | Rubber band                | Same list on an 852 pt view: drag 100, 300, 600 pt past the top; a horizontal pager                                                                   | displayed overflow against finger overflow; confirm c = 0.55 and d = the view's size on the axis                       | C      | `scroll.rubberBand`                                                                     |
+| M-PG1 | Paging                     | Photos full-screen swipes; a probe paging scroll view                                                                                                 | page chosen per release position × velocity (thresholds; at most one page?); contentOffset(t) onto the page            | B, C   | `scroll.paging`                                                                         |
+| M-ST1 | Scroll to top              | Settings scrolled down 500, 2000, 8000 pt; tap the status bar                                                                                         | contentOffset(t); duration against distance; curve or spring fit                                                       | B, C   | `scroll.scrollToTopRate`                                                                |
+| M-N1  | Navigation push            | Settings: tap General                                                                                                                                 | incoming leading edge x(t), outgoing x(t) (parallax fraction), dimming alpha(t); animation parameters                  | A, B   | `springs.navigationPush`                                                                |
+| M-N2  | Navigation pop             | General: back button                                                                                                                                  | same as M-N1                                                                                                           | A, B   | `springs.navigationPop`                                                                 |
+| M-N3  | Interactive pop            | Settings ▸ General: edge swipe released at 40 % of the width at 600 pt/s (finishes) and at 30 % at rest (cancels)                                     | x(t) after release; spring parameters; the finish / cancel rule (position, velocity)                                   | A, B   | `springs.navigationInteractivePopFinish`                                                |
+| M-A1  | Alert                      | Probe app: `UIAlertController(.alert)` presented and dismissed                                                                                        | scale(t), alpha(t) of the alert and the dimming view; animation parameters                                             | A      | `springs.alertPresent`, `.alertDismiss`                                                 |
+| M-AS1 | Action sheet and menu      | Probe app: `.actionSheet`; a button with a `UIMenu` as its primary action; Files: the … menu                                                          | scale, alpha, position (t) on open and close; animation parameters                                                     | A, B   | `springs.actionSheet*`, `.menu*`                                                        |
+| M-CM1 | Context menu               | Files: long-press an item; dismiss by tapping outside                                                                                                 | preview scale(t) on lift, backdrop blur and dim (t), menu scale(t); the preview's return on dismiss                    | A, B   | `springs.contextMenu*`                                                                  |
+| M-K1  | UIKit legacy spring        | Probe app: `UIView.animate(withDuration:usingSpringWithDamping:initialSpringVelocity:)`, durations 0.3, 0.5, 1 × ratios 0.5, 0.8, 1 × velocities 0, 2 | the `CASpringAnimation` UIKit attaches: mass, stiffness, damping, initialVelocity, duration, settlingDuration          | A      | `springs.ts` (UIKit's legacy springs)                                                   |
+| M-K2  | Default spring, keyboard   | Probe app: an animator with `UISpringTimingParameters()`; focus and blur a text field                                                                 | both springs' parameters and allowsOverdamping; the keyboard notification's duration and curve                         | A, D   | `springs.viewChange`, `.keyboard`, `timing.keyboard*`                                   |
+| M-CA1 | Settling duration          | none: `CASpringAnimation` mass 1, stiffness 100, damping 5, 10, 15, 20, 40 × initialVelocity 0, 5, −5 × allowsOverdamping on, off                     | `settlingDuration` of each (checks the critically damped and overdamped branches)                                      | D      | `springs.ts` (settling)                                                                 |
+| M-T1  | Banner                     | A notification pushed to the simulator while an app is in the foreground                                                                              | banner y(t) in and out; time on screen                                                                                 | B      | `springs.banner`                                                                        |
+| M-RM1 | Reduced Motion             | Reduce Motion on, Prefer Cross-Fade Transitions on and off: Settings push and pop, an alert (sheets: M-SH13; controls: M-SW11, M-SL12, M-SG15)        | which transitions become cross-fades; alpha(t), duration and curve; what still moves                                   | B      | `timing.reducedMotionCrossFadeMs` (a reference reading, not played: `spec:AST-094` FR8) |
+| M-NB1 | Navigation bar hide / show | none                                                                                                                                                  | `UINavigationController.hideShowBarDuration`                                                                           | D      | `timing.navigationBarHideShowMs`                                                        |
 
 Done (UIKit lab, iOS 26.2 simulator, Oct 23 2026; values in `uikit/` tagged
 `measured:`): M-S1, M-NB1, M-K2, M-CA1 (underdamped grid matched to the last
diff --git a/packages/core/src/motion/uikit/gestures.test.ts b/packages/core/src/motion/uikit/gestures.test.ts
index cb64b5a3abae1..2b80409c211b8 100644
--- a/packages/core/src/motion/uikit/gestures.test.ts
+++ b/packages/core/src/motion/uikit/gestures.test.ts
@@ -10,6 +10,8 @@
  */
 
 import {describe, expect, it} from 'vitest';
+import {PRESS_GESTURE_MEMORY_MS} from '../../utils/pressFeedback';
+import {PRESS_SLOP_PX} from '../../utils/pressGesture';
 import {
   HAPTIC_FEEDBACK_KINDS,
   HAPTIC_VIBRATION_PATTERNS,
@@ -54,6 +56,15 @@ describe('UIKIT_GESTURES', () => {
     expect(UIKIT_GESTURES.velocity.currentWeight.value).toBe(0.2);
   });
 
+  it('holds the press entries to the press model, one value per use', () => {
+    // The touch press model (utils/pressGesture.ts, utils/pressFeedback.ts)
+    // and the table name the same clocks: they cannot drift apart.
+    expect(UIKIT_GESTURES.press.slop.value).toBe(PRESS_SLOP_PX);
+    expect(UIKIT_GESTURES.press.momentumMemory.value).toBe(
+      PRESS_GESTURE_MEMORY_MS,
+    );
+  });
+
   it('keeps the pan decision within the distance WebKit claims a scroll at', () => {
     // Mobile Safari's last cancelable touchmove of a slow drag is at 10 px; a
     // pan that must cancel the native scroll decides by then.
diff --git a/packages/core/src/motion/uikit/scroll.ts b/packages/core/src/motion/uikit/scroll.ts
index 75cb365e16523..833e93c996f92 100644
--- a/packages/core/src/motion/uikit/scroll.ts
+++ b/packages/core/src/motion/uikit/scroll.ts
@@ -56,7 +56,7 @@ export const scroll = {
   rubberBand: {
     /**
      * c in b = (1 − 1 ÷ (x·c ÷ d + 1))·d, d = the scroll view's size on the
-     * axis (rubberBand.ts), x = the finger's travel past the edge after the
+     * axis, x = the finger's travel past the edge after the
      * pan's 10 pt hysteresis.
      * @source measured: UIKit lab (injected host app), iOS 26.2 simulator,
      *   iPhone 17 Pro, UIScrollView offsets released 100 / 300 / 600 pt past
@@ -83,7 +83,7 @@ export const scroll = {
   paging: {
     /**
      * Deceleration rate a paging release is projected with to pick the next
-     * page (projection.ts `selectPage`).
+     * page.
      * @source GUESS — UIScrollView paging behaves like a fast scroll view;
      *   the rate it uses internally is not documented
      * @measure M-PG1
@@ -112,7 +112,7 @@ export const scroll = {
    * Scroll-to-top after a status-bar tap: not a spring. The offset
    * approaches the top as 1 − e^(−9.7 t) whatever the distance (done in about
    * 1.6 s for 500, 2000 or 8000 pt), which is a decay at this per-millisecond
-   * rate (e^(−0.0097)) whose rest point is the top: `animator.decay` with a
+   * rate (e^(−0.0097)) whose rest point is the top: a decay with a
    * starting velocity of 9.7 × the distance per second.
    * @source measured: UIKit lab (injected host app), iOS 26.2 simulator,
    *   iPhone 17 Pro, setContentOffset log after status-bar taps (starts 85–95

From 1f751c9bd49756a32382dd7c283b9e29671e9511 Mon Sep 17 00:00:00 2001
From: Cindy Zhang <cindyxz@meta.com>
Date: Sun, 25 Oct 2026 15:30:18 -0700
Subject: [PATCH 15/17] docs(core): M-S2 feeds scroll.decelerationRate, where
 the coast reading is recorded

---
 packages/core/src/motion/MEASUREMENTS.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/core/src/motion/MEASUREMENTS.md b/packages/core/src/motion/MEASUREMENTS.md
index 91dcb9339f087..bbdf52edabea3 100644
--- a/packages/core/src/motion/MEASUREMENTS.md
+++ b/packages/core/src/motion/MEASUREMENTS.md
@@ -40,7 +40,7 @@ installed); rows marked † also on iOS 18 for the pre-glass delta. iPhone
 | ID    | What                       | App and gesture                                                                                                                                       | Extract                                                                                                                | Method | Feeds                                                                                   |
 | ----- | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | ------ | --------------------------------------------------------------------------------------- |
 | M-S1  | Deceleration rates         | none                                                                                                                                                  | `UIScrollView.DecelerationRate.normal.rawValue`, `.fast.rawValue`                                                      | D      | `scroll.decelerationRate`                                                               |
-| M-S2  | Momentum coast             | A long list (Contacts, or a probe table of 500 rows): flicks released at 1000, 2500, 5000 pt/s                                                        | contentOffset(t) from release to rest; decay constant; per-millisecond vs per-frame model; the speed at which it stops | C      | `decay.ts`                                                                              |
+| 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`                                                                         |

From d3a2e41c619322cec0e8ffb83c9804e3fc057611 Mon Sep 17 00:00:00 2001
From: Cindy Zhang <cindyxz@meta.com>
Date: Sun, 25 Oct 2026 19:01:18 -0700
Subject: [PATCH 16/17] fix(core): toSpring's clamp, FR6 for the rubber band's
 inverse, the press curve pinned

From CodeBunny's review at 7234d44 (the split is waived):

- README: `toSpring` clamps overdamping to critical only for a mass,
  stiffness and damping description that does not allow it; the duration
  and response forms are not clamped.
- rubberBand.ts cites spec:AST-094 FR6 (a finger catches any animation
  mid-flight) for why the inverse matters.
- uikit/values.test.ts pins `press.highlightOutCurve` to the press model's
  RELEASE_EASE, so the table and the shipped curve cannot drift apart.
---
 packages/core/src/motion/README.md            |  5 +++--
 packages/core/src/motion/rubberBand.ts        |  7 ++++---
 packages/core/src/motion/uikit/values.test.ts | 19 ++++++++++++++++++-
 3 files changed, 25 insertions(+), 6 deletions(-)

diff --git a/packages/core/src/motion/README.md b/packages/core/src/motion/README.md
index 967970fa3f9ea..1de471ca791e4 100644
--- a/packages/core/src/motion/README.md
+++ b/packages/core/src/motion/README.md
@@ -34,8 +34,9 @@ under the same rules.
 the model behind SwiftUI's `Spring`, `CASpringAnimation` and
 `UISpringTimingParameters`. A spring description stays in its source's
 vocabulary (mass, stiffness and damping; duration and bounce; response and
-damping ratio) and `toSpring` normalizes it, clamping overdamping to critical
-as Core Animation does for every spring UIKit attaches. The tests hold it to an
+damping ratio) and `toSpring` normalizes it. A mass, stiffness and damping
+description that does not allow overdamping is clamped to critical, as Core
+Animation does for every spring UIKit attaches. The tests hold it to an
 independent fourth-order Runge-Kutta integration over a sweep of damping
 ratios, responses and release velocities; to a port of WebKit's own spring
 solver; to the WWDC23 "Animate with springs" conversion equations; and to
diff --git a/packages/core/src/motion/rubberBand.ts b/packages/core/src/motion/rubberBand.ts
index e7faa517a1173..bde101ec3cc5b 100644
--- a/packages/core/src/motion/rubberBand.ts
+++ b/packages/core/src/motion/rubberBand.ts
@@ -15,9 +15,10 @@
  * displayed overflow b approaches d but never reaches it, and its slope at
  * the edge is c: the first points of overflow move at 55 % of the finger.
  *
- * The inverse matters for M2 (grab anything mid-flight): a finger that lands
- * on content still bouncing back has to resume the drag from the finger
- * position that would produce the overflow on screen, or the content jumps.
+ * The inverse matters for spec:AST-094 FR6 (a finger catches any animation
+ * mid-flight): a finger that lands on content still bouncing back has to
+ * resume the drag from the finger position that would produce the overflow
+ * on screen, or the content jumps.
  *
  * SYNC: When modified, update:
  * - /packages/core/src/motion/rubberBand.test.ts
diff --git a/packages/core/src/motion/uikit/values.test.ts b/packages/core/src/motion/uikit/values.test.ts
index eea2c7f149fc4..e64e09d3c9de8 100644
--- a/packages/core/src/motion/uikit/values.test.ts
+++ b/packages/core/src/motion/uikit/values.test.ts
@@ -6,10 +6,13 @@
  * @output Checks the table's values through the math that plays them: every
  *   spring is valid and settles; the alert spring is UIKit's legacy
  *   derivation; a sheet's detent and presentation springs render alike;
- *   scroll-to-top and the rubber band reproduce what UIKit was measured doing
+ *   scroll-to-top and the rubber band reproduce what UIKit was measured doing;
+ *   the press release curve is the press model's
  * @position Testing; the source rules are uikit.test.ts
  */
 
+import {readFileSync} from 'node:fs';
+import {join} from 'node:path';
 import {describe, expect, it} from 'vitest';
 import {solveDecay} from '../decay';
 import {rubberBand} from '../rubberBand';
@@ -21,6 +24,7 @@ import {
   type SpringDescription,
 } from '../spring';
 import {scroll, springs} from '.';
+import {press} from './timing';
 
 describe('UIKit constants table through the motion math', () => {
   const springEntries: [string, SpringDescription][] = [
@@ -90,4 +94,17 @@ describe('UIKit constants table through the motion math', () => {
       ).toBeLessThan(0.5);
     }
   });
+
+  it('the press release curve is the press model\u2019s RELEASE_EASE', () => {
+    // The table records the curve the touch press model ships with; this pins
+    // the two together so neither drifts alone.
+    const source = readFileSync(
+      join(__dirname, '../../utils/interactionOverlay.stylex.ts'),
+      'utf8',
+    );
+    const match = /const RELEASE_EASE = 'cubic-bezier\(([^)]*)\)'/.exec(source);
+    expect(match?.[1].split(',').map(Number)).toEqual([
+      ...press.highlightOutCurve,
+    ]);
+  });
 });

From bbcb3f4b16aaa2010ff44c7b9cccb6530864d027 Mon Sep 17 00:00:00 2001
From: Christopher Chedeau <vjeuxx@gmail.com>
Date: Mon, 26 Oct 2026 21:38:38 -0700
Subject: [PATCH 17/17] docs(core): the swipe values' changeset counts the
 releases its tests check, and releaseVelocity names the spec:AST-100 release
 velocity it compares

---
 .changeset/uikit-swipe-actions-values.md       | 2 +-
 packages/core/src/motion/uikit/swipeActions.ts | 8 +++++---
 2 files changed, 6 insertions(+), 4 deletions(-)

diff --git a/.changeset/uikit-swipe-actions-values.md b/.changeset/uikit-swipe-actions-values.md
index 29fd82a3fd37b..11beecc12f918 100644
--- a/.changeset/uikit-swipe-actions-values.md
+++ b/.changeset/uikit-swipe-actions-values.md
@@ -2,6 +2,6 @@
 '@astryxdesign/core': patch
 ---
 
-[chore] Internal: the UIKit values of a swipe-action row (the swipe threshold, the spring the row follows the finger and settles with, the touch claim distance the web needs) and the release rule that picks closed, open or fire (a fast release goes the way it moves, a slow one by where it is, and only a release past the commit point fires), checked against 50 releases read from UIKit. Not exported from the package entry point.
+[chore] Internal: the UIKit values of a swipe-action row (the swipe threshold, the spring the row follows the finger and settles with, the touch claim distance the web needs) and the release rule that picks closed, open or fire (a fast release goes the way it moves, a slow one by where it is, and only a release past the commit point fires), checked against 44 of the 51 releases the UIKit lab read in its batch 10a and against its slow and moving-back releases of batch 38. Not exported from the package entry point.
 
 @vjeux
diff --git a/packages/core/src/motion/uikit/swipeActions.ts b/packages/core/src/motion/uikit/swipeActions.ts
index e05f05c62d0ce..a3d0636c43dbb 100644
--- a/packages/core/src/motion/uikit/swipeActions.ts
+++ b/packages/core/src/motion/uikit/swipeActions.ts
@@ -89,9 +89,11 @@ export const swipeActions = {
   /**
    * A release this fast goes the way it moves: it opens the row when it
    * opens and closes it when it closes, from anywhere short of the commit
-   * point. A flick therefore never fires an action. The speed is the swipe
-   * pan's velocity when the finger lifts, which UIKit never decays: a lift
-   * after a pause carries the last moving speed.
+   * point. A flick therefore never fires an action. The speed is the release
+   * velocity of a dragged surface (`spec:AST-100` FR2): the pan's velocity as
+   * the finger lifts, and 0 once the finger has stayed still before lifting,
+   * where UIKit's pan, which never decays, still reports its last moving
+   * speed. The measurements below are UIKit's pan velocities.
    * @source measured: UIKit lab (injected host app), iOS 26.2 simulator,
    *   iPhone 17 Pro, the swipe pan's velocity read at its end: released past
    *   half the open width while closing at 19.9, 21.2, 35.7 and 40.7 pt/s