@goliapkg/sentori-react-native 1.3.0 → 2.1.0

package/src/__tests__/runtime-metrics-instruments.test.ts

@@ -0,0 +1,109 @@
+import { afterEach, beforeEach, expect, test } from 'bun:test';
+
+import {
+  __peekRuntimeMetricsSize,
+  __resetRuntimeMetricsForTests,
+  drainRuntimeMetricsForFlush,
+} from '@goliapkg/sentori-core';
+
+import {
+  __forceEmitFpsForTests,
+  __pushSampleForTests,
+  __resetFpsInstrumentForTests,
+  startFpsInstrument,
+  stopFpsInstrument,
+} from '../runtime-metrics-fps';
+import {
+  __forceHeapTickForTests,
+  __peekHeapInstrumentState,
+  startHeapInstrument,
+  stopHeapInstrument,
+} from '../runtime-metrics-heap';
+
+beforeEach(() => {
+  __resetRuntimeMetricsForTests();
+  __resetFpsInstrumentForTests();
+});
+
+afterEach(() => {
+  stopFpsInstrument();
+  stopHeapInstrument();
+});
+
+test('fps: pushes p50 + p95 emits into the runtime metrics ring', () => {
+  // 300 samples at a steady 16.67 ms cadence ≈ 60 fps.
+  for (let i = 0; i < 300; i++) {
+    __pushSampleForTests(16.67);
+  }
+  __forceEmitFpsForTests();
+
+  const drained = drainRuntimeMetricsForFlush();
+  expect(drained.length).toBe(2);
+  const names = drained.map((m) => m.name).sort();
+  expect(names).toEqual(['runtime.fps.p50', 'runtime.fps.p95']);
+  // Both should land near 60 fps.
+  const p50 = drained.find((m) => m.name === 'runtime.fps.p50')!;
+  expect(p50.value).toBeGreaterThanOrEqual(58);
+  expect(p50.value).toBeLessThanOrEqual(62);
+});
+
+test('fps: mixed-cadence run separates p50 from p95 sensibly', () => {
+  // 270 fast frames (60 fps) + 30 stutters (30 fps). p95 should
+  // land at the stutter zone.
+  for (let i = 0; i < 270; i++) __pushSampleForTests(16.67);
+  for (let i = 0; i < 30; i++) __pushSampleForTests(33.33);
+  __forceEmitFpsForTests();
+
+  const drained = drainRuntimeMetricsForFlush();
+  const p50 = drained.find((m) => m.name === 'runtime.fps.p50')!.value;
+  const p95 = drained.find((m) => m.name === 'runtime.fps.p95')!.value;
+  // p50 stays at the smooth-frame zone.
+  expect(p50).toBeGreaterThanOrEqual(58);
+  // p95 (worst-95th of Δt → slowest 5%) should drop into the
+  // 30 fps zone.
+  expect(p95).toBeLessThanOrEqual(35);
+});
+
+test('fps: start is idempotent — second call is a no-op', () => {
+  startFpsInstrument();
+  // Calling start twice mustn't spin up a second rAF loop. We
+  // don't directly observe that here (no two-loop probe), but
+  // we assert start doesn't throw + state stays running once.
+  expect(() => startFpsInstrument()).not.toThrow();
+  stopFpsInstrument();
+});
+
+test('heap: start is a no-op on hosts without performance.memory', () => {
+  // The default test runtime (bun) doesn't expose
+  // performance.memory, so start should silently skip and
+  // never schedule a timer.
+  startHeapInstrument();
+  expect(__peekHeapInstrumentState().running).toBe(false);
+});
+
+test('heap: force tick is a no-op on hosts without performance.memory', () => {
+  __forceHeapTickForTests();
+  // No metric should land in the ring.
+  expect(__peekRuntimeMetricsSize()).toBe(0);
+});
+
+test('heap: emits when performance.memory is shimmed', () => {
+  // Shim performance.memory so the read path exercises.
+  const g = globalThis as {
+    performance?: { memory?: { usedJSHeapSize?: number; totalJSHeapSize?: number } };
+  };
+  const before = g.performance;
+  g.performance = {
+    ...(before ?? {}),
+    memory: { usedJSHeapSize: 12_345_678, totalJSHeapSize: 23_456_789 },
+  };
+  try {
+    __forceHeapTickForTests();
+    const drained = drainRuntimeMetricsForFlush();
+    const names = drained.map((m) => m.name).sort();
+    expect(names).toEqual(['runtime.heap.total_bytes', 'runtime.heap.used_bytes']);
+    expect(drained.find((m) => m.name === 'runtime.heap.used_bytes')!.value).toBe(12_345_678);
+  } finally {
+    g.performance = before;
+  }
+});

package/src/__tests__/runtime-metrics-network.test.ts

@@ -0,0 +1,78 @@
+import { afterEach, beforeEach, expect, test } from 'bun:test';
+
+import {
+  __resetRuntimeMetricsForTests,
+  drainRuntimeMetricsForFlush,
+} from '@goliapkg/sentori-core';
+
+import {
+  __forceNetworkEmitForTests,
+  __peekNetworkCountersForTests,
+  __resetNetworkBytesForTests,
+  estimateRequestBytes,
+  estimateResponseBytes,
+  recordNetworkBytes,
+} from '../runtime-metrics-network';
+
+beforeEach(() => {
+  __resetRuntimeMetricsForTests();
+  __resetNetworkBytesForTests();
+});
+
+afterEach(() => __resetNetworkBytesForTests());
+
+test('recordNetworkBytes: cumulates sent + received separately', () => {
+  recordNetworkBytes(100, 200);
+  recordNetworkBytes(50, 0);
+  recordNetworkBytes(0, 25);
+  const { sent, received } = __peekNetworkCountersForTests();
+  expect(sent).toBe(150);
+  expect(received).toBe(225);
+});
+
+test('force emit: flushes both counters into the ring + resets', () => {
+  recordNetworkBytes(1234, 5678);
+  __forceNetworkEmitForTests();
+
+  const drained = drainRuntimeMetricsForFlush();
+  expect(drained.length).toBe(2);
+  const names = drained.map((m) => m.name).sort();
+  expect(names).toEqual(['runtime.network.bytes_received', 'runtime.network.bytes_sent']);
+  expect(drained.find((m) => m.name === 'runtime.network.bytes_sent')!.value).toBe(1234);
+  expect(drained.find((m) => m.name === 'runtime.network.bytes_received')!.value).toBe(5678);
+
+  const { sent, received } = __peekNetworkCountersForTests();
+  expect(sent).toBe(0);
+  expect(received).toBe(0);
+});
+
+test('force emit: skips zero counters (no empty metric emit)', () => {
+  __forceNetworkEmitForTests();
+  expect(drainRuntimeMetricsForFlush().length).toBe(0);
+});
+
+test('estimateRequestBytes: handles string body', () => {
+  expect(estimateRequestBytes({ body: 'hello world' })).toBe(11);
+  expect(estimateRequestBytes()).toBe(0);
+  expect(estimateRequestBytes({})).toBe(0);
+});
+
+test('estimateRequestBytes: reads byteLength from ArrayBuffer-like body', () => {
+  const buf = new Uint8Array([1, 2, 3, 4, 5]);
+  expect(estimateRequestBytes({ body: buf })).toBe(5);
+});
+
+test('estimateResponseBytes: parses content-length header', () => {
+  const h = new Headers({ 'content-length': '1024' });
+  expect(estimateResponseBytes(h)).toBe(1024);
+});
+
+test('estimateResponseBytes: returns 0 when header missing (chunked / stripped)', () => {
+  expect(estimateResponseBytes(new Headers())).toBe(0);
+  expect(estimateResponseBytes(null)).toBe(0);
+});
+
+test('estimateResponseBytes: returns 0 on unparseable header (undercount-safe)', () => {
+  const h = new Headers({ 'content-length': 'nope' });
+  expect(estimateResponseBytes(h)).toBe(0);
+});

package/src/config.ts

@@ -36,6 +36,11 @@ export type Config = {
    *  session-trail buffer and uploads it as a `sessionTrail`
    *  attachment. Defaults to false. */
   sessionTrailEnabled: boolean;
+  /** v2.0 W3 — when true, every `track(name, props)` call also
+   *  pushes a `{ type: 'track', data: { name, props } }` breadcrumb
+   *  so a subsequent capture carries the customer journey. Defaults
+   *  to false to preserve v1 customer breadcrumb shape on upgrade. */
+  trackAutoBreadcrumb: boolean;
   /** v2.3 — Sentori console output gate.
    *
    *  Default `warn`: SDK is silent on host's console unless

package/src/feedback.ts

@@ -0,0 +1,21 @@
+// v2.0 W3 — `feedback` subpath. The feedback widget pulls in a
+// component tree (react + tsx) and an internal viewer route, so
+// importing it eagerly from the SDK's top-level barrel pays a
+// bundle cost every consumer pays — even ones that never render
+// the widget.
+//
+// Subpath import `@goliapkg/sentori-react-native/feedback`
+// resolves to just the widget surface. Hosts that don't render
+// the feedback button pay zero bundle delta; hosts that do reach
+// for it import via this module and get exactly what they need.
+//
+// Top-level (`index.ts`) still re-exports `FeedbackButton` for one
+// more release cycle so v1 callsites don't break on upgrade. v3
+// will drop the top-level re-export — see
+// `docs/recipes/v1-to-v2-migration.md` for the deprecation timeline.
+
+export {
+  FeedbackButton,
+  type FeedbackButtonHandle,
+  type FeedbackButtonProps,
+} from './feedback-widget'

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/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';
@@ -73,6 +81,24 @@ export type InitOptions = {
      *  the buffer is sealed and uploaded as a `sessionTrail`
      *  attachment. Defaults to false. */
     sessionTrail?: boolean;
+    /** v2.0 W3 — when `true`, every `sentori.track(name, props)`
+     *  also pushes a `{ type: 'track', data: { name, props } }`
+     *  breadcrumb so a subsequent `captureException` /
+     *  `captureMessage` carries the customer journey leading up to
+     *  the failure. Defaults to `false` to preserve v1 customer
+     *  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`
@@ -197,6 +223,11 @@ export const init = (options: InitOptions): void => {
     traceSampleRate: options.sample?.traces ?? options.sampling?.traces ?? null,
     messageSampleRate: options.sample?.messages ?? options.sampling?.messages ?? null,
     sessionTrailEnabled: options.capture?.sessionTrail === true,
+    // v2.0 W3 — when true, every `track()` also pushes a
+    // `type: 'track'` breadcrumb so a subsequent captureException
+    // carries the customer journey. Defaults false to preserve v1
+    // breadcrumb shape on upgrade.
+    trackAutoBreadcrumb: options.capture?.trackAutoBreadcrumb === true,
   });
 
   // Tell the native crash handler about the config so the JSON it writes
@@ -236,6 +267,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/metrics.ts

@@ -11,6 +11,8 @@
 // outgoing connection pool. Batching makes the SDK safe to use as a
 // cheap counter primitive.
 
+import type { SpanContextLike } from '@goliapkg/sentori-core';
+
 import { getConfig, isInitialized } from './config';
 import { sendMetricsBatch } from './transport';
 
@@ -43,7 +45,7 @@ export function recordMetric(
   name: string,
   value: number,
   tags?: Record<string, string>,
-  opts?: { parent?: { spanId: string; traceId: string } },
+  opts?: { parent?: SpanContextLike },
 ): void {
   if (!isInitialized()) return;
   if (typeof name !== 'string' || name.length === 0 || name.length > 200) return;

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 };
+}