@astryxdesign/core 0.7.7 → 0.7.8-canary.0588a13

package/src/motion/animator.ts

@@ -4,11 +4,12 @@
  * @file animator.ts
  * @input An element, target values, and a spring, momentum curves (coast.ts)
  *   or any closed-form curve
- * @output Exports `createAnimator`: a compositor animator for translate,
- *   rotate, scale and opacity, with presentation values and velocities read
- *   from the analytic curves, velocity-preserving retargeting, freeze-in-place
- *   `stop`, completion promises, a shared clock, and UIKit's Reduced Motion
- *   substitution; plus its option, handle and transition types
+ * @output Exports `createMotionAnimator`, a compositor animator for
+ *   translate, rotate, scale and opacity, and its option, handle and
+ *   transition types. It reads presentation values and velocities from the
+ *   analytic curves. It retargets with the velocity kept, freezes in place on
+ *   `stop`, and gives completion promises, a shared clock, and UIKit's
+ *   Reduced Motion substitution.
  * @position Motion foundation (DOM). Internal to core: components use it for
  *   every touch-presentation animation; not exported from the package entry
  *
@@ -180,6 +181,7 @@
  */
 
 import {cubicBezier} from './bezier';
+import {LATE_START_MS} from './frameBlock';
 import {solveSpring, toSpring, type SpringDescription} from './spring';
 import {registerPresentedOffset, type PresentedSource} from './presentation';
 import {resolveMotion} from './resolveMotion';
@@ -188,6 +190,7 @@ import {
   registerReducedMotionCrossFade,
 } from './uikit/timing';
 import {planReducedMotion, type ReducedMotionView} from './reducedMotionPlan';
+import {themeReducesMotion} from '../privateAttributes/reducedMotion.stylex';
 
 /**
  * A value the animator can drive.
@@ -244,18 +247,18 @@ export interface AnimateOptions {
   crossfadeAs?: 'entrance' | 'exit';
   /**
    * When the call's animations start. By default a call from rest starts
-   * when the browser commits it, and a call that continues motion on screen
-   * (a retarget) starts now, from the value on screen. Ignored with `at`.
+   * when the browser commits it. A call that continues motion on screen (a
+   * retarget) starts now, from the value on screen. A curve whose tail
+   * already shows as at rest counts as rest. Ignored with `at`.
    * - `'commit'`: a call that continues motion also starts when the browser
-   *   commits it, dated by the browser rather than by the main thread, as a
-   *   call from rest is.
-   * - `'presented'`: a call from rest leaves its element at rest and creates
-   *   its animations two frames later, once the frame that carries the
-   *   element at rest has been presented; they then start at their commit. A
-   *   busy UI process delays the motion instead of skipping into it, for two
-   *   frames more before an idle start. Any other change to the animator
-   *   before then creates the animations first, in call order. A call that
-   *   continues motion on screen (a retarget) starts now, as by default.
+   *   commits it. The browser dates it, as it dates a call from rest.
+   * - `'presented'`: a call from rest leaves its element at rest. Its
+   *   animations are created two frames later, once the frame with the
+   *   element at rest has been presented. They then start at their commit,
+   *   so a busy UI process delays the motion instead of skipping into it.
+   *   Any other change to the animator before then creates the animations
+   *   first, in call order. A call that continues motion on screen starts
+   *   now, as by default.
    */
   start?: 'commit' | 'presented';
   /**
@@ -297,7 +300,7 @@ export interface MotionCurve {
 }
 
 /**
- * Options of `createAnimator`.
+ * Options of `createMotionAnimator`.
  */
 /** How `set` puts values in place. */
 export interface SetOptions {
@@ -652,15 +655,20 @@ const SAMPLE_TOLERANCE: Record<MotionProperty, number> = {
 /** Keyframes start on this grid (ms) and are split where the curve needs it. */
 const SAMPLE_GRID_MS = 1000 / 30;
 
-/** A curve that has not settled by then (an undamped spring) snaps. */
-const MAX_DURATION_MS = 30_000;
+/**
+ * A curve within this many sample tolerances of its target can show as at
+ * rest. A call on it then starts as one from rest does, at the browser's start.
+ */
+const REST_DISTANCE_TOLERANCES = 2;
 
 /**
- * How long a task must run on past its first call from rest before that
- * counts as a block (WebKit; startAfterBlock): two frames at 60 Hz.
+ * A curve shows as at rest only while it moves at most one `SAMPLE_TOLERANCE`
+ * a frame at this rate.
  */
-// Browser start times are frame times and a task's end a live clock, so only a block longer than a frame plus the task's own length can be told apart from that quantization.
-const LATE_START_MS = 34;
+const REST_FRAMES_PER_SECOND = 60;
+
+/** A curve that has not settled by then (an undamped spring) snaps. */
+const MAX_DURATION_MS = 30_000;
 
 /**
  * The task calls from rest are made in, shared by every call made in it
@@ -803,7 +811,7 @@ export function animatorFor(
   const key = options.pseudoElement ?? '';
   let animator = byPseudo.get(key);
   if (animator == null) {
-    animator = createAnimator(element, options);
+    animator = createMotionAnimator(element, options);
     byPseudo.set(key, animator);
   }
   return animator;
@@ -920,7 +928,7 @@ const REDUCED_TRANSITION: SpringTransition = {
  *
  * @example
  * ```
- * const animator = createAnimator(sheet);
+ * const animator = createMotionAnimator(sheet);
  * // finger lifts at 1200 px/s heading for the detent at 0 (a component
  * // passes the spring of its motion role):
  * animator.animate({y: 0}, {spring: {response: 0.45, dampingRatio: 0.9}, velocity: {y: 1200}});
@@ -929,7 +937,7 @@ const REDUCED_TRANSITION: SpringTransition = {
  * animator.stop(['y']);
  * ```
  */
-export function createAnimator(
+export function createMotionAnimator(
   element: HTMLElement | null,
   options: AnimatorOptions = {},
 ): Animator {
@@ -958,8 +966,10 @@ export function createAnimator(
         };
   const pseudoElement = options.pseudoElement;
   // Reduced Motion reads the person's settings and nothing else: no option
-  // overrides them (design:reduced-motion DR4).
-  const prefersReducedMotion = defaultPrefersReducedMotion;
+  // overrides them (design:reduced-motion DR4). A theme that reduces motion
+  // for everyone counts as the setting.
+  const prefersReducedMotion = () =>
+    defaultPrefersReducedMotion() || themeReducesMotion(target);
   const isCoarsePointer = defaultIsCoarsePointer;
   const resting: Record<MotionProperty, number> = {
     ...IDENTITY,
@@ -1165,6 +1175,22 @@ export function createAnimator(
     return curveAt(property, time);
   };
 
+  /**
+   * Whether a curve's tail already shows as at rest at `time`. Under a
+   * starved main thread the browser commits a call late. A call that starts
+   * at its own time then skips that far into its curve. One that starts at
+   * the commit holds an element that hardly moves.
+   */
+  const showsAtRest = (
+    property: MotionProperty,
+    segment: Segment,
+    time: number,
+  ): boolean =>
+    Math.abs(valueAt(property, time) - segment.target) <=
+      REST_DISTANCE_TOLERANCES * SAMPLE_TOLERANCE[property] &&
+    Math.abs(velocityAt(property, time)) <=
+      SAMPLE_TOLERANCE[property] * REST_FRAMES_PER_SECOND;
+
   const velocityAt = (property: MotionProperty, time: number): number => {
     const held = segments.get(property);
     if (held != null && isHeld(held)) {
@@ -2033,10 +2059,10 @@ export function createAnimator(
   // -- starting from rest ---------------------------------------------------
 
   /**
-   * A call starts from rest when nothing on the channels it drives is moving
-   * (a curve still waiting for its first frame counts as rest) and nothing
-   * pins its clock (`at`). Returns its start group, or null for an explicit
-   * start.
+   * A call starts from rest when nothing on the channels it drives moves on
+   * screen and nothing pins its clock (`at`). A curve still waiting for its
+   * first frame counts as rest, as does one whose tail already shows as at
+   * rest. Returns its start group, or null for an explicit start.
    */
   const beginGroup = (
     time: number,
@@ -2070,10 +2096,12 @@ export function createAnimator(
       }
       return null;
     }
-    // A call that continues motion starts now unless it asks for the
-    // browser's start (`commit`). `presented` asks only for a call from rest:
-    // an element still moving is not at rest, so a retarget starts now, from
-    // the value and velocity on screen (spec:AST-094 FR6).
+    // A call that continues motion starts now, unless it asks for the
+    // browser's start (`commit`). `presented` asks only for a call from rest.
+    // A curve that still moves is not at rest, so a call on it starts now,
+    // from the value and velocity on screen. A tail that shows as at rest
+    // counts as rest, so a call on it waits, under `presented` for its two
+    // frames.
     for (const channel of start === 'commit' ? [] : channels) {
       for (const property of CHANNELS[channel]) {
         const segment = segments.get(property);
@@ -2084,7 +2112,8 @@ export function createAnimator(
           time < endOf(property, segment) &&
           (segment.group == null ||
             segment.group.resolved ||
-            shownSince(property, segment) != null)
+            shownSince(property, segment) != null) &&
+          !showsAtRest(property, segment, time)
         ) {
           return null;
         }

package/src/motion/frameBlock.ts

@@ -0,0 +1,16 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file frameBlock.ts
+ * @input none
+ * @output LATE_START_MS
+ * @position The motion modules' shared measure of a main-thread block.
+ */
+
+/**
+ * How long a task must run on past a frame, or past its first call from rest,
+ * to count as a block. It is two frames at 60 Hz. Browser start times are
+ * frame times, while a task's end is on a live clock. So only a block longer
+ * than a frame plus the task's own length stands out from that quantization.
+ */
+export const LATE_START_MS = 34;

package/src/motion/progress.ts

@@ -0,0 +1,155 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file progress.ts
+ * @input A spring, a normalized progress, an animator's presented velocities
+ * @output Exports `progressCurve` (a spring's progress from 0 to 1 as a
+ *   MotionCurve), `mapProgress` (one curve as a function of another),
+ *   `mapRange` (the clamped linear map most companions use) and
+ *   `presentedProgressVelocity` (the progress velocity that continues what
+ *   an animator shows)
+ * @position Shared by the motion building blocks that move several channels
+ *   along one path and by companion motion (a
+ *   scrim's dim following a sheet): one velocity unit, one curve mapping and
+ *   one way to continue an interrupted motion
+ *
+ * A path is described by a normalized progress: 0 where it starts, 1 where
+ * it rests, beyond either end on a spring's overshoot. Its velocity is in
+ * progress per second; each channel's own velocity stays in the channel's
+ * units per second.
+ *
+ * An interrupted motion continues from what is on screen: the
+ * block reads the presented values and velocities from the animator at one
+ * `now` (`get`, `getVelocity`), restarts a path from those values, and starts
+ * its progress with the presented velocity projected on the path's tangent
+ * at its start, v·t / (t·t), where t = d(values)/dp. Channels are weighted
+ * into one unit first (px per unit of scale, say), so a scale and a
+ * translation count alike.
+ *
+ * A companion follows a driving curve through `mapProgress`, most often
+ * with `mapRange`: `mapProgress(sheetY, mapRange([closedY, openY], [0, dim]))`
+ * dims a scrim as a sheet rises. Played on another animator, it stays in
+ * lockstep only when it starts with its driver: pass the driver's start,
+ * `scrim.play({opacity}, {at: start})` with `start = await handle.started`
+ * (or one shared `at` for both calls); two calls from rest otherwise each
+ * start at their own commit.
+ *
+ * SYNC: When modified, update /packages/core/src/motion/progress.test.ts and
+ * /packages/core/src/motion/README.md.
+ */
+
+import type {Animator, MotionCurve, MotionProperty} from './animator';
+import {
+  SETTLING_EPSILON,
+  solveSpring,
+  toSpring,
+  type SpringDescription,
+} from './spring';
+
+/** The step of the finite differences taken on a progress. */
+const STEP = 1e-4;
+
+/**
+ * The progress of `spring` from 0 to 1, starting with `velocity` (progress
+ * per second): exactly 1 once it settles within `epsilon`.
+ */
+export function progressCurve(
+  spring: SpringDescription,
+  {
+    velocity = 0,
+    epsilon = SETTLING_EPSILON,
+  }: {velocity?: number; epsilon?: number} = {},
+): MotionCurve {
+  const curve = solveSpring(toSpring(spring), {from: 0, to: 1, velocity});
+  const duration = curve.settleTime(epsilon);
+  return {
+    duration,
+    at: t => (t >= duration ? 1 : curve.value(t)),
+    velocity: t => (t >= duration ? 0 : curve.velocity(t)),
+  };
+}
+
+/**
+ * The curve of `f(driver(t))`, its velocity by the chain rule: a channel
+ * following a path as its progress moves, or a companion following any
+ * driving curve (a sheet's `y` mapped onto its scrim's opacity). The driver
+ * is any MotionCurve, not only a progress from 0 to 1. A companion played on
+ * another animator starts with its driver (`{at: start}`; see the file
+ * header).
+ */
+export function mapProgress(
+  driver: MotionCurve,
+  f: (value: number) => number,
+): MotionCurve {
+  return {
+    duration: driver.duration,
+    at: t => f(driver.at(t)),
+    velocity: t => {
+      const value = driver.at(t);
+      return (
+        ((f(value + STEP) - f(value - STEP)) / (2 * STEP)) * driver.velocity(t)
+      );
+    },
+  };
+}
+
+/**
+ * The linear map from `input` to `output`, held at `output`'s ends outside
+ * `input` unless `clamp` is false: what most companions are (a scrim's dim
+ * along a sheet's travel, a parallax, a dismissal's fade). Either range may
+ * run backward (`[openY, closedY]`).
+ */
+export function mapRange(
+  input: readonly [number, number],
+  output: readonly [number, number],
+  {clamp = true}: {clamp?: boolean} = {},
+): (x: number) => number {
+  const [a, b] = input;
+  const [c, d] = output;
+  return x => {
+    let t = a === b ? (x < a ? 0 : 1) : (x - a) / (b - a);
+    if (clamp) {
+      t = Math.min(1, Math.max(0, t));
+    }
+    // Exact at both ends.
+    return t === 0 ? c : t === 1 ? d : c + (d - c) * t;
+  };
+}
+
+/**
+ * One channel of a path: an animator property and its value at each
+ * progress.
+ */
+export interface ProgressChannel {
+  readonly property: MotionProperty;
+  /** The property's value at progress `p`. */
+  at(p: number): number;
+  /**
+   * What one unit of the property weighs in the projection, in a unit the
+   * channels share (px per unit of scale for a box `weight` px wide). 1 by
+   * default.
+   */
+  readonly weight?: number;
+}
+
+/**
+ * The progress velocity, per second, that continues what `animator`
+ * presents at `now` along a path that starts there: the presented velocity
+ * projected on the path's tangent at progress 0, v·t / (t·t). 0 when the
+ * path does not move any of its channels.
+ */
+export function presentedProgressVelocity(
+  animator: Pick<Animator, 'getVelocity'>,
+  channels: ReadonlyArray<ProgressChannel>,
+  now?: number,
+): number {
+  let along = 0;
+  let squared = 0;
+  for (const channel of channels) {
+    const weight = channel.weight ?? 1;
+    const tangent = ((channel.at(STEP) - channel.at(0)) / STEP) * weight;
+    along += animator.getVelocity(channel.property, now) * weight * tangent;
+    squared += tangent * tangent;
+  }
+  return squared > 1e-12 ? along / squared : 0;
+}

package/src/motion/reducedMotion.ts

@@ -46,6 +46,7 @@
 
 import {defaultIsCoarsePointer, defaultPrefersReducedMotion} from './animator';
 import {resolveMotion} from './resolveMotion';
+import {themeReducesMotion} from '../privateAttributes/reducedMotion.stylex';
 import {
   reducedMotionCrossFade,
   registerReducedMotionCrossFade,
@@ -83,7 +84,8 @@ export function reducedMotionFade(
     touchRelease?: boolean;
   } = {},
 ): ReducedMotionFade | null {
-  if (!defaultPrefersReducedMotion()) {
+  // A theme that reduces motion for everyone counts as the setting.
+  if (!defaultPrefersReducedMotion() && !themeReducesMotion(element)) {
     return null;
   }
   const fades = options.touchRelease === true || defaultIsCoarsePointer();

package/src/motion/uikit/alert.ts

@@ -0,0 +1,43 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file alert.ts
+ * @input Nothing; data only
+ * @output Exports `alertController`: how UIAlertController (`.alert`) tracks
+ *   a finger across its actions
+ * @position The alert domain of the UIKit constants table (motion/uikit);
+ *   its springs are `springs.alertPresent` and `springs.alertDismiss`
+ *
+ * Every value was read from UIKit on the iOS 26.2 simulator. A host app
+ * presented `UIAlertController(.alert)` with two and with three actions.
+ * Real HID touches drove it, and the action views' highlight was sampled
+ * every frame. Lengths are in pt (CSS px), durations in ms.
+ *
+ * Every leaf carries one or more `@source`; GUESS values also carry the
+ * `@measure` task that will confirm or replace them. uikit.test.ts enforces
+ * both.
+ *
+ * SYNC: When modified, update /packages/core/src/motion/MEASUREMENTS.md
+ */
+
+export const alertController = {
+  actions: {
+    /**
+     * How long after touch-down the touched action highlights: none, it is
+     * highlighted in the touch-down frame (a tap and a 300 ms hold alike).
+     * @source measured: UIKit lab (injected host app), iOS 26.2 simulator,
+     *   iPhone 17 Pro, per-frame highlight of the action views under real HID
+     *   touches, Oct 23 2026
+     */
+    highlightOnsetMs: 0,
+    /**
+     * How far outside an action the finger may go and keep it highlighted:
+     * none. The highlight cleared 1 pt below the action, and a lift there ran
+     * nothing. UIButton keeps 70 pt; an alert action does not.
+     * @source measured: UIKit lab (injected host app), iOS 26.2 simulator,
+     *   iPhone 17 Pro, per-frame highlight of the action views under real HID
+     *   touches, Oct 23 2026
+     */
+    highlightExpansion: 0,
+  },
+} as const;

package/src/motion/uikit/datePicker.ts

@@ -0,0 +1,60 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file datePicker.ts
+ * @input Nothing; data only
+ * @output Exports `datePicker`: the rules UIDatePicker adds to its wheels. The
+ *   month/year wheels change the date, the AM/PM column follows the hour, a
+ *   column turns back onto a bound, and a day clamps to its month.
+ * @position The date picker domain of the UIKit constants table
+ *   (motion/uikit), for the date and time touch sheets. Every leaf names its
+ *   source, which uikit.test.ts checks.
+ *
+ * SYNC: When modified, update /packages/core/src/motion/MEASUREMENTS.md and
+ * /packages/core/src/motion/README.md.
+ */
+
+export const datePicker = {
+  calendar: {
+    monthYearWheels: {
+      /**
+       * Turning the month or year wheel changes the picker's date, keeping
+       * the day, and fires `valueChanged`.
+       * @source measured: UIKit lab, iOS 26.2 simulator, `.date` `.inline`,
+       *   October 15 → May 15 after the month wheel's fling, with a
+       *   `valueChanged` carrying May 15, Oct 23 2026
+       */
+      changesDate: true,
+    },
+  },
+  wheels: {
+    /**
+     * In 12-hour time the AM/PM column follows the hour. Turning the hour from
+     * 11 to 12 turns the time from AM to PM, and back. From 12 to 1 it keeps
+     * the half of the day.
+     * @source measured: UIKit lab, iOS 26.2 simulator, `.time` `.wheels`,
+     *   en_US: 11:58 AM, hour wheel +1 row → `valueChanged` 12:58 PM; then
+     *   the minute wheel's +4 rows carried the hour from 12 to 1 → 1:02 PM,
+     *   Oct 23 2026
+     */
+    meridiemFollowsHour: true,
+    /**
+     * A column that comes to rest past `minimumDate` or `maximumDate` turns
+     * back onto the bound. Its `valueChanged` already carries the bound. For
+     * example, with bounds 9:00–17:00, the hour of 10:00 dragged to 7 reads
+     * 9:00 at rest. The hour column then turns 64 pt, two rows, back to 9.
+     * @source measured: UIKit lab, iOS 26.2 simulator, `.time` `.wheels`
+     *   with bounds 9:00–17:00 and `minuteInterval` 15, per-frame hour
+     *   offsets after the rest (0.4, 2, 7.4, 16, 26.4, 37.7, 48.3, 56.7,
+     *   62, 64 pt at 33 ms steps) and the `valueChanged` time, Oct 23 2026
+     */
+    restPastBound: 'turnToBound',
+    /**
+     * In `.date` wheels a day the month does not have clamps to the month's
+     * last day (January 30, month +1 → February 28).
+     * @source measured: UIKit lab, iOS 26.2 simulator, `.date` `.wheels`
+     *   with bounds Jun 1 2026 – Mar 15 2027, Oct 23 2026
+     */
+    dayClampsToMonth: true,
+  },
+} as const;

package/src/motion/uikit/index.ts

@@ -4,10 +4,10 @@
  * @file index.ts
  * @input The domain files of the UIKit constants table
  * @output Re-exports `springs` and one constant per spring (`SHEET_PRESENT_SPRING`,
- *   …), `scroll`, `timing`, `navigation`, `progressBar`, `segmentedControl`,
- *   the `slider` and switch (`switchControl`) domains, and the gesture
- *   thresholds (one `UIKIT_*` group per recognizer, their union
- *   `UIKIT_GESTURES`, and the haptic tables)
+ *   …), `scroll`, `timing`, `navigation`, `picker`, `progressBar`,
+ *   `segmentedControl`, `datePicker`, `slider` and `switchControl`. It also
+ *   re-exports the gesture thresholds: one `UIKIT_*` group per recognizer,
+ *   their union `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
  *
@@ -39,7 +39,9 @@ export {
   type GestureConstantUnit,
   type HapticFeedbackKind,
 } from './gestures';
+export {datePicker} from './datePicker';
 export {navigation, registerNavigationTable} from './navigation';
+export {picker} from './picker';
 export {progressBar, registerProgressBarTable} from './progressBar';
 export {registerScrollTable, scroll} from './scroll';
 export {segmentedControl} from './segmented';

package/src/motion/uikit/picker.ts

@@ -0,0 +1,116 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file picker.ts
+ * @input Nothing; data only
+ * @output `picker`, UIPickerView's measured constants, and
+ *   `registerPickerTable`, which makes the tap spin's duration a motion role
+ * @position The picker domain of the UIKit table (motion/uikit); read by
+ *   DateInput's wheelPhysics.ts, wheelStrip.ts and PickerWheel.tsx
+ *
+ * Lengths are pt at UIKit's scale, times ms and velocities pt/ms. Every leaf
+ * carries one `@source`, as uikit.test.ts enforces.
+ *
+ * SYNC: When modified, update motion/MEASUREMENTS.md and PickerWheel.tsx.
+ */
+
+import {registerMotionTable} from '../roles';
+
+export const picker = {
+  geometry: {
+    /**
+     * Row pitch: rows sit at k × 32 pt in each column's table.
+     * @source measured: UIKit lab (injected host app), iOS 26.2 simulator,
+     *   iPhone 17 Pro, UIPickerView table offsets and cell frames, Oct 23 2026
+     */
+    rowHeight: 32,
+    /**
+     * The picker's height (its intrinsic content size).
+     * @source measured: UIKit lab (injected host app), iOS 26.2 simulator,
+     *   iPhone 17 Pro, UIPickerView frame, Oct 23 2026
+     */
+    height: 216,
+    /**
+     * d of the rubber band past the first or last row. The column's table view
+     * is 291 pt tall in a 216 pt picker. With c = 0.55, scroll.rubberBand's
+     * formula puts 10, 50 and 110 pt of finger travel past the end at 5.4, 25.1
+     * and 50.1 pt. The measured values are 5.3, 25 and 50.
+     * @source measured: UIKit lab (injected host app), iOS 26.2 simulator,
+     *   iPhone 17 Pro, UIPickerTableView frame and offsets during drags
+     *   20, 60 and 120 pt past the last row, Oct 23 2026
+     */
+    rubberBandDimension: 291,
+  },
+  release: {
+    /**
+     * The speed at which a coast ends. The scroll view projects the target at
+     * offset + (v − this) × r ÷ (1 − r), with r = scroll.decelerationRate
+     * .normal. That gives 461.33, 502.67 and 266.67 pt for v = 0.9334, 1.0162
+     * and 0.5436, all three to 0.3 pt. The coast onto the row it snaps to keeps
+     * the release velocity. It re-solves the rate so that the speed reaches
+     * this exactly at that row, where it stops. Two coasts fit it to 0.4 and
+     * 0.3 pt RMS, ending within 30 ms of the measured end.
+     * @source measured: UIKit lab (injected host app), iOS 26.2 simulator,
+     *   iPhone 17 Pro, scrollViewWillEndDragging targets and per-frame
+     *   offsets to rest, Oct 23 2026
+     */
+    stopSpeed: 0.0089,
+    /**
+     * Below this release speed (pt/ms, a scroll view's release velocity), a
+     * release inside the rows carries no velocity. The wheel then snaps to the
+     * nearest row instead of coasting. Past the first or last row the velocity
+     * is kept, however small (0.0816 kept). A pause before the lift does not
+     * zero it: the velocity changes only when the finger moves.
+     * @source measured: UIKit lab (injected host app), iOS 26.2 simulator,
+     *   iPhone 17 Pro, steady 100 pt drags mid-list lifted while moving: zeroed
+     *   at 100 to 250 pt/s both ways, passed from 260 pt/s (0.2577 the
+     *   smallest velocity handed on); a 300 pt/s drag held still 300 ms
+     *   still coasted, Oct 23 2026
+     */
+    minimumSpeed: 0.25,
+  },
+  /**
+   * A release without velocity, or a coast already on a row, eases onto the
+   * nearest row exponentially. Each millisecond it covers this fraction of the
+   * distance left: e^(−0.011 t), done in about 0.3 s. Snaps of 4, 6 and 8 pt
+   * fit 0.0099, 0.0107 and 0.0123.
+   * @source measured: UIKit lab (injected host app), iOS 26.2 simulator,
+   *   iPhone 17 Pro, per-frame offsets after three slow releases between
+   *   rows, Oct 23 2026
+   */
+  snapRate: 0.011,
+  tapSpin: {
+    /**
+     * A tap on a row turns the wheel onto it in this long (setContentOffset
+     * animated), on Core Animation's ease-in-ease-out (timing.curves.move). The
+     * row is selected on arrival. A tap on the band's row does nothing.
+     * @source measured: UIKit lab (injected host app), iOS 26.2 simulator,
+     *   iPhone 17 Pro, per-frame offsets after a tap two rows below the band
+     *   (6.8, 25.1, 50.2, 75.4, 93.7 % at 50 ms steps, arriving at 300 ms;
+     *   the same with Reduce Motion and Prefer Cross-Fade on), Oct 23 2026
+     */
+    durationMs: 300,
+  },
+  selectionTick: {
+    /**
+     * One selection haptic per row whose centre reaches the band's centre,
+     * at most one per this interval. Not during a tap's spin.
+     * @source measured: UIKit lab (injected host app), iOS 26.2 simulator,
+     *   iPhone 17 Pro, selectionChangedAtLocation: and the feedback
+     *   generator's minimum interval (0.040 s) logged during drags and
+     *   coasts, Oct 23 2026
+     */
+    minimumIntervalMs: 40,
+  },
+} as const;
+
+/**
+ * Registers the tap spin's duration as an internal motion role,
+ * `picker.tapSpin.durationMs`. Every other value stays an internal measured
+ * constant. The tap spin's curve is the shared role `timing.curves.move`, and
+ * the bounce at an end is `scroll.bounce`. Nothing registers on import, and
+ * registering again does nothing.
+ */
+export function registerPickerTable(): void {
+  registerMotionTable('picker', picker, {roles: ['tapSpin.durationMs']});
+}