@goliapkg/sentori-react-native 2.0.0 → 2.2.0

package/src/config.ts

@@ -1,21 +1,12 @@
-import type { LogLevel } from '@goliapkg/sentori-core';
+import type { BeforeSendHook, LogLevel, ReadyInfo } from '@goliapkg/sentori-core';
 
 /**
- * Optional structured signal handed to `onReady` after init
- * completes. Host wires the callback if they want to know the SDK
- * is live (alternative to scanning console).
+ * v2.3 — `ReadyInfo` is shared across SDKs via `@goliapkg/sentori-core`
+ * so a host that switches from web to RN reads the same shape. The RN
+ * SDK always populates `native` + `coldStartMs`; the core type marks
+ * both optional for the web SDK's benefit (web has no native module).
  */
-export type ReadyInfo = {
-  /** npm version string of @goliapkg/sentori-react-native */
-  sdkVersion: string;
-  /** Milliseconds between RN cold-start signal and SDK init
-   *  completion. May be undefined if native module wasn't bound. */
-  coldStartMs?: number;
-  /** Native module status. `bound: false` means screenshot /
-   *  wireframe / native crash capture won't fire — useful for
-   *  host to know if e.g. they forgot to autolink. */
-  native: { bound: boolean; methods: string[] };
-};
+export type { ReadyInfo };
 
 export type Config = {
   token: string;
@@ -56,6 +47,12 @@ export type Config = {
    *  the native-module bind status + cold-start timing. Host
    *  wraps any host-side logging here. */
   onReady?: (info: ReadyInfo) => void;
+  /** v2.3 — host-side mutate-or-drop hook called once per event
+   *  just before transport enqueue. Return the event to send it,
+   *  `null` to drop. Sync only. If the hook throws or returns a
+   *  non-event, SDK falls back to the un-mutated event and emits
+   *  one one-shot warn. */
+  beforeSend?: BeforeSendHook;
 };
 
 let _config: Config | null = null;

package/src/handlers/network.ts

@@ -2,6 +2,13 @@ import { normalizeUrl, startSpan } from '@goliapkg/sentori-core';
 
 import { addBreadcrumb } from '../breadcrumbs';
 import { getConfig } from '../config';
+// v2.1 W2 — bytes counters drive the runtime.network.{sent,received}
+// metrics. Cheap two-add per request, no allocation.
+import {
+  estimateRequestBytes,
+  estimateResponseBytes,
+  recordNetworkBytes,
+} from '../runtime-metrics-network';
 
 let _installed = false;
 let _graphqlEnabled = true;
@@ -88,6 +95,10 @@ function patchFetch(): void {
       const resp = await original(input, reqInit);
       span.setTag('http.status', String(resp.status));
       span.finish({ status: resp.status >= 400 ? 'error' : 'ok' });
+      // v2.1 W2 — bytes accounting. Sent estimated from
+      // init.body; received read from response Content-Length
+      // header (0 when missing / chunked — undercount-safe).
+      recordNetworkBytes(estimateRequestBytes(init), estimateResponseBytes(resp.headers));
       addBreadcrumb({
         type: 'net',
         data: gqlOp

package/src/index.ts

@@ -121,6 +121,20 @@ export type {
   CaptureMessageOptions,
   MessageLevel,
 } from '@goliapkg/sentori-core';
+/** v2.3 — logger surface re-exported from core so hosts can
+ *  `import { setLogLevel } from '@goliapkg/sentori-react-native'`
+ *  per design §3 ("Production override"). `setLogTransport` lets
+ *  hosts route Sentori-internal lines into their own log
+ *  aggregator (Datadog, etc.). */
+export {
+  getLogLevel,
+  type LogLevel,
+  logger,
+  type LogTransport,
+  setLogLevel,
+  setLogTransport,
+} from '@goliapkg/sentori-core';
+export type { ReadyInfo } from './config';
 export { ErrorBoundary } from './error-boundary';
 export { FeedbackButton, type FeedbackButtonHandle, type FeedbackButtonProps } from './feedback-widget';
 export {

package/src/init.ts

@@ -12,6 +12,14 @@ import {
 } from './launch-crash-guard';
 import { getInstallId } from './install-id';
 import { startMetricsTimer } from './metrics';
+import {
+  emitColdStart,
+  markColdStartT0,
+  startRuntimeMetricsTimer,
+} from './runtime-metrics';
+import { startFpsInstrument } from './runtime-metrics-fps';
+import { startHeapInstrument } from './runtime-metrics-heap';
+import { startNetworkBytesInstrument } from './runtime-metrics-network';
 import { startTrackTimer } from './track';
 import { drainNativePending, markNativeJsBridgeReady, setNativeConfig } from './native';
 import { getColdStartMs } from './mobile-vitals';
@@ -81,6 +89,16 @@ export type InitOptions = {
      *  breadcrumb shape on upgrade; recommended `true` for new
      *  integrations. See `docs/recipes/track-and-metrics.md`. */
     trackAutoBreadcrumb?: boolean;
+    /** v2.1 W2 — auto-instrument runtime metrics (FPS, JS heap,
+     *  cold-start, route nav timing, network bytes). Drains the
+     *  shared `@goliapkg/sentori-core` ring to
+     *  `/v1/runtime-metrics:batch` every 30 s. Defaults to `true`
+     *  in W2 part 2 — cold-start only, ~6 emits per session
+     *  per device, ~zero main-thread cost. Higher-cost instruments
+     *  (FPS / route-nav) land in W2 part 3 with per-tick perf
+     *  budget tests as stop-ship gates per
+     *  `.claude/CLAUDE.md` performance bedrock. */
+    runtimeMetrics?: boolean;
     /** v0.9.1 +S4 — pre-crash sentinel. Subscribes to JS-thread
      *  frame timing; when ≥ 50% of a 60-frame window misses the
      *  budget (default 32 ms / < 30 fps), emits a `kind: nearCrash`
@@ -158,6 +176,13 @@ export type InitOptions = {
    *  SDK is live instead of scanning the console. The `ReadyInfo`
    *  carries native-module bind status + cold-start timing. */
   onReady?: (info: ReadyInfo) => void;
+  /** v2.3 — mutate-or-drop hook on each outbound event (sync).
+   *  Return the event to ship it (possibly mutated), or `null` to
+   *  drop. See `BeforeSendHook` for the throwing / non-event
+   *  fallback policy. Used for host-side PII scrubbing the SDK
+   *  can't do automatically; server-side privacy_lab still runs
+   *  regardless. */
+  beforeSend?: import('@goliapkg/sentori-core').BeforeSendHook;
 };
 
 const DEFAULT_INGEST_URL = 'https://ingest.sentori.golia.jp';
@@ -210,6 +235,9 @@ export const init = (options: InitOptions): void => {
     // carries the customer journey. Defaults false to preserve v1
     // breadcrumb shape on upgrade.
     trackAutoBreadcrumb: options.capture?.trackAutoBreadcrumb === true,
+    // v2.3 — host-side beforeSend hook (sync). Stored on Config so
+    // capture.ts can pull it without re-resolving the InitOptions.
+    beforeSend: options.beforeSend,
   });
 
   // Tell the native crash handler about the config so the JSON it writes
@@ -249,6 +277,36 @@ export const init = (options: InitOptions): void => {
   startMetricsTimer();
   // v1.1 chunk B — drain `sentori.track()` ring every 30 s.
   startTrackTimer();
+  // v2.1 W2 — runtime metrics auto-instrument. Defaults on; host
+  // can opt out with `capture: { runtimeMetrics: false }`. The
+  // ring + emit live in `@goliapkg/sentori-core`; we own the
+  // 30 s flusher + the cold-start one-shot here. FPS / heap /
+  // route-nav / network instruments ship in W2 part 3 (each
+  // gated on its own per-tick perf budget CI test).
+  if (options.capture?.runtimeMetrics !== false) {
+    markColdStartT0();
+    startRuntimeMetricsTimer();
+    // Defer the emit one tick so React's first paint settles
+    // before we stamp "cold-start ended". 0-delay setTimeout puts
+    // the call after the current microtask queue drains.
+    setTimeout(emitColdStart, 0);
+    // FPS via rAF (per-tick budget < 0.5 ms — see
+    // runtime-metrics-fps.ts header). Heap is a 30 s polling
+    // tick; no-op when performance.memory isn't exposed (most
+    // RN engines today; we ship the wiring anyway so the same
+    // SDK works on web targets via @goliapkg/sentori-javascript).
+    startFpsInstrument();
+    startHeapInstrument();
+    // Network bytes counters drain every 30 s. The counters
+    // themselves are incremented inline by handlers/network.ts
+    // on every fetch round-trip — see the recordNetworkBytes
+    // call site there. No-op when `capture.network: false` is
+    // set (no fetch patch → no counter increments).
+    startNetworkBytesInstrument();
+    // Route-nav dwell timing emits inline from `navigation.ts`'s
+    // useTraceNavigation state listener — no extra start call
+    // needed; the host already mounts that hook for tracing.
+  }
   // v1.1 chunk S1 — warm the install-id cache. Fire-and-forget;
   // any event captured before the first resolve simply omits
   // `device.installId`. Subsequent captures pick it up via the

package/src/navigation.ts

@@ -22,7 +22,7 @@
 
 import { useEffect, useRef } from 'react';
 
-import { setActiveSpan, startSpan, type SpanHandle } from '@goliapkg/sentori-core';
+import { emitMetric, setActiveSpan, startSpan, type SpanHandle } from '@goliapkg/sentori-core';
 
 import {
   getNativeFrameCounters,
@@ -161,6 +161,19 @@ export function useTraceNavigation(navigationRef: NavigationRefLike): void {
       const prev = lastRouteRef.current;
       if (next === null || next === prev) return;
       const dwellMs = finishOpenSpanWithDwell();
+      // v2.1 W2 — emit dwell as a runtime metric so the BI panel
+      // can rank screens by how long users sat on them. Tagged
+      // with `from` + `to` so a release-over-release diff can spot
+      // a 2x dwell regression on Onboarding etc. emit is cheap +
+      // bounded by the core ring cap; if `capture.runtimeMetrics:
+      // false` the flush is off but the ring still records up to
+      // the cap before dropping oldest.
+      if (typeof dwellMs === 'number' && dwellMs >= 0) {
+        emitMetric('runtime.route_nav_ms', dwellMs, {
+          from: prev ?? '',
+          to: next ?? '',
+        });
+      }
       openScreenSpan(prev, next, dwellMs);
     });
 

package/src/runtime-metrics-fps.ts

@@ -0,0 +1,137 @@
+// v2.1 W2 part 3 — FPS auto-instrument.
+//
+// Rolling 5 s window of inter-frame Δt measured via rAF; emit
+// runtime.fps.p50 + runtime.fps.p95 every 5 s.
+//
+// Perf bedrock (.claude/CLAUDE.md):
+//   • per-tick cost must be < 0.5 ms on a Pixel-5-equivalent
+//     bench → stop-ship gate in W2 part 4 CI
+//   • main-thread sustained < 1 %
+//   • no allocation inside the rAF callback hot path
+//
+// Implementation choices:
+//   • single-frame Δt = perf.now() - prev — cheap, no allocation
+//   • rolling window stored in a fixed-size Float32Array (no
+//     splice / shift — circular buffer write index)
+//   • percentile computed by copying-and-sorting only at emit
+//     time (every 5 s, ~300 floats) — no per-tick sort
+//
+// Bail-outs:
+//   • if requestAnimationFrame isn't available (rare RN host),
+//     never start the loop
+//   • if perf.now() is missing (older RN engines), fall back to
+//     Date.now() — coarser but better than crashing
+
+import { emitMetric } from '@goliapkg/sentori-core';
+
+const TICK_FRAMES_BEFORE_EMIT = 300; // ~5 s at 60 fps
+const SAMPLE_CAP = 600; // safety: 10 s at 60 fps caps memory
+
+let _running = false;
+let _samples = new Float32Array(SAMPLE_CAP);
+let _write = 0;
+let _count = 0;
+let _prev = 0;
+
+function now(): number {
+  // Engines without perf.now() (very old RN runtimes / minimal
+  // JSCore builds) fall back to wall-clock. Date.now() has 1 ms
+  // resolution so FPS readings cap at 1000; good enough.
+  const p = (globalThis as { performance?: { now?: () => number } }).performance;
+  return p?.now ? p.now() : Date.now();
+}
+
+function rafTick(t: number): void {
+  if (!_running) return;
+  if (_prev !== 0) {
+    const dt = t - _prev;
+    if (dt > 0 && dt < 1000) {
+      _samples[_write] = dt;
+      _write = (_write + 1) % SAMPLE_CAP;
+      _count += 1;
+      if (_count >= TICK_FRAMES_BEFORE_EMIT) {
+        emitWindow();
+        _count = 0;
+        _write = 0;
+      }
+    }
+  }
+  _prev = t;
+  requestAnimationFrame(rafTick);
+}
+
+function emitWindow(): void {
+  // Copy + sort. ~300 floats, well under 1 ms even on a slow phone.
+  // Allocation lives outside the per-tick hot path — only at emit.
+  const n = _count;
+  if (n === 0) return;
+  const slice = new Float32Array(n);
+  for (let i = 0; i < n; i++) slice[i] = _samples[i]!;
+  slice.sort();
+  const p50dt = percentile(slice, 0.5);
+  const p95dt = percentile(slice, 0.95);
+  // FPS = 1000 ms / per-frame Δt.
+  const fpsP50 = p50dt > 0 ? Math.round(1000 / p50dt) : 0;
+  // p95 of Δt is the *slowest* 95 % — i.e. when frames are bad.
+  // p95 FPS conventionally means "5 % worst frames as fps".
+  const fpsP5Slow = p95dt > 0 ? Math.round(1000 / p95dt) : 0;
+  emitMetric('runtime.fps.p50', fpsP50);
+  emitMetric('runtime.fps.p95', fpsP5Slow);
+}
+
+function percentile(sorted: Float32Array, q: number): number {
+  if (sorted.length === 0) return 0;
+  // Discrete percentile — index = ceil(q * n) - 1, clamped.
+  const idx = Math.min(sorted.length - 1, Math.max(0, Math.ceil(q * sorted.length) - 1));
+  return sorted[idx]!;
+}
+
+/** Idempotent start. Safe to call multiple times; only the first
+ *  call kicks off the rAF loop. */
+export function startFpsInstrument(): void {
+  if (_running) return;
+  if (typeof requestAnimationFrame !== 'function') return;
+  _running = true;
+  _prev = 0;
+  _count = 0;
+  _write = 0;
+  requestAnimationFrame(rafTick);
+}
+
+/** Stop the loop. Used by tests + by hosts that want to opt out
+ *  mid-session. */
+export function stopFpsInstrument(): void {
+  _running = false;
+}
+
+/** Test-only state inspection. */
+export function __peekFpsInstrumentState(): {
+  count: number;
+  running: boolean;
+} {
+  return { count: _count, running: _running };
+}
+
+/** Test-only force-emit (skips the every-300-frames gate). */
+export function __forceEmitFpsForTests(): void {
+  emitWindow();
+  _count = 0;
+  _write = 0;
+}
+
+/** Test-only sample injection so we can assert without spinning
+ *  rAF in the test runner. */
+export function __pushSampleForTests(dt: number): void {
+  _samples[_write] = dt;
+  _write = (_write + 1) % SAMPLE_CAP;
+  _count += 1;
+}
+
+/** Test-only reset between runs. */
+export function __resetFpsInstrumentForTests(): void {
+  _running = false;
+  _samples = new Float32Array(SAMPLE_CAP);
+  _write = 0;
+  _count = 0;
+  _prev = 0;
+}

package/src/runtime-metrics-heap.ts

@@ -0,0 +1,78 @@
+// v2.1 W2 part 3 — JS heap auto-instrument.
+//
+// Polls `performance.memory.usedJSHeapSize` every 30 s, emits
+// runtime.heap.used_bytes. Web-only metric, RN best-effort —
+// the V8/Hermes value depends on which engine RN is wired to:
+//   • Hermes (RN ≥ 0.70 default): exposes a per-isolate count
+//     when memoryReporter is enabled (Hermes 0.12+)
+//   • JSC (legacy / explicit opt-in): no native equivalent
+//   • Web (sdk-javascript wires this same module): Chromium
+//     gates it behind a high-resolution-timer flag in some
+//     contexts; treat missing field as a silent no-op
+//
+// Cost: one number read + one emit every 30 s. Negligible.
+// The timer .unref()s so Node tests / CLI hosts exit cleanly.
+
+import { emitMetric } from '@goliapkg/sentori-core';
+
+const TICK_MS = 30_000;
+
+type MemoryShape = {
+  usedJSHeapSize?: number;
+  totalJSHeapSize?: number;
+  jsHeapSizeLimit?: number;
+};
+
+let _timer: null | ReturnType<typeof setInterval> = null;
+
+function readHeap(): MemoryShape | null {
+  const perf = (globalThis as { performance?: { memory?: MemoryShape } }).performance;
+  return perf?.memory ?? null;
+}
+
+function tickOnce(): void {
+  const m = readHeap();
+  if (!m) return;
+  if (typeof m.usedJSHeapSize === 'number' && Number.isFinite(m.usedJSHeapSize)) {
+    emitMetric('runtime.heap.used_bytes', m.usedJSHeapSize);
+  }
+  // Total + limit help capacity-plan but cost an extra ~16 B
+  // per row downstream — keep them only when present.
+  if (typeof m.totalJSHeapSize === 'number' && Number.isFinite(m.totalJSHeapSize)) {
+    emitMetric('runtime.heap.total_bytes', m.totalJSHeapSize);
+  }
+  if (typeof m.jsHeapSizeLimit === 'number' && Number.isFinite(m.jsHeapSizeLimit)) {
+    emitMetric('runtime.heap.limit_bytes', m.jsHeapSizeLimit);
+  }
+}
+
+/** Idempotent start. No-op on hosts that don't expose
+ *  performance.memory — checked once at start so we don't pay
+ *  for the detect on every tick. */
+export function startHeapInstrument(): void {
+  if (_timer !== null) return;
+  if (!readHeap()) return;
+  // One immediate sample at start so the first dashboard render
+  // doesn't sit empty for 30 s.
+  tickOnce();
+  _timer = setInterval(tickOnce, TICK_MS);
+  (_timer as unknown as { unref?: () => void }).unref?.();
+}
+
+/** Stop. Idempotent. */
+export function stopHeapInstrument(): void {
+  if (_timer !== null) {
+    clearInterval(_timer);
+    _timer = null;
+  }
+}
+
+/** Test-only force tick (skips the 30 s wait). */
+export function __forceHeapTickForTests(): void {
+  tickOnce();
+}
+
+/** Test-only state. */
+export function __peekHeapInstrumentState(): { running: boolean } {
+  return { running: _timer !== null };
+}

package/src/runtime-metrics-network.ts

@@ -0,0 +1,103 @@
+// v2.1 W2 part 4 — network bytes auto-instrument.
+//
+// Two counters (sent / received bytes) incremented by the existing
+// fetch patch on every request/response, drained every 30 s as
+// runtime.network.bytes_sent + runtime.network.bytes_received.
+//
+// Best-effort: not every Response exposes `content-length`
+// (chunked encoding, server stripped it, gzipped without a
+// pre-decode header). For those we report 0 — undercounts vs.
+// over-attributing arbitrary numbers. Request body size is
+// estimated only when init.body is a string or has `.byteLength`;
+// FormData / Blob / ReadableStream are not measured.
+//
+// XHR is NOT instrumented here — the existing patchXhr() in
+// handlers/network.ts does the trace span work, and XHR usage in
+// 2026-era RN apps is rare enough that the engineering cost of
+// a second patch isn't justified by the missing data. If a host
+// app shows up with significant XHR traffic we add it in a patch
+// release.
+
+import { emitMetric } from '@goliapkg/sentori-core';
+
+const TICK_MS = 30_000;
+
+let _bytesSent = 0;
+let _bytesReceived = 0;
+let _timer: null | ReturnType<typeof setInterval> = null;
+
+/** Called from handlers/network.ts on every outbound request.
+ *  Cheap — two adds, no allocation. */
+export function recordNetworkBytes(sent: number, received: number): void {
+  if (sent > 0) _bytesSent += sent;
+  if (received > 0) _bytesReceived += received;
+}
+
+function estimateBodyBytes(body: BodyInit | null | undefined): number {
+  if (body == null) return 0;
+  if (typeof body === 'string') return body.length;
+  // ArrayBuffer / Uint8Array / ArrayBufferView all carry byteLength.
+  const maybe = body as { byteLength?: number };
+  if (typeof maybe.byteLength === 'number') return maybe.byteLength;
+  // FormData / Blob / ReadableStream — not measured.
+  return 0;
+}
+
+/** Estimate request bytes from a fetch init. Used by the fetch
+ *  patch in handlers/network.ts. */
+export function estimateRequestBytes(init?: RequestInit): number {
+  return estimateBodyBytes(init?.body);
+}
+
+/** Read response bytes from the Content-Length header. Returns
+ *  0 if missing or unparseable — undercount-safe. */
+export function estimateResponseBytes(headers: Headers | undefined | null): number {
+  if (!headers) return 0;
+  const v = headers.get?.('content-length');
+  if (!v) return 0;
+  const n = parseInt(v, 10);
+  return Number.isFinite(n) && n > 0 ? n : 0;
+}
+
+function emit(): void {
+  if (_bytesSent > 0) {
+    emitMetric('runtime.network.bytes_sent', _bytesSent);
+    _bytesSent = 0;
+  }
+  if (_bytesReceived > 0) {
+    emitMetric('runtime.network.bytes_received', _bytesReceived);
+    _bytesReceived = 0;
+  }
+}
+
+/** Idempotent start — second call is a no-op. */
+export function startNetworkBytesInstrument(): void {
+  if (_timer !== null) return;
+  _timer = setInterval(emit, TICK_MS);
+  (_timer as unknown as { unref?: () => void }).unref?.();
+}
+
+/** Stop the periodic emit. Idempotent. */
+export function stopNetworkBytesInstrument(): void {
+  if (_timer !== null) {
+    clearInterval(_timer);
+    _timer = null;
+  }
+}
+
+/** Test-only: force one emit tick + reset counters. */
+export function __forceNetworkEmitForTests(): void {
+  emit();
+}
+
+/** Test-only: peek raw counter state without resetting. */
+export function __peekNetworkCountersForTests(): { sent: number; received: number } {
+  return { sent: _bytesSent, received: _bytesReceived };
+}
+
+/** Test-only: reset for clean test runs. */
+export function __resetNetworkBytesForTests(): void {
+  stopNetworkBytesInstrument();
+  _bytesSent = 0;
+  _bytesReceived = 0;
+}

package/src/runtime-metrics.ts

@@ -0,0 +1,122 @@
+// v2.1 W2 part 2 — RN runtime metrics flusher + cold-start
+// instrument.
+//
+// The buffer + emit primitives live in @goliapkg/sentori-core
+// (runtime-metrics.ts). This module owns:
+//   • the periodic flush timer (30 s, coalesced w/ event flush)
+//   • the rebuffer-on-failure recovery path
+//   • the cold-start auto-instrument (one-shot at init)
+//
+// Other auto-instrument modules (FPS / heap / route-nav / network
+// bytes) ship in the W2 part 3+ chunks; each is its own file with
+// its own per-tick perf budget test gated as stop-ship in CI.
+//
+// NEVER rule: every public surface here is wrapped in safeFn
+// boundaries by the SDK init layer; the flush timer itself
+// catches all rejections + reports via the circuit breaker.
+
+import {
+  drainRuntimeMetricsForFlush,
+  emitMetric,
+  rebufferRuntimeMetrics,
+  reportInternal,
+} from '@goliapkg/sentori-core';
+
+import { getConfig, isInitialized } from './config';
+import { sendRuntimeMetricsBatch } from './transport';
+
+const FLUSH_INTERVAL_MS = 30_000;
+
+let _timer: null | ReturnType<typeof setInterval> = null;
+let _coldStartT0: null | number = null;
+let _coldStartEmitted = false;
+
+/**
+ * Drain core's runtime-metrics ring and POST to
+ * /v1/runtime-metrics:batch. Rebuffers on failure so the next
+ * tick retries; sustained outages spill into the ring's drop
+ * counter which reports to the SDK self-report channel.
+ *
+ * Returns when the round-trip settles (success or failure). Per
+ * the NEVER rule, never throws — failure is logged + rebuffered,
+ * the resolved promise's value is undefined.
+ */
+export async function flushRuntimeMetrics(): Promise<void> {
+  if (!isInitialized()) return;
+  const config = getConfig();
+  if (!config) return;
+  const batch = drainRuntimeMetricsForFlush();
+  if (batch.length === 0) return;
+  const ok = await sendRuntimeMetricsBatch(config.ingestUrl, config.token, batch);
+  if (!ok) {
+    rebufferRuntimeMetrics(batch);
+    reportInternal('runtime-metrics.flush', new Error('runtime-metrics POST failed'));
+  }
+}
+
+/**
+ * Start the 30 s flush timer. Called once from `init()`. Idempotent
+ * — repeated calls are a no-op so users that call
+ * `Sentori.init({ metrics: true })` more than once (HMR, fast
+ * refresh) don't get multiple timers.
+ */
+export function startRuntimeMetricsTimer(): void {
+  if (_timer !== null) return;
+  _timer = setInterval(() => {
+    void flushRuntimeMetrics();
+  }, FLUSH_INTERVAL_MS);
+  // Don't keep Node alive solely for this timer. RN's setInterval
+  // is a NoopRef so this is harmless there; Node + CLI tests
+  // benefit so the process can exit cleanly.
+  (_timer as unknown as { unref?: () => void }).unref?.();
+}
+
+/**
+ * Capture the wall-clock at `init()` so cold-start instrumentation
+ * has a t0. Called from init() before any other auto-instrument
+ * fires. Returns the captured t0 in millis (callers that want to
+ * stash + use it later can hold the value).
+ */
+export function markColdStartT0(): number {
+  if (_coldStartT0 === null) {
+    _coldStartT0 = Date.now();
+  }
+  return _coldStartT0;
+}
+
+/**
+ * Emit one `runtime.cold_start_ms` metric point. Idempotent per
+ * session — the second + later calls are a no-op so route-nav
+ * instrument (W2 part 3) can call this safely without worrying
+ * about double-counting.
+ *
+ * Hosts that want a more interactive-pixel-perfect cold-start
+ * boundary (TTI vs. raw init→render) can call
+ * `markTimeToFullDisplay()` and we emit that separately as
+ * `runtime.time_to_full_display_ms` (existing v1 instrument).
+ */
+export function emitColdStart(): void {
+  if (_coldStartEmitted) return;
+  if (_coldStartT0 === null) return;
+  const ms = Date.now() - _coldStartT0;
+  if (ms <= 0 || ms > 60_000) {
+    // Implausible — likely the host called emit before init or
+    // we got into a freeze-then-resume situation. Drop silently.
+    return;
+  }
+  emitMetric('runtime.cold_start_ms', ms);
+  _coldStartEmitted = true;
+}
+
+/**
+ * Test-only escape hatch: stop the timer + reset cold-start state
+ * so vitest / bun:test teardown doesn't leak intervals across runs.
+ */
+export function __resetRuntimeMetricsRnForTests(): void {
+  if (_timer !== null) {
+    clearInterval(_timer);
+    _timer = null;
+  }
+  _coldStartT0 = null;
+  _coldStartEmitted = false;
+}