@astryxdesign/core 0.7.5-canary.fccd771 → 0.7.5

package/src/motion/MEASUREMENTS.md

@@ -0,0 +1,271 @@
+# 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` (played at 200 ms: `design:reduced-motion` DR2 caps it, DEC-1 of 2026-10-24, departing from the measured 0.5 s) |
+| M-PR1 | Press release curve        | Settings and Contacts: a row tapped and released (the deselect cross-fade)                                                                            | the timing function Core Animation attaches to the deselect fade (control points)                                      | A      | `timing.press.highlightOutCurve`                                                                                                                  |
+| M-NB1 | Navigation bar hide / show | none                                                                                                                                                  | `UINavigationController.hideShowBarDuration`                                                                           | D      | `timing.navigationBarHideShowMs`                                                                                                                  |
+
+Done (UIKit lab, iOS 26.2 simulator, Oct 23 2026; values in `uikit/` tagged
+`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-G14 | `UIKIT_GESTURES.velocity.scrollReleaseWeight`   | Safari page scroll (UIScrollView): HID flings with known speed profiles; back out the release velocity from the coast distance (0.998/ms decay) and compare with this blend on the same samples. | C      |
+| M-G16 | `UIKIT_GESTURES.velocity.stillness`             | Safari page scroll: HID drag, pause P ms, lift; smallest P after which the page does not coast.                                                                                                  | C      |
+| M-G17 | `UIKIT_GESTURES.click.strayClickWindow`         | Not a parity value: confirm in Safari and Chromium that the click follows touchend within one frame.                                                                                             | C      |
+| M-G18 | `HAPTIC_VIBRATION_PATTERNS` (every kind)        | On an Android device, compare against the platform HapticFeedbackConstants for the same moments.                                                                                                 | C      |
+| M-G19 | `UIKIT_GESTURES.press.momentumMemory`           | Safari page, hardest HID flick: time from the lift to the last scroll event.                                                                                                                     | C      |
+| M-G20 | `LongPressGestureRecognizer` taps phase         | Probe app: a UILongPressGestureRecognizer with numberOfTapsRequired 1: HID taps held 0.2, 0.5, 1, 2 s, then the press after gaps of 100 to 600 ms; record which recognize.                       | 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      |

package/src/motion/README.md

@@ -0,0 +1,218 @@
+# Motion
+
+Internal motion foundation for the touch presentations of core components: the
+UIKit constants table (every spring, duration, deceleration rate, rubber-band
+constant, curve and gesture threshold a touch presentation uses, each with its
+source), the spring, decay, rubber-band and projection math UIKit uses, and a
+compositor animator that plays it. Nothing here is exported from the package
+entry point. Core's motion and gesture modules read the table by path;
+components read touch motion through its internal motion roles (`roles.ts`),
+so each keeps its measured value; no shipped component reads the roles yet.
+
+## 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.                                                           |
+| `spring.ts`            | Closed-form damped spring, every Apple parameterization, settling duration, a spring chasing a moving target.              |
+| `decay.ts`             | UIScrollView's momentum coast.                                                                                             |
+| `coast.ts`             | A release's momentum curves for `animator.decay`: the coast, the edge spring, a release past an edge.                      |
+| `rubberBand.ts`        | UIScrollView's resistance past an edge, and its inverse.                                                                   |
+| `projection.ts`        | Release targets: the rest point nearest the projected coast.                                                               |
+| `resolveSnapPoint.ts`  | Release policy: the snap point a release lands on (flick, back-out cancel, step limit), on `selectSnapPoint`. Internal.    |
+| `selectPage.ts`        | Paging: at most one page per release, on `resolveSnapPoint`.                                                               |
+| `bezier.ts`            | Cubic-bézier timing functions (Core Animation's named curves).                                                             |
+| `animator.ts`          | Compositor animator: springs, coasts and any closed-form curve compiled to Web Animations, read back analytically.         |
+| `reducedMotionPlan.ts` | The animator's Reduce Motion planner: what one call becomes, a cross-fade whose travel lands while transparent or at once. |
+
+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.
+
+## Animator
+
+```
+import {createAnimator} from '../motion/animator';
+import {coast} from '../motion/coast';
+import {solveSpringTowardRamp, toSpring} from '../motion/spring';
+import {springs} from '../motion/uikit';
+
+const animator = createAnimator(sheet);
+
+// A drag writes one style per frame and never renders:
+animator.set({y: offset});
+
+// The finger lifts: spring to the detent with the release velocity (px/s).
+const handle = animator.animate({y: detent}, {spring: springs.sheetDetent, velocity: {y: 1200}});
+
+// A finger lands mid-flight: where is the sheet right now, how fast?
+const y = animator.get('y', event.timeStamp);
+const v = animator.getVelocity('y', event.timeStamp);
+animator.stop(['y']); // freezes at the value on screen
+
+// A throw on a scroll-like surface, with an edge (coast.ts builds the curves):
+animator.decay(coast(animator, {x: velocityX}, {bounds: {x: {min: -maxScroll, max: 0}}}));
+
+// Any closed-form curve, here a press that keeps deepening: the target
+// scale falls at 0.16/s and the platter follows it on a spring. Press
+// feedback has no fade of its own, so it is skipped under Reduce Motion.
+if (animator.reducedMotion() === 'off') {
+  const ramp = solveSpringTowardRamp(toSpring(springs.contextMenuLift), {
+    from: 1,
+    target: 1,
+    slope: -0.16,
+  });
+  animator.play({scale: {duration: 0.266, at: ramp.value, velocity: ramp.velocity}});
+}
+
+await handle.finished; // true if it ran to the end, false if interrupted
+```
+
+- Drives `x`, `y`, `rotate`, `scaleX`, `scaleY` (`scale` sets both) and
+  `opacity`, through the individual CSS properties `translate`, `rotate`,
+  `scale` and `opacity`. The element's `transform` stays the component's.
+- `get` / `getVelocity` evaluate the curves; the DOM is never read.
+- Promotion: every animation the animator creates, and every `set`, gives its
+  channels a compositing layer in the same task (inline `will-change`, merged
+  with the element's own), cleared 500 ms after the last motion. Mobile Safari
+  needs it to run a curve through a blocked main thread.
+- `atRest(properties)` resolves once none of them is moving, after the last
+  curve ends, whoever started it.
+- `rebase({y: -shift})` moves properties at once, as a layout shift does; a
+  property moving on a spring keeps its spring, velocity and target.
+- `play` bakes any curve given as value and velocity functions of time (a
+  spring chasing a moving target from `solveSpringTowardRamp`, a fitted UIKit
+  curve) exactly like a spring.
+- `animate` always starts from the presentation value with the presentation
+  velocity unless a velocity is handed in, so retargeting is continuous
+  (`handle.retarget(to)` keeps the call's spring).
+- A call from rest gets no start time, so the browser starts it when it
+  commits it, as Core Animation does: in Chromium a block before that frame
+  delays the motion instead of skipping into it (WebKit starts it at the
+  frame before the block). Everything the call starts shares that start
+  (`handle.started`); a retarget keeps an explicit one, and `{at}` puts
+  several animators on one clock.
+- Reduced Motion (`prefers-reduced-motion: reduce`, design:reduced-motion):
+  every `animate` and `play` is replaced and nothing moves, scales or
+  springs. On a coarse primary pointer, or for a call started by a touch
+  drag's release (`{touchRelease: true}`), it is an opacity-only cross-fade
+  of `timing.reducedMotionCrossFadeMs` (200 ms): an entrance from 0 lands and
+  fades in, an exit to 0 fades out then lands, an opacity change fades, any
+  other move dips (fade out, land, fade in). Travel lands with a plain style write while
+  the element is transparent, never as an animated transform. On any other
+  pointer it completes at once.
+  `{crossfadeAs: 'entrance'}` or `'exit'` gives a slide that changes no
+  opacity its direction. No option or theme value lengthens the fade or keeps
+  travel. For motion the animator does not drive, `reducedMotionFade()`
+  answers the same policy, and `reducedMotion.stylex.ts` holds its CSS
+  constants and the two media queries a StyleX transition spells.
+  A decay's momentum keeps its motion under Reduce Motion: momentum that
+  continues a throw is direct movement (DR2, DEC-2). A curve marked
+  `isTransition` (a coast's spring back from past an edge), like a spring a
+  component starts on release toward a target it picks, plays through the
+  Reduce Motion policy: a cross-fade on a coarse pointer or after a touch
+  release (`decay(curves, {touchRelease: true})`), at once elsewhere.
+- `animatorFor(element)` returns the one animator for an element, so code
+  that animates it from several places (a swipe on x, a removal on y)
+  composes in one `translate` track.
+
+### How it stays on the compositor
+
+Each curve is baked into keyframes, sampled adaptively until linear
+interpolation is within 0.05 px, and played with `easing: linear` on one
+start time. The element's inline style already holds the end values,
+and the keyframes hold the end state for a few seconds past the curve's end;
+the main thread drops the animation as soon as it runs after that end. So the
+frame an animation ends needs no main thread and shows no flicker, even when
+the main thread is blocked as the curve ends (WebKit's compositor otherwise
+falls back to the last value its main thread committed, mid-flight).
+
+Keyframes rather than one `linear()` easing: measured in Chromium, both are
+composited and, for the same samples, equally precise; but WebKit's Core
+Animation path does not accelerate an effect whose easing is `linear()` with
+points (`KeyframeEffect::canBeAccelerated`) unless its newer threaded
+animations are on, so on older iOS Safari a `linear()` spring would run on the
+main thread. Linear segments between keyframes map directly onto Core
+Animation keyframe animations.
+
+## Math
+
+`spring.ts` solves m·x″ + c·x′ + k·x = 0 in closed form in all three regimes:
+the model behind SwiftUI's `Spring`, `CASpringAnimation` and
+`UISpringTimingParameters`. A spring description stays in its source's
+vocabulary (mass, stiffness and damping; duration and bounce; response and
+damping ratio) and `toSpring` normalizes it. A mass, stiffness and damping
+description that does not allow overdamping is clamped to critical, as Core
+Animation does for every spring UIKit attaches. The tests hold it to an
+independent fourth-order Runge-Kutta integration over a sweep of damping
+ratios, responses and release velocities; to a port of WebKit's own spring
+solver; to the WWDC23 "Animate with springs" conversion equations; and to
+values read from UIKit on the iOS 26.2 simulator: `settlingDuration` for a
+grid of springs and velocities, and the durations UIKit gives its spring APIs,
+which the settling formula reproduces to the last digit (underdamped) or within
+0.02 % (critically damped). `decay.ts` is held to a literal per-millisecond
+simulation of the deceleration rate and to WWDC18's projection function;
+`rubberBand.ts` to UIScrollView's overscroll measured on the simulator.
+`uikit/values.test.ts` plays the table's values through this math.
+
+## Sources
+
+Every value in `uikit/` carries its source next to it, as a JSDoc tag on the
+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.