@goliapkg/sentori-react-native 4.0.0 → 5.1.0

package/src/long-task-monitor.ts

@@ -1,57 +1,39 @@
-// v0.9.6 #4 — JS thread long-task monitor.
+// long_freeze — detected warn scenario (design.md §3, category B:
+// 「app 卡住了 / 死了几秒」), JS-thread side.
 //
-// What it does: a setInterval(50ms) tick checks how much wall-clock
-// passed vs the requested interval. Excess = the JS thread was busy
-// doing something else for at least that much. When the excess
-// crosses 200ms (a "long task" per Chrome's PerformanceObserver
-// threshold) we emit a `sentori.longtask` span so the dashboard's
-// trace waterfall shows where the JS thread stalled.
+// Mini-spec: a setInterval(50 ms) tick measures wall-clock drift.
+// Drift ≤ 2 s ⇒ a `freeze` signal in the ring (context only —
+// brief jank is not worth an event). Drift > 2 s ⇒ one `warn`
+// event, scenario `long_freeze`, surface = current screen, with the
+// blocked duration. Rate-limited to 6 events/minute so a freeze
+// storm cannot flood ingest.
 //
-// What it does NOT do: capture the stack DURING the long task. JS
-// is single-threaded — by the time our tick runs, the busy code is
-// already gone. The span carries the duration + nearest navigation
-// context (via active span) so triage still has a route to blame.
-//
-// Why this and not a real Hermes sampler: Hermes ships a sampling
-// profiler but accessing it from JS requires RN-internal bridges
-// that vary per RN minor. We could swizzle / vendor headers but
-// that's an Insight-build-config burden. The long-task monitor
-// gets ~80% of the practical value (find slow renders, expensive
-// reducers, accidental sync work in render path) with zero native
-// code + zero RN-version sensitivity.
-//
-// Pairs naturally with +S4 (pre-crash sentinel, RAF frame budget,
-// fires at the slow-frame threshold) — long-task monitor fires
-// further down the slowness scale.
+// What it cannot do: capture the stack DURING the block — JS is
+// single-threaded; by the time our tick runs the busy code is gone.
+// The native watchdogs (HangWatchdog / AnrWatchdog) cover the
+// UI-thread side of the same scenario.
+
+import { pushSignal } from '@goliapkg/sentori-core';
 
-import { startSpan } from '@goliapkg/sentori-core';
+import { currentScreen } from './navigation';
+import { warnDetected } from './verbs';
 
 const TICK_INTERVAL_MS = 50;
-const LONGTASK_THRESHOLD_MS = 200; // > 200ms blocking = a longtask
-const MAX_EMITS_PER_MIN = 60;
+const SIGNAL_THRESHOLD_MS = 200; // ring entry: noticeable jank
+const WARN_THRESHOLD_MS = 2_000; // warn event: a real freeze
+const MAX_WARNS_PER_MIN = 6;
 
 let _timer: ReturnType<typeof setInterval> | null = null;
 let _lastTick = 0;
-let _emitWindowStart = 0;
-let _emitsThisWindow = 0;
+let _warnWindowStart = 0;
+let _warnsThisWindow = 0;
 
-export type LongTaskMonitorOptions = {
-  enabled: boolean;
-  /** Threshold ms above which a tick lag becomes a longtask span.
-   *  Default 200ms. Lower → noisier. */
-  thresholdMs?: number;
-};
-
-export function startLongTaskMonitor(opts: LongTaskMonitorOptions): void {
+export function startLongTaskMonitor(): void {
   if (_timer !== null) return;
-  if (!opts.enabled) return;
-  const threshold = opts.thresholdMs ?? LONGTASK_THRESHOLD_MS;
   _lastTick = Date.now();
-  _emitWindowStart = _lastTick;
-  _emitsThisWindow = 0;
-  _timer = setInterval(() => {
-    tick(threshold);
-  }, TICK_INTERVAL_MS);
+  _warnWindowStart = _lastTick;
+  _warnsThisWindow = 0;
+  _timer = setInterval(tick, TICK_INTERVAL_MS);
   (_timer as unknown as { unref?: () => void }).unref?.();
 }
 
@@ -62,38 +44,34 @@ export function stopLongTaskMonitor(): void {
   }
 }
 
-function tick(threshold: number): void {
+function tick(): void {
   const now = Date.now();
   const elapsed = now - _lastTick;
   _lastTick = now;
   const lag = elapsed - TICK_INTERVAL_MS;
-  if (lag <= threshold) return;
+  if (lag <= SIGNAL_THRESHOLD_MS) return;
+
+  pushSignal('freeze', { blockedMs: Math.round(lag) });
+  if (lag <= WARN_THRESHOLD_MS) return;
 
-  // Rate-limit emits: at most MAX_EMITS_PER_MIN per minute so a
-  // pathological scroll-block-storm doesn't generate 1000 spans.
-  if (now - _emitWindowStart >= 60_000) {
-    _emitWindowStart = now;
-    _emitsThisWindow = 0;
+  if (now - _warnWindowStart >= 60_000) {
+    _warnWindowStart = now;
+    _warnsThisWindow = 0;
   }
-  if (_emitsThisWindow >= MAX_EMITS_PER_MIN) return;
-  _emitsThisWindow += 1;
+  if (_warnsThisWindow >= MAX_WARNS_PER_MIN) return;
+  _warnsThisWindow += 1;
 
-  const span = startSpan('sentori.longtask', {
-    name: 'js.longtask',
-    startNowMs: now - lag,
-    tags: {
-      'profile.kind': 'longtask',
-      'profile.duration_ms': String(Math.round(lag)),
-      'profile.tick_interval_ms': String(TICK_INTERVAL_MS),
-    },
-  });
-  span.finish({ endNowMs: now, status: 'ok' });
+  warnDetected(
+    'long_freeze',
+    { screen: currentScreen() },
+    { blockedMs: Math.round(lag), thread: 'js' },
+  );
 }
 
 /** Test-only. */
 export function __resetLongTaskMonitorForTests(): void {
   stopLongTaskMonitor();
   _lastTick = 0;
-  _emitWindowStart = 0;
-  _emitsThisWindow = 0;
+  _warnWindowStart = 0;
+  _warnsThisWindow = 0;
 }

package/src/mask.ts

@@ -1,41 +1,39 @@
-// v0.7.3 — mask discovery via consumer-supplied query callback.
+// Screen masking — the privacy half of visual replay.
 //
-// The SDK does not own a registry of masked regions. The host app
-// keeps its own (e.g. a `Set<string>` updated as `<Maskable>`
-// components mount/unmount) and hands the SDK a thunk that returns
-// the current list of native-IDs to redact. The SDK calls the thunk
-// once per screenshot capture — cheap, called rarely, only on error.
+// 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.
 //
-// Why this shape: a logging SDK should never live on the render
-// path. Earlier iterations exported `<MaskRegion>` (React component)
-// and `setMaskedNode` (imperative ref helper), which forced every
-// PII-bearing UI file to import from the SDK and put SDK bugs in
-// the user's render tree. This module is JS-only — no React, no JSX,
-// no native module touch — so swapping or removing the SDK doesn't
-// affect rendering.
+// 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 a callback the SDK calls right before each screenshot
- * capture. Return the native-IDs (the `nativeID` prop on the RN
- * `<View>`) that should be blacked-out in the captured image.
- *
- * Idempotent: a second call replaces the first. Pass `null` (or
- * call `clearMaskQuery`) to detach.
- */
-export function registerMaskQuery(query: MaskQuery): void {
+/** Register (or with `null`, clear) the mask query. */
+export const registerMaskQuery = (query: MaskQuery | null): void => {
   _query = query;
-}
+};
 
-/** Unregister. Mostly for tests / teardown. */
-export function clearMaskQuery(): void {
-  _query = null;
-}
+/** 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 [];
+  }
+};
 
-/** Internal — read by `handlers/screenshot.ts` at capture time. */
-export function getRegisteredMaskQuery(): MaskQuery | null {
-  return _query;
-}
+export const __resetForTests = (): void => {
+  _query = null;
+};

package/src/mobile-vitals.ts

@@ -1,34 +1,25 @@
-// v0.9.4 #1 — Mobile Vitals.
+// slow_cold_start — detected warn scenario (design.md §3, category
+// C: 「启动过慢」).
 //
-// Three measurements, three call paths, one server schema:
-//
-//   • Cold start: native side measures at app launch (iOS
-//     mach_absolute_time / Android Process.getStartElapsedRealtime)
-//     and exposes via the bundled native module — read once on JS
-//     side at init() and ride along on the first event.
-//   • TTID (Time-To-Initial-Display): automatic via
-//     useTraceNavigation extension — span from navigation.dispatch
-//     to first frame after route mount.
-//   • TTFD (Time-To-Full-Display): manual. Host calls
-//     sentori.markTimeToFullDisplay('Home').end() when the screen's
-//     data has loaded.
-//   • Slow / frozen frame counts: native side hooks CADisplayLink /
-//     Choreographer.FrameCallback; counters flush per navigation
-//     span.
-//
-// JS-side first: TTFD API + bundle-level vital captures. Native
-// pieces ship as a separate native module method `getColdStartMs`
-// + `getFrameCounts()` — graceful no-op if not linked.
+// Mini-spec: the native side measures launch → JS-ready (iOS
+// mach_absolute_time / Android Process.getStartElapsedRealtime);
+// init() calls checkColdStart() once. > 3 s ⇒ one `warn` event,
+// scenario `slow_cold_start`, with the measured ms. Always pushes a
+// `lifecycle` signal so even a fast start shows on the timeline.
+// Graceful no-op when the native module isn't linked (Expo Go,
+// tests).
+
+import { pushSignal } from '@goliapkg/sentori-core';
 
-import { startSpan } from '@goliapkg/sentori-core';
+import { getNativeColdStartMs } from './native';
+import { warnDetected } from './verbs';
 
-import { getNativeColdStartMs, getNativeFrameCounters } from './native';
+const SLOW_COLD_START_MS = 3_000;
 
 let _coldStartMs: null | number = null;
 let _coldStartCaptured = false;
 
-/** Read the native-side cold start measurement once. Cached. Returns
- *  null when the native module isn't linked (Expo Go / tests). */
+/** Read the native-side cold start measurement once. Cached. */
 export function getColdStartMs(): null | number {
   if (_coldStartCaptured) return _coldStartMs;
   _coldStartCaptured = true;
@@ -40,69 +31,18 @@ export function getColdStartMs(): null | number {
   return _coldStartMs;
 }
 
-/**
- * v0.9.4 #1 — Time-To-Full-Display marker. Host calls this at the
- * point the screen is functionally "ready" (data fetched, images
- * loaded, etc.) so the dashboard can show real perceived load time
- * vs auto-detected TTID.
- *
- *     const h = sentori.markTimeToFullDisplay('Home');
- *     // ...data fetched, images rendered...
- *     h.end();
- *
- * If `.end()` is never called, the handle's span is finished as
- * `cancelled` at the next `markTimeToFullDisplay` call (one TTFD in
- * flight at a time is the typical case).
- */
-export type TimeToFullDisplayHandle = {
-  end: (opts?: { status?: 'cancelled' | 'error' | 'ok' }) => void;
-  cancel: () => void;
-};
-
-let _activeTtfd: null | {
-  finish: (status: 'cancelled' | 'error' | 'ok') => void;
-  route: string;
-} = null;
-
-export function markTimeToFullDisplay(route: string): TimeToFullDisplayHandle {
-  if (_activeTtfd && _activeTtfd.route !== route) {
-    _activeTtfd.finish('cancelled');
-  }
-  const span = startSpan('react.navigation.ttfd', {
-    name: route,
-    tags: { 'nav.route': route, 'vital.kind': 'ttfd' },
-  });
-  let finished = false;
-  const finish = (status: 'cancelled' | 'error' | 'ok'): void => {
-    if (finished) return;
-    finished = true;
-    span.finish({ status });
-    if (_activeTtfd && _activeTtfd.route === route) _activeTtfd = null;
-  };
-  _activeTtfd = { finish, route };
-  return {
-    cancel: () => finish('cancelled'),
-    end: (opts?: { status?: 'cancelled' | 'error' | 'ok' }) =>
-      finish(opts?.status ?? 'ok'),
-  };
-}
-
-/** v0.9.4 #1 — read the per-screen slow/frozen frame counts since
- *  the most recent navigation transition. Native module reads
- *  CADisplayLink / Choreographer counters; returns null when not
- *  linked. */
-export function getFrameCounters(): null | { slow: number; frozen: number } {
-  try {
-    return getNativeFrameCounters();
-  } catch {
-    return null;
+/** Called once from init(): signal always, warn when slow. */
+export function checkColdStart(detectEnabled: boolean): void {
+  const ms = getColdStartMs();
+  if (ms === null) return;
+  pushSignal('lifecycle', { phase: 'cold_start', ms });
+  if (detectEnabled && ms > SLOW_COLD_START_MS) {
+    warnDetected('slow_cold_start', {}, { coldStartMs: ms, thresholdMs: SLOW_COLD_START_MS });
   }
 }
 
 /** Test-only. */
 export function __resetMobileVitalsForTests(): void {
-  if (_activeTtfd) _activeTtfd.finish('cancelled');
-  _activeTtfd = null;
   _coldStartCaptured = false;
   _coldStartMs = null;
 }

package/src/native-pending.ts

@@ -0,0 +1,92 @@
+// Native pending-crash drain: the crash handlers (Swift/Kotlin)
+// write one JSON file per crash in the legacy event shape; this
+// module converts them to the v1 wire and enqueues.
+//
+// The converter lives on the JS side so the native writers stay
+// untouched — native code doesn't compile in preflight/CI, and a
+// silent .kt/.swift break ships to npm (the v3.0.0 K2 lesson).
+
+import { uuidV7 } from '@goliapkg/sentori-core';
+import type { SentoriError, WireEvent } from '@goliapkg/sentori-core';
+
+import { drainNativePending } from './native';
+import { enqueue, flush, uploadAttachment } from './transport';
+
+type LegacyNativeEvent = {
+  id?: string;
+  timestamp?: string;
+  platform?: string;
+  release?: string;
+  environment?: string;
+  device?: Record<string, unknown>;
+  app?: Record<string, unknown>;
+  error?: {
+    type?: string;
+    message?: string;
+    stack?: Array<Record<string, unknown>>;
+  };
+  _pendingAttachments?: Array<{
+    kind?: string;
+    base64?: string;
+    mediaType?: string;
+    source?: string;
+  }>;
+};
+
+const toWire = (raw: LegacyNativeEvent): WireEvent => {
+  const platform = raw.platform === 'android' ? 'android' : 'ios';
+  const error: SentoriError = {
+    type: raw.error?.type ?? 'NativeCrash',
+    message: raw.error?.message ?? '',
+    stack: (raw.error?.stack ?? []).map((f) => ({
+      file: typeof f.file === 'string' ? f.file : undefined,
+      function: typeof f.function === 'string' ? f.function : undefined,
+      line: typeof f.line === 'number' ? f.line : undefined,
+      inApp: typeof f.inApp === 'boolean' ? f.inApp : undefined,
+    })),
+    cause: null,
+  };
+  return {
+    id: raw.id ?? uuidV7(),
+    kind: 'error',
+    occurredAt: raw.timestamp ?? new Date().toISOString(),
+    platform,
+    release: raw.release ?? '',
+    environment: raw.environment ?? '',
+    payload: {
+      error,
+      device: raw.device as WireEvent['payload']['device'],
+      app: raw.app as WireEvent['payload']['app'],
+      nativeCrash: true,
+    },
+  };
+};
+
+/** Drain, convert, enqueue, and ship pre-death attachments. */
+export const shipNativePending = async (): Promise<void> => {
+  const files = await drainNativePending();
+  for (const text of files) {
+    try {
+      const raw = JSON.parse(text) as LegacyNativeEvent;
+      const pending = raw._pendingAttachments;
+      delete raw._pendingAttachments;
+      const wire = toWire(raw);
+      enqueue(wire);
+      if (pending && wire.id) {
+        for (const att of pending) {
+          if (att.base64 && att.kind) {
+            void uploadAttachment(
+              wire.id,
+              att.kind as import('@goliapkg/sentori-core').AttachmentKind,
+              { base64: att.base64, mediaType: att.mediaType ?? 'application/octet-stream' },
+              { source: (att.source as 'android' | 'ios' | 'js') ?? 'ios' },
+            );
+          }
+        }
+      }
+    } catch {
+      // One corrupt crash file must not block the rest.
+    }
+  }
+  if (files.length > 0) await flush();
+};

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 }> {