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

package/js/sdk/causes.ts

@@ -0,0 +1,932 @@
+// Which source caused each React commit (REQ-MEAS-32): the touch a window measures, a push from outside the device, an
+// earlier action, or nothing we can see.
+//
+// Every state update is stamped with the cause of the JavaScript task that scheduled it. React adds the updating fiber
+// to root.pendingUpdatersLaneMap synchronously inside scheduleUpdateOnFiber whenever a DevTools hook is present, so
+// wrapping those Sets' `add` sees every setState, dispatch and forceUpdate. The cause is carried from the code that
+// registers a continuation to the code that runs it: timers, animation frames, microtasks, promise reactions (async/await
+// goes through Promise.prototype.then in Hermes), XMLHttpRequest events, React's own scheduler tasks, and the first
+// layout or load event of a view. New causes start at a touch, at the user's typing, at a deep link, at app start, and
+// at every native event.
+
+type AnyFn = (...args: unknown[]) => unknown;
+
+/** `action`: a touch, typing, a deep link or app start. `push`: data that arrived from outside the device. `native`: any other native event. */
+export type RootKind = 'action' | 'push' | 'native';
+
+export interface CauseRoot {
+  readonly id: number;
+  readonly kind: RootKind;
+  /** The event behind the root: `touch`, `input`, `link`, `launch`, or the native event name. */
+  readonly source: string;
+  /** performance.now() when the event behind it reached JavaScript. */
+  readonly t: number;
+}
+
+/**
+ * One run of a timer callback after a newer action than the one behind the code that registered the timer: a long-lived
+ * timer (a queue drain, a poller, a ticker) carries an old cause into later work. Every run is its own tick, whether the
+ * timer repeats (setInterval) or re-registers itself (setTimeout, rAF chains). `net` turns true when the run, or a
+ * continuation of it, sends a request; work in the response is then poller-like. It is read when a commit is reported, so
+ * a run's render that comes before its request reads `net` as the run ends up. Nothing decides on it in the SDK beyond
+ * the window's split of its foreign part; the backend compares attribution approaches from it.
+ */
+export interface Tick {
+  readonly net: boolean;
+}
+
+/**
+ * Facts the commit stream records (phase 1 of "the SDK records, the backend decides"): one run of a timer callback, with
+ * the cause it was registered under. Every run gets one; whether it ran after a newer action is the backend's call.
+ */
+export interface TimerRun extends Tick {
+  readonly id: number;
+  readonly timer: string;
+  /** performance.now() when it ran, and when it was registered. */
+  readonly t: number;
+  readonly registeredT: number;
+  readonly registered: CauseSet;
+}
+
+/** One `setState` of a wrapped store, under the writer's own cause (before any move). */
+export interface StoreWrite {
+  readonly id: number;
+  readonly store: number;
+  readonly t: number;
+  readonly writer: CauseSet;
+  readonly run: TimerRun | null;
+}
+
+/** Up to this many parts are kept per commit; the rest are counted. */
+export const FACTS_CAP = 16;
+
+/**
+ * One kind of update in a set: the roots behind it (the writer's own for a store write, before any move), the timer run
+ * it ran in, and the store write it came from. Updates with the same three are one part.
+ */
+export interface Part {
+  readonly ids: readonly number[];
+  readonly run: TimerRun | null;
+  readonly write: StoreWrite | null;
+}
+
+/** The facts behind a set, kept in full where the four roots are a reduction (merged sets only). */
+export interface Facts {
+  readonly parts: readonly Part[];
+  /** Parts past the cap. */
+  readonly more: number;
+}
+
+/** A store write a carried tick made, moved to the newer action that wrote the same store before it. */
+export interface StoreMove {
+  readonly from: CauseRoot;
+  readonly to: CauseRoot;
+  /** The store's literal last writer, when it is not `to` (a late write of an older action came after `to`'s). */
+  readonly lastWrite?: CauseRoot;
+}
+
+/** The roots classification reads, and the tick, of a set. */
+interface Roots {
+  readonly native: CauseRoot | null;
+  readonly push: CauseRoot | null;
+  readonly newest: CauseRoot | null;
+  readonly oldest: CauseRoot | null;
+  readonly carried?: Tick;
+}
+
+/**
+ * A set of causes, kept as the four roots classification reads, so merging any number of causes costs the same: the
+ * first native root, the first push root, and the newest and oldest actions. `carried`: every update in it came from a
+ * timer tick after a newer action. `store`: some update in it came from a store write moved to a newer action; `task` is
+ * then the set as it would be without any move (the backend replays the other approaches from it).
+ */
+export interface CauseSet extends Roots {
+  readonly store?: StoreMove;
+  readonly task?: Roots;
+  /** The timer run this code runs in, and the store write it runs inside (the stream's facts). */
+  readonly run?: TimerRun;
+  readonly write?: StoreWrite;
+  /** Set by merges: the full facts of every set merged in. */
+  readonly facts?: Facts;
+}
+
+/** How timer-carried a commit is (REQ-MEAS-32 timers): `timer`, `timer-net` (its tick sent a request), or none. */
+export type Carrier = 'timer' | 'timer-net' | null;
+
+export const carrierOf = (set: CauseSet): Carrier => (set.carried ? (set.carried.net ? 'timer-net' : 'timer') : null);
+
+export interface CommitCauses {
+  readonly set: CauseSet;
+  /** Some update in the commit (or the commit itself) had no cause. */
+  readonly unknown: boolean;
+}
+
+/** Where a commit's work goes for one window: the judged part, or out of it as foreign work of one source. */
+export type WindowPart = { readonly judged: true } | { readonly judged: false; readonly source: string };
+
+/** Push events: the native event name and the source a background place is named after. */
+const PUSH_EVENTS: Readonly<Record<string, string>> = { websocketMessage: 'websocket' };
+const LINK_EVENTS = new Set(['url']);
+const SOCKET_EVENTS = new Set(['websocketOpen', 'websocketClosed', 'websocketFailed']);
+const SOCKET_END_EVENTS = new Set(['websocketClosed', 'websocketFailed']);
+/** Events the user produces without a new touch. They belong to the latest touch. */
+const USER_INPUT_EVENTS = new Set([
+  'topChange',
+  'topChangeText',
+  'topTextInput',
+  'topKeyPress',
+  'topSubmitEditing',
+  'topEndEditing',
+  'topSelectionChange',
+  'topFocus',
+  'topBlur',
+]);
+/** Events a finger drives: the touch itself, scrolling and its momentum, gesture handlers, pull to refresh, sliders. */
+const TOUCH_DRIVEN = /^top(Touch|Click|Pointer|Scroll|MomentumScroll|Refresh|ValueChange|Sliding)|GestureHandler/;
+/** Events that report on a view's first rendered output: the first of each kind after the view mounted takes its cause. */
+const FIRST_OUTPUT_EVENTS = new Set(['topLayout', 'topLoadStart', 'topLoad', 'topLoadEnd']);
+const XHR_EVENTS = [
+  '__didCreateRequest',
+  '__didUploadProgress',
+  '__didReceiveResponse',
+  '__didReceiveData',
+  '__didReceiveIncrementalData',
+  '__didReceiveDataProgress',
+  '__didCompleteResponse',
+];
+const GLOBAL_CONTINUATIONS = [
+  'setTimeout',
+  'setInterval',
+  'setImmediate',
+  'requestAnimationFrame',
+  'requestIdleCallback',
+  'queueMicrotask',
+];
+const HOST_COMPONENT = 5;
+
+const EMPTY: CauseSet = { native: null, push: null, newest: null, oldest: null };
+
+const isEmpty = (s: CauseSet) => s.native === null && s.push === null && s.newest === null;
+
+const setOf = (r: CauseRoot): CauseSet => {
+  if (r.kind === 'action') return { native: null, push: null, newest: r, oldest: r };
+  return r.kind === 'push' ? { ...EMPTY, push: r } : { ...EMPTY, native: r };
+};
+
+// Carried only when both sides are; then `net` only when both ticks sent a request (read when the commit is classified).
+const mergeTicks = (a: Tick | undefined, b: Tick | undefined): Tick | undefined => {
+  if (!a || !b) return undefined;
+  if (a === b) return a;
+  return {
+    get net() {
+      return a.net && b.net;
+    },
+  };
+};
+
+const mergeRoots = (a: Roots, b: Roots): Roots => {
+  const carried = mergeTicks(a.carried, b.carried);
+  return {
+    native: a.native ?? b.native,
+    push: a.push ?? b.push,
+    newest: a.newest === null || (b.newest !== null && b.newest.id > a.newest.id) ? b.newest : a.newest,
+    oldest: a.oldest === null || (b.oldest !== null && b.oldest.id < a.oldest.id) ? b.oldest : a.oldest,
+    ...(carried ? { carried } : {}),
+  };
+};
+
+const rootsOf = (s: CauseSet): Roots => {
+  const { store: _store, task: _task, ...roots } = s;
+  return roots;
+};
+
+const rootIds = (s: Roots): number[] => {
+  const out: number[] = [];
+  for (const r of [s.native, s.push, s.oldest, s.newest]) if (r !== null && !out.includes(r.id)) out.push(r.id);
+  return out;
+};
+
+/** The facts of a set: its own single part, or the parts its merges kept. */
+export const factsOf = (s: CauseSet): Facts =>
+  s.facts ?? { parts: [{ ids: rootIds(s), run: s.run ?? null, write: s.write ?? null }], more: 0 };
+
+/** Every root id of a set's parts, once. */
+export const factIds = (f: Facts): number[] => {
+  const out: number[] = [];
+  for (const p of f.parts) for (const id of p.ids) if (!out.includes(id)) out.push(id);
+  return out;
+};
+
+const samePart = (x: Part, y: Part) =>
+  x.run === y.run && x.write === y.write && x.ids.length === y.ids.length && x.ids.every((id, i) => id === y.ids[i]);
+
+const mergeFacts = (a: Facts, b: Facts): Facts => {
+  let parts: Part[] | null = null;
+  let more = a.more + b.more;
+  for (const part of b.parts) {
+    if (a.parts.some(p => samePart(p, part)) || parts?.some(p => samePart(p, part))) continue;
+    if ((parts ?? a.parts).length >= FACTS_CAP) {
+      more++;
+      continue;
+    }
+    (parts ??= [...a.parts]).push(part);
+  }
+  return parts === null && more === a.more ? a : { parts: parts ?? a.parts, more };
+};
+
+const sameRoots = (x: Roots, y: Roots) =>
+  x.native === y.native && x.push === y.push && x.newest === y.newest && x.oldest === y.oldest && x.carried === y.carried;
+
+const merge = (a: CauseSet, b: CauseSet): CauseSet => {
+  if (isEmpty(a)) return b;
+  if (isEmpty(b) || a === b) return a;
+  const store = a.store ?? b.store;
+  const task = a.task || b.task ? mergeRoots(a.task ?? rootsOf(a), b.task ?? rootsOf(b)) : undefined;
+  const fa = factsOf(a);
+  const facts = mergeFacts(fa, factsOf(b));
+  const out: CauseSet = {
+    ...mergeRoots(a, b),
+    ...(store ? { store } : {}),
+    ...(task ? { task } : {}),
+    facts,
+  };
+  return sameRoots(out, a) &&
+    out.store === a.store &&
+    facts === fa &&
+    (task === undefined || (a.task !== undefined && sameRoots(task, a.task)))
+    ? a
+    : out;
+};
+
+/** Marks the tasks React's scheduler runs: they take the causes of the render or effects they process. */
+const REACT_TASK: unique symbol = Symbol('react-task');
+type Current = CauseSet | typeof REACT_TASK | null;
+
+let current: Current = null;
+let nextRoot = 1;
+let installed = false;
+
+/** Causes of the render React is running or the commit whose effects it is flushing. */
+let reactCauses: CauseSet = EMPTY;
+let reactUnknown = false;
+/** The ambient cause when React scheduled the task it is running now (a ping, a retry, a render with no updaters). */
+let taskCauses: CauseSet | null = null;
+let renderStarted = false;
+
+let latestTouch: CauseRoot | null = null;
+/** App start: the bundle's first task and every surface the app starts. */
+let launchRoot: CauseRoot | null = null;
+let latestAction = 0;
+let newestActionT = -Infinity;
+/** performance.now() when the app last started a surface (REQ-MEAS-22): the start of the launch screen window. */
+let launchT: number | null = null;
+
+const clock = () => (globalThis.performance ? globalThis.performance.now() : Date.now());
+
+let inLaunch = false;
+
+/** When the app last started a surface (`AppRegistry.runApplication` or bridgeless `renderSurface`), or null before that. */
+export const launchedAt = (): number | null => launchT;
+
+/** The launch's own cause root: the launch screen window anchors at it (REQ-MEAS-22). */
+export const launchRootId = (): number | null => launchRoot?.id ?? null;
+
+export const causeStats = {
+  installed: false,
+  /** Whether `await` runs through Promise.prototype.then on this engine (checked at install). */
+  awaitThroughThen: null as boolean | null,
+  continuations: 0,
+  nativeEvents: 0,
+  touches: 0,
+  stamps: 0,
+  unknownStamps: 0,
+  hostEvents: 0,
+  hostEventsAttributed: 0,
+  carriedTicks: 0,
+  /** zustand stores created through the store wrapper (js/zustand-vanilla.js); 0 means no store write can move. */
+  storesWrapped: 0,
+  storeMoves: 0,
+  /** Writes by an action older than the store's newest writer: "last write" would have taken the store back to them. */
+  storeLateWrites: 0,
+  errors: 0,
+  patched: [] as string[],
+};
+
+const rootListeners = new Set<(root: CauseRoot) => void>();
+const writeListeners = new Set<(write: StoreWrite) => void>();
+
+/** Listeners (the commit stream) for every root the tracker creates and every store write it sees; each returns its removal. */
+export const addRootListener = (listener: (root: CauseRoot) => void) => {
+  rootListeners.add(listener);
+  return () => rootListeners.delete(listener);
+};
+
+export const addWriteListener = (listener: (write: StoreWrite) => void) => {
+  writeListeners.add(listener);
+  return () => writeListeners.delete(listener);
+};
+
+const newRoot = (kind: RootKind, source: string): CauseRoot => {
+  const root = { id: nextRoot++, kind, source, t: clock() };
+  if (kind === 'action') {
+    latestAction = root.id;
+    newestActionT = root.t;
+  }
+  for (const listener of rootListeners) listener(root);
+  return root;
+};
+
+let nextRun = 1;
+let nextWrite = 1;
+let nextStore = 1;
+
+const resolved = (): CommitCauses => {
+  if (current === REACT_TASK) {
+    if (!isEmpty(reactCauses)) return { set: reactCauses, unknown: reactUnknown };
+    return taskCauses ? { set: taskCauses, unknown: false } : { set: EMPTY, unknown: true };
+  }
+  return current ? { set: current, unknown: false } : { set: EMPTY, unknown: true };
+};
+
+const runUnder = <T>(cause: Current, fn: () => T): T => {
+  const prev = current;
+  current = cause;
+  try {
+    return fn();
+  } finally {
+    current = prev;
+  }
+};
+
+// The cause at registration, frozen: a React task resolves to the causes it is processing now.
+const captured = (): CauseSet | null => {
+  if (current === null) return null;
+  const { set } = resolved();
+  return isEmpty(set) ? null : set;
+};
+
+const bind = (fn: unknown): unknown => {
+  if (typeof fn !== 'function') return fn;
+  const cause = captured();
+  if (cause === null) return fn;
+  causeStats.continuations++;
+  const f = fn as AnyFn;
+  return function (this: unknown, ...args: unknown[]) {
+    return runUnder(cause, () => f.apply(this, args));
+  };
+};
+
+// A timer callback runs under its registration's cause; when a newer action came since, the run is a carried tick (one
+// tick record per run, shared by its continuations, so a request it sends marks its responses too).
+const bindTimer = (fn: unknown, timer: string): unknown => {
+  if (typeof fn !== 'function') return fn;
+  const cause = captured();
+  if (cause === null) return fn;
+  causeStats.continuations++;
+  const registeredT = clock();
+  const f = fn as AnyFn;
+  return function (this: unknown, ...args: unknown[]) {
+    const tick: TimerRun = { id: nextRun++, timer, t: clock(), registeredT, registered: cause, net: false };
+    const stale = cause.newest !== null && cause.newest.id < latestAction;
+    const { facts: _facts, write: _write, ...own } = cause;
+    const run: CauseSet = stale ? { ...own, run: tick, carried: tick } : { ...own, run: tick };
+    if (stale) causeStats.carriedTicks++;
+    return runUnder(run, () => f.apply(this, args));
+  };
+};
+
+const TIMERS = new Set(['setTimeout', 'setInterval', 'setImmediate', 'requestAnimationFrame', 'requestIdleCallback']);
+
+/** Called by the request counter when the app starts a request (fetch or XHR): a carried tick's chain is then poller-like. */
+export const noteRequestSent = () => {
+  if (current === null) return;
+  const set = resolved().set;
+  const tick = (set.run ?? set.carried) as { net: boolean } | undefined;
+  // A merged tick (two ticks in one render) is read-only: it reports `net` from both.
+  if (tick && !tick.net && Object.getOwnPropertyDescriptor(tick, 'net')?.writable) tick.net = true;
+};
+
+/**
+ * A zustand store's setState (REQ-MEAS-32 timers, option B). Each store keeps the newest action that wrote it (a late
+ * response of an older action does not take it back). A write under a carried tick, to a store a newer action wrote, runs
+ * under that action, and keeps the set it had as `task`: a timer that serves a queue does the work of the action that
+ * queued it. A poller's own writes stay its own.
+ */
+export const storeWriter = (set: AnyFn): AnyFn => {
+  causeStats.storesWrapped++;
+  const store = nextStore++;
+  let last: CauseRoot | null = null;
+  // The other ruling ("the last write"), kept so the backend can compare the two.
+  let lastWrite: CauseRoot | null = null;
+  return function (this: unknown, ...args: unknown[]) {
+    if (current === null) return set.apply(this, args);
+    const own = resolved().set;
+    const write: StoreWrite = { id: nextWrite++, store, t: clock(), writer: own, run: own.run ?? null };
+    for (const listener of writeListeners) listener(write);
+    const part: Facts = { parts: [{ ids: factIds(factsOf(own)), run: own.run ?? null, write }], more: 0 };
+    if (own.carried && own.newest !== null && last !== null && last.id > own.newest.id) {
+      causeStats.storeMoves++;
+      const move = lastWrite !== null && lastWrite !== last ? { from: own.newest, to: last, lastWrite } : { from: own.newest, to: last };
+      const moved: CauseSet = { ...setOf(last), store: move, task: rootsOf(own), write, facts: part };
+      return runUnder(moved, () => set.apply(this, args));
+    }
+    if (own.newest !== null && last !== null && own.newest.id < last.id) causeStats.storeLateWrites++;
+    if (own.newest !== null) lastWrite = own.newest;
+    if (own.newest !== null && (last === null || own.newest.id > last.id)) last = own.newest;
+    const { facts: _facts, ...rest } = own;
+    return runUnder({ ...rest, write, facts: part }, () => set.apply(this, args));
+  };
+};
+
+const wrapGlobal = (target: Record<string, unknown>, name: string) => {
+  const orig = target[name];
+  if (typeof orig !== 'function') return;
+  const fn = orig as AnyFn;
+  const timer = TIMERS.has(name);
+  const wrapped = function (this: unknown, ...args: unknown[]) {
+    args[0] = timer ? bindTimer(args[0], name) : bind(args[0]);
+    return fn.apply(this, args);
+  };
+  try {
+    Object.defineProperty(target, name, { value: wrapped, writable: true, configurable: true, enumerable: true });
+  } catch {
+    target[name] = wrapped;
+  }
+  causeStats.patched.push(name);
+};
+
+const wrapPromise = (P: { prototype: { then: AnyFn } } | undefined) => {
+  if (!P || typeof P.prototype.then !== 'function') return null;
+  const then = P.prototype.then;
+  P.prototype.then = function (this: unknown, onFulfilled: unknown, onRejected: unknown) {
+    return then.call(this, bind(onFulfilled), bind(onRejected));
+  };
+  causeStats.patched.push('Promise.then');
+  return then;
+};
+
+// --- React: stamps and render causes ---
+
+interface UpdaterSet {
+  add: (fiber: unknown) => unknown;
+  clear: () => unknown;
+  forEach: (cb: (fiber: unknown) => void) => void;
+}
+
+interface StampedFiber {
+  alternate?: StampedFiber | null;
+}
+
+/** The merged causes of the updates a fiber scheduled since the last render took them. */
+interface Stamp {
+  set: CauseSet;
+  unknown: boolean;
+}
+
+const pending = new WeakMap<object, Stamp>();
+const patchedRoots = new WeakSet<object>();
+
+const stampOf = (fiber: StampedFiber): Stamp | undefined =>
+  pending.get(fiber) ?? (fiber.alternate ? pending.get(fiber.alternate) : undefined);
+
+const stamp = (fiber: StampedFiber) => {
+  const { set, unknown } = resolved();
+  causeStats.stamps++;
+  if (unknown && isEmpty(set)) causeStats.unknownStamps++;
+  const s = stampOf(fiber);
+  if (s) {
+    s.set = merge(s.set, set);
+    s.unknown = s.unknown || unknown;
+    return;
+  }
+  const fresh = { set, unknown };
+  pending.set(fiber, fresh);
+  if (fiber.alternate) pending.set(fiber.alternate, fresh);
+};
+
+const beginRender = () => {
+  if (renderStarted) return;
+  renderStarted = true;
+  reactCauses = EMPTY;
+  reactUnknown = false;
+};
+
+// React moves the pending updaters into root.memoizedUpdaters when a render starts, so their stamps are the render's causes.
+const takeStamps = (fiber: StampedFiber) => {
+  beginRender();
+  const s = stampOf(fiber);
+  if (s) {
+    reactCauses = merge(reactCauses, s.set);
+    if (s.unknown) reactUnknown = true;
+  }
+  pending.delete(fiber);
+  if (fiber.alternate) pending.delete(fiber.alternate);
+};
+
+const patchSet = (set: UpdaterSet, onAdd: (fiber: StampedFiber) => void, onClear?: () => void) => {
+  const add = set.add;
+  set.add = function (this: unknown, fiber: unknown) {
+    try {
+      onAdd(fiber as StampedFiber);
+    } catch {
+      causeStats.errors++;
+    }
+    return add.call(this, fiber);
+  };
+  if (onClear) {
+    const clear = set.clear;
+    set.clear = function (this: unknown) {
+      onClear();
+      return clear.call(this);
+    };
+  }
+};
+
+/** Patches a root's updater Sets the first time the SDK sees it; the root's first render has no stamps. */
+const patchRoot = (root: { pendingUpdatersLaneMap?: unknown; memoizedUpdaters?: unknown }) => {
+  if (patchedRoots.has(root)) return;
+  patchedRoots.add(root);
+  if (Array.isArray(root.pendingUpdatersLaneMap)) {
+    for (const set of root.pendingUpdatersLaneMap as UpdaterSet[]) patchSet(set, stamp);
+  }
+  const memoized = root.memoizedUpdaters as UpdaterSet | undefined;
+  if (memoized && typeof memoized.add === 'function') patchSet(memoized, takeStamps, beginRender);
+};
+
+/**
+ * The causes of the commit React is reporting. Called from the commit hook before anything else reads the root. A commit
+ * whose render took no updaters (a Suspense retry, a render with nothing pending) has the cause of whoever scheduled it.
+ */
+export const commitCauses = (root: object): CommitCauses => {
+  patchRoot(root as { pendingUpdatersLaneMap?: unknown; memoizedUpdaters?: unknown });
+  let set = renderStarted ? reactCauses : EMPTY;
+  let unknown = renderStarted ? reactUnknown : true;
+  if (isEmpty(set)) {
+    const ambient = current === REACT_TASK ? taskCauses : current;
+    if (ambient && !isEmpty(ambient)) {
+      set = ambient;
+      unknown = false;
+    }
+  }
+  reactCauses = set;
+  reactUnknown = unknown;
+  renderStarted = false;
+  return { set, unknown };
+};
+
+/** A view's cause until its first layout and load events have taken it. */
+interface ViewCause {
+  readonly set: CauseSet;
+  readonly taken: Set<string>;
+}
+
+const viewCause = new Map<number, ViewCause>();
+
+const nativeTagOf = (fiber: { stateNode: unknown }) => {
+  const tag = (fiber.stateNode as { canonical?: { nativeTag?: unknown } } | null)?.canonical?.nativeTag;
+  return typeof tag === 'number' ? tag : null;
+};
+
+/** Records the cause of a host view the commit mounted, so the view's first layout and load events inherit it. */
+export const noteHostFiber = (fiber: { tag: number; alternate: unknown; stateNode: unknown }, causes: CommitCauses) => {
+  if (fiber.tag !== HOST_COMPONENT || fiber.alternate !== null || isEmpty(causes.set)) return;
+  const tag = nativeTagOf(fiber);
+  if (tag !== null) viewCause.set(tag, { set: causes.set, taken: new Set() });
+};
+
+export const forgetHostFiber = (fiber: { stateNode: unknown }) => {
+  const tag = nativeTagOf(fiber);
+  if (tag !== null) viewCause.delete(tag);
+};
+
+// --- Classification ---
+
+/**
+ * The newest action so far (a touch, typing with no touch yet, a deep link, the launch). A window takes it as its anchor
+ * when it starts: the action that opened it, or the one whose work led to it (a screen opened after an `await`).
+ */
+export const latestActionId = (): number => latestAction;
+
+/** When the newest action (a touch, typing, a link, the launch) reached JavaScript, or -Infinity before any. */
+export const latestActionAt = (): number => newestActionT;
+
+/**
+ * What started the code running now: its newest action (a touch, typing, a link, the launch), else the data pushed to the
+ * app, else the native event; null when nothing is known.
+ */
+export const currentCause = (): CauseRoot | null => {
+  const { set } = resolved();
+  return set.newest ?? set.push ?? set.native;
+};
+
+/**
+ * The part of a window a commit belongs to. It leaves the judged part only when every cause is proven foreign to the
+ * window: a push from outside the device, or an action older than the window's anchor. Work with no cause, work mixed
+ * with the window's own action, and work from other native events stay judged. The source of foreign work is the push's
+ * source (`websocket`), else the oldest action's (`launch`, `link`, `touch`, `input`).
+ */
+export const windowPart = (causes: CommitCauses, anchorId: number): WindowPart => {
+  const { set } = causes;
+  if (causes.unknown || isEmpty(set) || set.native !== null) return { judged: true };
+  if (set.newest !== null && set.newest.id >= anchorId) return { judged: true };
+  return { judged: false, source: set.push?.source ?? (set.oldest as CauseRoot).source };
+};
+
+/** Foreign to any window that could open now: the source of a commit that belongs to no open window's judged part. */
+export const backgroundSource = (causes: CommitCauses): string | null => {
+  const part = windowPart(causes, Number.POSITIVE_INFINITY);
+  return part.judged ? null : part.source;
+};
+
+/** Compact labels for the React export: `touch#12`, `push:websocket#40`, `native:keyboardDidShow#41`, `unknown`. */
+const keyOf = (r: CauseRoot) => (r.kind === 'action' ? `${r.source}#${r.id}` : `${r.kind}:${r.source}#${r.id}`);
+
+/**
+ * The store move behind a commit (`touch#3>touch#9`), or null. With `/touch#8`: the store's last write came from that older
+ * action, so the "last write" ruling would have moved the write there (or not at all when it is not newer than `from`).
+ */
+export const describeStore = (set: CauseSet): string | null =>
+  set.store ? `${keyOf(set.store.from)}>${keyOf(set.store.to)}${set.store.lastWrite ? `/${keyOf(set.store.lastWrite)}` : ''}` : null;
+
+/** A commit's carrier: none when some update had no cause (it may not be the tick's). */
+export const commitCarrier = (causes: CommitCauses): Carrier => (causes.unknown ? null : carrierOf(causes.set));
+
+/** The commit without any store move, when it had one: its causes and carrier as the registering code left them. */
+export const describeTask = (causes: CommitCauses): { causes: string[]; carrier: Carrier } | null =>
+  causes.set.task
+    ? { causes: describeCauses({ set: causes.set.task, unknown: causes.unknown }), carrier: commitCarrier({ set: causes.set.task, unknown: causes.unknown }) }
+    : null;
+
+export const describeCauses = (causes: CommitCauses): string[] => {
+  const { set } = causes;
+  const roots = [set.native, set.push, set.oldest, set.newest].filter((r, i, all): r is CauseRoot => r !== null && all.indexOf(r) === i);
+  const out = roots.map(keyOf);
+  if (causes.unknown) out.push('unknown');
+  return out;
+};
+
+// --- Entry points ---
+
+interface RawEvent {
+  eventName?: string;
+  nativeEvent?: { target?: unknown };
+}
+
+// The latest touch, while it is the latest action: after a deep link, a scroll is not proven to be the user's (a push can
+// scroll the list), so it gets no cause.
+const touchCause = (): CauseSet | null =>
+  latestTouch !== null && latestTouch.id === latestAction ? setOf(latestTouch) : null;
+
+const hostEventCause = (name: string, target: unknown): CauseSet | null => {
+  causeStats.hostEvents++;
+  if (!FIRST_OUTPUT_EVENTS.has(name) || typeof target !== 'number') return null;
+  const view = viewCause.get(target);
+  if (!view || view.taken.has(name)) return null;
+  view.taken.add(name);
+  if (view.taken.size === FIRST_OUTPUT_EVENTS.size) viewCause.delete(target);
+  causeStats.hostEventsAttributed++;
+  return view.set;
+};
+
+/**
+ * RawEventEmitter `*` listener: runs before any handler of the event. React Native can dispatch several events in one
+ * task, so the microtask after them leaves no cause behind rather than restoring one of theirs.
+ */
+const onRawEvent = (event: RawEvent) => {
+  const name = event?.eventName ?? '';
+  let cause: CauseSet | null;
+  if (name === 'topTouchStart') {
+    causeStats.touches++;
+    latestTouch = newRoot('action', 'touch');
+    cause = setOf(latestTouch);
+  } else if (TOUCH_DRIVEN.test(name)) {
+    cause = touchCause();
+  } else if (USER_INPUT_EVENTS.has(name)) {
+    cause = touchCause() ?? setOf(newRoot('action', 'input'));
+  } else {
+    cause = hostEventCause(name, event?.nativeEvent?.target);
+  }
+  current = cause;
+  rawThen?.call(Promise.resolve(), () => {
+    current = null;
+  });
+};
+
+let rawThen: AnyFn | null = null;
+
+const socketCause = new Map<unknown, CauseSet>();
+
+const wrapDeviceEmitter = (emitter: { emit: AnyFn } | undefined) => {
+  if (!emitter || typeof emitter.emit !== 'function') return;
+  const emit = emitter.emit;
+  emitter.emit = function (this: unknown, ...args: unknown[]) {
+    causeStats.nativeEvents++;
+    const type = typeof args[0] === 'string' ? args[0] : '';
+    let cause: CauseSet;
+    const push = PUSH_EVENTS[type];
+    if (push !== undefined) {
+      cause = setOf(newRoot('push', push));
+    } else if (LINK_EVENTS.has(type)) {
+      cause = setOf(newRoot('action', 'link'));
+    } else if (SOCKET_EVENTS.has(type)) {
+      const id = (args[1] as { id?: unknown } | undefined)?.id;
+      cause = socketCause.get(id) ?? setOf(newRoot('native', type));
+      if (SOCKET_END_EVENTS.has(type)) socketCause.delete(id);
+    } else {
+      cause = setOf(newRoot('native', type));
+    }
+    return runUnder(cause, () => emit.apply(this, args));
+  };
+  causeStats.patched.push('RCTDeviceEventEmitter.emit');
+};
+
+// Responses of a request run under the cause of the code that sent it.
+const wrapXhr = (proto: Record<string, unknown> | undefined) => {
+  if (!proto || typeof proto.send !== 'function') return;
+  const CAUSE = '__perflabCause';
+  const send = proto.send as AnyFn;
+  proto.send = function (this: Record<string, unknown>, ...args: unknown[]) {
+    this[CAUSE] = captured();
+    return send.apply(this, args);
+  };
+  for (const name of XHR_EVENTS) {
+    const fn = proto[name];
+    if (typeof fn !== 'function') continue;
+    const f = fn as AnyFn;
+    proto[name] = function (this: Record<string, unknown>, ...args: unknown[]) {
+      const cause = this[CAUSE] as CauseSet | null | undefined;
+      return cause ? runUnder(cause, () => f.apply(this, args)) : f.apply(this, args);
+    };
+  }
+  causeStats.patched.push('XMLHttpRequest');
+};
+
+// A socket's open, close and failure belong to the code that opened it; its messages are pushes.
+const wrapWebSocket = (proto: Record<string, unknown> | undefined) => {
+  if (!proto || typeof proto._registerEvents !== 'function') return;
+  const register = proto._registerEvents as AnyFn;
+  proto._registerEvents = function (this: Record<string, unknown>, ...args: unknown[]) {
+    const cause = captured();
+    if (cause) socketCause.set(this._socketId, cause);
+    return register.apply(this, args);
+  };
+  causeStats.patched.push('WebSocket');
+};
+
+const wrapScheduler = (scheduler: { unstable_scheduleCallback?: AnyFn } | undefined) => {
+  if (!scheduler || typeof scheduler.unstable_scheduleCallback !== 'function') return;
+  const schedule = scheduler.unstable_scheduleCallback;
+  const inReact = (cb: AnyFn, cause: CauseSet | null): AnyFn =>
+    function (this: unknown, ...args: unknown[]) {
+      const prevTask = taskCauses;
+      taskCauses = cause;
+      try {
+        const r = runUnder(REACT_TASK, () => cb.apply(this, args));
+        return typeof r === 'function' ? inReact(r as AnyFn, cause) : r;
+      } finally {
+        taskCauses = prevTask;
+      }
+    };
+  scheduler.unstable_scheduleCallback = (priority: unknown, cb: unknown, options: unknown) =>
+    schedule(priority, typeof cb === 'function' ? inReact(cb as AnyFn, captured()) : cb, options);
+  causeStats.patched.push('scheduler');
+};
+
+// The first render of every surface runs under app start, so work the app starts at launch (polls, subscriptions,
+// loops) keeps that cause instead of having none.
+const wrapAppRegistry = (registry: Record<string, unknown> | undefined, surfaces: Record<string, unknown> | undefined) => {
+  const wrapIn = (target: Record<string, unknown> | undefined, key: string) => {
+    const run = target?.[key];
+    if (!target || typeof run !== 'function') return false;
+    const fn = run as AnyFn;
+    try {
+      target[key] = function (this: unknown, ...args: unknown[]) {
+        // The bundle's first task already holds a launch root; a later start (an activity recreated in the same
+        // process) is a new launch. A surface started from inside another start is the same launch.
+        if (!inLaunch) {
+          if (launchT !== null || !launchRoot) launchRoot = newRoot('action', 'launch');
+          launchT = clock();
+        }
+        const outer = inLaunch;
+        inLaunch = true;
+        try {
+          return runUnder(launchRoot ? setOf(launchRoot) : null, () => fn.apply(this, args));
+        } finally {
+          inLaunch = outer;
+        }
+      };
+    } catch {
+      return false;
+    }
+    return target[key] !== fn;
+  };
+  // Bridgeless React Native starts surfaces through RN$SurfaceRegistry, which holds its own reference.
+  if (wrapIn(registry, 'runApplication')) causeStats.patched.push('AppRegistry');
+  if (wrapIn(surfaces, 'renderSurface')) causeStats.patched.push('SurfaceRegistry');
+};
+
+const load = <T>(id: () => unknown): T | undefined => {
+  try {
+    const mod = id() as { default?: T } & T;
+    return (mod?.default ?? mod) as T;
+  } catch {
+    return undefined;
+  }
+};
+
+export interface CauseDeps {
+  /** RawEventEmitter, RCTDeviceEventEmitter, XMLHttpRequest, WebSocket, scheduler and AppRegistry modules; injectable for tests. */
+  readonly modules?: {
+    readonly raw?: unknown;
+    readonly device?: unknown;
+    readonly xhr?: unknown;
+    readonly webSocket?: unknown;
+    readonly scheduler?: unknown;
+    readonly appRegistry?: unknown;
+  };
+}
+
+/**
+ * Installs the tracker. Must run before the React renderer loads (it reads the scheduler's exports once) and before the
+ * app's own modules capture timers. The SDK boot module runs before the app entry, so both hold.
+ */
+export const installCauses = (deps: CauseDeps = {}) => {
+  if (installed) return;
+  installed = true;
+  launchRoot = newRoot('action', 'launch');
+  const g = globalThis as unknown as Record<string, unknown>;
+  const m = deps.modules ?? {};
+  try {
+    for (const name of GLOBAL_CONTINUATIONS) wrapGlobal(g, name);
+    rawThen = wrapPromise(g.Promise as { prototype: { then: AnyFn } } | undefined);
+    wrapDeviceEmitter(
+      (m.device ?? load(() => require('react-native/Libraries/EventEmitter/RCTDeviceEventEmitter'))) as { emit: AnyFn } | undefined,
+    );
+    wrapXhr(
+      ((m.xhr ?? load(() => require('react-native/Libraries/Network/XMLHttpRequest'))) as { prototype?: Record<string, unknown> } | undefined)
+        ?.prototype,
+    );
+    wrapWebSocket(
+      ((m.webSocket ?? load(() => require('react-native/Libraries/WebSocket/WebSocket'))) as { prototype?: Record<string, unknown> } | undefined)
+        ?.prototype,
+    );
+    const registry = (m.appRegistry ??
+      (load<{ AppRegistry?: unknown }>(() => require('react-native/Libraries/ReactNative/AppRegistry'))?.AppRegistry ?? g.RN$AppRegistry)) as
+      | Record<string, unknown>
+      | undefined;
+    wrapAppRegistry(registry, g.RN$SurfaceRegistry as Record<string, unknown> | undefined);
+    wrapScheduler((m.scheduler ?? load(() => require('scheduler'))) as { unstable_scheduleCallback?: AnyFn } | undefined);
+    const raw = (m.raw ?? load(() => require('react-native/Libraries/Core/RawEventEmitter'))) as
+      | { addListener?: (type: string, fn: (event: RawEvent) => void) => unknown }
+      | undefined;
+    raw?.addListener?.('*', onRawEvent);
+    g.__PERFLAB_STORES__ = { writer: storeWriter };
+    causeStats.installed = true;
+  } catch {
+    causeStats.errors++;
+  }
+  // The bundle's first task is app start; anything native calls later starts with no cause.
+  current = setOf(launchRoot);
+  if (rawThen) {
+    const then = rawThen;
+    let before = 0;
+    const probe = async () => {
+      before = causeStats.continuations;
+      await null;
+      causeStats.awaitThroughThen = causeStats.continuations > before;
+    };
+    probe().catch(() => undefined);
+    then.call(Promise.resolve(), () => {
+      current = null;
+    });
+  } else {
+    current = null;
+  }
+};
+
+/** Test hook: the current cause as a list of labels. */
+export const currentCauseForTest = (): string[] => describeCauses(resolved());
+
+export const runAsActionForTest = <T>(source: string | CauseRoot, fn: (root: CauseRoot) => T): T => {
+  const root = typeof source === 'string' ? newRoot('action', source) : source;
+  return runUnder(setOf(root), () => fn(root));
+};
+
+/** Test hook: an app start at `t` with a launch root of its own (null: no start known). */
+export const markLaunchForTest = (t: number | null): CauseRoot | null => {
+  launchT = t;
+  launchRoot = t === null ? launchRoot : { ...newRoot('action', 'launch'), t };
+  return t === null ? null : launchRoot;
+};
+
+/** Test hook: forget every root and cause. */
+export const resetCausesForTest = () => {
+  current = null;
+  reactCauses = EMPTY;
+  reactUnknown = false;
+  taskCauses = null;
+  renderStarted = false;
+  latestTouch = null;
+  viewCause.clear();
+  socketCause.clear();
+};