@goliapkg/sentori-react-native 0.9.11 → 1.0.0-rc.10

package/src/native.ts

@@ -67,6 +67,44 @@ type SentoriNativeModule = {
    * snapshot string or null on failure.
    */
   captureWireframe?: (maskedIds: string[]) => null | string
+  /**
+   * v0.9.12 — diagnostic readout for the wireframe path. Cheap
+   * synchronous call that returns the path the last `captureWireframe`
+   * tick took plus scene/window counts at that moment. Used by the
+   * example app's debug button and the Insight verify flow to tell
+   * "no window resolvable" from "window walked but tree empty" without
+   * shipping a new pod.
+   */
+  probeWireframe?: () => {
+    lastPath: string
+    lastNodes: number
+    sceneCount?: number
+    windowCount?: number
+    trackedSource?: string
+    trackedActivity?: string
+    decorViewFound?: boolean
+    /** v1.0.0-rc.3: deepest descendant reached by the walker. If
+     *  this is 2-3 the walker bailed early; if it matches the
+     *  expected view-tree depth (~20-40 for RN apps) the capture
+     *  is healthy. */
+    lastDepthMax?: number
+    /** v1.0.0-rc.3: byte length of the last serialised payload. */
+    lastSizeBytes?: number
+    /** v1.0.0-rc.3: lifetime counters — totalTicks is the number
+     *  of times native captureWireframe ran; totalEmptyResultTicks
+     *  is the subset that came back null or empty. Ratio surfaces
+     *  intermittent failures (e.g. 200/240 ≈ 80% failure rate). */
+    totalTicks?: number
+    totalEmptyResultTicks?: number
+  }
+  /**
+   * v1.0.0-rc.2 — diagnostic mirror of probeWireframe for the
+   * screenshot path. Returned shape is best-effort cross-platform —
+   * Android carries `trackedActivity` / `decorViewFound` / dims,
+   * iOS carries `windowFound` / `rootViewControllerFound` / `bounds*`.
+   * Callers should treat unknown keys as missing.
+   */
+  probeScreenshot?: () => Record<string, unknown>
   /**
    * Phase 22 sub-D / sub-E: cross-platform main-thread watchdog.
    * Android: 5 s / 1 s defaults (matches the OS ANR threshold).
@@ -295,10 +333,149 @@ export async function captureNativeScreenshotWithMask(
 export function describeWireframeNative(): {
   bound: boolean
   hasCaptureWireframe: boolean
+  hasProbeWireframe: boolean
 } {
   const n = native()
   return {
     bound: n !== null,
     hasCaptureWireframe: Boolean(n?.captureWireframe),
+    hasProbeWireframe: Boolean(n?.probeWireframe),
+  }
+}
+
+/**
+ * v0.9.12 — JS entry to the native `probeWireframe` diagnostic. Safe
+ * to call before the first replay tick — returns the not-yet-called
+ * sentinel. When the ring stays empty, this is the single call that
+ * answers "why" without redeploying the pod.
+ *
+ *   path             meaning
+ *   ───────────────  ───────────────────────────────────────────────
+ *   none(not-yet…)   captureWireframe has never run yet
+ *   scene.fg.key     iOS: resolved via foregroundActive scene's key window
+ *   scene.fg.first   iOS: foregroundActive scene's first window (no key)
+ *   scene.fgi.first  iOS: foregroundInactive scene mid-transition
+ *   scene.any.first  iOS: had to fall back to any window
+ *   legacy.first     iOS: legacy UIApplication.windows path
+ *   none             iOS: no UIWindow reachable at the tick instant
+ *   activity.null    Android: no resumed Activity registered
+ *   decorView.null   Android: activity has no decor view yet
+ *   root.zero-size   Android: decorView size <= 0 (mid-layout)
+ *   activity.resumed Android: ok
+ */
+export function probeNativeWireframe(): {
+  available: boolean
+  lastNodes: number
+  lastPath: string
+  sceneCount: number
+  windowCount: number
+  /** v1.0.0-rc.3: max recursion depth reached by the walker on
+   *  the last tick. Healthy on an RN app: 20-40. If it's 2-3 the
+   *  walker bailed early (zero-size parent, masked root). */
+  lastDepthMax: number
+  /** v1.0.0-rc.3: byte length of the last serialised payload. */
+  lastSizeBytes: number
+  /** v1.0.0-rc.3: lifetime totals. `totalEmptyResultTicks /
+   *  totalTicks` is the failure rate. */
+  totalTicks: number
+  totalEmptyResultTicks: number
+  raw: Record<string, unknown>
+} {
+  const n = native()
+  if (!n || typeof n.probeWireframe !== 'function') {
+    return {
+      available: false,
+      lastDepthMax: 0,
+      lastNodes: 0,
+      lastPath: 'native.unavailable',
+      lastSizeBytes: 0,
+      raw: {},
+      sceneCount: 0,
+      totalEmptyResultTicks: 0,
+      totalTicks: 0,
+      windowCount: 0,
+    }
+  }
+  try {
+    const r = n.probeWireframe()
+    const raw = (r ?? {}) as Record<string, unknown>
+    return {
+      available: true,
+      lastDepthMax: typeof r?.lastDepthMax === 'number' ? r.lastDepthMax : 0,
+      lastNodes: typeof r?.lastNodes === 'number' ? r.lastNodes : 0,
+      lastPath: typeof r?.lastPath === 'string' ? r.lastPath : 'unknown',
+      lastSizeBytes: typeof r?.lastSizeBytes === 'number' ? r.lastSizeBytes : 0,
+      raw,
+      sceneCount: typeof r?.sceneCount === 'number' ? r.sceneCount : 0,
+      totalEmptyResultTicks:
+        typeof r?.totalEmptyResultTicks === 'number' ? r.totalEmptyResultTicks : 0,
+      totalTicks: typeof r?.totalTicks === 'number' ? r.totalTicks : 0,
+      windowCount: typeof r?.windowCount === 'number' ? r.windowCount : 0,
+    }
+  } catch (e) {
+    if (typeof __DEV__ !== 'undefined' && __DEV__) {
+      // eslint-disable-next-line no-console
+      console.warn('[sentori] probeWireframe threw', e)
+    }
+    return {
+      available: false,
+      lastDepthMax: 0,
+      lastNodes: 0,
+      lastPath: 'native.threw',
+      lastSizeBytes: 0,
+      raw: {},
+      sceneCount: 0,
+      totalEmptyResultTicks: 0,
+      totalTicks: 0,
+      windowCount: 0,
+    }
+  }
+}
+
+/**
+ * v1.0.0-rc.2 — JS entry to the `probeScreenshot` native diagnostic.
+ * Same shape contract as [probeNativeWireframe]: returns a flat
+ * key/value bag the consumer can ship back as-is when screenshot
+ * capture returns null.
+ *
+ *   path                       meaning
+ *   ─────────────────────────  ───────────────────────────────────────
+ *   none(not-yet-called)       captureScreenshot has never run
+ *   ok                         capture succeeded
+ *   activity.null              Android: foreground tracker had no Activity
+ *   window.null                Android/iOS: Activity/scene has no window
+ *   decorView.null             Android: window had no decor view
+ *   decorView.zero-size        Android: decorView size <= 0 (mid-layout)
+ *   api.unsupported            Android: API < 24 (no PixelCopy)
+ *   pixelCopy.notSuccess       Android: PixelCopy completed but reported failure
+ *   pixelCopy.threw:<class>    Android: PixelCopy threw mid-request
+ *   render.failed              iOS: UIGraphicsImageRenderer returned nil
+ *   empty                      iOS: walked tree but no view+screenshot output
+ *
+ * On Android the result also carries `trackedSource` (lifecycle.created /
+ * lifecycle.resumed / reflection.activityThread / manual.setActivity)
+ * so callers can tell whether the SDK back-filled via reflection.
+ */
+export function probeNativeScreenshot(): {
+  available: boolean
+  lastPath: string
+  raw: Record<string, unknown>
+} {
+  const n = native()
+  if (!n || typeof n.probeScreenshot !== 'function') {
+    return { available: false, lastPath: 'native.unavailable', raw: {} }
+  }
+  try {
+    const r = n.probeScreenshot()
+    const raw =
+      r && typeof r === 'object' && !Array.isArray(r) ? (r as Record<string, unknown>) : {}
+    const lastPath = typeof raw.lastPath === 'string' ? raw.lastPath : 'unknown'
+    return { available: true, lastPath, raw }
+  } catch (e) {
+    if (typeof __DEV__ !== 'undefined' && __DEV__) {
+      // eslint-disable-next-line no-console
+      console.warn('[sentori] probeScreenshot threw', e)
+    }
+    return { available: false, lastPath: 'native.threw', raw: {} }
   }
 }

package/src/replay.ts

@@ -1,21 +1,19 @@
-// v0.9.6 #2 — wireframe Session Replay (SDK side).
+// rc.9 — wireframe Session Replay v2 encoding.
 //
-// 60-slot ring buffer of native-captured wireframe snapshots. Each
-// tick calls into `SentoriReplayCapture.captureWireframe(maskIds)`
-// which walks the iOS UIView / Android View hierarchy and returns
-// one JSON string per snapshot. captureException flushes the ring
-// as a `replay` attachment (NDJSON: one snapshot per line).
+// Replaces rc.8's "one full snapshot per tick" with keyframe + delta:
+//   - Native walker still emits a full snapshot string every tick.
+//   - JS parses the snapshot, builds a fingerprint→node map, and either
+//     emits a keyframe (cold start / every KEYFRAME_INTERVAL_MS / when
+//     the delta would be bigger than a fresh key) OR a delta against
+//     the previous emit's reconstructed state.
+//   - Static-UI ticks produce zero-delta heartbeats which we drop.
 //
-// Why wireframe and not raster:
-//   • Storage: 80 nodes × ~80 bytes ≈ 6 KB per snapshot vs ~50 KB
-//     for a downsampled JPEG. 60-slot ring ≈ 400 KB raw / ~80 KB
-//     gzipped — fits comfortably in the 500 KB attachment cap.
-//   • Privacy: no pixels means no accidental PII leaks; mask
-//     registry decides what text to replace with "***".
-//   • Replay fidelity: less faithful to pixels but enough to see
-//     which screen the user was on and what was on it. Dashboard
-//     player renders SVG rects — denser-looking than a 1 Hz
-//     screenshot strip.
+// At 4 Hz capture / 4 s keyframes the wire bytes drop ~50 % vs rc.8 at
+// 1 Hz for the same 60 s pre-error window, and the dashboard player
+// cross-fades between captures at 24 fps so playback reads as motion
+// rather than a 1 Hz slideshow.
+//
+// Wire schema: docs/replay-encoding-v2.md.
 
 import { startSpan } from '@goliapkg/sentori-core';
 
@@ -24,41 +22,81 @@ import { describeWireframeNative } from './native';
 
 declare const __DEV__: boolean | undefined;
 
-const TICK_INTERVAL_MS = 1000;
-const RING_SIZE = 60;
+/** Default capture interval (2 Hz). Override via `replay.hz`. rc.10
+ *  rolled this back from rc.9's 4 Hz default: iOS sim measured 1 ms
+ *  per tick on a thin dev panel but extrapolation to a 200-node
+ *  Insight-class UI on Android pushes JS-thread occupancy past 1 %,
+ *  which violates the "几乎不能造成性能抖动" rule. Apps that want
+ *  smoother playback motion can opt into `replay.hz: 4` explicitly. */
+const TICK_INTERVAL_MS = 500;
+
+/** How often to emit a fresh keyframe — caps reconstruction chain
+ *  length and lets the player re-sync after a dropped line. */
+const KEYFRAME_INTERVAL_MS = 4_000;
+
+/** When the delta against the previous frame would carry ≥ this
+ *  fraction of the current node count, prefer a fresh keyframe —
+ *  emits roughly the same bytes but doesn't grow the chain. */
+const DELTA_TO_KEYFRAME_RATIO = 0.4;
+
+/** Floor under which the keyframe-vs-delta ratio heuristic does
+ *  not apply. Trivial UIs (≤ 10 nodes — boot splash, dev panel,
+ *  tests) shouldn't drop to keyframes on every change. */
+const KEYFRAME_RATIO_MIN_NODES = 10;
+
+/** Replay window kept in the ring buffer. captureException drains. */
+const REPLAY_WINDOW_MS = 60_000;
+
+/** Hard ceiling on ring item count — defence against a wedged tick
+ *  clock filling memory; under normal capture rates we evict by time
+ *  long before this fires. */
+const MAX_RING_ITEMS = 1000;
+
+/** Floor on tick period. < 100 ms the native view-tree walk dominates
+ *  the JS thread on mid-tier Android. */
+const MIN_TICK_PERIOD_MS = 100;
+
+type Node = {
+  x: number;
+  y: number;
+  w: number;
+  h: number;
+  kind?: string;
+  text?: string;
+  color?: string;
+};
+
+type NativeFrame = { ts: number; width: number; height: number; nodes: Node[] };
 
-/** Floor on tick period. < 250 ms (4 Hz) the native view-tree walk
- *  dominates the JS thread on mid-tier Android, especially with mask
- *  consultation. The default is 1 Hz; the option exists for
- *  benchmarking, not for production. */
-const MIN_TICK_PERIOD_MS = 250;
+type RingItem = { ts: number; line: string };
 
-let _ring: string[] = [];
+let _ring: RingItem[] = [];
 let _timer: ReturnType<typeof setInterval> | null = null;
 let _running = false;
 
-/** Native module ref, resolved once on first start. Caching here
- *  avoids the cost of `requireNativeModule('Sentori')` on every
- *  capture tick (Metro's require cache makes this cheap, but the
- *  per-tick string lookup and possible throw still cost more than
- *  reading a closed-over variable). */
+/** Last emit's reconstructed state — fingerprint → node. Null until
+ *  the first keyframe lands; reset on drain so the next session
+ *  starts with a fresh keyframe. */
+let _lastFrameState: Map<string, Node> | null = null;
+let _lastKeyframeTs = 0;
+
 let _nativeMod: ReplayNativeModule | null = null;
 
 export type ReplayOptions = {
   mode?: 'off' | 'wireframe';
-  /** Ticks per second. Default 1. */
+  /** Ticks per second. Default 2. Opt into 4 (or 8) for
+   *  motion-heavy apps where playback smoothness matters more than
+   *  the marginal CPU saving. */
   hz?: number;
+  /** Keyframe cadence in ms. Default 4000. */
+  keyframeMs?: number;
 };
 
+let _keyframeIntervalMs = KEYFRAME_INTERVAL_MS;
+
 export function startReplay(opts: ReplayOptions): void {
   if (_running) return;
   if (opts.mode !== 'wireframe') return;
-  // v0.9.10 — gate via expo-modules-core's registry (same path the
-  // screenshot capture uses). The previous `isNativeModuleLinked`
-  // check looked at the legacy `RN.NativeModules` map, but the
-  // Sentori module is registered through expo-modules-core; the
-  // legacy map never sees it, so this branch returned "not linked"
-  // forever even with the pod correctly attached (Insight 2026-05-17).
   const info = describeWireframeNative();
   if (!info.bound) {
     if (typeof __DEV__ !== 'undefined' && __DEV__) {
@@ -79,11 +117,18 @@ export function startReplay(opts: ReplayOptions): void {
   }
   _running = true;
   _nativeMod = loadNativeReplay();
-  const period = Math.max(MIN_TICK_PERIOD_MS, Math.floor(TICK_INTERVAL_MS / (opts.hz ?? 1)));
+  _keyframeIntervalMs = opts.keyframeMs ?? KEYFRAME_INTERVAL_MS;
+  const hz = opts.hz ?? 2;
+  const period = Math.max(MIN_TICK_PERIOD_MS, Math.round(1000 / hz));
   _timer = setInterval(() => {
     captureTick();
   }, period);
-  (_timer as unknown as { unref?: () => void }).unref?.();
+  if (typeof __DEV__ !== 'undefined' && __DEV__) {
+    // eslint-disable-next-line no-console
+    console.warn(
+      '[sentori] replay: scheduled tick period=', period, 'ms keyframe=', _keyframeIntervalMs, 'ms',
+    );
+  }
 }
 
 export function stopReplay(): void {
@@ -95,47 +140,207 @@ export function stopReplay(): void {
   _nativeMod = null;
   _emptyTickCount = 0;
   _emptyTickLogStride = 1;
+  _firstTickLogged = false;
+  _okTickCount = 0;
+  _thinTickCount = 0;
+  _thinTickLogStride = 1;
 }
 
 let _emptyTickCount = 0;
 let _emptyTickLogStride = 1;
+let _thinTickCount = 0;
+let _thinTickLogStride = 1;
+let _okTickCount = 0;
+let _firstTickLogged = false;
+
+const THIN_RESULT_NODES = 6;
 
 function captureTick(): void {
   if (!_running) return;
-  const tickSpan = startSpan('sentori.replay.tick', { name: 'tick' });
+  if (typeof __DEV__ !== 'undefined' && __DEV__ && !_firstTickLogged) {
+    // eslint-disable-next-line no-console
+    console.warn('[sentori] replay tick: FIRST INVOCATION');
+    _firstTickLogged = true;
+  }
+  let tickSpan: ReturnType<typeof startSpan> | null = null;
+  try {
+    tickSpan = startSpan('sentori.replay.tick', { name: 'tick' });
+  } catch {
+    // never fatal
+  }
   try {
     const maskIds = readMaskIds();
-    const snapshot = _nativeMod?.captureWireframe?.(maskIds);
-    if (typeof snapshot === 'string' && snapshot.length > 0) {
-      _ring.push(snapshot);
-      while (_ring.length > RING_SIZE) _ring.shift();
-      _emptyTickCount = 0;
-      _emptyTickLogStride = 1;
-    } else if (typeof __DEV__ !== 'undefined' && __DEV__) {
-      // v0.9.11 — Insight 2026-05-17 Finding 6: tick fires hundreds
-      // of times but ring stays empty → native returned null/empty.
-      // Log on a back-off schedule (1st, 10th, 100th, …) so the
-      // diagnostic is visible without spamming Metro at 1 Hz for a
-      // 15-minute session.
-      _emptyTickCount += 1;
-      if (_emptyTickCount === 1 || _emptyTickCount === _emptyTickLogStride) {
+    const snapshotJson = _nativeMod?.captureWireframe?.(maskIds);
+    if (typeof snapshotJson !== 'string' || snapshotJson.length === 0) {
+      handleEmptyTick(snapshotJson);
+      tickSpan?.finish({ status: 'ok' });
+      return;
+    }
+
+    let snapshot: NativeFrame;
+    try {
+      snapshot = JSON.parse(snapshotJson) as NativeFrame;
+    } catch (e) {
+      if (typeof __DEV__ !== 'undefined' && __DEV__) {
         // eslint-disable-next-line no-console
-        console.warn(
-          '[sentori] replay tick: native returned',
-          snapshot === null
-            ? 'null'
-            : typeof snapshot === 'string'
-              ? `empty (length=${snapshot.length})`
-              : typeof snapshot,
-          `(empty ticks so far: ${_emptyTickCount})`,
-        );
-        _emptyTickLogStride = Math.max(_emptyTickLogStride * 10, 10);
+        console.warn('[sentori] replay tick: native JSON parse failed', e);
       }
+      tickSpan?.finish({ status: 'error' });
+      return;
+    }
+
+    _emptyTickCount = 0;
+    _emptyTickLogStride = 1;
+
+    encodeAndPush(snapshot);
+
+    if (typeof __DEV__ !== 'undefined' && __DEV__) {
+      diagnosticForTick(snapshot, snapshotJson.length);
     }
-    tickSpan.finish({ status: 'ok' });
+    tickSpan?.finish({ status: 'ok' });
   } catch (e) {
-    if (e instanceof Error) tickSpan.setTag('error.message', e.message);
-    tickSpan.finish({ status: 'error' });
+    if (e instanceof Error) tickSpan?.setTag('error.message', e.message);
+    tickSpan?.finish({ status: 'error' });
+    if (typeof __DEV__ !== 'undefined' && __DEV__) {
+      // eslint-disable-next-line no-console
+      console.warn('[sentori] replay tick: threw', e);
+    }
+  }
+}
+
+function encodeAndPush(snapshot: NativeFrame): void {
+  const currentState = new Map<string, Node>();
+  for (const n of snapshot.nodes) currentState.set(fingerprint(n), n);
+
+  const ts = snapshot.ts;
+  const isCold = _lastFrameState === null;
+  const keyframeOverdue = ts - _lastKeyframeTs >= _keyframeIntervalMs;
+
+  let line: string;
+
+  if (isCold || keyframeOverdue) {
+    line = encodeKeyframe(snapshot);
+    _lastKeyframeTs = ts;
+  } else {
+    const delta = computeDelta(_lastFrameState as Map<string, Node>, currentState);
+    const totalChanged = delta.added.length + delta.changed.length + delta.removed.length;
+    if (totalChanged === 0) {
+      // No-op heartbeat — drop. Keep _lastFrameState as-is (identical).
+      return;
+    }
+    if (
+      currentState.size >= KEYFRAME_RATIO_MIN_NODES &&
+      totalChanged >= currentState.size * DELTA_TO_KEYFRAME_RATIO
+    ) {
+      // Big screen transition on a substantial UI — emit a fresh
+      // keyframe so reconstruction doesn't carry a near-rewrite delta.
+      line = encodeKeyframe(snapshot);
+      _lastKeyframeTs = ts;
+    } else {
+      line = JSON.stringify({
+        ts,
+        kind: 'delta',
+        added: delta.added,
+        changed: delta.changed,
+        removed: delta.removed,
+      });
+    }
+  }
+
+  _ring.push({ ts, line });
+  evictRing(ts);
+  _lastFrameState = currentState;
+}
+
+function encodeKeyframe(snapshot: NativeFrame): string {
+  return JSON.stringify({
+    ts: snapshot.ts,
+    kind: 'key',
+    width: snapshot.width,
+    height: snapshot.height,
+    nodes: snapshot.nodes,
+  });
+}
+
+function evictRing(nowTs: number): void {
+  const cutoff = nowTs - REPLAY_WINDOW_MS;
+  while (_ring.length > 0 && _ring[0]!.ts < cutoff) _ring.shift();
+  while (_ring.length > MAX_RING_ITEMS) _ring.shift();
+}
+
+/** Fingerprint integer-rounds before joining so sub-pixel jitter from
+ *  RN's Fabric layout (occasionally floats) doesn't break stable
+ *  matching across ticks. */
+function fingerprint(n: Node): string {
+  return `${n.x | 0},${n.y | 0},${n.w | 0},${n.h | 0}`;
+}
+
+type Delta = { added: Node[]; changed: Node[]; removed: Pick<Node, 'x' | 'y' | 'w' | 'h'>[] };
+
+export function computeDelta(prev: Map<string, Node>, curr: Map<string, Node>): Delta {
+  const added: Node[] = [];
+  const changed: Node[] = [];
+  const removed: Pick<Node, 'x' | 'y' | 'w' | 'h'>[] = [];
+  for (const [fp, node] of curr) {
+    const p = prev.get(fp);
+    if (!p) {
+      added.push(node);
+      continue;
+    }
+    if (
+      (p.kind ?? '') !== (node.kind ?? '') ||
+      (p.color ?? '') !== (node.color ?? '') ||
+      (p.text ?? '') !== (node.text ?? '')
+    ) {
+      changed.push(node);
+    }
+  }
+  for (const [fp, node] of prev) {
+    if (!curr.has(fp)) removed.push({ x: node.x, y: node.y, w: node.w, h: node.h });
+  }
+  return { added, changed, removed };
+}
+
+function handleEmptyTick(snapshot: unknown): void {
+  if (typeof __DEV__ === 'undefined' || !__DEV__) return;
+  _emptyTickCount += 1;
+  if (_emptyTickCount === 1 || _emptyTickCount === _emptyTickLogStride) {
+    // eslint-disable-next-line no-console
+    console.warn(
+      '[sentori] replay tick: native returned',
+      snapshot === null
+        ? 'null'
+        : typeof snapshot === 'string'
+          ? `empty (length=${snapshot.length})`
+          : typeof snapshot,
+      `(empty ticks so far: ${_emptyTickCount})`,
+    );
+    _emptyTickLogStride = Math.max(_emptyTickLogStride * 10, 10);
+  }
+}
+
+function diagnosticForTick(snapshot: NativeFrame, snapshotBytes: number): void {
+  _okTickCount += 1;
+  const nodeCount = snapshot.nodes.length;
+  const isThin = nodeCount < THIN_RESULT_NODES;
+  if (isThin) {
+    _thinTickCount += 1;
+    if (_thinTickCount === 1 || _thinTickCount === _thinTickLogStride) {
+      // eslint-disable-next-line no-console
+      console.warn(
+        `[sentori] replay tick: thin result nodes=${nodeCount} sizeBytes=${snapshotBytes} (thin ticks so far: ${_thinTickCount})`,
+      );
+      _thinTickLogStride = Math.max(_thinTickLogStride * 10, 10);
+    }
+  } else {
+    _thinTickCount = 0;
+    _thinTickLogStride = 1;
+  }
+  if (_okTickCount === 1) {
+    // eslint-disable-next-line no-console
+    console.warn(
+      `[sentori] replay tick: first ok — nodes=${nodeCount} sizeBytes=${snapshotBytes}`,
+    );
   }
 }
 
@@ -165,17 +370,36 @@ function loadNativeReplay(): ReplayNativeModule | null {
   }
 }
 
-/** Drain the ring as NDJSON (one snapshot per line). Empty string
- *  when the ring is empty. Also clears the ring so the next session's
- *  replay starts fresh. */
+export function isReplayRunning(): boolean {
+  return _running;
+}
+
+/** Drain the ring as NDJSON (keyframe or delta per line). Empty
+ *  string when the ring is empty. Resets state so the next session's
+ *  replay starts with a fresh keyframe. */
 export function drainReplay(): string {
   if (_ring.length === 0) return '';
-  const out = _ring.join('\n');
+  const out = _ring.map((r) => r.line).join('\n');
   _ring = [];
+  _lastFrameState = null;
+  _lastKeyframeTs = 0;
   return out;
 }
 
 export function __resetReplayForTests(): void {
   stopReplay();
   _ring = [];
+  _lastFrameState = null;
+  _lastKeyframeTs = 0;
+}
+
+/** rc.9 — test seam. Lets unit tests drive the encoder without a
+ *  native module; pretends we received `frameJson` on the tick. */
+export function __feedTickForTests(frameJson: string): void {
+  if (!_running) {
+    // Simulate "running" without an actual setInterval — caller drives.
+    _running = true;
+  }
+  const snapshot = JSON.parse(frameJson) as NativeFrame;
+  encodeAndPush(snapshot);
 }

package/src/transport.ts

@@ -391,6 +391,19 @@ export const uploadAttachment = async (
     // UploadResponse; non-JSON bodies fall through to null.
     if (resp.status < 200 || resp.status >= 300) {
       noteAttachmentFailure(eventId, kind, `http_${resp.status}`);
+      // rc.6 — surface the status in dev so Insight-style triage
+      // doesn't have to guess between 413/422/500. Pre-rc.6 only
+      // the breadcrumb carried the reason; logcat only saw the
+      // generic `upload returned null` line.
+      if (typeof __DEV__ !== 'undefined' && __DEV__) {
+        // eslint-disable-next-line no-console
+        console.warn(
+          '[sentori] attachment upload non-2xx',
+          'eventId=', eventId,
+          'kind=', kind,
+          'status=', resp.status,
+        );
+      }
       return null;
     }
     const j = (await resp.json().catch(() => null)) as null | {
@@ -401,6 +414,15 @@ export const uploadAttachment = async (
     };
     if (!j || !j.refId) {
       noteAttachmentFailure(eventId, kind, 'bad_response_body');
+      if (typeof __DEV__ !== 'undefined' && __DEV__) {
+        // eslint-disable-next-line no-console
+        console.warn(
+          '[sentori] attachment upload bad-response-body',
+          'eventId=', eventId,
+          'kind=', kind,
+          'status=', resp.status,
+        );
+      }
       return null;
     }
     return {
@@ -413,6 +435,15 @@ export const uploadAttachment = async (
   } catch (e) {
     const reason = e instanceof Error ? `fetch_${e.name}` : 'fetch_unknown';
     noteAttachmentFailure(eventId, kind, reason);
+    if (typeof __DEV__ !== 'undefined' && __DEV__) {
+      // eslint-disable-next-line no-console
+      console.warn(
+        '[sentori] attachment upload fetch threw',
+        'eventId=', eventId,
+        'kind=', kind,
+        'reason=', reason,
+      );
+    }
     return null;
   }
 };