@astryxdesign/core 0.7.5-canary.fccd771 → 0.7.5

package/src/motion/uikit/timing.ts

@@ -0,0 +1,210 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file timing.ts
+ * @input Nothing; data only
+ * @output Exports `timing`: the non-spring clocks and curves UIKit uses
+ *   (press highlight onset, flash and fade, Core Animation's named Bézier
+ *   curves, the navigation bar hide/show duration, the keyboard
+ *   notification duration, the Reduced Motion cross-fade)
+ * @position The timing domain of the UIKit constants table (motion/uikit)
+ *
+ * Every leaf carries one or more `@source` (apple-docs | wwdc | webkit |
+ * measured | GUESS); webkit and GUESS values also carry the `@measure` task
+ * that will confirm or replace them (MEASUREMENTS.md). uikit.test.ts
+ * enforces both.
+ *
+ * Durations are in ms (the unit of pointer-event timestamps, which these
+ * clocks are compared against); curves are cubic-bézier control points
+ * [x1, y1, x2, y2].
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/motion/MEASUREMENTS.md (measurement tasks)
+ * - /packages/core/src/utils/pressGesture.ts (the press clocks are measured
+ *   there and must agree; uikit/uikit.test.ts checks it)
+ */
+
+import {registerMotionTable} from '../roles';
+
+/**
+ * The touch press clocks, its own export so a reader of one clock does not
+ * bundle the rest of the table (`architecture:component-style-authoring`
+ * INV6).
+ */
+export const press = {
+  /**
+   * Highlight onset once a press is believed: none, the highlight is
+   * painted in the frame the touch is accepted (after
+   * `scroll.delaysContentTouchesMs` inside a scroller).
+   * @source measured: Settings and Contacts, iOS 26.2, simulator driven
+   *   with real HID touches at 60 fps (touch press model,
+   *   packages/core/src/utils/pressGesture.ts, 2026-10-06)
+   */
+  highlightInMs: 0,
+  /**
+   * A tap released before the onset delay still flashes the highlight at
+   * full strength for this long before fading.
+   * @source measured: Settings and Contacts, iOS 26.2, simulator driven
+   *   with real HID touches at 60 fps (PRESS_FLASH_MS,
+   *   packages/core/src/utils/pressGesture.ts, 2026-10-06)
+   */
+  flashMs: 100,
+  /**
+   * Highlight fade after release: UIKit's deselect cross-fade.
+   * @source measured: Settings and Contacts, iOS 26.2, simulator driven
+   *   with real HID touches at 60 fps (PRESS_FADE_MS / pressConsts.releaseMs,
+   *   packages/core/src/utils/pressGesture.ts, 2026-10-06)
+   */
+  highlightOutMs: 200,
+  /**
+   * The highlight fade's curve after release: an ease-out that spends the
+   * whole clock fading (strength about 0.2 at the midpoint).
+   * @source GUESS — the release curve the touch press model ships with
+   *   (`RELEASE_EASE`, packages/core/src/utils/interactionOverlay.stylex.ts),
+   *   chosen to read as UIKit's deselect cross-fade, not read from UIKit
+   * @measure M-PR1
+   */
+  highlightOutCurve: [0, 0, 0.2, 1],
+  /**
+   * A touch on a scroller that moved this recently brakes it instead of
+   * pressing.
+   * @source measured: Settings and Contacts, iOS 26.2, simulator driven
+   *   with real HID touches at 60 fps (PRESS_SCROLL_BRAKE_MS,
+   *   packages/core/src/utils/pressGesture.ts, 2026-10-06)
+   */
+  scrollBrakeMs: 150,
+  /**
+   * UIButton (filled configuration) release: the label cross-fade and the
+   * background color both run 0.25 s on `curves.move`.
+   * @source measured: UIKit lab (injected host app), iOS 26.2 simulator,
+   *   iPhone 17 Pro, CAAnimation read (CATransition fade and backgroundColor),
+   *   Oct 23 2026
+   */
+  buttonReleaseMs: 250,
+} as const;
+
+/**
+ * The Reduce Motion fade, its own export so the animator reads it without
+ * the rest of the table (`architecture:component-style-authoring` INV6).
+ * `timing` composes it under its table paths, `reducedMotionCrossFadeMs` and
+ * `curves.move`, so their roles are unchanged.
+ */
+export const reducedMotionCrossFade = {
+  /**
+   * The Reduced Motion cross-fade, in ms, on `curves.move`: under
+   * Reduce Motion an entrance, exit, presentation switch or state change
+   * becomes an opacity-only cross-fade of this length on a coarse pointer
+   * (design:reduced-motion DR2 caps it at 200 ms, by owner decision DEC-1
+   * of 2026-10-24, departing from UIKit's own navigation cross-fade,
+   * measured below at 0.5 s). Not a theme role: no theme lengthens it (DR4).
+   * @source apple-docs https://developer.apple.com/documentation/uikit/uiaccessibility/preferscrossfadetransitions
+   *   (the setting)
+   * @source measured: UIKit lab (injected host app), iOS 26.2 simulator,
+   *   iPhone 17 Pro, CAAnimation dump with Reduce Motion and Prefer
+   *   Cross-Fade Transitions on (opacity CABasicAnimation 0.5 s,
+   *   (0.42, 0, 0.58, 1)), Oct 23 2026
+   */
+  durationMs: 200,
+  /**
+   * `easeInEaseOut`; UIKit's default curve (`UIView.AnimationCurve
+   * .easeInOut`, "the default curve for most animations").
+   * @source apple-docs https://developer.apple.com/documentation/quartzcore/camediatimingfunctionname/easeineaseout
+   * @source measured: UIKit lab (injected host app), iOS 26.2 simulator,
+   *   iPhone 17 Pro, CAMediaTimingFunction read from UIView.animate,
+   *   Oct 23 2026
+   */
+  curve: [0.42, 0, 0.58, 1],
+} as const;
+
+// `timing` composes the fade from bindings, not property reads, so a bundle
+// that reads only the fade drops the rest of the table.
+const {durationMs: reducedMotionCrossFadeMs, curve: move} =
+  reducedMotionCrossFade;
+
+export const timing = {
+  press,
+  curves: {
+    /**
+     * `CAMediaTimingFunctionName.default`: "the timing of … most system
+     * animations" that are not springs.
+     * @source apple-docs https://developer.apple.com/documentation/quartzcore/camediatimingfunctionname/default
+     * @source measured: UIKit lab (injected host app), iOS 26.2 simulator,
+     *   iPhone 17 Pro, CAMediaTimingFunction read from UIView.animate,
+     *   Oct 23 2026
+     */
+    viewChange: [0.25, 0.1, 0.25, 1],
+    // The Reduce Motion fade's curve, sourced on `reducedMotionCrossFade`.
+    move,
+    /**
+     * `easeIn`.
+     * @source apple-docs https://developer.apple.com/documentation/quartzcore/camediatimingfunctionname/easein
+     * @source measured: UIKit lab (injected host app), iOS 26.2 simulator,
+     *   iPhone 17 Pro, CAMediaTimingFunction read from UIView.animate,
+     *   Oct 23 2026
+     */
+    exit: [0.42, 0, 1, 1],
+    /**
+     * `easeOut`.
+     * @source apple-docs https://developer.apple.com/documentation/quartzcore/camediatimingfunctionname/easeout
+     * @source measured: UIKit lab (injected host app), iOS 26.2 simulator,
+     *   iPhone 17 Pro, CAMediaTimingFunction read from UIView.animate,
+     *   Oct 23 2026
+     */
+    entrance: [0, 0, 0.58, 1],
+  },
+  /**
+   * `UINavigationController.hideShowBarDuration`, in ms.
+   * @source apple-docs https://developer.apple.com/documentation/uikit/uinavigationcontroller/hideshowbarduration
+   *   (the constant, not its value)
+   * @source measured: UIKit lab (injected host app), iOS 26.2 simulator,
+   *   iPhone 17 Pro, read, Oct 23 2026
+   */
+  navigationBarHideShowMs: 200,
+  /**
+   * The duration the keyboard notifications report
+   * (UIKeyboardAnimationDurationUserInfoKey, with curve 7), show and hide
+   * alike, in ms. The frame follows `springs.keyboard`, cut at this time.
+   * @source measured: UIKit lab (injected host app), iOS 26.2 simulator,
+   *   iPhone 17 Pro, UIKeyboardWillShow / WillHide / WillChangeFrame read,
+   *   Oct 23 2026
+   */
+  keyboardNotificationMs: 383.3,
+  /**
+   * Core Animation's implicit animation duration
+   * (`CATransaction.animationDuration()`), in ms.
+   * @source measured: UIKit lab (injected host app), iOS 26.2 simulator,
+   *   iPhone 17 Pro, read, Oct 23 2026
+   */
+  stateChangeMs: 250,
+  // The Reduce Motion fade's length, sourced on `reducedMotionCrossFade`.
+  reducedMotionCrossFadeMs,
+} as const;
+
+/**
+ * Registers the springs, durations and curves above that spec:AST-094 FR4
+ * names as internal motion roles (motion/roles.ts). Nothing registers on import: the touch code that
+ * animates with this table calls it once (it is idempotent), so a page that
+ * never does ships no registry.
+ */
+export function registerTimingTable(): void {
+  registerMotionTable('timing', timing, {
+    // Arbitration: who gets the touch, not how anything moves; the Reduced
+    // Motion fade, which nothing may lengthen (design:reduced-motion DR4);
+    // and the keyboard's own timing, which motion in step with the keyboard
+    // rides (spec:AST-094 FR4).
+    exclude: [
+      'press.scrollBrakeMs',
+      'reducedMotionCrossFadeMs',
+      'keyboardNotificationMs',
+    ],
+    // The motion roles: only the ones spec:AST-094 FR4 names. The press
+    // clocks and every other value are internal measured constants.
+    roles: [
+      'stateChangeMs',
+      'curves.viewChange',
+      'curves.exit',
+      'curves.entrance',
+      'curves.move',
+    ],
+  });
+}

package/src/motion/uikit/uikit.test.ts

@@ -0,0 +1,364 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file uikit.test.ts
+ * @input vitest, the UIKit constants table and its source text
+ * @output Enforces `spec:AST-094` FR2 on the table: every leaf has a source of an
+ *   allowed kind, every guess and every WebKit value names its measurement
+ *   task, every task is listed in motion/MEASUREMENTS.md, and no value ships
+ *   its source; checks the plain values (ratios, rates, curves) and that the
+ *   press clocks agree with the touch press model they were measured for
+ * @position Testing; validates motion/uikit/*.ts without a browser
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import {describe, expect, it} from 'vitest';
+import {
+  PRESS_FADE_MS,
+  PRESS_FLASH_MS,
+  PRESS_ONSET_MS,
+  PRESS_SCROLL_BRAKE_MS,
+} from '../../utils/pressGesture';
+import {scroll, springs, timing} from '.';
+
+// Modules in this folder that hold no table of their own (none yet).
+const NON_TABLE_FILES: string[] = [];
+// Every domain file carries its sources as JSDoc tags: a new one is enforced
+// the moment it lands.
+const TABLE_FILES = fs
+  .readdirSync(__dirname)
+  .filter(
+    file =>
+      file.endsWith('.ts') &&
+      file !== 'index.ts' &&
+      !file.endsWith('.test.ts') &&
+      !NON_TABLE_FILES.includes(file),
+  )
+  .sort();
+// Where a number comes from is documentation: a value that carried it would
+// ship it in every bundle that reads the value.
+const PROVENANCE_KEYS = new Set(['source', 'guess', 'measure']);
+/** A measurement names its subject, the iOS version it ran on and its date. */
+const MEASURED =
+  /^@source measured: .*iOS \d.*(\b20\d\d-\d\d-\d\d\b|\b(Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec)[a-z]* \d{1,2},? 20\d\d\b)/;
+const SOURCE_KINDS =
+  /^@source (apple-docs https:\/\/developer\.apple\.com\/|wwdc \d{4}-\d+ |webkit Source\/|measured: .*iOS \d|GUESS — )/;
+
+interface Leaf {
+  file: string;
+  key: string;
+  doc: string;
+}
+
+/**
+ * Every leaf of the exported table object with the JSDoc block right above
+ * it. A line ending in `{` opens a group (no source of its own); any other
+ * `key: value,` line is a leaf.
+ */
+function leavesOf(file: string): Leaf[] {
+  const text = fs.readFileSync(path.resolve(__dirname, file), 'utf8');
+  const lines = text.split('\n');
+  // Every exported object: a row when its own JSDoc carries the source (one
+  // spring, exported so a reader takes it alone), otherwise a table or a
+  // group of its own (the press clocks) whose leaves carry the sources.
+  const starts: number[] = [];
+  const rows: Leaf[] = [];
+  // The groups and rows this file exports itself: a leaf that only names one
+  // of them is checked where it is declared.
+  const exported = new Set<string>();
+  lines.forEach((line, index) => {
+    const match = /^export const (\w+) = \{/.exec(line);
+    if (match == null) {
+      return;
+    }
+    exported.add(match[1]);
+    const doc = docAbove(lines, index);
+    // A one-line export is a row whether or not it is sourced, so an
+    // unsourced one fails the source check below instead of being skipped.
+    if (/^@source /m.test(doc) || !line.endsWith('{')) {
+      rows.push({file, key: match[1], doc});
+    } else {
+      starts.push(index);
+    }
+  });
+  // Values bound from one of those groups (`const {curve: move} = group;`)
+  // are checked where the group declares them too.
+  const bindings = /^const \{([^}]+)\} =\s*(?:\n\s*)?(\w+);/gm;
+  for (const [, names, group] of text.matchAll(bindings)) {
+    if (exported.has(group)) {
+      for (const name of names.split(',')) {
+        exported.add(name.split(':').pop()!.trim());
+      }
+    }
+  }
+  expect(starts.length).toBeGreaterThan(0);
+  return [
+    ...starts.flatMap(start => leavesFrom(file, lines, start, exported)),
+    ...rows,
+  ];
+}
+
+/** The JSDoc block right above line `index`, without its comment markers. */
+function docAbove(lines: string[], index: number): string {
+  if (!lines[index - 1]?.trim().endsWith('*/')) {
+    return '';
+  }
+  let first = index - 1;
+  while (first > 0 && !lines[first].trim().startsWith('/**')) {
+    first--;
+  }
+  return lines
+    .slice(first, index)
+    .map(text => text.trim().replace(/^\/?\*+\/?\s?/, '') + '\n')
+    .join('');
+}
+
+function leavesFrom(
+  file: string,
+  lines: string[],
+  start: number,
+  exported: ReadonlySet<string>,
+): Leaf[] {
+  const leaves: Leaf[] = [];
+  let doc = '';
+  let inDoc = false;
+  let groupLeafCount: number[] = [];
+  for (const line of lines.slice(start + 1)) {
+    const trimmed = line.trim();
+    if (trimmed.startsWith('/**')) {
+      inDoc = true;
+      doc = '';
+    }
+    if (inDoc) {
+      doc += trimmed.replace(/^\/?\*+\/?\s?/, '') + '\n';
+      if (trimmed.endsWith('*/')) {
+        inDoc = false;
+      }
+      continue;
+    }
+    if (trimmed === '' || trimmed.startsWith('//')) {
+      continue;
+    }
+    const group = /^(\w+): \{$/.exec(trimmed);
+    if (group) {
+      groupLeafCount.push(0);
+      doc = '';
+      continue;
+    }
+    if (/^\},?$/.test(trimmed)) {
+      const count = groupLeafCount.pop();
+      expect(count, `${file}: empty group`).toBeGreaterThan(0);
+      continue;
+    }
+    if (trimmed.startsWith('} as const')) {
+      break;
+    }
+    // A group exported on its own and read back by name (`press,` or
+    // `tap: UIKIT_TAP,`): its leaves are checked where it is declared.
+    const reference = /^(?:\w+: )?(\w+),$/.exec(trimmed);
+    if (reference != null && exported.has(reference[1])) {
+      doc = '';
+      continue;
+    }
+    const leaf = /^(\w+): .+,$/.exec(trimmed);
+    expect(
+      leaf,
+      `${file}: unexpected line ${JSON.stringify(trimmed)}`,
+    ).not.toBeNull();
+    if (leaf) {
+      leaves.push({file, key: leaf[1], doc});
+      groupLeafCount = groupLeafCount.map(n => n + 1);
+    }
+    doc = '';
+  }
+  return leaves;
+}
+
+const MEASUREMENTS = fs.readFileSync(
+  path.resolve(__dirname, '../MEASUREMENTS.md'),
+  'utf8',
+);
+
+describe('UIKit constants table: every value is sourced (AST-094 FR2)', () => {
+  const leaves = TABLE_FILES.flatMap(leavesOf);
+
+  it('finds the table entries', () => {
+    expect(TABLE_FILES).toEqual(
+      expect.arrayContaining([
+        'gestures.ts',
+        'navigation.ts',
+        'scroll.ts',
+        'springs.ts',
+        'timing.ts',
+      ]),
+    );
+    expect(leaves.length).toBeGreaterThan(50);
+  });
+
+  for (const {file, key, doc} of leaves) {
+    it(`${file} › ${key}`, () => {
+      expect(
+        PROVENANCE_KEYS.has(key),
+        `${file} › ${key}: a source belongs in the JSDoc, not in the value`,
+      ).toBe(false);
+      expectSourced(key, doc);
+    });
+  }
+});
+
+describe('UIKit constants table: no source in a value', () => {
+  // Where a value comes from stays in its JSDoc, out of the bundle: no
+  // domain file writes a provenance key in code, at any depth.
+  for (const file of TABLE_FILES) {
+    it(file, () => {
+      const code = fs
+        .readFileSync(path.resolve(__dirname, file), 'utf8')
+        .replace(/\/\*[\s\S]*?\*\//g, '')
+        .replace(/\/\/.*$/gm, '');
+      expect(code).not.toMatch(/\b(source|guess|measure)\s*:/);
+    });
+  }
+});
+
+describe('UIKit constants table: blocks sourced as a whole', () => {
+  it('gestures.ts › HAPTIC_VIBRATION_PATTERNS', () => {
+    // Every pattern rests on the same guess, stated once above the object.
+    const text = fs.readFileSync(
+      path.resolve(__dirname, 'gestures.ts'),
+      'utf8',
+    );
+    const end = text.indexOf('export const HAPTIC_VIBRATION_PATTERNS');
+    expect(end).toBeGreaterThan(-1);
+    const block = text.slice(text.lastIndexOf('/**', end), end);
+    const doc = block
+      .split('\n')
+      .map(line => line.trim().replace(/^\/?\*+\/?\s?/, ''))
+      .join('\n');
+    expectSourced('HAPTIC_VIBRATION_PATTERNS', doc);
+  });
+});
+
+/** The JSDoc rules every sourced value follows. */
+function expectSourced(key: string, doc: string) {
+  // Collapse each tag's continuation lines onto it.
+  const tags = doc
+    .split(/\n(?=@)/)
+    .map(tag => tag.replace(/\s*\n\s*/g, ' ').trim())
+    .filter(tag => tag.startsWith('@'));
+  const sources = tags.filter(tag => tag.startsWith('@source '));
+  expect(sources.length, `${key} has no @source`).toBeGreaterThan(0);
+  for (const source of sources) {
+    expect(source, `${key}: unknown source kind`).toMatch(SOURCE_KINDS);
+    if (source.startsWith('@source measured: ')) {
+      expect(source, `${key}: a measurement needs its date`).toMatch(MEASURED);
+    }
+  }
+  const needsMeasurement = sources.some(source =>
+    /^@source (GUESS|webkit)/.test(source),
+  );
+  const measures = tags.filter(tag => tag.startsWith('@measure '));
+  if (needsMeasurement) {
+    expect(
+      measures.length,
+      `${key} is unconfirmed but names no @measure task`,
+    ).toBeGreaterThan(0);
+  }
+  for (const measure of measures) {
+    const id = /^@measure (M-[A-Z0-9]+)$/.exec(measure)?.[1];
+    expect(id, `${key}: malformed ${measure}`).toBeDefined();
+    expect(MEASUREMENTS, `${id} is not in motion/MEASUREMENTS.md`).toMatch(
+      new RegExp(`^\\| ${id} +\\|`, 'm'),
+    );
+  }
+}
+
+describe('UIKit constants table: values', () => {
+  it('names each platform preset for its use, not its source', () => {
+    // spec AST-094 FR4: a role is named for its use; the source stays in the
+    // JSDoc (SwiftUI .smooth, UISpringTimingParameters(), Core Animation's
+    // default curve).
+    expect(springs).toMatchObject({
+      fingerTracking: {response: 0.15, dampingRatio: 0.86},
+      emphasis: {duration: 0.5, bounce: 0.3},
+      settle: {duration: 0.5, bounce: 0},
+      quickChange: {duration: 0.5, bounce: 0.15},
+      viewChange: {mass: 3, stiffness: 1000, damping: 500},
+      timedChange: {duration: 0.5, bounce: 0},
+      stateChange: {response: 0.55, dampingRatio: 1},
+      directChange: {response: 0.5, dampingRatio: 0.825},
+    });
+    expect(timing.stateChangeMs).toBe(250);
+    expect(timing.curves).toEqual({
+      viewChange: [0.25, 0.1, 0.25, 1],
+      move: [0.42, 0, 0.58, 1],
+      exit: [0.42, 0, 1, 1],
+      entrance: [0, 0, 0.58, 1],
+    });
+    const sourceNames = [
+      'smooth',
+      'snappy',
+      'bouncy',
+      'interactive',
+      'uikitDefault',
+      'uikitSpringDuration',
+      'swiftUIDefault',
+      'swiftUISpring',
+    ];
+    for (const name of sourceNames) {
+      expect(springs).not.toHaveProperty(name);
+    }
+    expect(timing).not.toHaveProperty('implicitAnimationMs');
+  });
+
+  it('rows measured on one spring stay equal', () => {
+    // Each row is its own literal so a bundle keeps only the rows it
+    // imports (springRows.test.ts); these were measured to share a spring.
+    for (const group of [
+      // UIKit's default spring.
+      ['viewChange', 'sheetPresent', 'sheetDismiss', 'banner'],
+      ['navigationPush', 'navigationPop'],
+      // The presentation's pace at 80 % damping.
+      ['sheetReleaseFast', 'sheetDismissSwipe'],
+      // UIKit's legacy 0.404 s spring, critically damped.
+      [
+        'alertPresent',
+        'alertDismiss',
+        'actionSheetPresent',
+        'actionSheetDismiss',
+      ],
+      ['menuOpen', 'contextMenuLift'],
+      ['menuClose', 'contextMenuDismiss'],
+    ] as const) {
+      for (const name of group.slice(1)) {
+        expect(springs[name], name).toEqual(springs[group[0]]);
+      }
+    }
+  });
+
+  it('UIKit\u2019s default spring has the documented damping ratio 4.56 before clamping', () => {
+    const {mass, stiffness, damping} = springs.viewChange;
+    expect(damping / (2 * Math.sqrt(stiffness * mass))).toBeCloseTo(4.56, 2);
+  });
+
+  it('deceleration rates are per-millisecond factors in (0, 1), fast below normal', () => {
+    expect(scroll.decelerationRate.fast).toBeLessThan(
+      scroll.decelerationRate.normal,
+    );
+    expect(scroll.decelerationRate.normal).toBeLessThan(1);
+  });
+
+  it('press clocks agree with the touch press model they were measured for', () => {
+    expect(scroll.delaysContentTouchesMs).toBe(PRESS_ONSET_MS);
+    expect(timing.press.flashMs).toBe(PRESS_FLASH_MS);
+    expect(timing.press.highlightOutMs).toBe(PRESS_FADE_MS);
+    expect(timing.press.scrollBrakeMs).toBe(PRESS_SCROLL_BRAKE_MS);
+  });
+
+  it('curves are valid cubic-bézier control points', () => {
+    for (const [x1, , x2] of Object.values(timing.curves)) {
+      expect(x1).toBeGreaterThanOrEqual(0);
+      expect(x2).toBeLessThanOrEqual(1);
+    }
+  });
+});

package/src/motion/uikit/values.test.ts

@@ -0,0 +1,110 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file values.test.ts
+ * @input vitest, the UIKit constants table and the motion math
+ * @output Checks the table's values through the math that plays them: every
+ *   spring is valid and settles; the alert spring is UIKit's legacy
+ *   derivation; a sheet's detent and presentation springs render alike;
+ *   scroll-to-top and the rubber band reproduce what UIKit was measured doing;
+ *   the press release curve is the press model's
+ * @position Testing; the source rules are uikit.test.ts
+ */
+
+import {readFileSync} from 'node:fs';
+import {join} from 'node:path';
+import {describe, expect, it} from 'vitest';
+import {solveDecay} from '../decay';
+import {rubberBand} from '../rubberBand';
+import {
+  naturalFrequency,
+  settlingDuration,
+  springFromUIKitDampingDuration,
+  toSpring,
+  type SpringDescription,
+} from '../spring';
+import {scroll, springs} from '.';
+import {press} from './timing';
+
+describe('UIKit constants table through the motion math', () => {
+  const springEntries: [string, SpringDescription][] = [
+    ...Object.entries(springs),
+    ['scroll.bounce', scroll.bounce],
+    ['scroll.paging.snap', scroll.paging.snap],
+  ];
+
+  it.each(springEntries)(
+    '%s is a valid spring that settles',
+    (_, description) => {
+      const spring = toSpring(description);
+      const settle = settlingDuration(spring);
+      expect(settle).toBeGreaterThan(0.05);
+      expect(settle).toBeLessThan(2);
+    },
+  );
+
+  it('the alert spring is UIKit\u2019s legacy derivation at 0.404 s, critically damped', () => {
+    // UIKit asks for damping 600 (clamped to 1) over 0.404 s; the measured
+    // grid predicts the spring Core Animation was handed.
+    const derived = springFromUIKitDampingDuration({
+      duration: 0.404,
+      dampingRatio: 1,
+    });
+    expect(derived.stiffness).toBeCloseTo(springs.alertPresent.stiffness, 1);
+    expect(derived.damping).toBeCloseTo(springs.alertPresent.damping, 2);
+  });
+
+  it('a sheet\u2019s detent spring is its presentation spring as rendered (critical, same pace)', () => {
+    // Core Animation clamps UIKit\u2019s default spring to critical damping.
+    expect(naturalFrequency(toSpring(springs.sheetDetent))).toBeCloseTo(
+      naturalFrequency(toSpring(springs.sheetPresent)),
+      6,
+    );
+  });
+
+  it('scroll-to-top as a decay lands on the top along the measured curve', () => {
+    // 2000 pt from the top: remaining distance every ~50 ms after the start.
+    const measured = [1257, 768, 475, 296, 186, 118];
+    const coast = solveDecay({
+      from: 0,
+      velocity: 9.7 * 2000,
+      rate: scroll.scrollToTopRate,
+    });
+    expect(coast.rest).toBeCloseTo(2000, -1);
+    measured.forEach((remaining, i) => {
+      expect(
+        Math.abs(2000 - coast.value((i + 1) * 0.05) - remaining),
+      ).toBeLessThan(30);
+    });
+  });
+
+  it('the rubber band reproduces UIScrollView\u2019s released overscroll', () => {
+    // Finger 100 / 300 / 600 pt past the edge of an 874 pt view, minus the
+    // pan\u2019s 10 pt hysteresis.
+    const cases: [number, number][] = [
+      [90, 47],
+      [290, 135],
+      [590, 236.67],
+    ];
+    for (const [overflow, shown] of cases) {
+      expect(
+        Math.abs(
+          rubberBand(overflow, 874, scroll.rubberBand.coefficient) - shown,
+        ),
+      ).toBeLessThan(0.5);
+    }
+  });
+
+  it('the press release curve is the press model\u2019s RELEASE_EASE', () => {
+    // The table records the curve the touch press model ships with; this pins
+    // the two together so neither drifts alone.
+    const source = readFileSync(
+      join(__dirname, '../../utils/interactionOverlay.stylex.ts'),
+      'utf8',
+    );
+    const match = /const RELEASE_EASE = 'cubic-bezier\(([^)]*)\)'/.exec(source);
+    expect(match?.[1].split(',').map(Number)).toEqual([
+      ...press.highlightOutCurve,
+    ]);
+  });
+});

package/src/reset.a11y.chromium.spec.ts

@@ -1,4 +1,5 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
+// @pr-a11y release-only
 
 /**
  * @file reset.a11y.chromium.spec.ts

package/src/reset.until-found.a11y.browser.spec.ts

@@ -1,4 +1,5 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
+// @pr-a11y release-only
 
 /**
  * @file reset.until-found.a11y.browser.spec.ts