@goliapkg/sentori-react-native 0.7.2 → 0.7.4

package/src/capture.ts

@@ -9,6 +9,7 @@ import { parseStack } from './stack';
 import { getTrailBuffer } from './trail';
 import { enqueue, uploadAttachment } from './transport';
 import { uuidV7 } from './uuid';
+import { getCachedNetworkType } from './netinfo';
 import type { App, AttachmentMeta, Device, Event, SentoriError, Tags, User } from './types';
 
 export { captureStep, __resetTrailForTests } from './trail';
@@ -214,17 +215,41 @@ const errorToObject = (error: Error): SentoriError => {
 const collectDevice = (): Device => {
   let os: Device['os'] = 'other';
   let osVersion = '0';
+  let locale: string | undefined;
+  const networkType = getCachedNetworkType();
   try {
     const RN = require('react-native') as {
+      NativeModules: {
+        I18nManager?: { localeIdentifier?: string };
+        SettingsManager?: {
+          settings?: { AppleLanguages?: string[]; AppleLocale?: string };
+        };
+      };
       Platform: { OS: string; Version: string | number };
     };
     const rnOS = RN.Platform.OS;
     os = rnOS === 'ios' || rnOS === 'android' || rnOS === 'web' ? rnOS : 'other';
     osVersion = String(RN.Platform.Version);
+    // v0.8.0-a — RN reads user locale through native modules. These
+    // are stable RN-internal modules (SettingsManager since 0.4,
+    // I18nManager since 0.16) so we can read them directly without
+    // an extra peer dep. iOS returns e.g. "en_US"; Android returns
+    // e.g. "en_US" via `getDefault().toString()`. `AppleLocale` is
+    // the format the user picked in Settings; `AppleLanguages[0]`
+    // is the resolved language priority — prefer the former.
+    if (rnOS === 'ios') {
+      const s = RN.NativeModules.SettingsManager?.settings;
+      locale = s?.AppleLocale ?? s?.AppleLanguages?.[0];
+    } else if (rnOS === 'android') {
+      locale = RN.NativeModules.I18nManager?.localeIdentifier;
+    }
   } catch {
     // not in RN runtime (jest, bun test)
   }
-  return { os, osVersion };
+  const device: Device = { os, osVersion };
+  if (locale) device.locale = locale;
+  if (networkType) device.networkType = networkType;
+  return device;
 };
 
 const collectApp = (release: string): App => {

package/src/handlers/screenshot.ts

@@ -1,63 +1,32 @@
-// Phase 42 sub-D.03/04 — capture a screenshot of the current view tree
-// on `captureException`. Off-main-thread, best-effort, opt-in.
+// v0.7.3 — capture a screenshot of the current view tree on
+// `captureException`. Off-main-thread, best-effort, opt-in.
 //
-// Performance contract (sub-D.04):
-//   - Yield one paint via `requestAnimationFrame` before snapshotting
-//     so the screenshot reflects post-error UI state, not the frame
-//     that was already half-laid-out.
-//   - Capped output: 480 px on the longest edge, JPEG q=70. Typical
-//     payload 30-80 KB; multipart hard cap is 500 KB.
-//   - On any failure we silently return null. The error event still
-//     goes to the server; the user just doesn't see a thumbnail.
+// JS owns the registry of which regions to redact: the host app
+// passes a thunk via `sentori.registerMaskQuery(() => string[])` that
+// returns the `nativeID`s currently mounted as masked. We call it
+// once per capture and forward the list to the native module, which
+// renders the bitmap and paints black rectangles over the matching
+// subviews in a single pass.
 //
-// `react-native-view-shot` is an OPTIONAL peer. We `require()` it
-// lazily so apps that don't install it never pay the bundle cost
-// or fail at import time. Without it, `captureScreenshot()` returns
-// `null` immediately.
+// History: pre-v0.7.3 went through `react-native-view-shot` (peer
+// dep) and used a JS-side overlay-opacity trick (`<MaskRegion>` /
+// `setMaskedNode`) to hide PII before snapshotting. That design put
+// the SDK on the render path; a single SDK bug could break the host
+// app's UI. v0.7.3 cuts that coupling — the SDK no longer ships
+// React components, and the screenshot path runs entirely through
+// the native module already used for native-crash captures.
 //
-// 2026-05-15 — dropped `InteractionManager.runAfterInteractions`.
-// RN's docs mark `InteractionManager` as deprecated and recommend
-// `requestIdleCallback`, but `requestIdleCallback` doesn't actually
-// exist in RN (it's a web API), so the deprecation print is
-// unactionable for SDK consumers. The defensive "wait for the active
-// gesture batch to drain" semantics it provided is not reachable
-// from a screenshot triggered on captureException — by the time an
-// error fires, the user is between actions, not mid-gesture — so
-// removing it has no observable effect except silencing the warning.
-// The `requestAnimationFrame` calls below still guarantee one paint
-// commit before captureRef snapshots.
-
-import { engageMasks } from '../mask';
-
-type CaptureRef = (
-  // Phase 42: the lib accepts a React ref or — when we pass `undefined` —
-  // shoots the root window. We always go for the root (no per-component
-  // ref) so the screenshot lines up with what the user just saw.
-  refOrUndefined: undefined,
-  opts: {
-    format?: 'jpg' | 'png' | 'webm';
-    quality?: number;
-    result?: 'base64' | 'data-uri' | 'tmpfile';
-    width?: number;
-    height?: number;
-  },
-) => Promise<string>;
-
-type ViewShotModule = { captureRef?: CaptureRef; default?: { captureRef?: CaptureRef } };
-
-function loadCaptureRef(): CaptureRef | null {
-  try {
-    // eslint-disable-next-line @typescript-eslint/no-require-imports
-    const mod = require('react-native-view-shot') as ViewShotModule;
-    return mod.captureRef ?? mod.default?.captureRef ?? null;
-  } catch {
-    return null;
-  }
-}
+// Performance:
+//   - Yield one paint via `requestAnimationFrame` before the native
+//     call so post-error UI state has committed.
+//   - 480 px on the longest edge, JPEG q=70 (iOS) / WEBP_LOSSY q=70
+//     (Android 11+). Typical payload 30-80 KB; multipart hard cap
+//     is 500 KB.
+//   - On any failure we silently return null. The error event still
+//     goes to the server; the user just doesn't see a thumbnail.
 
-const MAX_LONG_EDGE_PX = 480;
-const WEBP_QUALITY = 0.7;
-const CAPTURE_TIMEOUT_MS = 1500;
+import { getRegisteredMaskQuery } from '../mask';
+import { captureNativeScreenshotWithMask } from '../native';
 
 /** What `captureScreenshot()` hands back when it succeeds. */
 export type ScreenshotBlob = {
@@ -67,74 +36,34 @@ export type ScreenshotBlob = {
 
 /**
  * Take one screenshot, yielding the JS thread first. Returns null on
- * any error (missing peer dep, native side refused, timeout, etc.).
- * Caller is responsible for opt-in checks (`config.screenshotsEnabled`).
+ * any error (no native module bound, native side refused, capture
+ * timed out, etc.). Caller is responsible for opt-in checks
+ * (`config.screenshotsEnabled`).
  */
 export async function captureScreenshot(): Promise<ScreenshotBlob | null> {
-  const captureRef = loadCaptureRef();
-  if (!captureRef) return null;
-
   // Yield one paint frame so the post-error UI has committed before
-  // we ask the OS to snapshot it. The previous
-  // `InteractionManager.runAfterInteractions` step was removed: see
-  // file header — its replacement (`requestIdleCallback`) doesn't
-  // exist in RN, and on captureException the user is between actions
-  // anyway, so the gesture-batch-drain semantics never came into
-  // play in practice.
-  await new Promise<void>((resolve) => {
-    requestAnimationFrame(() => resolve());
-  });
-
-  // Phase 48 sub-B — flip every registered MaskRegion overlay to
-  // opacity 1 (black covers the children) and every imperative
-  // setMaskedNode ref to opacity 0 (subtree disappears). Held for
-  // exactly one frame's worth of capture, then restored.
-  const restoreMasks = engageMasks();
-  // Yield one more frame so the overlay paint reaches the screen
-  // before captureRef snapshots. Without this the overlay opacity
-  // change is queued but the screenshotter may see the previous
-  // frame.
+  // we ask the OS to snapshot it.
   await new Promise<void>((resolve) => {
     requestAnimationFrame(() => resolve());
   });
 
-  try {
-    const base64 = await withTimeout(
-      captureRef(undefined, {
-        format: 'jpg',
-        quality: WEBP_QUALITY,
-        result: 'base64',
-        // Long-edge cap. RN view-shot scales preserving aspect ratio
-        // when only one dimension is set.
-        width: MAX_LONG_EDGE_PX,
-      }),
-      CAPTURE_TIMEOUT_MS,
-    );
-    restoreMasks();
-    if (!base64) return null;
-    // view-shot doesn't ship a WebP encoder on every RN version.
-    // JPEG q=70 fits the budget too (typical 40-100 KB) and every
-    // version handles it identically. We can swap to WebP once the
-    // RN minimum we support has it everywhere.
-    return { base64, mediaType: 'image/jpeg' };
-  } catch {
-    restoreMasks();
-    return null;
+  // Read the consumer-supplied mask query once per capture. If
+  // the host never called `registerMaskQuery`, no mask is applied
+  // and the full screenshot ships — sane default: SDK does nothing
+  // unless told to.
+  const query = getRegisteredMaskQuery();
+  let maskedIds: string[] = [];
+  if (query) {
+    try {
+      maskedIds = query();
+    } catch {
+      // A throwing query is the host's bug, not ours; skip mask
+      // rather than skip the screenshot.
+      maskedIds = [];
+    }
   }
-}
 
-function withTimeout<T>(p: Promise<T>, ms: number): Promise<T | null> {
-  return new Promise((resolve) => {
-    const t = setTimeout(() => resolve(null as unknown as T), ms);
-    p.then(
-      (v) => {
-        clearTimeout(t);
-        resolve(v);
-      },
-      () => {
-        clearTimeout(t);
-        resolve(null as unknown as T);
-      },
-    );
-  });
+  const result = await captureNativeScreenshotWithMask(maskedIds);
+  if (!result) return null;
+  return { base64: result.base64, mediaType: result.mediaType };
 }

package/src/index.ts

@@ -2,7 +2,7 @@ import { init } from './init';
 import { addBreadcrumb } from './breadcrumbs';
 import { setUser, getUser, captureError, captureException, captureStep } from './capture';
 import { ErrorBoundary } from './error-boundary';
-import { MaskRegion, setMaskedNode, unsetMaskedNode } from './mask';
+import { clearMaskQuery, registerMaskQuery } from './mask';
 import {
   endSession,
   markSessionCrashed,
@@ -18,9 +18,8 @@ export const sentori = {
   captureException,
   captureStep,
   ErrorBoundary,
-  MaskRegion,
-  setMaskedNode,
-  unsetMaskedNode,
+  registerMaskQuery,
+  clearMaskQuery,
   startSession,
   endSession,
   markSessionCrashed,
@@ -38,7 +37,7 @@ export {
   setUser,
 } from './capture';
 export { ErrorBoundary } from './error-boundary';
-export { MaskRegion, setMaskedNode, unsetMaskedNode } from './mask';
+export { clearMaskQuery, registerMaskQuery } from './mask';
 export {
   startAnrWatchdog,
   stopAnrWatchdog,

package/src/init.ts

@@ -4,6 +4,7 @@ import { installLifecycleHandler } from './handlers/lifecycle';
 import { installPromiseHandler } from './handlers/promise';
 import { installNetworkHandler } from './handlers/network';
 import { drainNativePending, setNativeConfig } from './native';
+import { startNetworkTypeWatch } from './netinfo';
 import { startSession } from './session-tracker';
 import {
   drainOfflineQueue,
@@ -33,10 +34,14 @@ export type InitOptions = {
      *  foreground (`AppState` → `active`), ends it on background.
      *  Drives crash-free rate. Set `false` to opt out. */
     sessions?: boolean;
-    /** Phase 42 sub-D.07: capture a screenshot of the current screen
-     *  on `captureException`. Opt-in — requires `react-native-view-shot`
-     *  installed and `<MaskRegion>` placed over any sensitive UI. The
-     *  image is webp q=70 480 px max, < 100 KB typical. */
+    /** Capture a screenshot of the current screen on
+     *  `captureException`. Opt-in. The capture runs through the
+     *  bundled native module — no extra peer dep required since
+     *  v0.7.3. To redact PII regions, register a mask query via
+     *  `sentori.registerMaskQuery(() => string[])` and put
+     *  `nativeID="..."` on the `<View>`s the SDK should black out.
+     *  The image is webp q=70 / jpeg q=70 at 480 px max, < 100 KB
+     *  typical. */
     screenshot?: boolean;
     /** Phase 46: record the last N steps (route changes, custom
      *  breadcrumbs) leading up to a crash. On `captureException`
@@ -91,6 +96,10 @@ export const init = (options: InitOptions): void => {
   });
 
   startTransport();
+  // v0.8.0-c — start watching network class. No-op if NetInfo isn't
+  // installed; events just won't carry `device.networkType` in that
+  // case.
+  startNetworkTypeWatch();
 
   const capture = options.capture ?? {};
   if (capture.globalErrors !== false) installGlobalHandler();

package/src/mask.ts

@@ -0,0 +1,41 @@
+// v0.7.3 — mask discovery via consumer-supplied query callback.
+//
+// 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.
+//
+// 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.
+
+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 {
+  _query = query;
+}
+
+/** Unregister. Mostly for tests / teardown. */
+export function clearMaskQuery(): void {
+  _query = null;
+}
+
+/** Internal — read by `handlers/screenshot.ts` at capture time. */
+export function getRegisteredMaskQuery(): MaskQuery | null {
+  return _query;
+}

package/src/native.ts

@@ -11,6 +11,18 @@ type SentoriNativeModule = {
     release: string
     token: string
   }) => void
+  /**
+   * v0.7.3 — JS-triggered screenshot with consumer-supplied mask IDs.
+   * `maskedIds` are RN `nativeID` strings; native walks the view
+   * tree, finds each subview by identifier, and paints a black
+   * rectangle over its frame in the captured bitmap. Resolves to
+   * `null` if there's no key window / API < 24 (Android) / render
+   * timed out. Replaced the previous `react-native-view-shot`
+   * peer-dep path.
+   */
+  captureScreenshotWithMask?: (
+    maskedIds: string[],
+  ) => Promise<null | { base64: string; mediaType: string }>
   /**
    * Phase 22 sub-D / sub-E: cross-platform main-thread watchdog.
    * Android: 5 s / 1 s defaults (matches the OS ANR threshold).
@@ -114,3 +126,26 @@ export function stopAnrWatchdog(): void {
     // ignore
   }
 }
+
+/**
+ * v0.7.3 — drives the native screenshot path. JS side passes the
+ * current list of mask `nativeID`s (read from the consumer's
+ * registered mask query); native renders + redacts.
+ *
+ * Returns `null` on every failure mode: no native module bound
+ * (jest, bun test, web), method missing (older native build still
+ * deployed), capture failed (no key window, timed out, etc.).
+ * Callers must treat `null` as "no screenshot this round" — the
+ * error event still ships, just without a thumbnail.
+ */
+export async function captureNativeScreenshotWithMask(
+  maskedIds: string[],
+): Promise<null | { base64: string; mediaType: string }> {
+  const n = native()
+  if (!n?.captureScreenshotWithMask) return null
+  try {
+    return await n.captureScreenshotWithMask(maskedIds)
+  } catch {
+    return null
+  }
+}

package/src/navigation.ts

@@ -54,6 +54,9 @@ export type NavigationRefLike = {
 export function useTraceNavigation(navigationRef: NavigationRefLike): void {
   // Latest route name we've observed.
   const lastRouteRef = useRef<null | string>(null);
+  // Wall-clock ms when the last screen was entered. Drives dwell time
+  // attached to the leaving span + the next captureStep breadcrumb.
+  const lastRouteEnteredAtRef = useRef<null | number>(null);
   // Span for the screen the user is currently on. Finished when the
   // next screen is entered (or on unmount).
   const openSpanRef = useRef<null | SpanHandle>(null);
@@ -65,7 +68,11 @@ export function useTraceNavigation(navigationRef: NavigationRefLike): void {
     // Each screen gets its own trace root — detach from whatever the
     // previous screen's span was (we keep it active, so without
     // `parent: null` the new one would nest under it).
-    const openScreenSpan = (from: null | string, to: string) => {
+    const openScreenSpan = (
+      from: null | string,
+      to: string,
+      prevDwellMs: null | number,
+    ) => {
       const span = startSpan('react.navigation', {
         name: from ? `${from} → ${to}` : to,
         parent: null,
@@ -74,33 +81,54 @@ export function useTraceNavigation(navigationRef: NavigationRefLike): void {
       openSpanRef.current = span;
       setActiveSpan(span);
       lastRouteRef.current = to;
-      // Phase 46 — record the screen transition into the session trail.
-      // No-op when sessionTrail isn't enabled (the buffer just grows
-      // unbounded until cleared by captureException, but stays cheap).
+      lastRouteEnteredAtRef.current = Date.now();
+      // v0.8.0-b — dwell on the previous screen surfaces in the
+      // session trail. The leaving span's `durationMs` already
+      // carries the same number, but the trail is the most-glanced
+      // surface so we duplicate it as breadcrumb data. No bytes wasted:
+      // a breadcrumb without sessionTrail enabled is a no-op.
       captureStep(`screen:${to}`, {
-        breadcrumb: { type: 'navigation', message: from ? `${from} → ${to}` : to },
+        breadcrumb: {
+          data: prevDwellMs !== null ? { dwellMsPrev: prevDwellMs } : undefined,
+          message: from ? `${from} → ${to}` : to,
+          type: 'navigation',
+        },
       });
     };
 
+    const finishOpenSpanWithDwell = (): null | number => {
+      const span = openSpanRef.current;
+      const enteredAt = lastRouteEnteredAtRef.current;
+      if (!span) return null;
+      const dwellMs = enteredAt !== null ? Math.max(0, Date.now() - enteredAt) : null;
+      span.finish({
+        status: 'ok',
+        // Tag values are strings on the wire — cast at finish-time.
+        tags: dwellMs !== null ? { 'nav.dwell_ms': String(dwellMs) } : undefined,
+      });
+      return dwellMs;
+    };
+
     // Open a span for the initial screen so its requests are grouped
     // too (auth / config / first data load are usually the busiest
     // screen of a session).
     const initial = navigationRef.getCurrentRoute()?.name ?? null;
-    if (initial !== null) openScreenSpan(null, initial);
+    if (initial !== null) openScreenSpan(null, initial, null);
     else lastRouteRef.current = null;
 
     const unsubscribe = navigationRef.addListener('state', () => {
       const next = navigationRef.getCurrentRoute()?.name ?? null;
       const prev = lastRouteRef.current;
       if (next === null || next === prev) return;
-      openSpanRef.current?.finish({ status: 'ok' });
-      openScreenSpan(prev, next);
+      const dwellMs = finishOpenSpanWithDwell();
+      openScreenSpan(prev, next, dwellMs);
     });
 
     return () => {
       unsubscribe();
-      openSpanRef.current?.finish({ status: 'ok' });
+      finishOpenSpanWithDwell();
       openSpanRef.current = null;
+      lastRouteEnteredAtRef.current = null;
       setActiveSpan(null);
     };
   }, [navigationRef]);

package/src/netinfo.ts

@@ -0,0 +1,81 @@
+// v0.8.0-c — cached read of the current network class.
+//
+// `@react-native-community/netinfo` is an OPTIONAL peer dep. If the
+// host app has it installed (most production RN apps do — it's a
+// standard library), we subscribe at SDK init time and cache the
+// latest network state. `collectDevice()` reads the cache
+// synchronously at capture time. If the peer isn't installed, the
+// cache stays `undefined` and `device.networkType` is omitted —
+// no warning, no crash.
+//
+// We collapse NetInfo's enum into the smaller set the protocol
+// allows (see `Device.networkType` in `sdk/core/src/types.ts`):
+// `wifi`, `2g/3g/4g/slow-2g`, `offline`, `unknown`. 5G collapses
+// into `4g` because the schema doesn't have a 5g slot yet; the
+// information loss is acceptable for an analytics dimension.
+
+import type { Device } from '@goliapkg/sentori-core';
+
+type NetworkType = Device['networkType'];
+
+type NetInfoState = {
+  details?: { cellularGeneration?: null | string };
+  isConnected?: boolean | null;
+  type?: string;
+};
+
+type NetInfoModule = {
+  addEventListener?: (cb: (state: NetInfoState) => void) => () => void;
+  default?: { addEventListener?: (cb: (state: NetInfoState) => void) => () => void };
+};
+
+let _cached: NetworkType;
+let _started = false;
+let _unsubscribe: (() => void) | null = null;
+
+function mapState(state: NetInfoState): NetworkType {
+  if (state.isConnected === false) return 'offline';
+  if (state.type === 'wifi' || state.type === 'ethernet') return 'wifi';
+  if (state.type === 'cellular') {
+    const gen = state.details?.cellularGeneration;
+    if (gen === '2g' || gen === '3g' || gen === '4g') return gen;
+    if (gen === '5g') return '4g';
+    return 'unknown';
+  }
+  if (state.type === 'none' || state.type === 'unknown') return 'unknown';
+  return undefined;
+}
+
+/**
+ * Idempotent — subscribe to NetInfo state changes and cache the
+ * latest network class. Called once from `init()`. Pure no-op if
+ * the peer isn't installed or we're not in an RN runtime.
+ */
+export function startNetworkTypeWatch(): void {
+  if (_started) return;
+  _started = true;
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const mod = require('@react-native-community/netinfo') as NetInfoModule;
+    const add = mod.addEventListener ?? mod.default?.addEventListener;
+    if (typeof add !== 'function') return;
+    _unsubscribe = add((state) => {
+      _cached = mapState(state);
+    });
+  } catch {
+    // not installed — leave cache undefined
+  }
+}
+
+/** Synchronous read at capture time. */
+export function getCachedNetworkType(): NetworkType {
+  return _cached;
+}
+
+/** Test-only. */
+export function __resetNetworkTypeForTests(): void {
+  _unsubscribe?.();
+  _unsubscribe = null;
+  _started = false;
+  _cached = undefined;
+}