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

package/js/sdk/core.ts

@@ -0,0 +1,2403 @@
+// perf-lab core: settings, windows, the commit walk, observers, faults, logs.
+// Loaded by boot.ts, which Metro runs before the app's entry module.
+
+import {
+  type ActivationStore,
+  type Decision,
+  MODE,
+  PERF_LAB_DEEP_LINK_PATH,
+  PERF_LAB_ENABLED,
+  parseQuery,
+  type PolyfillActivation,
+} from './activation';
+import {
+  componentName,
+  type Fiber,
+  type FiberRoot,
+  isComponentTag,
+  nameStats,
+  noteMounted,
+  noteUnmounted,
+  registrySizes,
+} from './fiber';
+import {
+  type ArtifactEntry,
+  type ArtifactReason,
+  ARTIFACT_UPLOAD_DEADLINE_MS,
+  type ArtifactUploadSummary,
+  buildManifest,
+  LONG_TASK_MS,
+  manifestName,
+  selectArtifacts,
+  summarizeArtifacts,
+  type WrittenFile,
+} from './artifacts';
+import {
+  backgroundSource,
+  type Carrier,
+  commitCarrier,
+  causeStats,
+  type CommitCauses,
+  latestActionAt,
+  latestActionId,
+  noteRequestSent,
+  commitCauses,
+  describeCauses,
+  describeStore,
+  describeTask,
+  forgetHostFiber,
+  noteHostFiber,
+  addRootListener,
+  addWriteListener,
+  windowPart,
+} from './causes';
+import { createCpuProfiler, type CpuProfileNative } from './cpuprof';
+import { createNetCounter, type NetWindow } from './net';
+import { createStream } from './stream';
+import {
+  addCommitProfile,
+  brokeFrameBudget,
+  type CommitProfile,
+  createCommitProfile,
+  createWindowProfile,
+  type FrameBudget,
+  isProfilingFiber,
+  type ProfiledFiber,
+  type ProfiledRoot,
+  recordFiber,
+  selfMs,
+  summarizeWindowProfile,
+  totalMs,
+  updateCause,
+  type WindowProfile,
+} from './profile';
+import {
+  buildReactExport,
+  createAncestorPaths,
+  type ExportCommit,
+  exportFiber,
+  fiberId,
+} from './profile-export';
+import {
+  applySamplerParams,
+  estimateOffset,
+  frameBudgetFromRecord,
+  OPEN_SAMPLE_TOLERANCE_MS,
+  type SamplerRecord,
+  type SamplerSettings,
+  samplerDefaults,
+  type WindowSampler,
+  windowAggregate,
+} from './sampler';
+
+export { PERF_LAB_DEEP_LINK_PATH, PERF_LAB_ENABLED, parseQuery };
+
+type LogSink = 'console' | 'native' | 'both';
+
+interface Faults {
+  cpu: number;
+  rerender: number;
+  leak: number;
+  leakjs: number;
+  defer: number;
+  dupnet: number;
+}
+
+interface Settings extends SamplerSettings {
+  marks: boolean;
+  hook: boolean;
+  po: boolean;
+  file: boolean;
+  clear: boolean;
+  gcwin: boolean;
+  net: boolean;
+  log: LogSink;
+  faults: Faults;
+  faultTarget: string;
+  // Per-component update causes (any renderer) and render times (profiling renderer).
+  profile: boolean;
+  // React DevTools v5 export file per window (for TraceSift).
+  rexport: boolean;
+  // Hermes sampling profiler around windows, one .cpuprofile per span.
+  cpuprof: boolean;
+  cpuhz: number;
+  // Diagnostic iteration: React exports on, and at flush every raw file of the
+  // run is kept and uploaded (otherwise only files of budget-breaking windows).
+  diag: boolean;
+}
+
+interface PerfLabNative extends Partial<CpuProfileNative> {
+  beginAsyncSection(name: string, cookie: number): void;
+  endAsyncSection(name: string, cookie: number): void;
+  setCounter(name: string, value: number): void;
+  isTracing(): boolean;
+  log(message: string): void;
+  clockSnapshot(): Record<string, number>;
+  writeText(fileName: string, content: string): string | null;
+  samplerConfigure(mode: string, intervalMs: number): Record<string, unknown>;
+  samplerSample(reason: string): SamplerRecord | null;
+  // Schedules a sample on the sampler's own thread and returns at once; the record shows up in samplerRecent with this reason.
+  samplerRequest?(reason: string): void;
+  // Removes and returns the record a samplerRequest took (kept natively outside the ring).
+  samplerTake?(reason: string): SamplerRecord | null;
+  samplerRecent(sinceT: number): SamplerRecord[];
+  samplerNow(): number;
+  flushSignal?(status: string, detail: string): void;
+  // GC before the action: Android finishes the pending command broadcast with this result; iOS shows it on `perflab.ack`.
+  commandDone?(n: number, data: string): void;
+  /** Android: whether the broadcast of command n still waits for its answer (native finishes it at a deadline). */
+  commandPending?(n: number): boolean;
+  ackSignal?(text: string): void;
+  commandListen?(on: boolean): void;
+  addListener?(event: 'perflabCommand', listener: (e: { cmd: string; n: number; tNative: number }) => void): { remove(): void };
+}
+
+interface RendererInternals {
+  version?: string;
+  rendererPackageName?: string;
+  bundleType?: number;
+}
+
+interface PerfEntry {
+  entryType: string;
+  name: string;
+  startTime: number;
+  duration: number;
+  processingStart?: number;
+  processingEnd?: number;
+  interactionId?: number;
+}
+
+interface PerfObserverList {
+  getEntries(): PerfEntry[];
+}
+
+interface PerfObserver {
+  observe(options: Record<string, unknown>): void;
+  disconnect(): void;
+  takeRecords?: () => PerfEntry[];
+}
+
+type PerfObserverCtor = new (
+  callback: (list: PerfObserverList) => void,
+) => PerfObserver;
+
+interface HermesInternalApi {
+  getRuntimeProperties?: () => Record<string, unknown>;
+  getInstrumentedStats?: () => Record<string, number>;
+}
+
+interface PerformanceLike {
+  now(): number;
+  memory?: Record<string, number>;
+  mark?: (name: string) => void;
+  measure?: (
+    name: string,
+    start: string,
+    end: string,
+  ) => { duration?: number } | undefined;
+  clearMarks?: (name?: string) => void;
+  clearMeasures?: (name?: string) => void;
+  getEntriesByType?: (type: string) => unknown[];
+}
+
+interface HookListener {
+  onInject?: (id: number, internals: RendererInternals) => void;
+  onCommit: (id: number, root: FiberRoot) => void;
+  onUnmount?: (id: number, fiber: Fiber) => void;
+}
+
+interface PolyfillHook {
+  state: {
+    installedAt: number;
+    typeofHookAtPolyfill: string;
+    dev: boolean;
+    mode: string;
+    chainedTargets: number;
+    replacedAfterInstall: number;
+    injections: {
+      id: number;
+      pkg?: string;
+      version?: string;
+      bundleType?: number;
+      t: number;
+    }[];
+    commitsByRenderer: Record<string, number>;
+    unmountsByRenderer: Record<string, number>;
+    lastRootByRenderer: Record<string, FiberRoot>;
+    errors: number;
+    invalid: boolean;
+  };
+  ensure: () => string;
+  attach: (listener: HookListener | null) => void;
+}
+
+interface PerfLabGlobal {
+  HermesInternal?: HermesInternalApi;
+  PerformanceObserver?: PerfObserverCtor & { supportedEntryTypes?: string[] };
+  performance?: PerformanceLike;
+  gc?: () => void;
+  console: { log: (...args: unknown[]) => void; timeStamp?: unknown };
+  expo?: { modules?: Record<string, unknown> };
+  __REACT_DEVTOOLS_GLOBAL_HOOK__?: Record<string, unknown>;
+  __PERFLAB_HOOK__?: PolyfillHook;
+  __PERFLAB_ACTIVATION__?: PolyfillActivation;
+  __PERF_LAB__?: unknown;
+}
+
+const g = globalThis as unknown as PerfLabGlobal;
+
+const NO_FAULTS: Faults = {
+  cpu: 0,
+  rerender: 0,
+  leak: 0,
+  leakjs: 0,
+  defer: 0,
+  dupnet: 0,
+};
+
+// Measure-only builds run someone else's test (Maestro, Detox, Appium) that cannot send our
+// deep link, so collection has to be on from the first frame. A dormant build loads this
+// module only once activated, and then measures like an auto build.
+const AUTO = MODE !== 'manual';
+
+// Faults run on press windows whose name contains one of these (comma-separated).
+const DEFAULT_FAULT_TARGET = 'community.nav.chat';
+
+const defaultSettings = (): Settings => ({
+  marks: true,
+  hook: AUTO,
+  po: AUTO,
+  file: false,
+  clear: true,
+  gcwin: false,
+  net: AUTO,
+  log: AUTO ? 'both' : 'console',
+  faults: { ...NO_FAULTS },
+  faultTarget: DEFAULT_FAULT_TARGET,
+  profile: (process.env.EXPO_PUBLIC_KEEPSNAPPY_PROFILE ?? process.env.EXPO_PUBLIC_PERF_LAB_PROFILE) === '1',
+  rexport: (process.env.EXPO_PUBLIC_KEEPSNAPPY_REACT_EXPORT ?? process.env.EXPO_PUBLIC_PERF_LAB_REACT_EXPORT) === '1',
+  cpuprof: (process.env.EXPO_PUBLIC_KEEPSNAPPY_CPUPROF ?? process.env.EXPO_PUBLIC_PERF_LAB_CPUPROF) === '1',
+  cpuhz: Number((process.env.EXPO_PUBLIC_KEEPSNAPPY_CPUPROF_HZ ?? process.env.EXPO_PUBLIC_PERF_LAB_CPUPROF_HZ)) || 250,
+  diag: false,
+  ...samplerDefaults({
+    auto: AUTO,
+    sampler: (process.env.EXPO_PUBLIC_KEEPSNAPPY_SAMPLER ?? process.env.EXPO_PUBLIC_PERF_LAB_SAMPLER),
+    samplerMs: (process.env.EXPO_PUBLIC_KEEPSNAPPY_SAMPLER_MS ?? process.env.EXPO_PUBLIC_PERF_LAB_SAMPLER_MS),
+  }),
+});
+
+export const settings: Settings = defaultSettings();
+
+// A diagnostic iteration always records the React export (its raw files are the point).
+const exportOn = () => settings.rexport || settings.diag;
+
+export const now = () => (g.performance ? g.performance.now() : Date.now());
+export const fmt = (ms: number) => ms.toFixed(3);
+const noop = () => undefined;
+
+let nativeModule: PerfLabNative | null | undefined;
+let nativeMissingLogged = false;
+
+const getNative = (): PerfLabNative | null => {
+  if (nativeModule) {
+    return nativeModule;
+  }
+  const found = g.expo?.modules?.PerfLab as PerfLabNative | undefined;
+  if (found) {
+    nativeModule = found;
+    return found;
+  }
+  if (!nativeMissingLogged) {
+    nativeMissingLogged = true;
+    g.console.log(
+      'PERF_LAB native module PerfLab missing (expo.modules.PerfLab)',
+    );
+  }
+  return null;
+};
+
+// Unique per launch, so files written by one process never overwrite another's.
+export const PROCESS_ID = `${Date.now().toString(36)}${Math.random().toString(36).slice(2, 6)}`;
+
+// Every commit of the process with its cause facts, for the backend's split (stream.ts).
+const commitStream = createStream(PROCESS_ID);
+addRootListener(root => commitStream.noteRoot(root));
+addWriteListener(write => commitStream.noteWrite(write));
+
+// A process with a run token ends with `flush=1`: files are written there,
+// never at window end, so no file I/O lands inside a measured window.
+const inRun = () => runToken !== null;
+
+const cpu = createCpuProfiler({
+  processId: PROCESS_ID,
+  deferDump: inRun,
+  native: () => {
+    const native = getNative();
+    return native?.cpuProfileStart &&
+      native.cpuProfileStop &&
+      native.cpuProfileDump
+      ? (native as CpuProfileNative)
+      : null;
+  },
+  now: () => now(),
+});
+
+export const perfLog = (message: string, sink: LogSink = settings.log) => {
+  if (!PERF_LAB_ENABLED) {
+    return;
+  }
+  const line = `PERF_LAB ${message}`;
+  if (sink === 'console' || sink === 'both') {
+    g.console.log(line);
+  }
+  if (sink === 'native' || sink === 'both') {
+    const native = getNative();
+    if (native) {
+      native.log(line);
+    } else if (sink === 'native') {
+      g.console.log(line);
+    }
+  }
+};
+
+// Requests started per window (fetch/XHR hooks in net-install.ts feed it).
+export const net = createNetCounter({ now, onStart: noteRequestSent });
+
+const samplerState = {
+  mode: 'off' as string,
+  intervalMs: 0,
+  // performance.now() minus the native sampler clock, measured when the sampler is configured.
+  offsetMs: 0,
+  status: null as Record<string, unknown> | null,
+  error: null as string | null,
+};
+
+const syncSampler = () => {
+  const unchanged =
+    samplerState.mode === settings.sampler &&
+    (settings.sampler === 'off' ||
+      samplerState.intervalMs === settings.samplerMs);
+  if (unchanged) {
+    return;
+  }
+  const native = getNative();
+  if (!native || typeof native.samplerConfigure !== 'function') {
+    samplerState.error = 'native sampler unavailable';
+    return;
+  }
+  try {
+    samplerState.status = native.samplerConfigure(
+      settings.sampler,
+      settings.samplerMs,
+    );
+    const before = now();
+    const nativeNow = native.samplerNow();
+    samplerState.offsetMs = estimateOffset(before, nativeNow, now());
+    samplerState.mode = settings.sampler;
+    samplerState.intervalMs = settings.samplerMs;
+    samplerState.error = null;
+  } catch (error) {
+    samplerState.error = String(error);
+  }
+};
+
+const nativeSamplerNow = () => {
+  try {
+    return getNative()?.samplerNow() ?? -1;
+  } catch {
+    return -1;
+  }
+};
+
+// On-demand sample: logged natively like the automatic ones and returned. Null when the sampler is off.
+export const sample = (reason = 'manual'): SamplerRecord | null => {
+  if (!PERF_LAB_ENABLED || samplerState.mode === 'off') {
+    return null;
+  }
+  try {
+    const record = getNative()?.samplerSample(reason) ?? null;
+    noteFrames(record);
+    return record;
+  } catch (error) {
+    samplerState.error = String(error);
+    return null;
+  }
+};
+
+// The device frame budget, from the sampler's frame counter once it has run
+// (iOS: the display's top rate); 16.7 ms until then.
+let frameBudget: FrameBudget = { ms: 16.7, hz: null, source: 'default' };
+
+const noteFrames = (record: SamplerRecord | null | undefined) => {
+  const found = frameBudgetFromRecord(record);
+  if (found) {
+    frameBudget = { ms: found.ms, hz: found.hz, source: 'sampler' };
+  }
+};
+
+export const samplerStatus = () => ({
+  ...samplerState,
+  settings: {
+    sampler: settings.sampler,
+    samplerMs: settings.samplerMs,
+  },
+});
+
+// The sample taken when the last window closed, and that window's end time (performance.now timebase). A window that
+// opens right after takes it as its own open sample: one native call is the close of the old window and the open of
+// the new one.
+let lastClose: { record: SamplerRecord; t1: number } | null = null;
+
+interface OpenSampleState {
+  openRecord: SamplerRecord | null;
+  // Reason of an asynchronous request still to be read back from native; null when none is pending.
+  openPending: string | null;
+}
+
+// Open sample of a window starting at t0 (performance.now timebase). Runs in the touch-start handler, so it never
+// blocks on the native sampler:
+// - a window that starts exactly where the last one ended (finishPress passes the next touch's time to both) takes that
+//   window's close sample however late it was taken: the two brackets are contiguous, no gap, no overlap;
+// - so does a window that starts within OPEN_SAMPLE_TOLERANCE_MS of the close sample (restarted key);
+// - a window detected long after its t0 (a screen window opened by a press, seen after the new screen rendered) gets
+//   none: its bound is the press's open sample;
+// - else the sampler is asked to sample on its own thread.
+const openSampleFor = (id: number, t0: number): OpenSampleState => {
+  const none = { openRecord: null, openPending: null };
+  if (samplerState.mode === 'off') {
+    return none;
+  }
+  const t0Native = t0 - samplerState.offsetMs;
+  if (
+    lastClose &&
+    (lastClose.t1 === t0 ||
+      Math.abs(lastClose.record.t - t0Native) <= OPEN_SAMPLE_TOLERANCE_MS)
+  ) {
+    return { openRecord: lastClose.record, openPending: null };
+  }
+  if (now() - samplerState.offsetMs - t0Native > OPEN_SAMPLE_TOLERANCE_MS) {
+    return none;
+  }
+  const reason = `window-start:${id}`;
+  const native = getNative();
+  try {
+    if (native && typeof native.samplerRequest === 'function') {
+      native.samplerRequest(reason);
+      return { openRecord: null, openPending: reason };
+    }
+  } catch (error) {
+    samplerState.error = String(error);
+    return none;
+  }
+  return { openRecord: sample(reason), openPending: null };
+};
+
+// Reads an asynchronous open request back, at finalize only (no timer: a blocking native read in the middle of the
+// tap's response would be the cost this design avoids). Native pins request records outside the 64-record ring, so a
+// long window still finds its own.
+const resolveOpenSample = (state: OpenSampleState) => {
+  const reason = state.openPending;
+  const native = getNative();
+  if (state.openRecord || !reason || !native) {
+    return;
+  }
+  try {
+    const found =
+      native.samplerTake?.(reason) ??
+      native.samplerRecent(0).find(r => r.reason === reason) ??
+      null;
+    if (found) {
+      state.openRecord = found;
+      state.openPending = null;
+    }
+  } catch (error) {
+    samplerState.error = String(error);
+  }
+};
+
+// Runs at finalize, right after the window closed, so the close sample never lands inside it. The bracket is
+// the window's open sample and this close sample (a background sample only adds peak memory). The window keeps
+// its open record, so a long window whose open sample left the native ring still has its bound.
+const samplerForWindow = (
+  window: {
+    id: number;
+    t0: number;
+    t1: number | null;
+  } & OpenSampleState,
+): WindowSampler | null => {
+  const native = getNative();
+  if (samplerState.mode === 'off' || !native || window.t1 === null) {
+    return null;
+  }
+  const t0 = window.t0 - samplerState.offsetMs;
+  const t1 = window.t1 - samplerState.offsetMs;
+  try {
+    resolveOpenSample(window);
+    const records = native.samplerRecent(t0 - samplerState.intervalMs - 1000);
+    const open = window.openRecord;
+    if (open && !records.some(r => r.seq === open.seq)) {
+      records.push(open);
+    }
+    noteFrames(records[records.length - 1]);
+    // A tap that ends a press and a screen window at once (same t1) takes one close sample for both.
+    const close =
+      lastClose && lastClose.t1 === window.t1
+        ? lastClose.record
+        : sample(`window-end:${window.id}`);
+    lastClose = close ? { record: close, t1: window.t1 } : null;
+    if (close) {
+      records.push(close);
+    }
+    return windowAggregate(records, t0, t1, open ?? undefined);
+  } catch (error) {
+    samplerState.error = String(error);
+    return null;
+  }
+};
+
+export const percentile = (values: number[], p: number) => {
+  if (values.length === 0) {
+    return null;
+  }
+  const sorted = [...values].sort((a, b) => a - b);
+  const index = Math.min(
+    sorted.length - 1,
+    Math.max(0, Math.ceil((p / 100) * sorted.length) - 1),
+  );
+  return sorted[index] ?? null;
+};
+
+const readHermesStats = (): Record<string, number> | null => {
+  try {
+    return g.HermesInternal?.getInstrumentedStats?.() ?? null;
+  } catch {
+    return null;
+  }
+};
+
+const readMemory = (): Record<string, number> | null => {
+  try {
+    const memory = g.performance?.memory;
+    return memory ? { ...memory } : null;
+  } catch {
+    return null;
+  }
+};
+
+const diffStats = (
+  before: Record<string, number> | null,
+  after: Record<string, number> | null,
+) => {
+  if (!before || !after) {
+    return null;
+  }
+  const out: Record<string, number> = {};
+  for (const key of Object.keys(after)) {
+    const a = after[key];
+    const b = before[key];
+    if (typeof a === 'number' && typeof b === 'number') {
+      out[key] = a - b;
+    }
+  }
+  return out;
+};
+
+// `background`: the work of one external source over the run (REQ-MEAS-32), opened by its first commit.
+export type WindowKind = 'marker' | 'press' | 'screen' | 'background';
+
+interface MarkerWindow {
+  id: number;
+  key: string;
+  name: string;
+  kind: WindowKind;
+  trace: string;
+  t0: number;
+  t1: number | null;
+  openRecord: SamplerRecord | null;
+  openPending: string | null;
+  endReason: string | null;
+  commits: number;
+  commitsByRenderer: Record<string, number>;
+  fibersVisited: number;
+  renders: Record<string, number>;
+  mounts: number;
+  hookCostMs: number[];
+  statsStart: Record<string, number> | null;
+  memoryStart: Record<string, number> | null;
+  points: { name: string; t: number }[];
+  settingsAtStart: string;
+  lastCommitT: number | null;
+  heapAfterGc: Record<string, number> | null;
+  details: (() => Record<string, unknown>) | null;
+  backfill: { commits: number; complete: boolean } | null;
+  net: boolean;
+  profile: WindowProfile | null;
+  exportCommits: ExportCommit[] | null;
+  // Work in the window that was proven foreign to it, per source (REQ-MEAS-32); out of every other count.
+  external: Record<string, ExternalPart>;
+  // The newest action when the window started (causes.ts `latestActionId`); older actions are foreign to it.
+  anchorAction: number;
+  // Commit-stream seqs this window was given (judged or not), as [first, last] runs: the window model's part of the split.
+  offered: [number, number][];
+  exportFibers: number;
+  exportTruncated: boolean;
+  cpuSpan: number | null;
+}
+
+interface ExternalPart {
+  commits: number;
+  renderMs: number[];
+  // The part carried by a timer tick after a newer action (a queue drain, a poller, a ticker).
+  timerCarried: { commits: number; renderMs: number[] };
+}
+
+const MAX_HOOK_SAMPLES = 5000;
+// Rendered-fiber entries kept per window for the React export (memory cap).
+const MAX_EXPORT_FIBERS = 200000;
+
+interface CommitRecord {
+  t: number;
+  // The process's commit count at this commit (the commit stream's `seq`).
+  seq: number;
+  rendererId: number;
+  renders: Record<string, number>;
+  mounts: number;
+  visited: number;
+  costMs: number;
+  profile: CommitProfile | null;
+  exported: ExportCommit | null;
+  causes: CommitCauses;
+  // Timer-carried (causes.ts `commitCarrier`), fixed when the commit is reported.
+  carrier: Carrier;
+  // A window judged it, at its commit or when a back-dated window took it later (backfill).
+  judged: boolean;
+  // Its background source when no window judged it at its commit; it goes there when every window ends (flush or app
+  // background) unless a back-dated window judged it in the meantime (REQ-MEAS-32).
+  background: string | null;
+  // Counted by its background window; no later window takes it.
+  routed: boolean;
+  // Set once a tap or scroll window has counted it: such a window is closed at the next touch's hardware time, which reaches
+  // JS later, so the commit that lands in between was already counted by the window that was open. It stays there.
+  pressTaken?: boolean;
+}
+
+// Commits a window opened late with a backdated start (a screen detected after the action that caused it) can still
+// take (REQ-MEAS-28: bounded by events, not by time). No such window starts before the open time of the current screen
+// visit (screens.ts sets the floor) nor before an open window, so older commits are dropped. Without a screen floor, the
+// newest action bounds it.
+let retainFloor: () => number = latestActionAt;
+export const setRetainFloor = (floor: (() => number) | null) => {
+  retainFloor = floor ?? latestActionAt;
+};
+const recentCommits: CommitRecord[] = [];
+let newestDroppedCommitT = -Infinity;
+// Foreign commits that left the ring before any window judged them. A back-dated window still takes them, so the ring's
+// bound never decides between a window and the background; they go to the background when every window ends.
+const unclaimed: CommitRecord[] = [];
+
+const recordCommit = (record: CommitRecord) => {
+  recentCommits.push(record);
+  let floor = retainFloor();
+  for (const window of openWindows.values()) {
+    floor = Math.min(floor, window.t0);
+  }
+  let drop = 0;
+  while (
+    drop < recentCommits.length &&
+    (recentCommits[drop] as CommitRecord).t < floor
+  ) {
+    drop++;
+  }
+  if (drop > 0) {
+    newestDroppedCommitT = (recentCommits[drop - 1] as CommitRecord).t;
+    for (const old of recentCommits.splice(0, drop)) {
+      if (!old.judged && old.background !== null) {
+        unclaimed.push(old);
+      }
+    }
+  }
+};
+
+// Adds the commit to the window's judged part, or to its foreign work (REQ-MEAS-32). Returns whether it was judged.
+const addCommit = (window: MarkerWindow, record: CommitRecord): boolean => {
+  const run = window.offered[window.offered.length - 1];
+  if (run && run[1] === record.seq - 1) {
+    run[1] = record.seq;
+  } else if (!run || run[1] !== record.seq) {
+    window.offered.push([record.seq, record.seq]);
+  }
+  if (window.kind === 'press') {
+    record.pressTaken = true;
+  }
+  window.lastCommitT = record.t;
+  if (window.kind !== 'background') {
+    const part = windowPart(record.causes, window.anchorAction);
+    if (!part.judged) {
+      const into = (window.external[part.source] ??= { commits: 0, renderMs: [], timerCarried: { commits: 0, renderMs: [] } });
+      into.commits++;
+      if (record.profile?.renderMs != null) {
+        into.renderMs.push(record.profile.renderMs);
+      }
+      if (record.carrier !== null) {
+        into.timerCarried.commits++;
+        if (record.profile?.renderMs != null) {
+          into.timerCarried.renderMs.push(record.profile.renderMs);
+        }
+      }
+      return false;
+    }
+  }
+  window.commits++;
+  window.commitsByRenderer[record.rendererId] =
+    (window.commitsByRenderer[record.rendererId] ?? 0) + 1;
+  for (const name in record.renders) {
+    window.renders[name] =
+      (window.renders[name] ?? 0) + (record.renders[name] as number);
+  }
+  window.mounts += record.mounts;
+  window.fibersVisited += record.visited;
+  if (window.hookCostMs.length < MAX_HOOK_SAMPLES) {
+    window.hookCostMs.push(record.costMs);
+  }
+  if (window.profile && record.profile) {
+    addCommitProfile(window.profile, record.profile);
+  }
+  if (window.exportCommits && record.exported) {
+    if (
+      window.exportFibers + record.exported.fibers.length <=
+      MAX_EXPORT_FIBERS
+    ) {
+      window.exportCommits.push(record.exported);
+      window.exportFibers += record.exported.fibers.length;
+    } else {
+      window.exportTruncated = true;
+    }
+  }
+  return true;
+};
+
+const backfill = (window: MarkerWindow) => {
+  let commits = 0;
+  for (const record of [...unclaimed, ...recentCommits]) {
+    if (
+      record.t >= window.t0 &&
+      !record.routed &&
+      !(window.kind === 'press' && record.pressTaken)
+    ) {
+      if (addCommit(window, record)) {
+        record.judged = true;
+      }
+      commits++;
+    }
+  }
+  window.backfill = {
+    commits,
+    complete: newestDroppedCommitT < window.t0,
+  };
+};
+
+let nextWindowId = 1;
+const openWindows = new Map<string, MarkerWindow>();
+
+// Retained-heap probe: a full GC takes 60-120 ms on a large heap, so it runs only while nothing is
+// measured, a short idle after the last window ends. The next window takes that reading as its
+// heap after GC; a window that starts before the probe ran has none. Tap and scroll windows never take it (see start).
+const IDLE_GC_MS = 500;
+let idleGcTimer: ReturnType<typeof setTimeout> | null = null;
+let idleHeap: Record<string, number> | null = null;
+
+const clearIdleGc = () => {
+  if (idleGcTimer !== null) {
+    clearTimeout(idleGcTimer);
+    idleGcTimer = null;
+  }
+};
+
+const scheduleIdleGc = () => {
+  clearIdleGc();
+  if (!PERF_LAB_ENABLED || !settings.gcwin || openWindows.size > 0) {
+    return;
+  }
+  idleGcTimer = setTimeout(() => {
+    idleGcTimer = null;
+    if (!settings.gcwin || openWindows.size > 0) {
+      return;
+    }
+    g.gc?.();
+    idleHeap = readHermesStats();
+  }, IDLE_GC_MS);
+};
+
+export const lastCommitAt = (key: string) =>
+  openWindows.get(key)?.lastCommitT ?? null;
+
+export const isWindowOpen = (key?: string) =>
+  key ? openWindows.has(key) : openWindows.size > 0;
+
+const traceName = (name: string) => `perf-lab:${name}`;
+
+interface StartOptions {
+  key?: string;
+  kind?: WindowKind;
+  // Backdates t0 (e.g. to the hardware touch time). performance.now() timebase.
+  at?: number;
+  details?: () => Record<string, unknown>;
+  // The action the window belongs to (a cause root id); default: the newest action when it starts.
+  anchor?: number;
+}
+
+const settingsSnapshot = () =>
+  JSON.stringify({
+    hook: settings.hook,
+    po: settings.po,
+    faults: settings.faults,
+    profile: settings.profile,
+    rexport: settings.rexport,
+    cpuprof: settings.cpuprof ? settings.cpuhz : 0,
+    diag: settings.diag,
+    gcwin: settings.gcwin,
+  });
+
+// One window per foreign source (REQ-MEAS-32): it takes every commit that no open window judges and whose causes are
+// proven foreign (a push, an earlier action, the launch), from its first such commit until the app leaves the foreground
+// or the run flushes. It has no sampler, CPU or memory parts.
+const backgroundWindows = new Map<string, MarkerWindow>();
+
+const backgroundWindow = (source: string, t: number): MarkerWindow => {
+  const existing = backgroundWindows.get(source);
+  if (existing) {
+    return existing;
+  }
+  const name = `background:${source}`;
+  const window: MarkerWindow = {
+    id: nextWindowId++,
+    key: name,
+    name,
+    kind: 'background',
+    trace: traceName(name),
+    t0: t,
+    t1: null,
+    openRecord: null,
+    openPending: null,
+    endReason: null,
+    commits: 0,
+    commitsByRenderer: {},
+    fibersVisited: 0,
+    renders: {},
+    mounts: 0,
+    hookCostMs: [],
+    statsStart: null,
+    memoryStart: null,
+    points: [],
+    lastCommitT: null,
+    heapAfterGc: null,
+    details: null,
+    backfill: null,
+    net: false,
+    profile: settings.profile ? createWindowProfile() : null,
+    exportCommits: exportOn() ? [] : null,
+    external: {},
+    offered: [],
+    anchorAction: latestActionId(),
+    exportFibers: 0,
+    exportTruncated: false,
+    cpuSpan: null,
+    settingsAtStart: settingsSnapshot(),
+  };
+  backgroundWindows.set(source, window);
+  perfLog(`PERF_MARK ${name} start t=${fmt(t)} id=${window.id} kind=background`);
+  return window;
+};
+
+const routeToBackground = (record: CommitRecord) => {
+  if (record.routed || record.judged || record.background === null) {
+    return;
+  }
+  record.routed = true;
+  addCommit(backgroundWindow(record.background, record.t), record);
+};
+
+// Segments written and not yet listed for upload (listed at the next flush).
+const pendingStreamFiles: WrittenFile[] = [];
+// A segment is cut at this many commits even between flushes, so a long stretch outside a run stays bounded.
+const MAX_SEGMENT_COMMITS = 5000;
+
+const cutStream = () => {
+  const segment = commitStream.cut(now());
+  if (!segment) {
+    return;
+  }
+  let path: string | null = null;
+  try {
+    path = getNative()?.writeText(segment.name, segment.json) ?? null;
+  } catch (error) {
+    perfLog(`stream write error ${String(error)}`);
+  }
+  if (path) {
+    pendingStreamFiles.push({ name: segment.name, windows: [], bytes: segment.json.length });
+  }
+  perfLog(`stream ${JSON.stringify({ name: segment.name, commits: segment.commits, bytes: segment.json.length, fibersDropped: segment.fibersDropped, written: path !== null })}`);
+};
+
+const endBackground = (reason: string) => {
+  for (const record of [...unclaimed.splice(0), ...recentCommits]) {
+    routeToBackground(record);
+  }
+  // Every window ended (the flush or the app leaving the foreground): no later window starts before this, so the ring
+  // keeps nothing older.
+  const last = recentCommits[recentCommits.length - 1];
+  if (last) {
+    newestDroppedCommitT = last.t;
+    recentCommits.length = 0;
+  }
+  for (const window of backgroundWindows.values()) {
+    window.t1 = now();
+    window.endReason = reason;
+    perfLog(`PERF_MARK ${window.name} end t=${fmt(window.t1)} id=${window.id} reason=${reason}`);
+    finalizeBackground(window);
+  }
+  backgroundWindows.clear();
+  cutStream();
+};
+
+const start = (name: string, options: StartOptions = {}) => {
+  if (!PERF_LAB_ENABLED || !settings.marks) {
+    return null;
+  }
+  const key = options.key ?? name;
+  if (openWindows.has(key)) {
+    end(key, 'restarted');
+  }
+  let heapAfterGc: Record<string, number> | null = null;
+  if (openWindows.size === 0) {
+    clearIdleGc();
+    // Tap and scroll windows (window model 2) get no reading: forced GC is never run in them, and a reading from the idle
+    // probe would be a different kind of reading from the rest of their cycles. Their leak slope is missing.
+    heapAfterGc = settings.gcwin && options.kind !== 'press' ? idleHeap : null;
+    idleHeap = null;
+  }
+  const statsStart = readHermesStats();
+  const id = nextWindowId++;
+  const startT = options.at ?? now();
+  const openSample = openSampleFor(id, startT);
+  const window: MarkerWindow = {
+    id,
+    key,
+    name,
+    kind: options.kind ?? 'marker',
+    trace: traceName(name),
+    t0: startT,
+    t1: null,
+    ...openSample,
+    endReason: null,
+    commits: 0,
+    commitsByRenderer: {},
+    fibersVisited: 0,
+    renders: {},
+    mounts: 0,
+    hookCostMs: [],
+    statsStart,
+    memoryStart: readMemory(),
+    points: [],
+    lastCommitT: null,
+    heapAfterGc,
+    details: options.details ?? null,
+    backfill: null,
+    net: settings.net,
+    profile: settings.profile ? createWindowProfile() : null,
+    exportCommits: exportOn() ? [] : null,
+    external: {},
+    offered: [],
+    anchorAction: options.anchor ?? latestActionId(),
+    exportFibers: 0,
+    exportTruncated: false,
+    cpuSpan: null,
+    settingsAtStart: settingsSnapshot(),
+  };
+  if (options.at !== undefined && settings.hook) {
+    backfill(window);
+  }
+  if (window.net) {
+    net.windowOpen(id, window.t0, options.at !== undefined);
+  }
+  openWindows.set(key, window);
+  window.cpuSpan = cpu.windowOpened(window.id);
+  for (const listener of windowStartListeners) {
+    listener();
+  }
+  getNative()?.beginAsyncSection(window.trace, window.id);
+  g.performance?.mark?.(`${window.trace}:start:${window.id}`);
+  perfLog(
+    `PERF_MARK ${name} start t=${fmt(window.t0)} id=${window.id} kind=${window.kind}`,
+  );
+  return window;
+};
+
+const end = (key: string, reason = 'end', at?: number) => {
+  const window = openWindows.get(key);
+  if (!window) {
+    return;
+  }
+  window.t1 = at ?? now();
+  window.endReason = reason;
+  openWindows.delete(key);
+  getNative()?.endAsyncSection(window.trace, window.id);
+  let measured: number | null = null;
+  try {
+    g.performance?.mark?.(`${window.trace}:end:${window.id}`);
+    measured =
+      g.performance?.measure?.(
+        `${window.trace}:${window.id}`,
+        `${window.trace}:start:${window.id}`,
+        `${window.trace}:end:${window.id}`,
+      )?.duration ?? null;
+  } catch {
+    measured = null;
+  }
+  perfLog(
+    `PERF_MARK ${window.name} end t=${fmt(window.t1)} id=${window.id} dur=${fmt(window.t1 - window.t0)} reason=${reason}${measured === null ? '' : ` measure=${fmt(measured)}`}`,
+  );
+  // Written now: a process killed right after the window ends must still have it.
+  // Observer entries not yet delivered to the callback are taken synchronously.
+  drainObservers();
+  finalizeWindow(window);
+  scheduleIdleGc();
+};
+
+// Ends every open window, e.g. when the app leaves the foreground: iOS pauses
+// JS timers in the background, so no timer could end them before a kill.
+const windowsEndListeners = new Set<(reason: string) => void>();
+export const onWindowsEnd = (listener: (reason: string) => void) => {
+  windowsEndListeners.add(listener);
+};
+
+const endAll = (reason: string) => {
+  for (const key of [...openWindows.keys()]) {
+    end(key, reason);
+  }
+  endBackground(reason);
+  for (const listener of windowsEndListeners) {
+    listener(reason);
+  }
+};
+
+const rename = (key: string, name: string) => {
+  const window = openWindows.get(key);
+  if (window && window.name !== name) {
+    perfLog(`PERF_MARK ${window.name} renamed=${name} id=${window.id}`);
+    window.name = name;
+  }
+};
+
+const point = (name: string) => {
+  if (!PERF_LAB_ENABLED || !settings.marks) {
+    return;
+  }
+  const t = now();
+  for (const window of openWindows.values()) {
+    window.points.push({ name, t });
+  }
+  perfLog(`PERF_MARK ${name} point t=${fmt(t)}`);
+};
+
+export const markers = { start, end, endAll, rename, point };
+
+const PERFORMED_WORK = 1;
+
+const hookState = {
+  installed: false,
+  source: 'none' as 'none' | 'polyfill' | 'boot',
+  preexisting: false,
+  injected: [] as {
+    id: number;
+    version?: string;
+    pkg?: string;
+    bundleType?: number;
+  }[],
+  totalCommits: 0,
+  totalCostMs: 0,
+  outsideWindowCostMs: 0,
+  profilingRenderer: null as boolean | null,
+};
+
+// Every commit is walked (bailed-out subtrees skipped): renders are counted for
+// the open windows and the recent-commit ring, and newly mounted host/screen
+// fibers feed the registries that name touches and screens.
+const walkCommit = (
+  root: FiberRoot,
+  profile: CommitProfile | null,
+  exported: ExportCommit | null,
+  causes: CommitCauses,
+) => {
+  const stack: Fiber[] = [root.current];
+  const renders: Record<string, number> = {};
+  let mounts = 0;
+  let visited = 0;
+  const ancestors = exported ? createAncestorPaths() : null;
+  while (stack.length > 0) {
+    const fiber = stack.pop() as Fiber;
+    visited++;
+    const mounted = fiber.alternate === null;
+    if (mounted) {
+      noteMounted(fiber);
+    }
+    noteHostFiber(fiber, causes);
+    if (isComponentTag(fiber.tag) && (fiber.flags & PERFORMED_WORK) !== 0) {
+      const name = componentName(fiber);
+      renders[name] = (renders[name] ?? 0) + 1;
+      if (mounted) {
+        mounts++;
+      }
+      if (profile || exported) {
+        const cause = updateCause(fiber as ProfiledFiber);
+        if (profile) {
+          recordFiber(profile, name, fiber as ProfiledFiber, cause, fiberId(fiber));
+        }
+        if (exported) {
+          exported.fibers.push(
+            exportFiber(
+              fiber,
+              name,
+              cause,
+              totalMs(fiber as ProfiledFiber),
+              selfMs(fiber as ProfiledFiber),
+              (ancestors as (f: Fiber) => number[])(fiber),
+            ),
+          );
+        }
+      }
+    }
+    // Children not cloned in this render are the previous commit's fibers and
+    // carry stale flags, so a bailed-out subtree is skipped entirely.
+    const alternate = fiber.alternate;
+    if (alternate !== null && fiber.child === alternate.child) {
+      continue;
+    }
+    for (let child = fiber.child; child !== null; child = child.sibling) {
+      stack.push(child);
+    }
+  }
+  return { renders, mounts, visited };
+};
+
+const afterCommitListeners = new Set<() => void>();
+const windowStartListeners = new Set<() => void>();
+
+export const onWindowStart = (listener: () => void) => {
+  windowStartListeners.add(listener);
+};
+
+export const onAfterCommit = (listener: () => void) => {
+  afterCommitListeners.add(listener);
+};
+
+const onCommitFiberRoot = (rendererId: number, root: FiberRoot) => {
+  if (!settings.hook) {
+    return;
+  }
+  hookState.totalCommits++;
+  const seq = hookState.totalCommits;
+  const t0 = now();
+  const causes = commitCauses(root);
+  const windows = [...openWindows.values()];
+  let walked: ReturnType<typeof walkCommit> | null = null;
+  let profile: CommitProfile | null = null;
+  let exported: ExportCommit | null = null;
+  let renderMs: number | null = null;
+  try {
+    const profiled = root as unknown as ProfiledRoot;
+    if (hookState.profilingRenderer === null) {
+      hookState.profilingRenderer = isProfilingFiber(profiled.current);
+    }
+    // The figure `profile.renderMs` reads; null when the renderer does not time commits.
+    renderMs = isProfilingFiber(profiled.current) ? totalMs(profiled.current) : null;
+    if (settings.profile) {
+      profile = createCommitProfile(profiled, seq);
+    }
+    // Only commits a window can take are exported (open now, or backfilled
+    // into a window opened later with a backdated start).
+    if (exportOn()) {
+      exported = {
+        t: t0,
+        durationMs: totalMs(profiled.current) ?? 0,
+        updaters: profile?.updaters ?? null,
+        causes: describeCauses(causes),
+        carrier: commitCarrier(causes),
+        store: describeStore(causes.set),
+        task: describeTask(causes),
+        fibers: [],
+      };
+    }
+    walked = walkCommit(root, profile, exported, causes);
+  } catch (error) {
+    perfLog(`hook walk error ${String(error)}`);
+  }
+  const cost = now() - t0;
+  hookState.totalCostMs += cost;
+  if (windows.length === 0) {
+    hookState.outsideWindowCostMs += cost;
+  }
+  const record: CommitRecord = {
+    t: t0,
+    seq,
+    rendererId,
+    renders: walked?.renders ?? {},
+    mounts: walked?.mounts ?? 0,
+    visited: walked?.visited ?? 0,
+    costMs: cost,
+    profile,
+    exported,
+    causes,
+    carrier: commitCarrier(causes),
+    judged: false,
+    background: null,
+    routed: false,
+  };
+  for (const window of windows) {
+    record.judged = addCommit(window, record) || record.judged;
+  }
+  // Work no open window judges is the background of its source: pushes, and loops of earlier actions or of the launch.
+  record.background = record.judged ? null : backgroundSource(causes);
+  commitStream.noteCommit({ seq, t: t0, renderMs, causes, fibers: exported?.fibers ?? null, updaters: profile?.updaters ?? null });
+  if (commitStream.size() >= MAX_SEGMENT_COMMITS) {
+    cutStream();
+  }
+  recordCommit(record);
+  for (const listener of afterCommitListeners) {
+    listener();
+  }
+};
+
+const onCommitFiberUnmount = (_rendererId: number, fiber: Fiber) => {
+  if (settings.hook) {
+    noteUnmounted(fiber);
+    forgetHostFiber(fiber);
+  }
+};
+
+export const lastRoot = (rendererId = 1): FiberRoot | null =>
+  g.__PERFLAB_HOOK__?.state.lastRootByRenderer[rendererId] ?? null;
+
+// The polyfill (withPerfLab) installed the hook before React loaded; attach to
+// it. Without the polyfill, fall back to installing it now, as the prototype did.
+export const attachHook = () => {
+  if (!PERF_LAB_ENABLED || hookState.installed) {
+    return;
+  }
+  const polyfill = g.__PERFLAB_HOOK__;
+  if (polyfill) {
+    polyfill.ensure();
+    polyfill.attach({
+      onInject: (id, internals) => {
+        hookState.injected.push({
+          id,
+          version: internals.version,
+          pkg: internals.rendererPackageName,
+          bundleType: internals.bundleType,
+        });
+      },
+      onCommit: onCommitFiberRoot,
+      onUnmount: onCommitFiberUnmount,
+    });
+    for (const injection of polyfill.state.injections) {
+      hookState.injected.push(injection);
+    }
+    hookState.preexisting = polyfill.state.mode === 'chained';
+    hookState.source = 'polyfill';
+    hookState.installed = true;
+    return;
+  }
+  if (g.__REACT_DEVTOOLS_GLOBAL_HOOK__) {
+    hookState.preexisting = true;
+    g.console.log('PERF_LAB hook already present, not replacing it');
+    return;
+  }
+  let nextRendererId = 1;
+  g.__REACT_DEVTOOLS_GLOBAL_HOOK__ = {
+    supportsFiber: true,
+    isDisabled: false,
+    renderers: new Map<number, RendererInternals>(),
+    inject(internals: RendererInternals) {
+      const id = nextRendererId++;
+      hookState.injected.push({
+        id,
+        version: internals.version,
+        pkg: internals.rendererPackageName,
+        bundleType: internals.bundleType,
+      });
+      g.console.log(
+        `PERF_LAB hook inject id=${id} renderer=${internals.rendererPackageName} version=${internals.version} bundleType=${internals.bundleType}`,
+      );
+      return id;
+    },
+    onCommitFiberRoot,
+    onPostCommitFiberRoot: noop,
+    onCommitFiberUnmount,
+    setStrictMode: noop,
+    checkDCE: noop,
+  };
+  hookState.source = 'boot';
+  hookState.installed = true;
+};
+
+const MAX_ENTRIES = 1000;
+export const entries: PerfEntry[] = [];
+let observers: PerfObserver[] = [];
+
+const pushEntries = (list: PerfObserverList) => {
+  for (const entry of list.getEntries()) {
+    entries.push({
+      entryType: entry.entryType,
+      name: entry.name,
+      startTime: entry.startTime,
+      duration: entry.duration,
+      processingStart: entry.processingStart,
+      processingEnd: entry.processingEnd,
+      interactionId: entry.interactionId,
+    });
+  }
+  if (entries.length > MAX_ENTRIES) {
+    entries.splice(0, entries.length - MAX_ENTRIES);
+  }
+};
+
+const startObservers = () => {
+  if (observers.length > 0 || !g.PerformanceObserver) {
+    return;
+  }
+  const Ctor = g.PerformanceObserver;
+  for (const type of ['longtask', 'event']) {
+    try {
+      const observer = new Ctor(pushEntries);
+      observer.observe(
+        type === 'event'
+          ? { type, buffered: false, durationThreshold: 0 }
+          : { type, buffered: false },
+      );
+      observers.push(observer);
+    } catch (error) {
+      perfLog(`observer ${type} failed ${String(error)}`);
+    }
+  }
+};
+
+const drainObservers = () => {
+  for (const observer of observers) {
+    try {
+      const pending = observer.takeRecords?.();
+      if (pending && pending.length > 0) {
+        pushEntries({ getEntries: () => pending });
+      }
+    } catch (error) {
+      perfLog(`observer takeRecords failed ${String(error)}`);
+    }
+  }
+};
+
+const stopObservers = () => {
+  for (const observer of observers) {
+    observer.disconnect();
+  }
+  observers = [];
+  entries.length = 0;
+};
+
+const summarizeEntries = (window: MarkerWindow) => {
+  const t1 = window.t1 ?? now();
+  const longtasks = entries.filter(
+    e =>
+      e.entryType === 'longtask' &&
+      e.startTime < t1 &&
+      e.startTime + e.duration > window.t0,
+  );
+  const events = entries.filter(
+    e =>
+      e.entryType === 'event' &&
+      e.startTime >= window.t0 - 1000 &&
+      e.startTime < t1,
+  );
+  return {
+    longtaskCount: longtasks.length,
+    longtaskTotalMs: longtasks.reduce((sum, e) => sum + e.duration, 0),
+    longtaskMaxMs: longtasks.reduce((max, e) => Math.max(max, e.duration), 0),
+    events: events.map(e => ({
+      name: e.name,
+      startTime: e.startTime,
+      duration: e.duration,
+      inputDelay:
+        e.processingStart === undefined
+          ? null
+          : e.processingStart - e.startTime,
+      processing:
+        e.processingStart === undefined || e.processingEnd === undefined
+          ? null
+          : e.processingEnd - e.processingStart,
+      interactionId: e.interactionId,
+    })),
+  };
+};
+
+const clearPerformanceBuffers = () => {
+  const perf = g.performance;
+  if (!perf) {
+    return null;
+  }
+  const counts = {
+    marks: perf.getEntriesByType?.('mark')?.length ?? null,
+    measures: perf.getEntriesByType?.('measure')?.length ?? null,
+  };
+  // RN's mark/measure buffers have no size limit; nothing in the app reads them.
+  perf.clearMarks?.();
+  perf.clearMeasures?.();
+  return counts;
+};
+
+const topRenders = (renders: Record<string, number>, limit: number) =>
+  Object.entries(renders)
+    .sort((a, b) => b[1] - a[1])
+    .slice(0, limit);
+
+const safeDetails = (window: MarkerWindow) => {
+  if (!window.details) {
+    return null;
+  }
+  try {
+    return window.details();
+  } catch (error) {
+    return { error: String(error) };
+  }
+};
+
+const netForWindow = (window: MarkerWindow): NetWindow | null =>
+  window.net ? net.windowClose(window.id) : null;
+
+const reactExportName = (window: MarkerWindow) =>
+  `react-${PROCESS_ID}-${window.id}-${window.name.replace(/[^\w.:+-]/g, '_')}.json`;
+
+interface PendingExport {
+  name: string;
+  window: number;
+  t0: number;
+  commits: ExportCommit[];
+  fibers: number;
+}
+
+// React exports held until flush (inside a run), capped like a window's.
+const MAX_PENDING_EXPORT_FIBERS = 400000;
+const pendingExports: PendingExport[] = [];
+let pendingExportFibers = 0;
+
+const writeExportFile = (name: string, t0: number, commits: ExportCommit[]) => {
+  const json = JSON.stringify(buildReactExport(t0, commits));
+  return { path: getNative()?.writeText(name, json) ?? null, bytes: json.length };
+};
+
+const writeReactExport = (window: MarkerWindow) => {
+  if (!window.exportCommits) {
+    return null;
+  }
+  const name = reactExportName(window);
+  const base = {
+    name,
+    commits: window.exportCommits.length,
+    fibers: window.exportFibers,
+    truncated: window.exportTruncated,
+  };
+  if (inRun()) {
+    if (pendingExportFibers + window.exportFibers > MAX_PENDING_EXPORT_FIBERS) {
+      return { ...base, deferred: true, dropped: true };
+    }
+    pendingExports.push({
+      name,
+      window: window.id,
+      t0: window.t0,
+      commits: window.exportCommits,
+      fibers: window.exportFibers,
+    });
+    pendingExportFibers += window.exportFibers;
+    return { ...base, deferred: true, dropped: false };
+  }
+  try {
+    return { ...base, deferred: false, ...writeExportFile(name, window.t0, window.exportCommits) };
+  } catch (error) {
+    return { ...base, deferred: false, error: String(error) };
+  }
+};
+
+// The span's file goes on the window that closed it; the others name the span.
+const cpuForWindow = (window: MarkerWindow) => {
+  if (window.cpuSpan === null) {
+    return null;
+  }
+  const result = cpu.windowClosed(openWindows.size);
+  if (result && !result.deferred) {
+    perfLog(`cpuprofile ${JSON.stringify(result)}`);
+  }
+  return result ?? { span: window.cpuSpan };
+};
+
+// Windows of this run that broke a budget on the device, by id: their raw
+// files are kept even outside a diagnostic iteration (plan 40 §3.3).
+const budgetBreaks = new Map<number, ArtifactReason[]>();
+
+const noteBudgetBreak = (window: MarkerWindow, frame: boolean, longTaskMaxMs: number | null) => {
+  if (!inRun()) {
+    return;
+  }
+  const reasons: ArtifactReason[] = [];
+  if (frame) {
+    reasons.push('frame-budget');
+  }
+  if (longTaskMaxMs !== null && longTaskMaxMs > LONG_TASK_MS) {
+    reasons.push('long-task');
+  }
+  if (reasons.length > 0) {
+    budgetBreaks.set(window.id, reasons);
+  }
+};
+
+const bytesOf = (file: Record<string, unknown> | null) =>
+  typeof file?.bytes === 'number' ? file.bytes : null;
+
+// Runs at flush, after the windows ended and before lines are sent: the CPU
+// span is stopped and dumped, the held React exports are written. Returns the
+// files the run keeps (diagnostic iteration, or budget-breaking windows).
+const writeDeferredFiles = (): ArtifactEntry[] => {
+  const t0 = now();
+  const cpuResult = cpu.dump();
+  if (cpuResult) {
+    perfLog(`cpuprofile ${JSON.stringify(cpuResult)}`);
+  }
+  const exports = pendingExports.splice(0);
+  pendingExportFibers = 0;
+  const written: WrittenFile[] = [];
+  for (const pending of exports) {
+    let result: Record<string, unknown>;
+    try {
+      result = writeExportFile(pending.name, pending.t0, pending.commits);
+      if (result.path) {
+        written.push({ name: pending.name, windows: [pending.window], bytes: bytesOf(result) });
+      }
+    } catch (error) {
+      result = { error: String(error) };
+    }
+    perfLog(
+      `rexport ${JSON.stringify({ name: pending.name, commits: pending.commits.length, fibers: pending.fibers, ...result })}`,
+    );
+  }
+  const cpuFile: WrittenFile | null =
+    cpuResult?.fileName && cpuResult.file
+      ? { name: cpuResult.fileName, windows: cpuResult.windows, bytes: bytesOf(cpuResult.file) }
+      : null;
+  const artifacts = inRun()
+    ? selectArtifacts({ diag: settings.diag, runToken, breaks: budgetBreaks, cpu: cpuFile, exports: written, stream: pendingStreamFiles.splice(0) })
+    : [];
+  budgetBreaks.clear();
+  if (cpuResult || exports.length > 0) {
+    perfLog(
+      `flush files ${JSON.stringify({ ms: now() - t0, cpuprofile: cpuResult?.fileName ?? null, rexports: exports.length, artifacts: artifacts.length })}`,
+    );
+  }
+  return artifacts;
+};
+
+type ArtifactHandler = (
+  entries: ArtifactEntry[],
+  runToken: string | null,
+  processId: string,
+  deadline: number,
+) => Promise<ArtifactUploadSummary>;
+let artifactHandler: ArtifactHandler | null = null;
+
+export const setArtifactHandler = (handler: ArtifactHandler | null) => {
+  artifactHandler = handler;
+};
+
+// Entries a window interrupted wait for the next flush of this process.
+let artifactBacklog: ArtifactEntry[] = [];
+
+const writeManifest = (entries: ArtifactEntry[], upload: ArtifactUploadSummary | null) => {
+  try {
+    const manifest = buildManifest({
+      processId: PROCESS_ID,
+      diag: settings.diag,
+      frameBudgetMs: frameBudget.ms,
+      artifacts: entries,
+      upload,
+    });
+    getNative()?.writeText(manifestName(PROCESS_ID), JSON.stringify(manifest));
+  } catch (error) {
+    perfLog(`artifacts manifest failed ${String(error)}`);
+  }
+};
+
+// After the lines: the kept files go up, outside any measured window. A
+// failed upload leaves the files on the device and never fails the flush.
+const sendArtifacts = async (fresh: ArtifactEntry[], deadline: number) => {
+  const entries = [...artifactBacklog, ...fresh];
+  artifactBacklog = [];
+  if (entries.length === 0) {
+    return null;
+  }
+  writeManifest(entries, null);
+  let summary: ArtifactUploadSummary;
+  if (artifactHandler) {
+    try {
+      summary = await artifactHandler(entries, runToken, PROCESS_ID, deadline);
+    } catch (error) {
+      for (const entry of entries) {
+        if (entry.state === 'pending') {
+          entry.state = 'local';
+          entry.error = String(error);
+        }
+      }
+      summary = summarizeArtifacts(entries, 0, String(error));
+    }
+  } else {
+    for (const entry of entries) {
+      entry.state = 'local';
+      entry.error = 'push not configured';
+    }
+    summary = summarizeArtifacts(entries, 0, 'push not configured');
+  }
+  artifactBacklog = entries.filter(entry => entry.state === 'pending' || entry.state === 'failed');
+  writeManifest(entries, summary);
+  perfLog(`artifacts ${JSON.stringify(summary)}`);
+  return summary;
+};
+
+// Declared on every window line so the backend can tell windows of this model from older ones (REQ-VER-34).
+// 2: a tap or scroll window runs from its touch to the next touch, the background or the flush; no quiet rule, no `+3s` twin.
+// 3: model 2, and a screen window also ends at the next action, the next screen, the background or the flush; no 3 s cap.
+export const WINDOW_MODEL = 3;
+
+const finalizeWindow = (window: MarkerWindow) => {
+  const statsEnd = readHermesStats();
+  // Sampler first: its records carry the display rate the frame budget needs.
+  const sampler = samplerForWindow(window);
+  const profile = window.profile
+    ? summarizeWindowProfile(window.profile, { budget: frameBudget })
+    : null;
+  const perf = settings.po ? summarizeEntries(window) : null;
+  noteBudgetBreak(
+    window,
+    profile !== null && brokeFrameBudget(profile),
+    perf ? perf.longtaskMaxMs : null,
+  );
+  const totalRenders = Object.values(window.renders).reduce((s, n) => s + n, 0);
+  const summary = {
+    v: 1,
+    windowModel: WINDOW_MODEL,
+    id: window.id,
+    name: window.name,
+    kind: window.kind,
+    t0: window.t0,
+    t1: window.t1,
+    durMs: window.t1 === null ? null : window.t1 - window.t0,
+    endReason: window.endReason,
+    settings: JSON.parse(window.settingsAtStart) as unknown,
+    points: window.points,
+    react: settings.hook
+      ? {
+          commits: window.commits,
+          commitsByRenderer: window.commitsByRenderer,
+          renders: totalRenders,
+          mounts: window.mounts,
+          fibersVisited: window.fibersVisited,
+          backfill: window.backfill,
+          // Commit records the SDK holds when the window ends (recent ring and foreign ones waiting for the flush).
+          ring: { records: recentCommits.length, unclaimed: unclaimed.length },
+          componentsDistinct: Object.keys(window.renders).length,
+          top: topRenders(window.renders, 40),
+          hookCostMs: {
+            n: window.hookCostMs.length,
+            sum: window.hookCostMs.reduce((s, n) => s + n, 0),
+            p50: percentile(window.hookCostMs, 50),
+            p99: percentile(window.hookCostMs, 99),
+            max: percentile(window.hookCostMs, 100),
+          },
+          profile,
+          external: externalSummary(window, profile !== null && profile.renderer === 'profiling'),
+          causes: {
+            awaitThroughThen: causeStats.awaitThroughThen,
+            storesWrapped: causeStats.storesWrapped,
+            anchor: window.anchorAction,
+            // Requests mark carried ticks `timer-net` only while the request counter runs.
+            requestsMarked: window.net,
+            // The commit-stream segment open when the window ended: the backend needs every segment up to it.
+            process: PROCESS_ID,
+            streamSeq: commitStream.seq(),
+            offered: window.offered,
+          },
+          export: writeReactExport(window),
+        }
+      : null,
+    cpuprofile: cpuForWindow(window),
+    perf,
+    [window.kind === 'screen' ? 'screen' : 'interaction']: safeDetails(window),
+    hermesDelta: diffStats(window.statsStart, statsEnd),
+    hermesEnd: statsEnd,
+    heapAfterGc: window.heapAfterGc,
+    memoryStart: window.memoryStart,
+    memoryEnd: readMemory(),
+    retainedLeakMB: leakState.retainedMB,
+    sampler,
+    net: netForWindow(window),
+    buffersBeforeClear: settings.clear ? clearPerformanceBuffers() : null,
+  };
+  writeWindowRecord(window, summary);
+  forwardSamples();
+};
+
+const writeWindowRecord = (window: MarkerWindow, summary: Record<string, unknown>) => {
+  const json = JSON.stringify(summary);
+  perfLog(`window ${json}`);
+  windowListener?.(`${Date.now()} PERF_LAB window ${json}`);
+  if (settings.file) {
+    const path = getNative()?.writeText(
+      `window-${window.id}-${window.name.replace(/[^\w.:+-]/g, '_')}.json`,
+      json,
+    );
+    perfLog(`window file id=${window.id} path=${path ?? 'unavailable'}`);
+  }
+};
+
+const roundMs = (ms: number) => Math.round(ms * 1000) / 1000;
+
+const renderSummary = (ms: number[], timed: boolean) =>
+  timed
+    ? {
+        sum: roundMs(ms.reduce((s, n) => s + n, 0)),
+        max: roundMs(ms.reduce((m, n) => Math.max(m, n), 0)),
+        n: ms.length,
+      }
+    : null;
+
+const externalSummary = (window: MarkerWindow, timed: boolean) => {
+  const out: Record<
+    string,
+    {
+      commits: number;
+      renderMs: { sum: number; max: number; n: number } | null;
+      timerCarried: { commits: number; renderMs: { sum: number; max: number; n: number } | null };
+    }
+  > = {};
+  for (const source of Object.keys(window.external).sort()) {
+    const part = window.external[source] as ExternalPart;
+    out[source] = {
+      commits: part.commits,
+      renderMs: renderSummary(part.renderMs, timed),
+      timerCarried: { commits: part.timerCarried.commits, renderMs: renderSummary(part.timerCarried.renderMs, timed) },
+    };
+  }
+  return out;
+};
+
+const finalizeBackground = (window: MarkerWindow) => {
+  const profile = window.profile
+    ? summarizeWindowProfile(window.profile, { budget: frameBudget })
+    : null;
+  writeWindowRecord(window, {
+    v: 1,
+    windowModel: WINDOW_MODEL,
+    id: window.id,
+    name: window.name,
+    kind: window.kind,
+    t0: window.t0,
+    t1: window.t1,
+    durMs: window.t1 === null ? null : window.t1 - window.t0,
+    endReason: window.endReason,
+    settings: JSON.parse(window.settingsAtStart) as unknown,
+    react: {
+      commits: window.commits,
+      commitsByRenderer: window.commitsByRenderer,
+      renders: Object.values(window.renders).reduce((s, n) => s + n, 0),
+      mounts: window.mounts,
+      fibersVisited: window.fibersVisited,
+      componentsDistinct: Object.keys(window.renders).length,
+      top: topRenders(window.renders, 40),
+      profile,
+      causes: { process: PROCESS_ID, streamSeq: commitStream.seq(), offered: window.offered },
+      export: writeReactExport(window),
+    },
+  });
+};
+
+let sink = 0;
+
+export const burnCpu = (ms: number) => {
+  const t0 = now();
+  let x = sink;
+  while (now() - t0 < ms) {
+    for (let i = 0; i < 1000; i++) {
+      x = (x * 1103515245 + 12345) % 2147483648;
+    }
+  }
+  sink = x;
+  return now() - t0;
+};
+
+const leakState = {
+  retained: [] as unknown[],
+  retainedMB: 0,
+};
+
+const MB = 1024 * 1024;
+
+const leakNative = (mb: number) => {
+  // fill() touches every page, so the allocation shows in RSS/PSS and not only
+  // as reserved address space. ArrayBuffer memory is external to the Hermes heap.
+  leakState.retained.push(new Uint8Array(mb * MB).fill(1));
+  leakState.retainedMB += mb;
+};
+
+const leakJsHeap = (mb: number) => {
+  // ~8 bytes per element in the Hermes GC heap.
+  leakState.retained.push(
+    new Array(Math.round((mb * MB) / 8)).fill(Math.random()),
+  );
+  leakState.retainedMB += mb;
+};
+
+export const isFaultTarget = (windowName: string) =>
+  settings.faultTarget
+    .split(',')
+    .map(part => part.trim())
+    .some(part => part !== '' && windowName.includes(part));
+
+export const runOpenFaults = (where: string) => {
+  const faults = settings.faults;
+  if (faults.cpu > 0) {
+    const actual = burnCpu(faults.cpu);
+    perfLog(
+      `fault cpu where=${where} ms=${faults.cpu} actual=${fmt(actual)} t=${fmt(now())}`,
+    );
+  }
+  if (faults.leak > 0) {
+    leakNative(faults.leak);
+    perfLog(
+      `fault leak where=${where} mb=${faults.leak} retainedMB=${leakState.retainedMB}`,
+    );
+  }
+  if (faults.leakjs > 0) {
+    leakJsHeap(faults.leakjs);
+    perfLog(
+      `fault leakjs where=${where} mb=${faults.leakjs} retainedMB=${leakState.retainedMB}`,
+    );
+  }
+  if (faults.rerender > 0) {
+    // The prototype re-rendered a probe component placed in the chat sheet;
+    // with no app code there is no component to re-render.
+    perfLog(`fault rerender unsupported where=${where}`);
+  }
+};
+
+export const runDeferredFault = (where: string) => {
+  const ms = settings.faults.defer;
+  if (ms <= 0) {
+    return;
+  }
+  setTimeout(() => {
+    point('fault.defer.start');
+    const actual = burnCpu(ms);
+    point('fault.defer.end');
+    perfLog(`fault defer where=${where} ms=${ms} actual=${fmt(actual)}`);
+  }, 0);
+};
+
+const parseFaults = (spec: string): Faults => {
+  const faults: Faults = { ...NO_FAULTS };
+  if (spec === '' || spec === 'none' || spec === '0') {
+    return faults;
+  }
+  for (const part of spec.split(',')) {
+    const [key = '', value = '1'] = part.split(':');
+    if (key in faults) {
+      const parsed = Number(value);
+      faults[key as keyof Faults] =
+        Number.isFinite(parsed) && parsed > 0 ? parsed : 0;
+    } else {
+      perfLog(`unknown fault ${key}`);
+    }
+  }
+  return faults;
+};
+
+const flag = (value: string | undefined, current: boolean) =>
+  value === undefined ? current : value === '1' || value === 'true';
+
+type WindowListener = (line: string) => void;
+let windowListener: WindowListener | null = null;
+
+// Native clock of the last sampler record handed to the listener; records at
+// or before it are never sent again.
+let samplesSentT = -1;
+
+// Inside a run the sampler's records go out with the window lines (after a
+// window or at flush, never inside one), so the server derives the run-level
+// sampler.* metrics the CLI reads from the log. The native ring keeps the
+// last 64 records, so a gap without windows longer than that loses the oldest.
+const forwardSamples = () => {
+  const native = getNative();
+  if (!windowListener || !inRun() || samplerState.mode === 'off' || !native) {
+    return;
+  }
+  try {
+    for (const record of native.samplerRecent(Math.max(0, samplesSentT))) {
+      if (record.t <= samplesSentT) {
+        continue;
+      }
+      windowListener(`${record.wallMs} PERF_LAB sample ${JSON.stringify(record)}`);
+      samplesSentT = record.t;
+    }
+  } catch (error) {
+    samplerState.error = String(error);
+  }
+};
+
+export const setWindowListener = (listener: WindowListener | null) => {
+  windowListener = listener;
+};
+
+// Keyed by the run token and n: the driver numbers its commands from 1 in every session, so a number alone repeats across
+// runs of one process. Emptied at every flush, so a run never takes an answer of the run before it.
+const commandAnswers = new Map<string, string>();
+const COMMAND_ANSWERS_KEPT = 64;
+let gcRanSinceFlush = false;
+
+// A run event the backend derives from (the GC command, an AppState change): logged, and inside a run sent with the window lines.
+// AppState changes go out only once a GC command ran since the last flush, so a run without GC uploads exactly what it did
+// before, and the next run's activation link (a pause on Android) never lands in the run before it.
+export const writeRunEvent = (kind: 'gc' | 'appstate', record: Record<string, unknown>) => {
+  const json = JSON.stringify({ ...record, t: now(), wallMs: Date.now() });
+  perfLog(`${kind} ${json}`);
+  if (inRun() && (kind === 'gc' || gcRanSinceFlush)) {
+    windowListener?.(`${Date.now()} PERF_LAB ${kind} ${json}`);
+  }
+};
+
+// Kept out of `settings` because settings are logged. One per process in a
+// dormant build: set from the activation that started it, links only change
+// the next launch's.
+let runToken: string | null = null;
+
+export const getRunToken = () => runToken;
+
+let activation: { decision: Decision; store: ActivationStore } | null = null;
+
+type FlushResult = { ok: boolean; batches: number; lines: number; error: string | null };
+type FlushHandler = (deadline: number) => Promise<FlushResult>;
+let flushHandler: FlushHandler | null = null;
+
+export const setFlushHandler = (handler: FlushHandler | null) => {
+  flushHandler = handler;
+};
+
+// `flush=1`: end the open windows, send every unsent line, then show the result
+// to the test driver as an accessibility element (iOS: id `perflab.flushed`,
+// label `ok` / `error` / `off`), so a flow can wait for it without network access.
+const flushOnce = async () => {
+  // One deadline for the whole flush (lines, clock, artifacts); the end report of the upload comes after it.
+  const deadline = Date.now() + ARTIFACT_UPLOAD_DEADLINE_MS;
+  endAll('flush');
+  forwardSamples();
+  let artifacts: ArtifactEntry[] = [];
+  try {
+    artifacts = writeDeferredFiles();
+  } catch (error) {
+    perfLog(`flush files failed ${String(error)}`);
+  }
+  let status = 'off';
+  let detail = 'push not configured';
+  if (flushHandler) {
+    try {
+      const result = await flushHandler(deadline);
+      status = result.ok ? 'ok' : 'error';
+      detail = result.ok
+        ? `batches=${result.batches} lines=${result.lines}`
+        : String(result.error);
+    } catch (error) {
+      status = 'error';
+      detail = String(error);
+    }
+  }
+  try {
+    const sent = await sendArtifacts(artifacts, deadline);
+    if (sent) {
+      detail += ` artifacts=${sent.uploaded}/${sent.total}`;
+    }
+  } catch (error) {
+    perfLog(`artifacts failed ${String(error)}`);
+  }
+  perfLog(`flush ${status} ${detail}`);
+  try {
+    getNative()?.flushSignal?.(status, detail);
+  } catch (error) {
+    perfLog(`flush signal failed ${String(error)}`);
+  }
+};
+
+// A second flush link while one runs (the driver's final flush) waits for it: the flush signal means the
+// uploads of the first are done, so it must not be raised by a flush that has nothing left to send.
+let flushing: Promise<void> | null = null;
+export const flushNow = (): Promise<void> => {
+  commandAnswers.clear();
+  gcRanSinceFlush = false;
+  // The first flush starts at once (it ends the open windows in the same tick as the link).
+  const run = flushing === null ? flushOnce() : flushing.then(flushOnce);
+  const tail: Promise<void> = run
+    .catch(() => undefined)
+    .then(() => {
+      if (flushing === tail) {
+        flushing = null;
+      }
+    });
+  flushing = tail;
+  return run;
+};
+
+// The activation's profile/cpuprof turn those on for the whole process; off
+// leaves the build's env defaults.
+// A PerfLab run (one with a run token) forces an idle GC between windows so heap-after-GC
+// readings exist for the leak slope (plan 41 Q7); `gcwin=0` in a link still turns it off.
+const applyDecision = (decision: Decision) => {
+  settings.diag = decision.diag;
+  if (decision.runToken !== null) {
+    settings.gcwin = true;
+  }
+  if (decision.profile) {
+    settings.profile = true;
+  }
+  if (decision.cpuprof > 0) {
+    settings.cpuprof = true;
+    settings.cpuhz = decision.cpuprof;
+  }
+};
+
+export const setActivation = (decision: Decision, store: ActivationStore) => {
+  activation = { decision, store };
+  runToken = decision.runToken;
+  applyDecision(decision);
+  scheduleIdleGc();
+  syncCommandListener();
+};
+
+const activationReport = () => {
+  if (!activation) {
+    return { mode: 'active', buildMode: MODE, read: 'none' };
+  }
+  const { decision, store } = activation;
+  const next = store.current();
+  return {
+    mode: 'active',
+    buildMode: decision.mode,
+    read: decision.read,
+    installMs: g.__PERFLAB_ACTIVATION__?.installMs,
+    runToken: runToken !== null,
+    expiresAt: decision.expiresAt,
+    diag: decision.diag,
+    profile: decision.profile,
+    cpuprof: decision.cpuprof,
+    renderer: g.__PERFLAB_ACTIVATION__?.renderer ?? null,
+    next: next
+      ? {
+          active: next.active,
+          runToken: next.runToken !== null,
+          expiresAt: next.expiresAt,
+          diag: next.diag,
+          profile: next.profile,
+          cpuprof: next.cpuprof,
+        }
+      : null,
+    ...store.stats(),
+  };
+};
+
+export const applySettings = (params: Record<string, string>) => {
+  if (params.reset === '1') {
+    Object.assign(settings, defaultSettings());
+    if (activation) {
+      applyDecision(activation.decision);
+    }
+    leakState.retained = [];
+    leakState.retainedMB = 0;
+  }
+  // A dormant build takes both from the activation it started with; a link
+  // there only changes the next launch's.
+  if (params.runToken !== undefined && MODE !== 'dormant') {
+    runToken = params.runToken === '' ? null : params.runToken;
+    samplesSentT = nativeSamplerNow();
+    syncCommandListener();
+    if (runToken !== null) {
+      settings.gcwin = true;
+    }
+  }
+  if (params.diag !== undefined && MODE !== 'dormant') {
+    settings.diag = flag(params.diag, settings.diag);
+  }
+  settings.marks = flag(params.marks, settings.marks);
+  settings.hook = flag(params.hook, settings.hook);
+  settings.po = flag(params.po, settings.po);
+  settings.file = flag(params.file, settings.file);
+  settings.clear = flag(params.clear, settings.clear);
+  settings.gcwin = flag(params.gcwin, settings.gcwin);
+  scheduleIdleGc();
+  settings.net = flag(params.net, settings.net);
+  settings.rexport = flag(params.rexport, settings.rexport);
+  // Dormant: from the activation only, so the settings match the renderer the
+  // process loaded; these link params go to the next launch's record.
+  if (MODE !== 'dormant') {
+    settings.profile = flag(params.profile, settings.profile);
+    settings.cpuprof = flag(params.cpuprof, settings.cpuprof);
+    if (params.cpuhz !== undefined && Number(params.cpuhz) > 0) {
+      settings.cpuhz = Number(params.cpuhz);
+    }
+  }
+  cpu.configure(settings.cpuprof, settings.cpuhz);
+  if (
+    params.log === 'console' ||
+    params.log === 'native' ||
+    params.log === 'both'
+  ) {
+    settings.log = params.log;
+  }
+  if (params.fault !== undefined) {
+    settings.faults = parseFaults(params.fault);
+  }
+  if (params.target !== undefined) {
+    settings.faultTarget = params.target;
+  }
+  Object.assign(settings, applySamplerParams(settings, params));
+  syncSampler();
+  if (params.sample === '1') {
+    const record = sample('link');
+    if (!record) {
+      perfLog(`sample skipped sampler=${settings.sampler}`);
+    }
+  }
+  if (settings.po) {
+    startObservers();
+  } else {
+    stopObservers();
+  }
+  if (params.gc === '1') {
+    const before = readHermesStats();
+    g.gc?.();
+    perfLog(
+      `gc forced before=${JSON.stringify(before)} after=${JSON.stringify(readHermesStats())}`,
+    );
+  }
+  perfLog(
+    `settings ${JSON.stringify(settings)} hookCommits=${hookState.totalCommits} hookCostMs=${fmt(hookState.totalCostMs)} shortNames=${nameStats.short}/${nameStats.total}`,
+  );
+  if (params.dump === '1') {
+    logStartup('dump');
+  }
+};
+
+// GC before the action (docs/plans/gc-before-action.md): the driver's command n, sent before a declared step's start marker when
+// the run asks for it. It ends the open windows (the command is the test's next action), samples, runs a full GC, reads the heap,
+// samples again and answers. The answer is the signal the driver waits for; no time decides anything.
+
+const answerCommand = (n: number, text: string) => {
+  const native = getNative();
+  try {
+    native?.commandDone?.(n, text);
+    native?.ackSignal?.(text);
+  } catch (error) {
+    perfLog(`command answer failed ${String(error)}`);
+  }
+};
+
+export const actionGc = (n: number, tNative?: number): string => {
+  const key = `${runToken ?? '-'}#${n}`;
+  const known = commandAnswers.get(key);
+  if (known !== undefined) {
+    answerCommand(n, known);
+    return known;
+  }
+  let answer: string;
+  // Without a GC the command changes nothing: no window ends, no sample is taken, and the driver turns the command off.
+  if (typeof g.gc !== 'function') {
+    answer = `gc:${n} unavailable`;
+    writeRunEvent('gc', { n, status: 'unavailable' });
+  } else {
+    const queueMs = tNative === undefined ? null : (getNative()?.samplerNow() ?? tNative) - tNative;
+    const closed = [...openWindows.values()].map(w => w.id);
+    endAll('gc-command');
+    const pre = sample(`gc-pre:${n}`);
+    const heapBefore = readHermesStats();
+    const t0 = now();
+    g.gc();
+    const gcMs = now() - t0;
+    const heapAfter = readHermesStats();
+    const post = sample(`gc-post:${n}`);
+    // The idle probe end() just scheduled would GC again: this reading is the heap after GC the next window takes.
+    clearIdleGc();
+    idleHeap = heapAfter;
+    answer = `gc:${n} ok`;
+    gcRanSinceFlush = true;
+    writeRunEvent('gc', { n, status: 'ok', queueMs, gcMs, pre: pre?.seq ?? null, post: post?.seq ?? null, heapBefore, heapAfter, closed });
+  }
+  // The gc-pre / gc-post records go out now: the backend pairs them with this command by their seq.
+  forwardSamples();
+  commandAnswers.set(key, answer);
+  if (commandAnswers.size > COMMAND_ANSWERS_KEPT) {
+    commandAnswers.delete(commandAnswers.keys().next().value as string);
+  }
+  answerCommand(n, answer);
+  return answer;
+};
+
+let commandSubscription: { remove(): void } | null = null;
+
+// Android's receiver exists only while a run with a token measures; a dormant or tokenless process registers nothing.
+const syncCommandListener = () => {
+  const native = getNative();
+  if (!native?.commandListen) {
+    return;
+  }
+  const on = PERF_LAB_ENABLED && runToken !== null;
+  if (on && commandSubscription === null) {
+    commandSubscription =
+      native.addListener?.('perflabCommand', e => {
+        // A command native already timed out on is not run: its GC would land in the next step's action.
+        if (native.commandPending?.(e.n) === false) {
+          perfLog(`command gc:${e.n} late, skipped`);
+          return;
+        }
+        handlePerfLabCommand(e.cmd, e.n, e.tNative);
+      }) ?? null;
+  }
+  native.commandListen(on);
+};
+
+/** A command (`cmd=<name>&n=<n>`), from a link (iOS) or the native receiver (Android); unknown commands are ignored. */
+export const handlePerfLabCommand = (cmd: string | undefined, n: number, tNative?: number): boolean => {
+  if (!PERF_LAB_ENABLED || cmd !== 'gc' || !Number.isInteger(n) || n < 1) {
+    return false;
+  }
+  // Every received command is answered, so the Android receiver is never left pending.
+  try {
+    actionGc(n, tNative);
+  } catch (error) {
+    perfLog(`command gc:${n} failed ${String(error)}`);
+    answerCommand(n, `gc:${n} error`);
+  }
+  return true;
+};
+
+export const handlePerfLabDeepLink = (url: string) => {
+  if (!PERF_LAB_ENABLED) {
+    return;
+  }
+  const params = parseQuery(url.split('?')[1]);
+  // A command changes no settings and writes no activation record.
+  if (params.cmd !== undefined) {
+    handlePerfLabCommand(params.cmd, Number(params.n));
+    return;
+  }
+  const written = activation?.store.apply(params) ?? null;
+  if (written) {
+    perfLog(
+      `activation next-launch active=${written.active} runToken=${written.runToken !== null} expiresAt=${written.expiresAt}`,
+    );
+  }
+  applySettings(params);
+  if (params.flush === '1') {
+    void flushNow();
+  }
+};
+
+const safe = <T>(read: () => T): T | string => {
+  try {
+    return read();
+  } catch (error) {
+    return `error: ${String(error)}`;
+  }
+};
+
+const extraStartupSections = new Map<string, () => unknown>();
+
+export const addStartupSection = (name: string, read: () => unknown) => {
+  extraStartupSections.set(name, read);
+};
+
+export const logStartup = (phase: string) => {
+  const native = getNative();
+  const polyfill = g.__PERFLAB_HOOK__?.state;
+  const extra: Record<string, unknown> = {};
+  for (const [name, read] of extraStartupSections) {
+    extra[name] = safe(read);
+  }
+  const report = {
+    phase,
+    t: now(),
+    processId: PROCESS_ID,
+    runtimeProperties: safe(
+      () => g.HermesInternal?.getRuntimeProperties?.() ?? null,
+    ),
+    instrumentedStats: safe(
+      () => g.HermesInternal?.getInstrumentedStats?.() ?? null,
+    ),
+    supportedEntryTypes: safe(
+      () => g.PerformanceObserver?.supportedEntryTypes ?? null,
+    ),
+    typeofGc: typeof g.gc,
+    typeofConsoleTimeStamp: typeof g.console.timeStamp,
+    performanceMemory: safe(readMemory),
+    hook: {
+      installed: hookState.installed,
+      source: hookState.source,
+      preexisting: hookState.preexisting,
+      injected: hookState.injected,
+      totalCommits: hookState.totalCommits,
+      totalCostMs: hookState.totalCostMs,
+      outsideWindowCostMs: hookState.outsideWindowCostMs,
+      profilingRenderer: hookState.profilingRenderer,
+      polyfill: polyfill
+        ? {
+            installedAt: polyfill.installedAt,
+            typeofHookAtPolyfill: polyfill.typeofHookAtPolyfill,
+            dev: polyfill.dev,
+            mode: polyfill.mode,
+            chainedTargets: polyfill.chainedTargets,
+            replacedAfterInstall: polyfill.replacedAfterInstall,
+            injections: polyfill.injections,
+            commitsByRenderer: polyfill.commitsByRenderer,
+            errors: polyfill.errors,
+            invalid: polyfill.invalid,
+          }
+        : null,
+    },
+    activation: activationReport(),
+    registries: registrySizes(),
+    sampler: samplerStatus(),
+    ...extra,
+    native: native !== null,
+    tracing: native ? safe(() => native.isTracing()) : null,
+    clock: native
+      ? safe(() => {
+          const before = now();
+          const snapshot = native.clockSnapshot();
+          return { perfNowBefore: before, ...snapshot, perfNowAfter: now() };
+        })
+      : null,
+  };
+  // Startup goes to both sinks so day 1 learns whether console.log reaches
+  // logcat in a release build at all.
+  perfLog(`startup ${JSON.stringify(report)}`, native ? 'both' : 'console');
+};
+
+export const exposeGlobal = () => {
+  g.__PERF_LAB__ = {
+    settings,
+    set: applySettings,
+    markers,
+    sample,
+    // App lines in the same native log as the SDK's (log.txt / logcat), whatever the sink.
+    log: (message: string) => perfLog(`app ${message}`, 'both'),
+    dump: () => logStartup('global'),
+  };
+};