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

package/js/sdk/profile.ts

@@ -0,0 +1,539 @@
+// Per-component render cost and update causes, read from fibers in the commit
+// hook. Causes need only fields every renderer keeps (props, hook list,
+// context dependencies), so they work in a plain Release build. Times
+// (actualDuration / selfBaseDuration) and updaters (root.memoizedUpdaters)
+// exist only when the app runs React's profiling renderer.
+
+import {
+  CLASS_COMPONENT,
+  componentName,
+  type Fiber,
+  FORWARD_REF,
+  FUNCTION_COMPONENT,
+  SIMPLE_MEMO_COMPONENT,
+} from './fiber';
+
+export interface HookNode {
+  memoizedState: unknown;
+  queue: unknown;
+  next: HookNode | null;
+}
+
+export interface ContextDependency {
+  memoizedValue: unknown;
+  next: ContextDependency | null;
+}
+
+export interface ProfiledFiber extends Fiber {
+  memoizedState?: unknown;
+  dependencies?: { firstContext: ContextDependency | null } | null;
+  actualDuration?: number;
+  selfBaseDuration?: number;
+}
+
+export interface ProfiledRoot {
+  current: ProfiledFiber;
+  memoizedUpdaters?: Set<ProfiledFiber>;
+}
+
+export interface UpdateCause {
+  mount: boolean;
+  props: string[] | null;
+  hooks: number[] | null;
+  state: boolean;
+  context: boolean;
+  // Re-rendered only because the parent did: new props object, same values.
+  parent: boolean;
+}
+
+export const isProfilingFiber = (fiber: ProfiledFiber) =>
+  typeof fiber.actualDuration === 'number';
+
+const isObject = (value: unknown): value is Record<string, unknown> =>
+  value !== null && typeof value === 'object';
+
+export const changedKeys = (prev: unknown, next: unknown): string[] | null => {
+  if (prev === next || !isObject(prev) || !isObject(next)) {
+    return null;
+  }
+  const keys: string[] = [];
+  for (const key in next) {
+    if (!Object.is(prev[key], next[key])) {
+      keys.push(key);
+    }
+  }
+  for (const key in prev) {
+    if (!(key in next)) {
+      keys.push(key);
+    }
+  }
+  return keys.sort();
+};
+
+// Same rule as React DevTools: only hooks that can schedule an update
+// (useState/useReducer have `queue.pending`, useSyncExternalStore has
+// `queue.value` + `queue.getSnapshot`). Indexes count every hook in the list.
+const canScheduleUpdate = (hook: HookNode) => {
+  const queue = hook.queue;
+  if (!isObject(queue)) {
+    return false;
+  }
+  if ('pending' in queue) {
+    return true;
+  }
+  return 'value' in queue && typeof queue.getSnapshot === 'function';
+};
+
+const isHook = (value: unknown): value is HookNode =>
+  isObject(value) && 'memoizedState' in value && 'next' in value;
+
+export const changedHooks = (prev: unknown, next: unknown): number[] => {
+  const out: number[] = [];
+  let a = isHook(prev) ? prev : null;
+  let b = isHook(next) ? next : null;
+  let index = 0;
+  while (a !== null && b !== null) {
+    if (canScheduleUpdate(b) && !Object.is(a.memoizedState, b.memoizedState)) {
+      out.push(index);
+    }
+    a = a.next;
+    b = b.next;
+    index++;
+  }
+  return out;
+};
+
+export const contextChanged = (prev: ProfiledFiber, next: ProfiledFiber) => {
+  let a = prev.dependencies?.firstContext ?? null;
+  let b = next.dependencies?.firstContext ?? null;
+  while (a !== null && b !== null) {
+    if (!Object.is(a.memoizedValue, b.memoizedValue)) {
+      return true;
+    }
+    a = a.next;
+    b = b.next;
+  }
+  return false;
+};
+
+const usesHooks = (tag: number) =>
+  tag === FUNCTION_COMPONENT ||
+  tag === FORWARD_REF ||
+  tag === SIMPLE_MEMO_COMPONENT;
+
+// `fiber` is the committed fiber that performed work; its alternate is the
+// previous commit's version (null on mount).
+export const updateCause = (fiber: ProfiledFiber): UpdateCause => {
+  const prev = fiber.alternate as ProfiledFiber | null;
+  if (prev === null) {
+    return {
+      mount: true,
+      props: null,
+      hooks: null,
+      state: false,
+      context: false,
+      parent: false,
+    };
+  }
+  const props = changedKeys(prev.memoizedProps, fiber.memoizedProps);
+  const hooks = usesHooks(fiber.tag)
+    ? changedHooks(prev.memoizedState, fiber.memoizedState)
+    : null;
+  const state =
+    fiber.tag === CLASS_COMPONENT &&
+    !Object.is(prev.memoizedState, fiber.memoizedState);
+  const context = contextChanged(prev, fiber);
+  const parent =
+    (props === null || props.length === 0) &&
+    (hooks === null || hooks.length === 0) &&
+    !state &&
+    !context &&
+    prev.memoizedProps !== fiber.memoizedProps;
+  return {
+    mount: false,
+    props: props && props.length > 0 ? props : null,
+    hooks: hooks && hooks.length > 0 ? hooks : null,
+    state,
+    context,
+    parent,
+  };
+};
+
+// Time the fiber spent in its own render function (profiling renderer only).
+export const selfMs = (fiber: ProfiledFiber): number | null =>
+  typeof fiber.selfBaseDuration === 'number' ? fiber.selfBaseDuration : null;
+
+// Own render plus every descendant rendered in the same commit.
+export const totalMs = (fiber: ProfiledFiber): number | null =>
+  typeof fiber.actualDuration === 'number' ? fiber.actualDuration : null;
+
+export const updaterNames = (root: ProfiledRoot): string[] | null => {
+  const updaters = root.memoizedUpdaters;
+  if (!(updaters instanceof Set)) {
+    return null;
+  }
+  const names: string[] = [];
+  for (const fiber of updaters) {
+    names.push(componentName(fiber));
+  }
+  return names.sort();
+};
+
+export interface ComponentProfile {
+  renders: number;
+  mounts: number;
+  // Distinct instances (fiber pairs) that rendered.
+  instances: Set<number>;
+  selfMs: number;
+  // Self time of the renders that were first mounts.
+  mountSelfMs: number;
+  totalMs: number;
+  timed: number;
+  props: Record<string, number>;
+  hooks: Record<string, number>;
+  state: number;
+  context: number;
+  parent: number;
+  other: number;
+}
+
+export interface CommitProfile {
+  // Index of the commit in this process (1-based), for aligning windows.
+  seq: number;
+  timed: boolean;
+  renderMs: number | null;
+  updaters: string[] | null;
+  components: Map<string, ComponentProfile>;
+}
+
+const emptyComponent = (): ComponentProfile => ({
+  renders: 0,
+  mounts: 0,
+  instances: new Set(),
+  selfMs: 0,
+  mountSelfMs: 0,
+  totalMs: 0,
+  timed: 0,
+  props: {},
+  hooks: {},
+  state: 0,
+  context: 0,
+  parent: 0,
+  other: 0,
+});
+
+export const createCommitProfile = (root: ProfiledRoot, seq = 0): CommitProfile => {
+  const timed = isProfilingFiber(root.current);
+  return {
+    seq,
+    timed,
+    renderMs: timed ? totalMs(root.current) : null,
+    updaters: timed ? updaterNames(root) : null,
+    components: new Map(),
+  };
+};
+
+const bump = (map: Record<string, number>, key: string, by = 1) => {
+  map[key] = (map[key] ?? 0) + by;
+};
+
+export const recordFiber = (
+  commit: CommitProfile,
+  name: string,
+  fiber: ProfiledFiber,
+  cause: UpdateCause,
+  instance?: number,
+) => {
+  let entry = commit.components.get(name);
+  if (!entry) {
+    entry = emptyComponent();
+    commit.components.set(name, entry);
+  }
+  entry.renders++;
+  if (instance !== undefined) {
+    entry.instances.add(instance);
+  }
+  if (cause.mount) {
+    entry.mounts++;
+  } else {
+    let explained = false;
+    for (const key of cause.props ?? []) {
+      bump(entry.props, key);
+      explained = true;
+    }
+    for (const index of cause.hooks ?? []) {
+      bump(entry.hooks, String(index));
+      explained = true;
+    }
+    if (cause.state) {
+      entry.state++;
+      explained = true;
+    }
+    if (cause.context) {
+      entry.context++;
+      explained = true;
+    }
+    if (cause.parent) {
+      entry.parent++;
+      explained = true;
+    }
+    if (!explained) {
+      entry.other++;
+    }
+  }
+  const self = selfMs(fiber);
+  const total = totalMs(fiber);
+  if (self !== null && total !== null) {
+    entry.selfMs += self;
+    if (cause.mount) {
+      entry.mountSelfMs += self;
+    }
+    entry.totalMs += total;
+    entry.timed++;
+  }
+};
+
+export interface WindowProfile {
+  commits: number;
+  firstSeq: number | null;
+  lastSeq: number | null;
+  timedCommits: number;
+  renderMs: number[];
+  updaters: Record<string, number>;
+  components: Map<string, ComponentProfile>;
+}
+
+export const createWindowProfile = (): WindowProfile => ({
+  commits: 0,
+  firstSeq: null,
+  lastSeq: null,
+  timedCommits: 0,
+  renderMs: [],
+  updaters: {},
+  components: new Map(),
+});
+
+const mergeCounts = (into: Record<string, number>, from: Record<string, number>) => {
+  for (const key in from) {
+    bump(into, key, from[key] as number);
+  }
+};
+
+export const addCommitProfile = (window: WindowProfile, commit: CommitProfile) => {
+  window.commits++;
+  if (commit.seq > 0) {
+    window.firstSeq = window.firstSeq === null ? commit.seq : Math.min(window.firstSeq, commit.seq);
+    window.lastSeq = window.lastSeq === null ? commit.seq : Math.max(window.lastSeq, commit.seq);
+  }
+  if (commit.timed) {
+    window.timedCommits++;
+  }
+  if (commit.renderMs !== null) {
+    window.renderMs.push(commit.renderMs);
+  }
+  for (const name of commit.updaters ?? []) {
+    bump(window.updaters, name);
+  }
+  for (const [name, from] of commit.components) {
+    let into = window.components.get(name);
+    if (!into) {
+      into = emptyComponent();
+      window.components.set(name, into);
+    }
+    into.renders += from.renders;
+    into.mounts += from.mounts;
+    for (const id of from.instances) {
+      into.instances.add(id);
+    }
+    into.selfMs += from.selfMs;
+    into.mountSelfMs += from.mountSelfMs;
+    into.totalMs += from.totalMs;
+    into.timed += from.timed;
+    into.state += from.state;
+    into.context += from.context;
+    into.parent += from.parent;
+    into.other += from.other;
+    mergeCounts(into.props, from.props);
+    mergeCounts(into.hooks, from.hooks);
+  }
+};
+
+const round = (ms: number) => Math.round(ms * 1000) / 1000;
+
+const sortedCounts = (map: Record<string, number>) => {
+  const out: Record<string, number> = {};
+  for (const key of Object.keys(map).sort()) {
+    out[key] = map[key] as number;
+  }
+  return out;
+};
+
+// Sizes of the per-window summary (plan 40 §3.1): component rows, cause keys
+// per component, updaters.
+export const PROFILE_LIMITS = { components: 30, causeKeys: 3, updaters: 5 };
+
+// The budgets every timed window counts commits against (120 Hz and 60 Hz),
+// plus the device's own when it is neither.
+export const STANDARD_BUDGETS_MS = [8.3, 16.7];
+
+export interface FrameBudget {
+  ms: number;
+  hz: number | null;
+  source: 'sampler' | 'default';
+}
+
+const ranked = (a: [string, number], b: [string, number]) =>
+  b[1] - a[1] || (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0);
+
+// Every cause key of a component with its render count, flat:
+// `mount`, `props.<key>`, `hooks.<index>`, `state`, `context`, `parent`, `other`.
+export const causeCounts = (entry: ComponentProfile): [string, number][] => {
+  const out: [string, number][] = [];
+  if (entry.mounts > 0) out.push(['mount', entry.mounts]);
+  for (const key in entry.props) out.push([`props.${key}`, entry.props[key] as number]);
+  for (const key in entry.hooks) out.push([`hooks.${key}`, entry.hooks[key] as number]);
+  if (entry.state > 0) out.push(['state', entry.state]);
+  if (entry.context > 0) out.push(['context', entry.context]);
+  if (entry.parent > 0) out.push(['parent', entry.parent]);
+  if (entry.other > 0) out.push(['other', entry.other]);
+  return out.sort(ranked);
+};
+
+export interface CauseSummary {
+  props?: Record<string, number>;
+  hooks?: Record<string, number>;
+  state?: number;
+  context?: number;
+  parent?: number;
+  other?: number;
+  // Cause keys left out (beyond the top keys).
+  omitted?: number;
+}
+
+// Render counts of the top cause keys (mounts excluded: the row has them), in
+// the nested shape `derive` reads. Counts, not shares, so windows add up.
+export const causeSummary = (entry: ComponentProfile, limit = Infinity): CauseSummary => {
+  const all = causeCounts(entry).filter(([key]) => key !== 'mount');
+  const kept = all.slice(0, limit);
+  const out: CauseSummary = {};
+  for (const [key, n] of kept.sort((a, b) => (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0))) {
+    const dot = key.indexOf('.');
+    if (dot > 0) {
+      const group = key.slice(0, dot) as 'props' | 'hooks';
+      out[group] = { ...(out[group] ?? {}), [key.slice(dot + 1)]: n };
+    } else {
+      out[key as 'state' | 'context' | 'parent' | 'other'] = n;
+    }
+  }
+  if (all.length > kept.length) {
+    out.omitted = all.length - kept.length;
+  }
+  return out;
+};
+
+// Share of the component's renders per cause key (mount included), top keys
+// only. One render can have several causes, so shares can sum past 1.
+export const causeShares = (entry: ComponentProfile, limit = PROFILE_LIMITS.causeKeys) => {
+  const out: Record<string, number> = {};
+  if (entry.renders === 0) {
+    return out;
+  }
+  for (const [key, n] of causeCounts(entry).slice(0, limit)) {
+    out[key] = round(n / entry.renders);
+  }
+  return out;
+};
+
+// Commits whose render time exceeds each budget. Keys are the budget in ms
+// with one decimal (`"8.3"`, `"16.7"`).
+export const overBudgetCounts = (renderMs: number[], budgets: number[]) => {
+  const out: Record<string, number> = {};
+  for (const budget of [...new Set(budgets.map(b => Math.round(b * 10) / 10))].sort((a, b) => a - b)) {
+    out[budget.toFixed(1)] = renderMs.filter(ms => ms > budget).length;
+  }
+  return out;
+};
+
+const DEFAULT_BUDGET: FrameBudget = { ms: 16.7, hz: null, source: 'default' };
+
+// Component rows: [name, renders, mounts, instances, selfMs, totalMs]; times
+// are null without the profiling renderer. Rows are the top components by self
+// time when timed, else by renders (then name), so a production-renderer run
+// with the same renders prints the same rows.
+export type ComponentRow = [string, number, number, number, number | null, number | null];
+
+export const summarizeWindowProfile = (
+  window: WindowProfile,
+  options: { budget?: FrameBudget; limits?: Partial<typeof PROFILE_LIMITS> } = {},
+) => {
+  const limits = { ...PROFILE_LIMITS, ...options.limits };
+  const budget = options.budget ?? DEFAULT_BUDGET;
+  const timed = window.timedCommits > 0;
+  const all = [...window.components.entries()].sort(
+    (a, b) =>
+      (timed ? b[1].selfMs - a[1].selfMs : 0) ||
+      b[1].renders - a[1].renders ||
+      (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0),
+  );
+  const kept = all.slice(0, limits.components);
+  const components: ComponentRow[] = kept.map(([name, entry]) => [
+    name,
+    entry.renders,
+    entry.mounts,
+    entry.instances.size,
+    timed ? round(entry.selfMs) : null,
+    timed ? round(entry.totalMs) : null,
+  ]);
+  const causes: Record<string, CauseSummary> = {};
+  const shares: Record<string, Record<string, number>> = {};
+  for (const [name, entry] of kept) {
+    const summary = causeSummary(entry, limits.causeKeys);
+    if (Object.keys(summary).length > 0) {
+      causes[name] = summary;
+    }
+    shares[name] = causeShares(entry, limits.causeKeys);
+  }
+  const updaters = Object.entries(window.updaters).sort(ranked);
+  const renderSum = window.renderMs.reduce((s, n) => s + n, 0);
+  const selfTotal = timed
+    ? [...window.components.values()].reduce((s, e) => s + e.selfMs, 0)
+    : null;
+  const mountSelfTotal = timed
+    ? [...window.components.values()].reduce((s, e) => s + e.mountSelfMs, 0)
+    : null;
+  return {
+    renderer: timed ? 'profiling' : 'production',
+    commits: window.commits,
+    commitSeq:
+      window.firstSeq === null || window.lastSeq === null
+        ? null
+        : [window.firstSeq, window.lastSeq],
+    renderMs: timed
+      ? {
+          sum: round(renderSum),
+          max: round(window.renderMs.reduce((m, n) => Math.max(m, n), 0)),
+          n: window.renderMs.length,
+        }
+      : null,
+    frameBudget: budget,
+    overBudget: timed
+      ? overBudgetCounts(window.renderMs, [...STANDARD_BUDGETS_MS, budget.ms])
+      : null,
+    selfMsTotal: selfTotal === null ? null : round(selfTotal),
+    mountSelfMs: mountSelfTotal === null ? null : round(mountSelfTotal),
+    updaters: timed ? sortedCounts(Object.fromEntries(updaters.slice(0, limits.updaters))) : null,
+    updatersOmitted: timed ? Math.max(0, updaters.length - limits.updaters) : 0,
+    components,
+    causes,
+    shares,
+    omitted: all.length - kept.length,
+  };
+};
+
+export type WindowProfileSummary = ReturnType<typeof summarizeWindowProfile>;
+
+// The window broke the device frame budget: a commit took longer than a frame.
+export const brokeFrameBudget = (summary: WindowProfileSummary) => {
+  const key = (Math.round(summary.frameBudget.ms * 10) / 10).toFixed(1);
+  return (summary.overBudget?.[key] ?? 0) > 0;
+};

package/js/sdk/push-install.ts

@@ -0,0 +1,158 @@
+// Wires the push client to React Native: env config, device info, AppState.
+// Push stays off unless both EXPO_PUBLIC_KEEPSNAPPY_INGEST_URL and
+// EXPO_PUBLIC_KEEPSNAPPY_KEY are set at build time.
+
+import { AppState, Platform } from 'react-native';
+
+import { MODE } from './activation';
+import { type ArtifactUploadNative, createArtifactUploader } from './artifacts';
+import {
+  addStartupSection,
+  getRunToken,
+  isWindowOpen,
+  perfLog,
+  setArtifactHandler,
+  setFlushHandler,
+  setWindowListener,
+} from './core';
+import { ownFetch } from './net-install';
+import { createPushClient, type DeviceInfo, type PushSpool } from './push';
+
+const INGEST_URL = (process.env.EXPO_PUBLIC_KEEPSNAPPY_INGEST_URL);
+const INGEST_KEY = (process.env.EXPO_PUBLIC_KEEPSNAPPY_KEY);
+
+const randomId = () =>
+  `r${Date.now().toString(36)}${Math.random().toString(36).slice(2, 10)}`;
+
+// The published package.json carries the release version (scripts/release/stage.ts).
+const sdkVersion = (): string | null => {
+  try {
+    const v = (require('../../package.json') as { version?: unknown }).version;
+    return typeof v === 'string' ? v : null;
+  } catch {
+    return null;
+  }
+};
+
+const readDevice = async (): Promise<DeviceInfo> => {
+  let installId = randomId();
+  let model: string | null = null;
+  let os: string | null = null;
+  let build: string | null = null;
+  try {
+    const Device = require('expo-device');
+    model = Device.modelName ?? Device.modelId ?? null;
+    os = Device.osVersion ?? null;
+  } catch {
+    // device fields stay null
+  }
+  try {
+    const Application = require('expo-application');
+    build = Application.nativeBuildVersion ?? null;
+    const id =
+      Platform.OS === 'ios'
+        ? await Application.getIosIdForVendorAsync()
+        : Application.getAndroidId?.();
+    if (id) {
+      installId = String(id);
+    }
+  } catch {
+    // keeps the per-process random id
+  }
+  return {
+    model,
+    os,
+    install_id: installId,
+    app_build: build,
+    platform: Platform.OS,
+    sdk_version: sdkVersion(),
+  };
+};
+
+interface SpoolNative {
+  spoolRead?: () => string | null;
+  spoolAppend?: (record: string) => void;
+  spoolReplace?: (content: string) => boolean;
+}
+
+// Gzip + PUT of a raw profile file. Without it (an older binary) the files of
+// a run stay on the device and the manifest says so.
+const nativeArtifacts = (): ArtifactUploadNative | null => {
+  const native = (
+    globalThis as unknown as { expo?: { modules?: Record<string, unknown> } }
+  ).expo?.modules?.PerfLab as Partial<ArtifactUploadNative> | undefined;
+  if (!native || typeof native.artifactUpload !== 'function') {
+    return null;
+  }
+  const { artifactUpload } = native;
+  return { artifactUpload: (...args) => artifactUpload.apply(native, args) };
+};
+
+// The journal file next to the log (perf-lab/push-spool.jsonl). Without these
+// native functions (an older binary) the queue is memory-only, as before.
+const nativeSpool = (): PushSpool | null => {
+  const native = (
+    globalThis as unknown as { expo?: { modules?: Record<string, unknown> } }
+  ).expo?.modules?.PerfLab as SpoolNative | undefined;
+  if (
+    !native ||
+    typeof native.spoolRead !== 'function' ||
+    typeof native.spoolAppend !== 'function' ||
+    typeof native.spoolReplace !== 'function'
+  ) {
+    return null;
+  }
+  const { spoolRead, spoolAppend, spoolReplace } = native;
+  return {
+    read: () => spoolRead.call(native),
+    append: record => spoolAppend.call(native, record),
+    replace: content => spoolReplace.call(native, content),
+  };
+};
+
+export const installPush = () => {
+  if (!INGEST_URL || !INGEST_KEY) {
+    addStartupSection('push', () => ({ enabled: false }));
+    return;
+  }
+  // A measured run (dormant build activated, or a process started with a run
+  // token) sends nothing while it runs: lines stay in the journal file until a
+  // `flush=1` link at the end of the iteration. Other builds push when idle.
+  const autoFlush = MODE !== 'dormant' && getRunToken() === null;
+  const push = createPushClient({
+    autoFlush,
+    url: INGEST_URL,
+    key: INGEST_KEY,
+    fetch: ownFetch,
+    now: Date.now,
+    setTimer: (run, ms) => setTimeout(run, ms),
+    clearTimer: handle => clearTimeout(handle as ReturnType<typeof setTimeout>),
+    isWindowOpen: () => isWindowOpen(),
+    getRunToken,
+    getDevice: readDevice,
+    spool: nativeSpool(),
+  });
+  // The journal of earlier processes is read at the first idle send or at the
+  // flush link, never during startup or inside a measured window.
+  setWindowListener(push.enqueue);
+  setFlushHandler(deadline => push.flushAll(3, deadline));
+  const artifacts = createArtifactUploader({
+    url: INGEST_URL,
+    key: INGEST_KEY,
+    fetch: ownFetch,
+    native: nativeArtifacts,
+    isWindowOpen: () => isWindowOpen(),
+    now: Date.now,
+    sleep: ms => new Promise(resolve => setTimeout(resolve, ms)),
+    log: message => perfLog(message),
+  });
+  setArtifactHandler(artifacts.upload);
+  if (autoFlush) {
+    AppState.addEventListener('change', state => {
+      if (state === 'background' || state === 'inactive') {
+        void push.flush('background');
+      }
+    });
+  }
+  addStartupSection('push', () => push.stats());
+};