@astryxdesign/core 0.7.5-canary.fccd771 → 0.7.5

package/src/gestures/__tests__/fixtures/pointer-streams/ios-safari-slow.json

@@ -0,0 +1,101 @@
+{
+  "schema": 1,
+  "platform": "iOS 26.2 simulator, iPhone 17 Pro",
+  "browser": "Safari 26.2",
+  "ua": "Mozilla/5.0 (iPhone; CPU iPhone OS 18_7 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/26.2 Mobile/15E148 Safari/604.1",
+  "dpr": 3,
+  "pointerType": "touch",
+  "coarse": true,
+  "gesture": "slow",
+  "caveat": "Rig input is synthetic, not a finger: Android injects at 120 Hz through a uinput touchscreen and desktop through CDP, each through the browser's real input pipeline; iOS input is HID through idb on a leased simulator, which delivers a move every ~30 ms (not 120 Hz), so iOS speeds are the distance Safari delivered between the first and last moving pointermove, over that time. A physical finger's 120–240 Hz jittered sampling is not reproduced.",
+  "injected": {
+    "source": "idb ui swipe (companion-side steps of 6 pt), iOS 26.2 simulator, iPhone 17 Pro; the companion delivers a step about every 30 ms (measured), not at a set rate",
+    "hz": null,
+    "commanded": {
+      "fromPx": [0, 0],
+      "toPx": [0, 200],
+      "deltaPt": 6,
+      "durationMs": 330
+    },
+    "speed": 183.538,
+    "restMs": 0,
+    "speedFrom": "Safari's delivery: the first to the last moving pointermove"
+  },
+  "release": {
+    "at": "lastMove",
+    "check": "shape",
+    "note": "idb lifts 85 ms after the last move, longer than the 40 ms stillness interval, which a finger lifting mid-motion does not do: the replay releases at the last move. The simulator delivers each step 29-44 ms apart: against the speed Safari delivered, from its first to its last moving pointermove, the pan release reads 22.9% under and the scroll release 2.3% over. One misses 10%, so this drag is not velocity evidence, and only its direction and axis are checked"
+  },
+  "liftAfterLastMoveMs": 85,
+  "events": [
+    ["pointerdown", 0, 0, 0],
+    ["touchstart", 0, 0, 0],
+    ["pointermove", 48, 0, 6, [[48, 0, 6]], 0],
+    ["touchmove", 48, 0, 6],
+    ["pointermove", 48, 0, 6, [[48, 0, 6]], 0],
+    ["pointermove", 90, 0, 18.333, [[90, 0, 18.333]], 0],
+    ["touchmove", 90, 0, 18.333],
+    ["pointermove", 119, 0, 24.333, [[119, 0, 24.333]], 0],
+    ["touchmove", 119, 0, 24.333],
+    ["pointermove", 161, 0, 30.333, [[161, 0, 30.333]], 0],
+    ["touchmove", 161, 0, 30.333],
+    ["pointermove", 190, 0, 36.333, [[190, 0, 36.333]], 0],
+    ["touchmove", 190, 0, 36.333],
+    ["pointermove", 220, 0, 42.333, [[220, 0, 42.333]], 0],
+    ["touchmove", 220, 0, 42.333],
+    ["pointermove", 260, 0, 48.333, [[260, 0, 48.333]], 1],
+    ["touchmove", 260, 0, 48.333],
+    ["pointermove", 290, 0, 54.667, [[290, 0, 54.667]], 1],
+    ["touchmove", 290, 0, 54.667],
+    ["pointermove", 320, 0, 60.667, [[320, 0, 60.667]], 1],
+    ["touchmove", 320, 0, 60.667],
+    ["pointermove", 361, 0, 66.667, [[361, 0, 66.667]], 2],
+    ["touchmove", 361, 0, 66.667],
+    ["pointermove", 390, 0, 72.667, [[390, 0, 72.667]], 2],
+    ["touchmove", 390, 0, 72.667],
+    ["pointermove", 419, 0, 78.667, [[419, 0, 78.667]], 2],
+    ["touchmove", 419, 0, 78.667],
+    ["pointermove", 461, 0, 85, [[461, 0, 85]], 2],
+    ["touchmove", 461, 0, 85],
+    ["pointermove", 490, 0, 91, [[490, 0, 91]], 3],
+    ["touchmove", 490, 0, 91],
+    ["pointermove", 519, 0, 97, [[519, 0, 97]], 3],
+    ["touchmove", 519, 0, 97],
+    ["pointermove", 561, 0, 103, [[561, 0, 103]], 3],
+    ["touchmove", 561, 0, 103],
+    ["pointermove", 593, 0, 109, [[593, 0, 109]], 3],
+    ["touchmove", 593, 0, 109],
+    ["pointermove", 619, 0, 115, [[619, 0, 115]], 3],
+    ["touchmove", 619, 0, 115],
+    ["pointermove", 661, 0, 121.333, [[661, 0, 121.333]], 3],
+    ["touchmove", 661, 0, 121.333],
+    ["pointermove", 690, 0, 127.333, [[690, 0, 127.333]], 3],
+    ["touchmove", 690, 0, 127.333],
+    ["pointermove", 719, 0, 133.333, [[719, 0, 133.333]], 3],
+    ["touchmove", 719, 0, 133.333],
+    ["pointermove", 761, 0, 139.333, [[761, 0, 139.333]], 4],
+    ["touchmove", 761, 0, 139.333],
+    ["pointermove", 790, 0, 145.333, [[790, 0, 145.333]], 4],
+    ["touchmove", 790, 0, 145.333],
+    ["pointermove", 820, 0, 151.667, [[820, 0, 151.667]], 4],
+    ["touchmove", 820, 0, 151.667],
+    ["pointermove", 862, 0, 157.667, [[862, 0, 157.667]], 4],
+    ["touchmove", 862, 0, 157.667],
+    ["pointermove", 890, 0, 163.667, [[890, 0, 163.667]], 4],
+    ["touchmove", 890, 0, 163.667],
+    ["pointermove", 927, 0, 169.667, [[927, 0, 169.667]], 4],
+    ["touchmove", 927, 0, 169.667],
+    ["pointermove", 961, 0, 175.667, [[961, 0, 175.667]], 4],
+    ["touchmove", 961, 0, 175.667],
+    ["pointermove", 990, 0, 181.667, [[990, 0, 181.667]], 4],
+    ["touchmove", 990, 0, 181.667],
+    ["pointermove", 1019, 0, 188, [[1019, 0, 188]], 4],
+    ["touchmove", 1019, 0, 188],
+    ["pointermove", 1061, 0, 194, [[1061, 0, 194]], 4],
+    ["touchmove", 1061, 0, 194],
+    ["pointermove", 1105, 0, 200, [[1105, 0, 200]], 4],
+    ["touchmove", 1105, 0, 200],
+    ["pointerup", 1190, 0, 200],
+    ["touchend", 1190, 0, 200]
+  ]
+}

package/src/gestures/__tests__/fixtures/pointer-streams/ios-safari-stop-release.json

@@ -0,0 +1,130 @@
+{
+  "schema": 1,
+  "platform": "iOS 26.2 simulator, iPhone 17 Pro",
+  "browser": "Safari 26.2",
+  "ua": "Mozilla/5.0 (iPhone; CPU iPhone OS 18_7 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/26.2 Mobile/15E148 Safari/604.1",
+  "dpr": 3,
+  "pointerType": "touch",
+  "coarse": true,
+  "gesture": "stop-release",
+  "caveat": "Rig input is synthetic, not a finger: Android injects at 120 Hz through a uinput touchscreen and desktop through CDP, each through the browser's real input pipeline; iOS input is HID through idb on a leased simulator, which delivers a move every ~30 ms (not 120 Hz), so iOS speeds are the distance Safari delivered between the first and last moving pointermove, over that time. A physical finger's 120–240 Hz jittered sampling is not reproduced.",
+  "injected": {
+    "source": "one continuous touch through idb's HID API, iOS 26.2 simulator, iPhone 17 Pro; moves delivered about every 45 ms (measured), then held still before the lift",
+    "hz": null,
+    "commanded": {
+      "fromPx": [0, 0],
+      "toPx": [0, 200],
+      "stillMs": 300
+    },
+    "speed": 87.822,
+    "speedFrom": "Safari's delivery: the first to the last moving pointermove",
+    "restMs": 300
+  },
+  "release": {
+    "at": "pointerup"
+  },
+  "liftAfterLastMoveMs": 400,
+  "events": [
+    ["pointerdown", 0, 0, 0],
+    ["touchstart", 0, 0, 0],
+    ["pointermove", 49, 0, 4.333, [[49, 0, 4.333]], 0],
+    ["touchmove", 49, 0, 4.333],
+    ["pointermove", 49, 0, 4.333, [[49, 0, 4.333]], 0],
+    ["pointermove", 79, 0, 8.333, [[79, 0, 8.333]], 0],
+    ["touchmove", 79, 0, 8.333],
+    ["pointermove", 135, 0, 12.333, [[135, 0, 12.333]], 0],
+    ["touchmove", 135, 0, 12.333],
+    ["pointermove", 208, 0, 16.667, [[208, 0, 16.667]], 0],
+    ["touchmove", 208, 0, 16.667],
+    ["pointermove", 235, 0, 20.667, [[235, 0, 20.667]], 0],
+    ["touchmove", 235, 0, 20.667],
+    ["pointermove", 276, 0, 25, [[276, 0, 25]], 0],
+    ["touchmove", 276, 0, 25],
+    ["pointermove", 335, 0, 29.333, [[335, 0, 29.333]], 1],
+    ["touchmove", 335, 0, 29.333],
+    ["pointermove", 407, 0, 33.333, [[407, 0, 33.333]], 1],
+    ["touchmove", 407, 0, 33.333],
+    ["pointermove", 435, 0, 37.667, [[435, 0, 37.667]], 2],
+    ["touchmove", 435, 0, 37.667],
+    ["pointermove", 476, 0, 41.667, [[476, 0, 41.667]], 2],
+    ["touchmove", 476, 0, 41.667],
+    ["pointermove", 536, 0, 45.667, [[536, 0, 45.667]], 3],
+    ["touchmove", 536, 0, 45.667],
+    ["pointermove", 578, 0, 50, [[578, 0, 50]], 3],
+    ["touchmove", 578, 0, 50],
+    ["pointermove", 638, 0, 54.333, [[638, 0, 54.333]], 3],
+    ["touchmove", 638, 0, 54.333],
+    ["pointermove", 681, 0, 58.333, [[681, 0, 58.333]], 4],
+    ["touchmove", 681, 0, 58.333],
+    ["pointermove", 735, 0, 62.667, [[735, 0, 62.667]], 4],
+    ["touchmove", 735, 0, 62.667],
+    ["pointermove", 779, 0, 66.667, [[779, 0, 66.667]], 4],
+    ["touchmove", 779, 0, 66.667],
+    ["pointermove", 837, 0, 70.667, [[837, 0, 70.667]], 4],
+    ["touchmove", 837, 0, 70.667],
+    ["pointermove", 880, 0, 75, [[880, 0, 75]], 4],
+    ["touchmove", 880, 0, 75],
+    ["pointermove", 935, 0, 79.333, [[935, 0, 79.333]], 4],
+    ["touchmove", 935, 0, 79.333],
+    ["pointermove", 978, 0, 83.333, [[978, 0, 83.333]], 4],
+    ["touchmove", 978, 0, 83.333],
+    ["pointermove", 1036, 0, 87.667, [[1036, 0, 87.667]], 4],
+    ["touchmove", 1036, 0, 87.667],
+    ["pointermove", 1077, 0, 91.667, [[1077, 0, 91.667]], 4],
+    ["touchmove", 1077, 0, 91.667],
+    ["pointermove", 1106, 0, 95.667, [[1106, 0, 95.667]], 4],
+    ["touchmove", 1106, 0, 95.667],
+    ["pointermove", 1137, 0, 100, [[1137, 0, 100]], 4],
+    ["touchmove", 1137, 0, 100],
+    ["pointermove", 1177, 0, 104.333, [[1177, 0, 104.333]], 4],
+    ["touchmove", 1177, 0, 104.333],
+    ["pointermove", 1236, 0, 108.333, [[1236, 0, 108.333]], 4],
+    ["touchmove", 1236, 0, 108.333],
+    ["pointermove", 1276, 0, 112.667, [[1276, 0, 112.667]], 4],
+    ["touchmove", 1276, 0, 112.667],
+    ["pointermove", 1335, 0, 116.667, [[1335, 0, 116.667]], 4],
+    ["touchmove", 1335, 0, 116.667],
+    ["pointermove", 1406, 0, 120.667, [[1406, 0, 120.667]], 4],
+    ["touchmove", 1406, 0, 120.667],
+    ["pointermove", 1479, 0, 125, [[1479, 0, 125]], 4],
+    ["touchmove", 1479, 0, 125],
+    ["pointermove", 1535, 0, 129.333, [[1535, 0, 129.333]], 4],
+    ["touchmove", 1535, 0, 129.333],
+    ["pointermove", 1577, 0, 133.333, [[1577, 0, 133.333]], 4],
+    ["touchmove", 1577, 0, 133.333],
+    ["pointermove", 1635, 0, 137.667, [[1635, 0, 137.667]], 4],
+    ["touchmove", 1635, 0, 137.667],
+    ["pointermove", 1677, 0, 141.667, [[1677, 0, 141.667]], 4],
+    ["touchmove", 1677, 0, 141.667],
+    ["pointermove", 1707, 0, 145.667, [[1707, 0, 145.667]], 4],
+    ["touchmove", 1707, 0, 145.667],
+    ["pointermove", 1735, 0, 150, [[1735, 0, 150]], 4],
+    ["touchmove", 1735, 0, 150],
+    ["pointermove", 1778, 0, 154.333, [[1778, 0, 154.333]], 4],
+    ["touchmove", 1778, 0, 154.333],
+    ["pointermove", 1836, 0, 158.333, [[1836, 0, 158.333]], 4],
+    ["touchmove", 1836, 0, 158.333],
+    ["pointermove", 1878, 0, 162.667, [[1878, 0, 162.667]], 4],
+    ["touchmove", 1878, 0, 162.667],
+    ["pointermove", 1935, 0, 166.667, [[1935, 0, 166.667]], 4],
+    ["touchmove", 1935, 0, 166.667],
+    ["pointermove", 1977, 0, 170.667, [[1977, 0, 170.667]], 4],
+    ["touchmove", 1977, 0, 170.667],
+    ["pointermove", 2006, 0, 175, [[2006, 0, 175]], 4],
+    ["touchmove", 2006, 0, 175],
+    ["pointermove", 2035, 0, 179.333, [[2035, 0, 179.333]], 4],
+    ["touchmove", 2035, 0, 179.333],
+    ["pointermove", 2079, 0, 183.333, [[2079, 0, 183.333]], 4],
+    ["touchmove", 2079, 0, 183.333],
+    ["pointermove", 2135, 0, 187.667, [[2135, 0, 187.667]], 4],
+    ["touchmove", 2135, 0, 187.667],
+    ["pointermove", 2177, 0, 191.667, [[2177, 0, 191.667]], 4],
+    ["touchmove", 2177, 0, 191.667],
+    ["pointermove", 2235, 0, 195.667, [[2235, 0, 195.667]], 4],
+    ["touchmove", 2235, 0, 195.667],
+    ["pointermove", 2277, 0, 200, [[2277, 0, 200]], 4],
+    ["touchmove", 2277, 0, 200],
+    ["pointerup", 2677, 0, 200],
+    ["touchend", 2677, 0, 200]
+  ]
+}

package/src/gestures/__tests__/harness.ts

@@ -0,0 +1,204 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file harness.ts
+ * @input Nothing
+ * @output Exports the synthetic-input harness the gesture tests share: a
+ *   manual clock, an arena wired to a transition log, and fingers that land,
+ *   move and lift at explicit timestamps
+ * @position Test-only helper of packages/core/src/gestures (excluded from the
+ *   build with the rest of __tests__)
+ */
+
+import {GestureArena, type GestureClock} from '../GestureArena';
+import type {GestureRecognizer} from '../GestureRecognizer';
+import type {
+  GestureEnvironment,
+  GestureTouch,
+  NativeScrollProbe,
+  TouchConsumer,
+} from '../types';
+
+/** A clock that only moves when the test says so. */
+export class ManualClock implements GestureClock {
+  time = 0;
+  now(): number {
+    return this.time;
+  }
+  setTimeout(): number {
+    return 0;
+  }
+  clearTimeout(): void {}
+}
+
+export interface Harness {
+  arena: GestureArena;
+  clock: ManualClock;
+  /** `name:state` for every transition, in order, with its time. */
+  log: string[];
+  /** Touch ids claimed from the browser, in order. */
+  claims: number[];
+  /** Deferred clicks as they resolved. */
+  deferredClicks: {id: number; allowed: boolean; time: number}[];
+  environment: {width: number; height: number; rtl: boolean};
+  finger(id: number): Finger;
+  /** Advance the clock and run every timer due by `time`. */
+  advance(time: number): void;
+}
+
+export function createHarness(): Harness {
+  const clock = new ManualClock();
+  const log: string[] = [];
+  const claims: number[] = [];
+  const deferredClicks: Harness['deferredClicks'] = [];
+  const environment = {width: 390, height: 844, rtl: false};
+  const fingers = new Map<number, Finger>();
+  const env: GestureEnvironment = {
+    viewportSize: () => ({
+      width: environment.width,
+      height: environment.height,
+    }),
+    isRtl: () => environment.rtl,
+  };
+  const arena: GestureArena = new GestureArena({
+    clock,
+    environment: env,
+    onTransition: (recognizer, _from, to) => {
+      log.push(`${recognizer.name}:${to}@${round(arena.now())}`);
+    },
+    onClaim: ids => claims.push(...ids),
+    onDeferredClick: (touch, allowed) =>
+      deferredClicks.push({id: touch.id, allowed, time: arena.now()}),
+  });
+  const harness: Harness = {
+    arena,
+    clock,
+    log,
+    claims,
+    deferredClicks,
+    environment,
+    finger: id => {
+      let finger = fingers.get(id);
+      if (finger == null) {
+        finger = new Finger(harness, id);
+        fingers.set(id, finger);
+      }
+      return finger;
+    },
+    advance: time => {
+      clock.time = time;
+      arena.advanceTime(time);
+    },
+  };
+  return harness;
+}
+
+function round(value: number): number {
+  return Math.round(value * 100) / 100;
+}
+
+export interface DownOptions {
+  recognizers: ReadonlyArray<GestureRecognizer>;
+  consumer?: TouchConsumer | null;
+  scroll?: NativeScrollProbe | null;
+  pointerType?: 'touch' | 'mouse' | 'pen';
+  target?: unknown;
+}
+
+/** One contact, driven with explicit timestamps. */
+export class Finger {
+  x = 0;
+  y = 0;
+  time = 0;
+  constructor(
+    private readonly harness: Harness,
+    readonly id: number,
+  ) {}
+
+  down(x: number, y: number, time: number, options: DownOptions): this {
+    this.x = x;
+    this.y = y;
+    this.time = time;
+    this.harness.clock.time = time;
+    this.harness.arena.began([
+      {
+        id: this.id,
+        x,
+        y,
+        time,
+        pointerType: options.pointerType ?? 'touch',
+        target: options.target ?? null,
+        scroll: options.scroll ?? null,
+        recognizers: options.recognizers,
+        consumer: options.consumer ?? null,
+      },
+    ]);
+    return this;
+  }
+
+  move(x: number, y: number, time: number): this {
+    this.x = x;
+    this.y = y;
+    this.time = time;
+    this.harness.clock.time = time;
+    this.harness.arena.moved([{id: this.id, x, y, time}]);
+    return this;
+  }
+
+  /** Move in `steps` equal steps over `duration` ms. */
+  drag(dx: number, dy: number, duration: number, steps = 8): this {
+    const x0 = this.x;
+    const y0 = this.y;
+    const t0 = this.time;
+    for (let i = 1; i <= steps; i++) {
+      const k = i / steps;
+      this.move(x0 + dx * k, y0 + dy * k, t0 + duration * k);
+    }
+    return this;
+  }
+
+  up(time: number, x = this.x, y = this.y) {
+    this.time = time;
+    this.harness.clock.time = time;
+    return this.harness.arena.ended([{id: this.id, x, y, time}]).get(this.id);
+  }
+
+  cancel(time: number): void {
+    this.harness.clock.time = time;
+    this.harness.arena.cancelled([this.id], time);
+  }
+
+  takenByBrowser(time: number): void {
+    this.harness.clock.time = time;
+    this.harness.arena.browserTookOver([this.id], time);
+  }
+}
+
+/** A consumer that records what the arena delivered to it. */
+export class RecordingConsumer implements TouchConsumer {
+  events: string[] = [];
+  veto: ((recognizer: unknown) => boolean) | null = null;
+  touchBegan(touch: GestureTouch): void {
+    this.events.push(`began:${touch.id}`);
+  }
+  touchMoved(touch: GestureTouch): void {
+    this.events.push(`moved:${touch.id}`);
+  }
+  touchEnded(touch: GestureTouch): void {
+    this.events.push(`ended:${touch.id}`);
+  }
+  touchCancelled(touch: GestureTouch): void {
+    this.events.push(`cancelled:${touch.id}`);
+  }
+  allowsAncestorRecognizer(recognizer: unknown): boolean {
+    return this.veto == null ? true : !this.veto(recognizer);
+  }
+}
+
+/** A scroll probe with a scripted answer. */
+export function scrollProbe(
+  canScroll: (dx: number, dy: number) => boolean,
+  isInsideScroller = true,
+): NativeScrollProbe {
+  return {canScroll, isInsideScroller, allowsNativePan: true};
+}

package/src/gestures/geometry.ts

@@ -0,0 +1,55 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file geometry.ts
+ * @input Touches
+ * @output Exports the small geometry helpers recognizers share: centroid,
+ *   distance, span and angle of two touches, angle unwrapping
+ * @position Pure helpers under packages/core/src/gestures
+ */
+
+import type {GestureTouch, Point} from './types';
+
+export function centroid(
+  touches: Iterable<GestureTouch>,
+  excluding?: ReadonlySet<number>,
+): Point {
+  let x = 0;
+  let y = 0;
+  let count = 0;
+  for (const touch of touches) {
+    if (excluding?.has(touch.id)) {
+      continue;
+    }
+    x += touch.x;
+    y += touch.y;
+    count += 1;
+  }
+  return count === 0 ? {x: 0, y: 0} : {x: x / count, y: y / count};
+}
+
+export function distance(a: Point, b: Point): number {
+  return Math.hypot(a.x - b.x, a.y - b.y);
+}
+
+/** How far a touch is from where it landed. */
+export function travel(touch: GestureTouch): number {
+  return Math.hypot(touch.x - touch.startX, touch.y - touch.startY);
+}
+
+/** The angle of the vector from the first touch to the second, radians. */
+export function angleBetween(a: Point, b: Point): number {
+  return Math.atan2(b.y - a.y, b.x - a.x);
+}
+
+/** `angle` shifted by whole turns to be within half a turn of `reference`. */
+export function unwrapAngle(angle: number, reference: number): number {
+  let result = angle;
+  while (result - reference > Math.PI) {
+    result -= 2 * Math.PI;
+  }
+  while (result - reference < -Math.PI) {
+    result += 2 * Math.PI;
+  }
+  return result;
+}

package/src/gestures/types.ts

@@ -0,0 +1,161 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file types.ts
+ * @input Nothing
+ * @output Exports the data the gesture system passes around: recognizer
+ *   states, pointer kinds, touches (UITouch), the per-event context, the
+ *   environment a host provides, and the view-level touch consumer contract
+ * @position Shared vocabulary of packages/core/src/gestures; no runtime code
+ */
+
+/**
+ * UIGestureRecognizer.State. A discrete recognizer goes straight from
+ * `possible` to `ended` (UIKit's `.recognized` is the same value).
+ */
+export type GestureState =
+  'possible' | 'began' | 'changed' | 'ended' | 'cancelled' | 'failed';
+
+/** What made the contact. A pen on an iPad is `pen`, not `touch`. */
+export type PointerKind = 'touch' | 'mouse' | 'pen';
+
+export interface Point {
+  readonly x: number;
+  readonly y: number;
+}
+
+/** One position of a contact at one instant, in client (viewport) CSS px. */
+export interface TouchSample {
+  readonly x: number;
+  readonly y: number;
+  /** Milliseconds on the `performance.now()` clock (an event's `timeStamp`). */
+  readonly time: number;
+}
+
+export type TouchPhase = 'began' | 'moved' | 'ended' | 'cancelled';
+
+/**
+ * The scrollers between a touch and the page, as the host sees them: enough
+ * for a recognizer to ask whether the browser would scroll something if the
+ * finger moved one way, without the recognizer touching the DOM.
+ */
+export interface NativeScrollProbe {
+  /**
+   * Whether a finger moving by (dx, dy) would scroll some element under the
+   * touch (one that has room left in that direction and whose `touch-action`
+   * lets the browser pan that axis).
+   */
+  canScroll(dx: number, dy: number): boolean;
+  /**
+   * How much further (px) the scroller that would move for a finger moving
+   * by (dx, dy) can scroll before it reaches its edge; 0 when none would.
+   * Lets a reader place the point where the content runs out between two
+   * samples instead of at the next one.
+   */
+  distanceToEdge?(dx: number, dy: number): number;
+  /** Whether any element under the touch can scroll natively at all. */
+  readonly isInsideScroller: boolean;
+  /**
+   * Whether `touch-action` from the touch target to the page lets the
+   * browser pan at all: when it does not, the browser cannot have taken the
+   * touch for a scroll, whatever its events say.
+   */
+  readonly allowsNativePan: boolean;
+}
+
+/**
+ * One contact: UITouch. The arena owns it and updates it in place; a
+ * recognizer keeps a reference to every touch it receives.
+ */
+export interface GestureTouch {
+  /** Unique among the contacts the arena tracks at once. */
+  readonly id: number;
+  readonly pointerType: PointerKind;
+  phase: TouchPhase;
+  /** Latest position, client CSS px. */
+  x: number;
+  y: number;
+  /** Timestamp of the latest position. */
+  time: number;
+  readonly startX: number;
+  readonly startY: number;
+  readonly startTime: number;
+  /**
+   * Positions since the previous event, oldest first, ending with the
+   * current one (coalesced samples where the platform has them). Velocity
+   * trackers read these; actions fire once per event.
+   */
+  samples: TouchSample[];
+  /** The node the contact began on. Opaque to the arena. */
+  readonly target: unknown;
+  /** The native scrollers under the contact, when the host knows them. */
+  readonly scroll: NativeScrollProbe | null;
+  /** The browser took this contact for its own pan or zoom. */
+  takenByBrowser: boolean;
+}
+
+/** The input a host hands the arena for one contact in one event. */
+export interface TouchInput {
+  readonly id: number;
+  readonly x: number;
+  readonly y: number;
+  readonly time: number;
+  /** Extra positions since the previous event, oldest first (coalesced). */
+  readonly history?: ReadonlyArray<TouchSample>;
+}
+
+/** A new contact: where it is, what made it, and what it landed on. */
+export interface TouchBeganInput extends TouchInput {
+  readonly pointerType: PointerKind;
+  readonly target: unknown;
+  readonly scroll?: NativeScrollProbe | null;
+}
+
+/** What a recognizer is told alongside the touches that changed. */
+export interface GestureEventContext {
+  /** Timestamp of the event being processed. */
+  readonly time: number;
+  /** Every contact the arena currently tracks, not only this recognizer's. */
+  readonly allTouches: ReadonlyArray<GestureTouch>;
+}
+
+/**
+ * Facts about the page a recognizer may need and must not read from the DOM
+ * itself: the viewport for screen-edge pans, and the writing direction of a
+ * view for `leading` / `trailing`.
+ */
+export interface GestureEnvironment {
+  viewportSize(): {readonly width: number; readonly height: number};
+  isRtl(view: unknown): boolean;
+}
+
+export const DEFAULT_ENVIRONMENT: GestureEnvironment = {
+  viewportSize() {
+    if (typeof window === 'undefined') {
+      return {width: 0, height: 0};
+    }
+    return {width: window.innerWidth, height: window.innerHeight};
+  },
+  isRtl() {
+    return false;
+  },
+};
+
+/**
+ * A view-level touch consumer: what UIKit delivers `touchesBegan` /
+ * `touchesEnded` to when no gesture recognizer takes the touch (a UIControl).
+ * The arena delivers through it, honoring `delaysTouchesBegan`,
+ * `delaysTouchesEnded` and `cancelsTouchesInView`.
+ */
+export interface TouchConsumer {
+  touchBegan(touch: GestureTouch): void;
+  touchMoved(touch: GestureTouch): void;
+  touchEnded(touch: GestureTouch): void;
+  touchCancelled(touch: GestureTouch): void;
+  /**
+   * UIControl's iOS 6 rule: a control's own action wins over an overlapping
+   * single-tap recognizer on an ancestor. Return false to stop `recognizer`
+   * (attached above this consumer) from beginning for a touch on it.
+   */
+  allowsAncestorRecognizer?(recognizer: unknown): boolean;
+}

package/src/hooks/AnnounceRenderedText.tsx

@@ -0,0 +1,27 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file AnnounceRenderedText.tsx
+ * @input Uses React, useAnnounceRenderedText
+ * @output Exports AnnounceRenderedText (internal; not re-exported from
+ *   hooks/index.ts, so it ships no public API without `spec:AST-002`)
+ * @position Internal client island that lets a presentational, server-safe
+ *   component announce its own content; rendered by EmptyState around its
+ *   message. On the server it only renders its `div`: effects never run there.
+ */
+
+import {useRef, type HTMLAttributes} from 'react';
+import {useAnnounceRenderedText} from './useAnnounceRenderedText';
+
+/**
+ * A `div` whose rendered text is announced once through the shared polite
+ * live region when it appears or changes after the page loaded, and never for
+ * text present when the page first rendered (`spec:AST-086` FR11).
+ */
+export function AnnounceRenderedText(props: HTMLAttributes<HTMLDivElement>) {
+  const ref = useRef<HTMLDivElement>(null);
+  useAnnounceRenderedText(ref, true, '', {skipFirstRender: true});
+  return <div ref={ref} {...props} />;
+}