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

package/src/native.ts

@@ -67,6 +67,31 @@ 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.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 +320,121 @@ 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
+} {
+  const n = native()
+  if (!n || typeof n.probeWireframe !== 'function') {
+    return {
+      available: false,
+      lastNodes: 0,
+      lastPath: 'native.unavailable',
+      sceneCount: 0,
+      windowCount: 0,
+    }
+  }
+  try {
+    const r = n.probeWireframe()
+    return {
+      available: true,
+      lastNodes: typeof r?.lastNodes === 'number' ? r.lastNodes : 0,
+      lastPath: typeof r?.lastPath === 'string' ? r.lastPath : 'unknown',
+      sceneCount: typeof r?.sceneCount === 'number' ? r.sceneCount : 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,
+      lastNodes: 0,
+      lastPath: 'native.threw',
+      sceneCount: 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

@@ -37,6 +37,26 @@ let _ring: string[] = [];
 let _timer: ReturnType<typeof setInterval> | null = null;
 let _running = false;
 
+/**
+ * v0.9.13 — frame-level delta encoding: when the new snapshot matches
+ * the last one byte-for-byte (static UI, no animation, off-screen
+ * app), skip pushing it. The ring stays meaningful (one frame =
+ * one *change*), the attachment shrinks proportionally, and a real
+ * idle phase no longer evicts a useful pre-error frame.
+ *
+ * We only check against the most-recently-pushed snapshot, not the
+ * whole ring — that's cheap (one string comparison per tick) and
+ * catches the dominant case (idle screens). True content changes
+ * fall through and push as before.
+ *
+ * Budget verification on the iOS showcase (apps/ios-showcase): 60
+ * frames at ~120 bytes each → ≈ 7 KB raw NDJSON, well under the
+ * 500 KB attachment cap. Heavier RN apps with 200+ visible nodes
+ * per frame can land in the 400 KB band; future work in v1.x adds
+ * native gzip on upload if real-world traffic ever pushes the cap.
+ */
+let _lastPushed: null | string = null;
+
 /** 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
@@ -83,7 +103,20 @@ export function startReplay(opts: ReplayOptions): void {
   _timer = setInterval(() => {
     captureTick();
   }, period);
-  (_timer as unknown as { unref?: () => void }).unref?.();
+  // v0.9.12 — Insight 2026-05-17 report: 0.9.11 emitted the
+  // "starting bound=true" line then went silent. Root cause was the
+  // `.unref?.()` call that used to live here. Hermes 0.81 doesn't
+  // ship a Timer object with the Node-style `unref` method, and the
+  // optional-chained call ended up dereferencing a `prototype`
+  // property on `undefined` — throwing synchronously inside
+  // startReplay, which RN's bridge swallowed silently. Net effect:
+  // setInterval registered, captureTick never invoked. Drop the
+  // call; replay tick lifecycle is bound to the app process, no
+  // event-loop tweak needed.
+  if (typeof __DEV__ !== 'undefined' && __DEV__) {
+    // eslint-disable-next-line no-console
+    console.warn('[sentori] replay: scheduled tick period=', period, 'ms');
+  }
 }
 
 export function stopReplay(): void {
@@ -95,20 +128,49 @@ export function stopReplay(): void {
   _nativeMod = null;
   _emptyTickCount = 0;
   _emptyTickLogStride = 1;
+  _firstTickLogged = false;
 }
 
 let _emptyTickCount = 0;
 let _emptyTickLogStride = 1;
+let _firstTickLogged = false;
 
 function captureTick(): void {
   if (!_running) return;
-  const tickSpan = startSpan('sentori.replay.tick', { name: 'tick' });
+  // v0.9.12 — UNCONDITIONAL first-tick log. Proves the setInterval
+  // callback is firing at all, before any other code that could
+  // throw. 0.9.11's diagnostic was inside a `else if (snapshot==null)`
+  // branch that could only surface AFTER the native call returned;
+  // useless when the bug is that the tick body never enters.
+  if (typeof __DEV__ !== 'undefined' && __DEV__ && !_firstTickLogged) {
+    // eslint-disable-next-line no-console
+    console.warn('[sentori] replay tick: FIRST INVOCATION');
+    _firstTickLogged = true;
+  }
+  // 0.9.11 called startSpan OUTSIDE the catch block. If
+  // `@goliapkg/sentori-core` failed to initialise (or startSpan
+  // threw for any other reason on the first tick) the whole tick
+  // callback died silently. Wrap so worst case is "no span for this
+  // tick" not "no ticks for the session".
+  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();
+      // v0.9.13 — skip pushing if the frame is identical to the last
+      // pushed one. See _lastPushed comment for the rationale.
+      if (snapshot !== _lastPushed) {
+        _ring.push(snapshot);
+        _lastPushed = snapshot;
+        while (_ring.length > RING_SIZE) {
+          _ring.shift();
+        }
+      }
       _emptyTickCount = 0;
       _emptyTickLogStride = 1;
     } else if (typeof __DEV__ !== 'undefined' && __DEV__) {
@@ -132,10 +194,14 @@ function captureTick(): void {
         _emptyTickLogStride = Math.max(_emptyTickLogStride * 10, 10);
       }
     }
-    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);
+    }
   }
 }
 
@@ -172,10 +238,12 @@ export function drainReplay(): string {
   if (_ring.length === 0) return '';
   const out = _ring.join('\n');
   _ring = [];
+  _lastPushed = null;
   return out;
 }
 
 export function __resetReplayForTests(): void {
   stopReplay();
   _ring = [];
+  _lastPushed = null;
 }