@goliapkg/sentori-react-native 5.0.0 → 5.1.0

package/src/init.ts

@@ -17,6 +17,7 @@ import { checkColdStart } from './mobile-vitals';
 import { markNativeJsBridgeReady, setNativeConfig } from './native';
 import { shipNativePending } from './native-pending';
 import { drainReplay, startReplay } from './replay';
+import { drainScreenReplay, startScreenReplay } from './replay-screens';
 import { drainOfflineQueue, startTransport, uploadAttachment } from './transport';
 
 let _initialized = false;
@@ -50,6 +51,7 @@ export const init = safeFn('init', (config: InitConfig): void => {
       slowApi: config.detect?.slowApi ?? false,
     },
     replaySeconds: config.replaySeconds ?? 30,
+    replayScreens: config.replayScreens ?? false,
     beforeSend: config.beforeSend,
   });
   setLogLevel(config.logLevel ?? 'warn');
@@ -69,19 +71,35 @@ export const init = safeFn('init', (config: InitConfig): void => {
   const replaySeconds = config.replaySeconds ?? 30;
   if (replaySeconds > 0) {
     startReplay({ mode: 'wireframe' });
+    // Visual ring is opt-in: screenshots can carry user content.
+    if (config.replayScreens === true) startScreenReplay(replaySeconds);
     registerEmitHook((event) => {
       if (event.kind !== 'error' && event.kind !== 'warn') return;
       if (!event.id) return;
       const lines = drainReplay();
-      if (!lines) return;
-      const base64 = base64Encode(lines);
-      if (!base64) return;
-      void uploadAttachment(
-        event.id,
-        'replay',
-        { base64, mediaType: 'application/x-sentori-replay' },
-        { source: 'js' },
-      );
+      if (lines) {
+        const base64 = base64Encode(lines);
+        if (base64) {
+          void uploadAttachment(
+            event.id,
+            'replay',
+            { base64, mediaType: 'application/x-sentori-replay' },
+            { source: 'js' },
+          );
+        }
+      }
+      const frames = drainScreenReplay();
+      if (frames) {
+        const base64 = base64Encode(frames);
+        if (base64) {
+          void uploadAttachment(
+            event.id,
+            'screens',
+            { base64, mediaType: 'application/x-sentori-screens' },
+            { source: 'js' },
+          );
+        }
+      }
     });
   }
 

package/src/mask.ts

@@ -0,0 +1,39 @@
+// Screen masking — the privacy half of visual replay.
+//
+// The host registers a query returning the `nativeID`s of views
+// that must never appear in a screenshot (camera feeds, user
+// identity, payment fields). Native paints black rectangles over
+// those subtrees in the same render pass, so the pixels never
+// leave the device.
+//
+// The query runs on every frame tick; keep it cheap (return a
+// cached array). A throwing query is swallowed and masks NOTHING
+// that tick — so a broken query fails visible-in-review rather
+// than silently, and can never take the capture path down.
+
+import { reportInternal } from '@goliapkg/sentori-core';
+
+type MaskQuery = () => string[];
+
+let _query: MaskQuery | null = null;
+
+/** Register (or with `null`, clear) the mask query. */
+export const registerMaskQuery = (query: MaskQuery | null): void => {
+  _query = query;
+};
+
+/** The current mask list; empty when unregistered or throwing. */
+export const maskedNativeIds = (): string[] => {
+  if (!_query) return [];
+  try {
+    const ids = _query();
+    return Array.isArray(ids) ? ids.filter((x) => typeof x === 'string') : [];
+  } catch (e) {
+    reportInternal('mask-query', e);
+    return [];
+  }
+};
+
+export const __resetForTests = (): void => {
+  _query = null;
+};

package/src/native.ts

@@ -69,6 +69,13 @@ type SentoriNativeModule = {
    * snapshot string or null on failure.
    */
   captureWireframe?: (maskedIds: string[]) => null | string
+
+  /** v5.1 — low-bitrate replay frame; absent on older native builds. */
+  captureReplayFrame?: (
+    maskedIds: string[],
+    longEdgePx: number,
+    quality: number,
+  ) => Promise<null | { base64: string; mediaType: string }>
   /**
    * v0.9.12 — diagnostic readout for the wireframe path. Cheap
    * synchronous call that returns the path the last `captureWireframe`
@@ -387,6 +394,32 @@ export function getRecentNativeException(): null | {
  * Callers must treat `null` as "no screenshot this round" — the
  * error event still ships, just without a thumbnail.
  */
+/** v5.1 — one low-bitrate frame for the screens replay ring.
+ *  Null on every failure mode (module unbound, method missing on an
+ *  older native build, capture failed); the ring just skips a beat. */
+let warnedNoReplayFrame = false
+export async function captureNativeReplayFrame(
+  maskedIds: string[],
+  longEdgePx: number,
+  quality: number,
+): Promise<null | { base64: string; mediaType: string }> {
+  const n = native()
+  if (!n) return null
+  if (!n.captureReplayFrame) {
+    if (!warnedNoReplayFrame) {
+      warnedNoReplayFrame = true
+      logger.warn('native', 'captureReplayFrame missing — rebuild the native app for visual replay')
+    }
+    return null
+  }
+  try {
+    return (await n.captureReplayFrame(maskedIds, longEdgePx, quality)) ?? null
+  } catch (e) {
+    logger.warn('native', 'captureReplayFrame threw', e)
+    return null
+  }
+}
+
 export async function captureNativeScreenshotWithMask(
   maskedIds: string[],
 ): Promise<null | { base64: string; mediaType: string }> {

package/src/rage-tap.tsx

@@ -13,11 +13,18 @@
 import React, { useCallback, useRef } from 'react';
 import { View, type GestureResponderEvent, type ViewProps } from 'react-native';
 
-import { pushSignal } from '@goliapkg/sentori-core';
+import { pushSignal, snapshotSignals } from '@goliapkg/sentori-core';
 
 import { getConfig } from './config';
 import { currentScreen } from './navigation';
 import { RAGE_THRESHOLD, RAGE_WINDOW_MS, recordTap } from './rage-tap-detector';
+import {
+  RESPONSE_WINDOW_MS,
+  SLUGGISH_MS,
+  classifyTap,
+  recordDeadTap,
+  recordSluggish,
+} from './responsiveness-detector';
 import { warnDetected } from './verbs';
 
 export function RageTapCapture({
@@ -25,13 +32,50 @@ export function RageTapCapture({
   ...rest
 }: ViewProps & { children?: React.ReactNode }): React.JSX.Element {
   const recent = useRef<Map<number, number[]>>(new Map());
+  const deadBuckets = useRef<Map<number, number[]>>(new Map());
+  const sluggishWarns = useRef<Map<number, number>>(new Map());
 
   const onTouchEnd = useCallback((e: GestureResponderEvent) => {
     try {
       const target = e.nativeEvent?.target;
       if (typeof target !== 'number') return;
+      const tapAt = Date.now();
       pushSignal('tap', { target });
-      if (!recordTap(recent.current, target, Date.now())) return;
+
+      // Responsiveness verdict lands after the window closes: the
+      // ring tells us whether the app reacted to this tap at all.
+      setTimeout(() => {
+        try {
+          const screen = currentScreen();
+          // Ring snapshots carry event-relative seconds (one decimal);
+          // rebase them onto the epoch for the classifier.
+          const nowMs = Date.now();
+          const times = snapshotSignals(nowMs)
+            .filter((s) => s.kind !== 'tap')
+            .map((s) => nowMs + s.t * 1000);
+          const outcome = classifyTap(tapAt, times);
+          if (outcome === 'dead' && recordDeadTap(deadBuckets.current, target, Date.now())) {
+            warnDetected(
+              'dead_button',
+              { screen, element: String(target) },
+              { windowMs: RESPONSE_WINDOW_MS },
+            );
+          } else if (
+            outcome === 'sluggish' &&
+            recordSluggish(sluggishWarns.current, target, Date.now())
+          ) {
+            warnDetected(
+              'sluggish_button',
+              { screen, element: String(target) },
+              { thresholdMs: SLUGGISH_MS },
+            );
+          }
+        } catch {
+          // detector bug must never surface
+        }
+      }, RESPONSE_WINDOW_MS + 50);
+
+      if (!recordTap(recent.current, target, tapAt)) return;
       if (getConfig()?.detect.rageTap === false) return;
       warnDetected(
         'rage_tap',

package/src/replay-screens.ts

@@ -0,0 +1,95 @@
+// B-type visual replay — a rolling ring of low-bitrate screenshots.
+//
+// OFF by default (privacy + the client-zero-cost rule): enable
+// with `init({ replayScreens: true })`. One frame every 2.5 s at
+// 360 px / q≈0.35 runs 10-20 KB, so the 60 s window a triage
+// actually wants is ~24 frames and a few hundred KB — and those
+// bytes only ever leave the device when an error/warn fires,
+// stapled to that event as a `screens` attachment.
+//
+// Older native builds have no `captureReplayFrame`; the ring then
+// simply stays empty (one warn) — wireframe replay still works.
+
+import { logger } from '@goliapkg/sentori-core';
+
+import { maskedNativeIds } from './mask';
+import { captureNativeReplayFrame } from './native';
+
+type CaptureFn = typeof captureNativeReplayFrame;
+let _capture: CaptureFn = captureNativeReplayFrame;
+
+/** Frame cadence. 2.5 s keeps the main-thread cost of a capture
+ *  (~1-3 ms) far under the 1 % occupancy budget. */
+const TICK_INTERVAL_MS = 2_500;
+/** Long edge of a replay frame, px. Enough to read a screen's
+ *  layout and large text; deliberately not enough to read a
+ *  document over someone's shoulder. */
+const FRAME_LONG_EDGE_PX = 360;
+/** JPEG/WebP quality for replay frames. */
+const FRAME_QUALITY = 0.35;
+
+type ScreenFrame = { t: number; base64: string; mediaType: string };
+
+let _ring: ScreenFrame[] = [];
+let _capacity = 0;
+let _timer: ReturnType<typeof setInterval> | null = null;
+let _capturing = false;
+
+/** Start the ring. `windowSeconds` is how far back the replay
+ *  reaches when an event fires. */
+export const startScreenReplay = (windowSeconds: number): void => {
+  if (_timer !== null || windowSeconds <= 0) return;
+  _capacity = Math.max(1, Math.ceil((windowSeconds * 1000) / TICK_INTERVAL_MS));
+  _timer = setInterval(() => {
+    void tick();
+  }, TICK_INTERVAL_MS);
+  logger.debug('replay-screens', `ring started: ${_capacity} slots / ${windowSeconds}s`);
+};
+
+const tick = async (): Promise<void> => {
+  // Never overlap captures: a slow frame skips a beat instead of
+  // queueing main-thread work.
+  if (_capturing) return;
+  _capturing = true;
+  try {
+    const frame = await _capture(maskedNativeIds(), FRAME_LONG_EDGE_PX, FRAME_QUALITY);
+    if (frame) {
+      _ring.push({ t: Date.now(), ...frame });
+      if (_ring.length > _capacity) _ring.splice(0, _ring.length - _capacity);
+    }
+  } finally {
+    _capturing = false;
+  }
+};
+
+/** Drain the ring into the wire form: NDJSON, one frame per line,
+ *  `t` rewritten to seconds-before-now (negative, so the player
+ *  reads "-42.5s → 0s"). Returns null when empty. The ring is NOT
+ *  cleared — a second error two seconds later should still see
+ *  the minute before it. */
+export const drainScreenReplay = (): null | string => {
+  if (_ring.length === 0) return null;
+  const now = Date.now();
+  return _ring
+    .map((f) =>
+      JSON.stringify({
+        t: Number(((f.t - now) / 1000).toFixed(1)),
+        mediaType: f.mediaType,
+        base64: f.base64,
+      }),
+    )
+    .join('\n');
+};
+
+export const __resetForTests = (): void => {
+  if (_timer !== null) clearInterval(_timer);
+  _timer = null;
+  _ring = [];
+  _capacity = 0;
+  _capturing = false;
+  _capture = captureNativeReplayFrame;
+};
+
+export const __setCaptureForTests = (fn: CaptureFn): void => {
+  _capture = fn;
+};

package/src/responsiveness-detector.ts

@@ -0,0 +1,66 @@
+// dead_button / sluggish_button — pure detection logic.
+//
+// A tap is judged by what the signal ring records after it: any
+// non-tap signal (navigation, network, a trace point) inside the
+// response window counts as the app reacting.
+//
+//   - responsive: a reaction within SLUGGISH_MS.
+//   - sluggish:   a reaction, but slower than SLUGGISH_MS.
+//   - dead:       no reaction at all inside RESPONSE_WINDOW_MS.
+//
+// One dead tap is usually decoration (backgrounds, labels), so a
+// dead_button warn needs DEAD_THRESHOLD dead taps on the SAME
+// target inside DEAD_WINDOW_MS — a user repeatedly poking one
+// unresponsive control, at a slower cadence than a rage tap.
+// Sluggish warns are per-target cooldown-limited so one slow
+// button files one issue, not one per tap.
+
+export const RESPONSE_WINDOW_MS = 1_500;
+export const SLUGGISH_MS = 1_000;
+export const DEAD_THRESHOLD = 3;
+export const DEAD_WINDOW_MS = 30_000;
+export const SLUGGISH_COOLDOWN_MS = 60_000;
+
+export type TapOutcome = 'dead' | 'responsive' | 'sluggish';
+
+/** Judge one tap by the ring signals that followed it.
+ *  `signalTimes` are the timestamps (ms) of every non-tap signal
+ *  recorded after `tapAt`. */
+export function classifyTap(tapAt: number, signalTimes: number[]): TapOutcome {
+  const first = signalTimes
+    .filter((t) => t > tapAt && t - tapAt <= RESPONSE_WINDOW_MS)
+    .sort((a, b) => a - b)[0];
+  if (first === undefined) return 'dead';
+  return first - tapAt > SLUGGISH_MS ? 'sluggish' : 'responsive';
+}
+
+/** Per-target dead-tap bookkeeping. Returns true when this dead tap
+ *  crosses the warn threshold (and clears the bucket so the next
+ *  warn needs a fresh run of dead taps). */
+export function recordDeadTap(
+  buckets: Map<number, number[]>,
+  target: number,
+  now: number,
+): boolean {
+  const fresh = (buckets.get(target) ?? []).filter((t) => now - t <= DEAD_WINDOW_MS);
+  fresh.push(now);
+  if (fresh.length >= DEAD_THRESHOLD) {
+    buckets.delete(target);
+    return true;
+  }
+  buckets.set(target, fresh);
+  return false;
+}
+
+/** Per-target sluggish cooldown. Returns true when a warn should
+ *  fire (and stamps the cooldown). */
+export function recordSluggish(
+  lastWarnAt: Map<number, number>,
+  target: number,
+  now: number,
+): boolean {
+  const last = lastWarnAt.get(target);
+  if (last !== undefined && now - last < SLUGGISH_COOLDOWN_MS) return false;
+  lastWarnAt.set(target, now);
+  return true;
+}