Skip to content

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

TypeScript

chore(core): the UIKit constants table for touch presentations (#8053)

Christopher Chedeau4abbc5265296
diff --git a/.changeset/uikit-constants-table.md b/.changeset/uikit-constants-table.md
new file mode 100644
index 0000000000..01fd41a182
--- /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 0000000000..bbdf52edab
--- /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 | `scroll.decelerationRate` |
+| M-S3 | Bounce-back spring | Same list: drag 120 pt past the top, hold still, release; a flick into the top edge at 3000 pt/s | contentOffset(t) after release and after edge contact; spring response and damping ratio; velocity hand-off | C | `scroll.bounce` |
+| M-S5 | Rubber band | Same list on an 852 pt view: drag 100, 300, 600 pt past the top; a horizontal pager | displayed overflow against finger overflow; confirm c = 0.55 and d = the view's size on the axis | C | `scroll.rubberBand` |
+| M-PG1 | Paging | Photos full-screen swipes; a probe paging scroll view | page chosen per release position × velocity (thresholds; at most one page?); contentOffset(t) onto the page | B, C | `scroll.paging` |
+| M-ST1 | Scroll to top | Settings scrolled down 500, 2000, 8000 pt; tap the status bar | contentOffset(t); duration against distance; curve or spring fit | B, C | `scroll.scrollToTopRate` |
+| M-N1 | Navigation push | Settings: tap General | incoming leading edge x(t), outgoing x(t) (parallax fraction), dimming alpha(t); animation parameters | A, B | `springs.navigationPush` |
+| M-N2 | Navigation pop | General: back button | same as M-N1 | A, B | `springs.navigationPop` |
+| M-N3 | Interactive pop | Settings ▸ General: edge swipe released at 40 % of the width at 600 pt/s (finishes) and at 30 % at rest (cancels) | x(t) after release; spring parameters; the finish / cancel rule (position, velocity) | A, B | `springs.navigationInteractivePopFinish` |
+| M-A1 | Alert | Probe app: `UIAlertController(.alert)` presented and dismissed | scale(t), alpha(t) of the alert and the dimming view; animation parameters | A | `springs.alertPresent`, `.alertDismiss` |
+| M-AS1 | Action sheet and menu | Probe app: `.actionSheet`; a button with a `UIMenu` as its primary action; Files: the … menu | scale, alpha, position (t) on open and close; animation parameters | A, B | `springs.actionSheet*`, `.menu*` |
+| M-CM1 | Context menu | Files: long-press an item; dismiss by tapping outside | preview scale(t) on lift, backdrop blur and dim (t), menu scale(t); the preview's return on dismiss | A, B | `springs.contextMenu*` |
+| M-K1 | UIKit legacy spring | Probe app: `UIView.animate(withDuration:usingSpringWithDamping:initialSpringVelocity:)`, durations 0.3, 0.5, 1 × ratios 0.5, 0.8, 1 × velocities 0, 2 | the `CASpringAnimation` UIKit attaches: mass, stiffness, damping, initialVelocity, duration, settlingDuration | A | `springs.ts` (UIKit's legacy springs) |
+| M-K2 | Default spring, keyboard | Probe app: an animator with `UISpringTimingParameters()`; focus and blur a text field | both springs' parameters and allowsOverdamping; the keyboard notification's duration and curve | A, D | `springs.viewChange`, `.keyboard`, `timing.keyboard*` |
+| M-CA1 | Settling duration | none: `CASpringAnimation` mass 1, stiffness 100, damping 5, 10, 15, 20, 40 × initialVelocity 0, 5, −5 × allowsOverdamping on, off | `settlingDuration` of each (checks the critically damped and overdamped branches) | D | `springs.ts` (settling) |
+| M-T1 | Banner | A notification pushed to the simulator while an app is in the foreground | banner y(t) in and out; time on screen | B | `springs.banner` |
+| M-RM1 | Reduced Motion | Reduce Motion on, Prefer Cross-Fade Transitions on and off: Settings push and pop, an alert (sheets: M-SH13; controls: M-SW11, M-SL12, M-SG15) | which transitions become cross-fades; alpha(t), duration and curve; what still moves | B | `timing.reducedMotionCrossFadeMs` (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
+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-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: 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)
+
+Subject "switch S": the first switch in Settings ▸ Accessibility ▸ Display &
+Text Size (Bold Text row); a minimal host app holds a UISwitch on a plain view
+where a switch outside any scroll view is needed.
+
+Captured (iOS 26.2 simulator, Oct 23 2026), with their values landing in the
+switch's own table: M-SW02, M-SW03, M-SW04, M-SW05, M-SW06, M-SW09 (UISwitch
+makes no haptic call), M-SW11 (Reduce Motion: the lift stays, the stretch
+goes), M-SW16 (iOS 26.2). Until that table lands they stay open here, and
+`springs.switchThumbMove` and `switchThumbStretch` keep WebKit's values.
+Partly: M-SW07 (a single tap only). Still open: M-SW17, and M-SW11's On/Off
+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, which lands with the
+context menu; its springs are `springs.contextMenuLift` and
+`springs.contextMenuDismiss`.
+
+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.
+
+| 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 0000000000..eee925f2d8
--- /dev/null
+++ b/packages/core/src/motion/README.md
@@ -0,0 +1,81 @@
+# 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. 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
+
+| 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 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
+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.
+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
+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 0000000000..2b80409c21
--- /dev/null
+++ b/packages/core/src/motion/uikit/gestures.test.ts
@@ -0,0 +1,79 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file gestures.test.ts
+ * @input The gesture constants table
+ * @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
+ */
+
+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,
+ 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 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);
+ 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('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.
+ 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 0000000000..77243930da
--- /dev/null
+++ b/packages/core/src/motion/uikit/gestures.ts
@@ -0,0 +1,309 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file gestures.ts
+ * @input Nothing: plain data
+ * @output Exports UIKIT_GESTURES, the gesture thresholds gesture recognizers
+ * 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.
+ *
+ * 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 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 `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.
+ *
+ * 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.
+ */
+
+import {DELAYS_CONTENT_TOUCHES_MS} from './scroll';
+import {press} from './timing';
+
+export type GestureConstantUnit =
+ 'px' | 'ms' | 'px/s' | 'rad' | 'ratio' | 'count';
+
+/**
+ * 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;
+}
+
+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
+ */
+ 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.
+ * @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: {
+ /**
+ * 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.
+ * @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'},
+ },
+ swipe: {
+ /**
+ * 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'},
+ },
+ 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'},
+ },
+ rotation: {
+ /**
+ * 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.
+ * @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'},
+ },
+ press: {
+ /**
+ * 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: 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: 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: 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'},
+ },
+ 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.
+ * @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'},
+ },
+ 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'},
+ },
+} 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.
+ * @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: {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'},
+};
diff --git a/packages/core/src/motion/uikit/index.ts b/packages/core/src/motion/uikit/index.ts
new file mode 100644
index 0000000000..7f10784449
--- /dev/null
+++ b/packages/core/src/motion/uikit/index.ts
@@ -0,0 +1,31 @@
+// 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 (`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.
+ *
+ * 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,
+ UIKIT_GESTURES,
+ type GestureConstant,
+ type GestureConstantUnit,
+ type HapticFeedbackKind,
+} 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 0000000000..62dd928f4c
--- /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 0000000000..833e93c996
--- /dev/null
+++ b/packages/core/src/motion/uikit/scroll.ts
@@ -0,0 +1,122 @@
+// 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 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 MEASUREMENTS.md). uikit.test.ts
+ * enforces both.
+ *
+ * SYNC: When modified, update:
+ * - /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). 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, 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.
+ * @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: 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
+ * 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: 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
+ * 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 0000000000..569d345c14
--- /dev/null
+++ b/packages/core/src/motion/uikit/springs.ts
@@ -0,0 +1,329 @@
+// 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; 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 |
+ * 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.
+ *
+ * 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.
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/motion/MEASUREMENTS.md (measurement tasks)
+ */
+
+/**
+ * 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;
+
+/** 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:)
+ */
+ 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:)
+ */
+ 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:)
+ */
+ 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:)
+ */
+ 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
+ */
+ 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:)
+ */
+ 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:)
+ */
+ 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)).
+ * Overdamped on paper; Core Animation treats overdamping as critical
+ * 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)
+ * @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
+ */
+ viewChange: 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. 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
+ */
+ 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). 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},
+ /**
+ * 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). As
+ * for `switchThumbMove`, UIKit's own frames differ.
+ * @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 0000000000..c3c4c461d7
--- /dev/null
+++ b/packages/core/src/motion/uikit/timing.ts
@@ -0,0 +1,153 @@
+// 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 (MEASUREMENTS.md). uikit.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)
+ */
+
+/**
+ * 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,
+ 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
+ */
+ viewChange: [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
+ */
+ move: [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
+ */
+ exit: [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
+ */
+ entrance: [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
+ */
+ stateChangeMs: 250,
+ /**
+ * Reduce Motion with Prefer Cross-Fade Transitions: a navigation push or pop
+ * 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. 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,
+ * 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 0000000000..3ac1607fdd
--- /dev/null
+++ b/packages/core/src/motion/uikit/uikit.test.ts
@@ -0,0 +1,287 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file uikit.test.ts
+ * @input vitest, the UIKit constants table and its source text
+ * @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
+ * 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 '.';
+
+// 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(
+ file =>
+ file.endsWith('.ts') &&
+ file !== 'index.ts' &&
+ !file.endsWith('.test.ts') &&
+ !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)/;
+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');
+ // 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;
+ 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;
+ }
+ // 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,
+ `${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 (AST-094 FR2)', () => {
+ const leaves = TABLE_FILES.flatMap(leavesOf);
+
+ it('finds the table entries', () => {
+ expect(TABLE_FILES).toEqual(
+ expect.arrayContaining([
+ 'gestures.ts',
+ 'navigation.ts',
+ 'scroll.ts',
+ 'springs.ts',
+ 'timing.ts',
+ ]),
+ );
+ expect(leaves.length).toBeGreaterThan(50);
+ });
+
+ for (const {file, key, doc} of leaves) {
+ it(`${file} › ${key}`, () => {
+ 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: 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.
+ 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);
+ });
+});
+
+/** 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('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.viewChange;
+ 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);
+ }
+ });
+});