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

package/js/sdk/retain-floor.ts

@@ -0,0 +1,11 @@
+/**
+ * The oldest commit a later window can still need (REQ-MEAS-28, bounded by events): no visit starts before the current
+ * one opened; until the launch window opens (and before the first flush or trip to the background) the launch window can
+ * still start at the app's start; otherwise the newest action.
+ */
+export const retainFloorOf = (
+  openedAt: number | null,
+  launchPending: boolean,
+  launchT: number | null,
+  newestActionT: number,
+): number => openedAt ?? (launchPending && launchT !== null ? launchT : newestActionT);

package/js/sdk/sampler.ts

@@ -0,0 +1,236 @@
+// Native resource sampler: settings parsing and per-window aggregation.
+// Pure (no React Native imports) so it runs under `bun test`; core.ts wires it to the native module.
+
+export type SamplerMode = 'auto' | 'manual' | 'off';
+
+export interface SamplerSettings {
+  sampler: SamplerMode;
+  samplerMs: number;
+}
+
+// One record as the native module returns and logs it. Per-interval fields cover the time since the
+// previous sample of any mode; *Total / *Ms fields are cumulative, so any two samples can be differenced.
+export interface SamplerRecord {
+  v: number;
+  seq: number;
+  reason: string;
+  t: number;
+  wallMs: number;
+  dtMs?: number;
+  collectMs: number;
+  thermal?: number;
+  mem: { footprintMb?: number; residentMb?: number };
+  cpu: {
+    processMs?: number;
+    mainMs?: number;
+    jsMs?: number;
+    jsThread?: string;
+    processCores?: number;
+    mainCores?: number;
+    jsCores?: number;
+  };
+  frames: {
+    presentedTotal: number;
+    missedTotal: number;
+    presented?: number;
+    missed?: number;
+    longestGapMs?: number;
+    budgetMs?: number;
+    // iOS: UIScreen.maximumFramesPerSecond (120 on ProMotion).
+    maxHz?: number;
+    // Android FrameMetrics (frames the activity window drew, and those past their deadline); evidence only. Absent on iOS
+    // and on SDKs before alpha.10. A frame is counted at the first record taken after it ended. `longestMs` is the longest
+    // frame since the previous record, absent when none was drawn. `droppedTotal`: frames the framework dropped before
+    // reporting them (not in `drawnTotal`). `windowCovered`: another window (RN Modal, popup, system dialog) held focus
+    // during the interval, so its counts are unknown (not zero); SurfaceView/TextureView content is never in them.
+    drawnTotal?: number;
+    jankTotal?: number;
+    droppedTotal?: number;
+    drawn?: number;
+    jank?: number;
+    longestMs?: number;
+    windowCovered?: boolean;
+    source?: 'framemetrics';
+    // 'deadline': API 31+ FrameMetrics.DEADLINE. 'display-rate': API below 31, the current display frame interval.
+    jankBasis?: 'deadline' | 'display-rate';
+  };
+}
+
+export interface WindowSampler {
+  samples: number;
+  spanMs: number;
+  leadMs: number;
+  lagMs: number;
+  footprintStartMb: number | null;
+  footprintEndMb: number | null;
+  footprintDeltaMb: number | null;
+  footprintMaxMb: number | null;
+  cpuCores: number | null;
+  mainCores: number | null;
+  jsCores: number | null;
+  framesPresented: number;
+  framesMissed: number;
+  longestGapMs: number | null;
+  framesDrawn: number | null;
+  framesJank: number | null;
+  longestFrameMs: number | null;
+  // True: another window held focus inside the window, so framesDrawn, framesJank and longestFrameMs are null (unknown).
+  framesCovered: boolean | null;
+  framesJankBasis: 'deadline' | 'display-rate' | null;
+  collectMsMax: number;
+}
+
+export const SAMPLER_MS_MIN = 250;
+export const SAMPLER_MS_MAX = 60_000;
+// Background interval between native samples. 4 s: Arek 2026-10-16 (followups, RULING ~09:00); windows get their own
+// samples at open and close, so the background ones only serve peak memory in long windows and the heat trend.
+// The native samplers keep the same number as their unconfigured fallback (PerfLabSampler.swift / .kt).
+export const SAMPLER_MS_DEFAULT = 4000;
+
+export const parseSamplerMode = (
+  value: string | undefined,
+): SamplerMode | undefined =>
+  value === 'auto' || value === 'manual' || value === 'off' ? value : undefined;
+
+export const parseSamplerMs = (value: string | undefined): number | undefined => {
+  if (value === undefined || value === '') {
+    return undefined;
+  }
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed) || parsed <= 0) {
+    return undefined;
+  }
+  return Math.min(SAMPLER_MS_MAX, Math.max(SAMPLER_MS_MIN, Math.round(parsed)));
+};
+
+export interface SamplerEnv {
+  auto: boolean;
+  sampler?: string;
+  samplerMs?: string;
+}
+
+// Off unless enabled: the build env names the mode, measure-only (AUTO) builds default to auto.
+export const samplerDefaults = (env: SamplerEnv): SamplerSettings => ({
+  sampler: parseSamplerMode(env.sampler) ?? (env.auto ? 'auto' : 'off'),
+  samplerMs: parseSamplerMs(env.samplerMs) ?? SAMPLER_MS_DEFAULT,
+});
+
+export const applySamplerParams = (
+  current: SamplerSettings,
+  params: Record<string, string>,
+): SamplerSettings => ({
+  sampler: parseSamplerMode(params.sampler) ?? current.sampler,
+  samplerMs: parseSamplerMs(params.samplerMs) ?? current.samplerMs,
+});
+
+// Native clock and performance.now() are the same clock on both platforms today; the offset
+// is measured anyway so a mismatch shows up as a number instead of misaligned windows.
+export const estimateOffset = (before: number, native: number, after: number) =>
+  (before + after) / 2 - native;
+
+// How far past t0 a sample can be and still be the start bound of a window that has no open sample of its own, and how
+// late after its t0 a window can start and still take one. It gates only screen windows (a screen window opened by a
+// press is detected after the new screen rendered and takes the press's open sample, taken the touch delivery delay
+// past the press's t0) and the reuse of a close sample for a restarted key. Press windows do not depend on it: they
+// take the previous window's close sample by contiguity. Evidence for 50: idle lab event timing of 4.9-19.1 ms
+// (packages/derive/test/fixtures/p37-*.log); no loaded-device data. Measure the touchstart delivery delay p99 per
+// device from farm data (docs/log/followups.md).
+export const OPEN_SAMPLE_TOLERANCE_MS = 50;
+// A sample at or after t1 (the close sample) can also land a hair past it.
+const EDGE_TOLERANCE_MS = 1;
+
+const delta = (a: number | undefined, b: number | undefined) =>
+  a === undefined || b === undefined ? null : b - a;
+
+const rate = (a: number | undefined, b: number | undefined, ms: number) => {
+  const d = delta(a, b);
+  return d === null || d < 0 || ms <= 0 ? null : d / ms;
+};
+
+/**
+ * Aggregate of the samples that bracket [t0, t1] (native clock ms): the window's own open sample when it has one, else
+ * the last sample at or before t0 plus OPEN_SAMPLE_TOLERANCE_MS (a screen window's bound is the press's open sample,
+ * taken after the press's t0 by the touch delivery delay), and the first
+ * sample at/after t1 (the close sample). `leadMs` / `lagMs` say how far the bracket reaches outside the window;
+ * `leadMs` is slightly negative when the open sample is the touch delivery delay past t0.
+ */
+export const windowAggregate = (
+  records: readonly SamplerRecord[],
+  t0: number,
+  t1: number,
+  open?: SamplerRecord,
+): WindowSampler | null => {
+  const sorted = [...records].sort((x, y) => x.t - y.t);
+  let a: SamplerRecord | undefined = open && open.t < t1 ? open : undefined;
+  if (!a) {
+    for (const r of sorted) {
+      if (r.t <= t0 + OPEN_SAMPLE_TOLERANCE_MS && r.t <= t1) {
+        a = r;
+      }
+    }
+  }
+  const b = sorted.find(r => r.t >= t1 - EDGE_TOLERANCE_MS && (a === undefined || r.t > a.t));
+  if (!a || !b) {
+    return null;
+  }
+  const first = a;
+  const inside = sorted.filter(r => r.t > first.t && r.t <= b.t);
+  const span = b.t - a.t;
+  const sameJsThread = a.cpu.jsThread === b.cpu.jsThread;
+  const footprints = [a, ...inside]
+    .map(r => r.mem.footprintMb)
+    .filter((x): x is number => x !== undefined);
+  const gaps = inside
+    .map(r => r.frames.longestGapMs)
+    .filter((x): x is number => x !== undefined);
+  const frameMs = inside
+    .map(r => r.frames.longestMs)
+    .filter((x): x is number => x !== undefined);
+  const covered = [...inside].some(r => r.frames.windowCovered === true);
+  const counted = !covered && a.frames.drawnTotal !== undefined && b.frames.drawnTotal !== undefined;
+  return {
+    samples: inside.length + 1,
+    spanMs: span,
+    leadMs: t0 - a.t,
+    lagMs: b.t - t1,
+    footprintStartMb: a.mem.footprintMb ?? null,
+    footprintEndMb: b.mem.footprintMb ?? null,
+    footprintDeltaMb: delta(a.mem.footprintMb, b.mem.footprintMb),
+    footprintMaxMb: footprints.length ? Math.max(...footprints) : null,
+    cpuCores: rate(a.cpu.processMs, b.cpu.processMs, span),
+    mainCores: rate(a.cpu.mainMs, b.cpu.mainMs, span),
+    jsCores: sameJsThread ? rate(a.cpu.jsMs, b.cpu.jsMs, span) : null,
+    framesPresented: Math.max(0, b.frames.presentedTotal - a.frames.presentedTotal),
+    framesMissed: Math.max(0, b.frames.missedTotal - a.frames.missedTotal),
+    longestGapMs: gaps.length ? Math.max(...gaps) : null,
+    framesDrawn: counted ? Math.max(0, b.frames.drawnTotal! - a.frames.drawnTotal!) : null,
+    framesJank:
+      counted && a.frames.jankTotal !== undefined && b.frames.jankTotal !== undefined
+        ? Math.max(0, b.frames.jankTotal - a.frames.jankTotal)
+        : null,
+    longestFrameMs: counted && frameMs.length ? Math.max(...frameMs) : null,
+    framesCovered: b.frames.windowCovered === undefined ? null : covered,
+    framesJankBasis: b.frames.jankBasis ?? null,
+    collectMsMax: Math.max(...[a, ...inside].map(r => r.collectMs)),
+  };
+};
+
+// The device frame budget from a sampler record: the display's top rate when
+// the record has it (iOS lowers the current rate on idle ProMotion screens),
+// else the current frame interval (Android: 1000 / refresh rate). Null when
+// the frame counter has not run.
+export const frameBudgetFromRecord = (
+  record: Pick<SamplerRecord, 'frames'> | null | undefined,
+): { ms: number; hz: number } | null => {
+  const frames = record?.frames;
+  if (!frames) {
+    return null;
+  }
+  if (typeof frames.maxHz === 'number' && frames.maxHz > 1) {
+    return { ms: Math.round(10000 / frames.maxHz) / 10, hz: frames.maxHz };
+  }
+  if (typeof frames.budgetMs === 'number' && frames.budgetMs > 1) {
+    return { ms: Math.round(frames.budgetMs * 10) / 10, hz: Math.round(1000 / frames.budgetMs) };
+  }
+  return null;
+};