@keepsnappy/react-native 0.0.0-stage → 0.1.0-alpha.11

package/js/sdk/interactions.ts

@@ -0,0 +1,531 @@
+// Generic interaction windows. React Native's Fabric renderer emits every
+// native event to RawEventEmitter before any handler runs; touch payloads carry
+// the touched view's native tag and the hardware touch time. A press window
+// opens at that time, is named from the touched fiber, and ends at the next
+// touch, when the app goes to the background, or when the run is flushed; never
+// after a quiet period. A touch that turns into a drag is renamed after
+// the scroll view it moved, not the row under the finger, so the name is the
+// same in every run.
+
+import { AppState, Keyboard } from 'react-native';
+
+import { type CauseRoot, currentCause } from './causes';
+import {
+  entries,
+  fmt,
+  isFaultTarget,
+  isWindowOpen,
+  lastRoot,
+  markers,
+  now,
+  perfLog,
+  runDeferredFault,
+  runOpenFaults,
+  settings,
+  writeRunEvent,
+} from './core';
+import {
+  describeScrollContainer,
+  describeTarget,
+  type Fiber,
+  findInTree,
+  hostFiber,
+  propsOf,
+  type ScrollContainer,
+  type TargetDescription,
+} from './fiber';
+
+const DRAG_SLOP_PT = 10;
+const LONG_PRESS_MS = 500;
+
+interface RawEvent {
+  eventName: string;
+  nativeEvent: Record<string, unknown>;
+}
+
+interface Emitter {
+  addListener(type: string, listener: (event: RawEvent) => void): unknown;
+}
+
+interface ActivePress {
+  key: string;
+  seq: number;
+  target: TargetDescription;
+  host: Fiber | null;
+  container: ScrollContainer | null;
+  identifier: unknown;
+  touchStartT: number;
+  touchEndT: number | null;
+  startX: number;
+  startY: number;
+  maxMovePt: number;
+  maxDxPt: number;
+  maxDyPt: number;
+  scrolled: boolean;
+  /** The touch was cancelled by the scroll view above it (it took the gesture, e.g. on a list still moving from a fling). */
+  takenByScroll: boolean;
+  focused: boolean;
+  kind: 'press' | 'drag' | null;
+  faultsRun: boolean;
+}
+
+const rawStats = {
+  events: {} as Record<string, number>,
+  listenerN: 0,
+  listenerSumMs: 0,
+  listenerMaxMs: 0,
+  errors: 0,
+};
+
+export const interactionStats = () => ({
+  ...rawStats,
+  events: { ...rawStats.events },
+});
+
+let seq = 0;
+let active: ActivePress | null = null;
+// `cause`: the touch's own cause root (the cause tracker's listener runs before this one).
+let lastPress: { t0: number; name: string; cause: CauseRoot | null } | null = null;
+
+export const lastPressStart = () => lastPress;
+
+export const resetLastPressForTest = () => {
+  lastPress = null;
+};
+
+const pressStartListeners = new Set<(t0: number) => void>();
+
+export const onPressStart = (listener: (t0: number) => void) => {
+  pressStartListeners.add(listener);
+};
+
+// react-native-screens lifecycle events (and RN Modal `show`, kept for S4).
+// The listener only buffers them; names are resolved later, off this path.
+const NATIVE_SCREEN_EVENTS = new Set([
+  'willAppear',
+  'appear',
+  'willDisappear',
+  'disappear',
+  'dismissed',
+  'sheetDetentChanged',
+  'finishTransitioning',
+  'gestureCancel',
+  'nativeDismissCancelled',
+  'show',
+]);
+
+export interface NativeScreenEvent {
+  type: string;
+  tag: number | null;
+  // Native creation time (Fabric `timeStamp`), performance.now() timebase.
+  t: number;
+  deliveredT: number;
+  host: Fiber | null;
+  hostType: string | null;
+  resolution: unknown;
+}
+
+const MAX_NATIVE_EVENTS = 200;
+export const nativeScreenEvents: NativeScreenEvent[] = [];
+const nativeLag = { n: 0, sumMs: 0, maxMs: 0, missingTimeStamp: 0 };
+const nativeEventListeners = new Set<(event: NativeScreenEvent) => void>();
+
+export const onNativeScreenEvent = (
+  listener: (event: NativeScreenEvent) => void,
+) => {
+  nativeEventListeners.add(listener);
+};
+
+export const nativeLagStats = () => ({
+  n: nativeLag.n,
+  meanMs: nativeLag.n === 0 ? null : nativeLag.sumMs / nativeLag.n,
+  maxMs: nativeLag.maxMs,
+  missingTimeStamp: nativeLag.missingTimeStamp,
+});
+
+const onNativeScreen = (type: string, ne: Record<string, unknown>) => {
+  const deliveredT = now();
+  const stamp = num(ne.timeStamp);
+  const tag = num(ne.target);
+  const host = tag === null ? null : hostFiber(tag);
+  if (stamp === null) {
+    nativeLag.missingTimeStamp++;
+  } else {
+    const lag = deliveredT - stamp;
+    nativeLag.n++;
+    nativeLag.sumMs += lag;
+    nativeLag.maxMs = Math.max(nativeLag.maxMs, lag);
+  }
+  const event: NativeScreenEvent = {
+    type,
+    tag,
+    t: stamp ?? deliveredT,
+    deliveredT,
+    host,
+    hostType: host && typeof host.type === 'string' ? host.type : null,
+    resolution: null,
+  };
+  nativeScreenEvents.push(event);
+  if (nativeScreenEvents.length > MAX_NATIVE_EVENTS) {
+    nativeScreenEvents.splice(0, nativeScreenEvents.length - MAX_NATIVE_EVENTS);
+  }
+  for (const listener of nativeEventListeners) {
+    listener(event);
+  }
+};
+
+const num = (value: unknown): number | null =>
+  typeof value === 'number' && Number.isFinite(value) ? value : null;
+
+const shortType = (eventName: string) =>
+  eventName.startsWith('top')
+    ? eventName.charAt(3).toLowerCase() + eventName.slice(4)
+    : eventName;
+
+const pressName = (press: ActivePress) => `press:${press.target.name}`;
+
+const dragName = (press: ActivePress) =>
+  `drag:${press.container?.name ?? press.target.name}`;
+
+const dragAxis = (press: ActivePress) => {
+  if (press.maxDxPt === press.maxDyPt) {
+    return null;
+  }
+  return press.maxDxPt > press.maxDyPt ? 'x' : 'y';
+};
+
+const eventEntriesFor = (press: ActivePress) => {
+  const from = press.touchStartT - 1;
+  const to = (press.touchEndT ?? press.touchStartT) + 1;
+  return entries.filter(
+    e => e.entryType === 'event' && e.startTime >= from && e.startTime <= to,
+  );
+};
+
+const details = (press: ActivePress) => () => {
+  const events = eventEntriesFor(press);
+  const eventEnd = events.reduce<number | null>(
+    (max, e) =>
+      max === null
+        ? e.startTime + e.duration
+        : Math.max(max, e.startTime + e.duration),
+    null,
+  );
+  return {
+    gesture: press.kind ?? 'press',
+    target: press.target,
+    ...(press.kind === 'drag'
+      ? {
+          touched: press.target.name,
+          container: press.container,
+          nameSource: press.container
+            ? `container.${press.container.source}`
+            : 'fallback.touched',
+        }
+      : {}),
+    touchStartT: press.touchStartT,
+    touchEndT: press.touchEndT,
+    holdMs:
+      press.touchEndT === null ? null : press.touchEndT - press.touchStartT,
+    longPress:
+      press.touchEndT !== null &&
+      press.touchEndT - press.touchStartT >= LONG_PRESS_MS,
+    maxMovePt: press.maxMovePt,
+    scrolled: press.scrolled,
+    takenByScroll: press.takenByScroll,
+    focused: press.focused,
+    eventEntries: events.map(e => ({
+      name: e.name,
+      startTime: e.startTime,
+      duration: e.duration,
+      processingStart: e.processingStart ?? null,
+      processingEnd: e.processingEnd ?? null,
+    })),
+    // First visual response: native mount of the first commit the touch caused.
+    eventEndT: eventEnd,
+    eventEndMs: eventEnd === null ? null : eventEnd - press.touchStartT,
+    rawListener: {
+      n: rawStats.listenerN,
+      sumMs: rawStats.listenerSumMs,
+      maxMs: rawStats.listenerMaxMs,
+    },
+  };
+};
+
+const finishPress = (press: ActivePress, reason: string, at?: number) => {
+  if (isWindowOpen(press.key)) {
+    markers.end(press.key, reason, at);
+    if (press.faultsRun) {
+      runDeferredFault(press.target.name);
+    }
+  }
+  if (active === press) {
+    active = null;
+  }
+};
+
+const onTouchStart = (ne: Record<string, unknown>) => {
+  const touches = ne.touches;
+  if (Array.isArray(touches) && touches.length > 1) {
+    // Extra fingers belong to the gesture already being tracked.
+    return;
+  }
+  const tag = num(ne.target);
+  const touchStartT = num(ne.timestamp) ?? now();
+  if (active) {
+    // A press whose touchEnd never reached JS (view unmounted mid-touch) is still active here, with the only finger down
+    // being this new one: the new touch ends it.
+    finishPress(
+      active,
+      active.touchEndT === null ? 'touch-lost' : 'next-press',
+      touchStartT,
+    );
+  }
+  const target: TargetDescription =
+    tag === null
+      ? {
+          name: 'unknown',
+          source: 'tag',
+          tag: -1,
+          testID: null,
+          accessibilityLabel: null,
+          component: null,
+          actionable: false,
+        }
+      : describeTarget(tag);
+  seq++;
+  const press: ActivePress = {
+    key: `press#${seq}`,
+    seq,
+    target,
+    host: tag === null ? null : hostFiber(tag),
+    container: null,
+    identifier: ne.identifier,
+    touchStartT,
+    touchEndT: null,
+    startX: num(ne.pageX) ?? 0,
+    startY: num(ne.pageY) ?? 0,
+    maxMovePt: 0,
+    maxDxPt: 0,
+    maxDyPt: 0,
+    scrolled: false,
+    takenByScroll: false,
+    focused: false,
+    kind: null,
+    faultsRun: false,
+  };
+  active = press;
+  const name = pressName(press);
+  lastPress = { t0: touchStartT, name, cause: currentCause() };
+  for (const listener of pressStartListeners) {
+    listener(touchStartT);
+  }
+  markers.start(name, {
+    key: press.key,
+    kind: 'press',
+    at: touchStartT,
+    details: details(press),
+  });
+};
+
+const onTouchMove = (ne: Record<string, unknown>) => {
+  const press = active;
+  if (
+    !press ||
+    press.touchEndT !== null ||
+    ne.identifier !== press.identifier
+  ) {
+    return;
+  }
+  const x = num(ne.pageX);
+  const y = num(ne.pageY);
+  if (x === null || y === null) {
+    return;
+  }
+  press.maxMovePt = Math.max(
+    press.maxMovePt,
+    Math.hypot(x - press.startX, y - press.startY),
+  );
+  press.maxDxPt = Math.max(press.maxDxPt, Math.abs(x - press.startX));
+  press.maxDyPt = Math.max(press.maxDyPt, Math.abs(y - press.startY));
+};
+
+let queryClient: { refetchQueries?: unknown; getQueryCache?: unknown } | null =
+  null;
+
+// Finds the app's TanStack QueryClient through QueryClientProvider's `client`
+// prop, so the dupnet fault needs no import from the app.
+const findQueryClient = () => {
+  if (queryClient) {
+    return queryClient;
+  }
+  const root = lastRoot(1);
+  if (!root) {
+    return null;
+  }
+  queryClient = findInTree(root.current, (fiber: Fiber) => {
+    const client = propsOf(fiber)?.client as
+      | { getQueryCache?: unknown; refetchQueries?: unknown }
+      | undefined;
+    return client &&
+      typeof client.getQueryCache === 'function' &&
+      typeof client.refetchQueries === 'function'
+      ? client
+      : null;
+  }) as typeof queryClient;
+  return queryClient;
+};
+
+interface QueryLike {
+  isActive(): boolean;
+  queryKey: unknown;
+  state: { status: string; dataUpdatedAt: number };
+}
+
+const duplicateLatestQuery = () => {
+  const client = findQueryClient() as {
+    getQueryCache(): { getAll(): QueryLike[] };
+    refetchQueries(filters: Record<string, unknown>): Promise<unknown>;
+  } | null;
+  if (!client) {
+    perfLog('fault dupnet no QueryClient in tree');
+    return;
+  }
+  const latest = client
+    .getQueryCache()
+    .getAll()
+    .filter(query => query.isActive() && query.state.status === 'success')
+    .sort((a, b) => b.state.dataUpdatedAt - a.state.dataUpdatedAt)[0];
+  if (!latest) {
+    perfLog('fault dupnet no active query');
+    return;
+  }
+  markers.point('fault.dupnet');
+  perfLog(`fault dupnet key=${JSON.stringify(latest.queryKey)}`);
+  client
+    .refetchQueries({ queryKey: latest.queryKey, exact: true })
+    .catch(() => undefined);
+};
+
+const onTouchEnd = (ne: Record<string, unknown>, cancelled: boolean) => {
+  const press = active;
+  if (!press || press.touchEndT !== null) {
+    return;
+  }
+  if (Array.isArray(ne.touches) && ne.touches.length > 0) {
+    return;
+  }
+  press.touchEndT = num(ne.timestamp) ?? now();
+  // A scroll view cancels the touch when it takes the gesture. On a list still moving from a fling it does so at once,
+  // before the finger passes the slop, so the move alone would call a fling a press on the row under the finger.
+  press.takenByScroll = cancelled && describeScrollContainer(press.host, null) !== null;
+  const drag = press.maxMovePt >= DRAG_SLOP_PT || press.scrolled || press.takenByScroll;
+  press.kind = drag ? 'drag' : 'press';
+  if (drag) {
+    press.container = describeScrollContainer(press.host, dragAxis(press));
+    const name = dragName(press);
+    markers.rename(press.key, name);
+    return;
+  }
+  if (cancelled) {
+    markers.point('touch.cancel');
+  }
+  const name = pressName(press);
+  if (!cancelled && isFaultTarget(name)) {
+    press.faultsRun = true;
+    runOpenFaults(name);
+    if (settings.faults.dupnet > 0) {
+      duplicateLatestQuery();
+    }
+  }
+};
+
+const onRawEvent = (event: RawEvent) => {
+  const t0 = now();
+  try {
+    const type = shortType(event.eventName);
+    rawStats.events[type] = (rawStats.events[type] ?? 0) + 1;
+    const ne = event.nativeEvent ?? {};
+    switch (type) {
+      case 'touchStart':
+        onTouchStart(ne);
+        break;
+      case 'touchMove':
+        onTouchMove(ne);
+        break;
+      case 'touchEnd':
+        onTouchEnd(ne, false);
+        break;
+      case 'touchCancel':
+        onTouchEnd(ne, true);
+        break;
+      case 'scroll':
+      case 'scrollBeginDrag':
+        if (active && active.touchEndT === null) {
+          active.scrolled = true;
+        }
+        break;
+      case 'focus':
+        if (active) {
+          active.focused = true;
+          markers.point('focus');
+        }
+        break;
+      default:
+        if (NATIVE_SCREEN_EVENTS.has(type)) {
+          onNativeScreen(type, ne);
+        }
+        break;
+    }
+  } catch (error) {
+    rawStats.errors++;
+    if (rawStats.errors <= 3) {
+      perfLog(`raw event error ${String(error)}`);
+    }
+  }
+  const cost = now() - t0;
+  rawStats.listenerN++;
+  rawStats.listenerSumMs += cost;
+  if (cost > rawStats.listenerMaxMs) {
+    rawStats.listenerMaxMs = cost;
+  }
+};
+
+const loadRawEventEmitter = (): Emitter | null => {
+  try {
+    // Private RN module (exposed to the renderer via ReactNativePrivateInterface).
+    const mod = require('react-native/Libraries/Core/RawEventEmitter') as {
+      default?: Emitter;
+    } & Emitter;
+    return mod.default ?? mod;
+  } catch (error) {
+    perfLog(`RawEventEmitter unavailable ${String(error)}`);
+    return null;
+  }
+};
+
+let installed = false;
+
+export const installInteractions = () => {
+  if (installed) {
+    return;
+  }
+  installed = true;
+  const emitter = loadRawEventEmitter();
+  if (!emitter) {
+    return;
+  }
+  emitter.addListener('*', onRawEvent);
+  Keyboard.addListener('keyboardDidShow', () => {
+    markers.point('keyboard.didShow');
+  });
+  AppState.addEventListener('change', state => {
+    // Derivation reads these to tell an iOS GC command (a link that may pass through inactive) from a clean one.
+    writeRunEvent('appstate', { state });
+    if (state === 'background') {
+      markers.endAll('background');
+      active = null;
+    }
+  });
+  perfLog(`interactions installed t=${fmt(now())}`);
+};