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.mdnew file mode 100644index 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.++@vjeuxdiff --git a/packages/core/src/motion/MEASUREMENTS.md b/packages/core/src/motion/MEASUREMENTS.mdnew file mode 100644index 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.mdnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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);+ }+ });+});