@goliapkg/sentori-react-native 0.8.4 → 0.9.0

package/src/mobile-vitals.ts

@@ -0,0 +1,114 @@
+// v0.9.4 #1 — Mobile Vitals.
+//
+// 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.
+
+import { startSpan } from '@goliapkg/sentori-core';
+
+import { getNativeColdStartMs } from './native';
+
+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). */
+export function getColdStartMs(): null | number {
+  if (_coldStartCaptured) return _coldStartMs;
+  _coldStartCaptured = true;
+  try {
+    _coldStartMs = getNativeColdStartMs();
+  } catch {
+    _coldStartMs = null;
+  }
+  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 {
+    // native binding lazily required in native.ts
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const nativeMod = require('./native') as {
+      getNativeFrameCounters?: () => null | { frozen: number; slow: number };
+    };
+    if (typeof nativeMod.getNativeFrameCounters !== 'function') return null;
+    return nativeMod.getNativeFrameCounters();
+  } catch {
+    return null;
+  }
+}
+
+/** Test-only. */
+export function __resetMobileVitalsForTests(): void {
+  if (_activeTtfd) _activeTtfd.finish('cancelled');
+  _activeTtfd = null;
+  _coldStartCaptured = false;
+  _coldStartMs = null;
+}

package/src/native-loader.ts

@@ -0,0 +1,33 @@
+// v0.8.5 — shared guard for "JS package is in node_modules but native
+// module isn't linked".
+//
+// The pattern that bit us in 0.8.0–0.8.3 (NetInfo, AsyncStorage,
+// expo-sensors, ...): host had the JS package via npm hoisting (or
+// via our old `optionalDependencies` mistake) but never ran
+// `pod install` / `prebuild` / `react-native link`. We `require(...)`
+// successfully, call a method, then the lib's internal native bridge
+// access throws — and most of those errors arrive on an emitter or
+// microtask where our try/catch can't reach.
+//
+// Fix: before requireing such a package, check that the registered
+// NativeModule actually exists. `null` → skip the whole feature; cost
+// is one nullable map read.
+
+export function isNativeModuleLinked(name: string): boolean {
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const RN = require('react-native') as {
+      NativeModules?: Record<string, unknown>;
+    };
+    return RN.NativeModules?.[name] != null;
+  } catch {
+    return false;
+  }
+}
+
+/** Some native modules are registered under multiple alternative names
+ *  across RN versions / Expo packaging. Returns `true` iff *any* name
+ *  is linked. */
+export function isAnyNativeModuleLinked(names: string[]): boolean {
+  return names.some(isNativeModuleLinked);
+}

package/src/native.ts

@@ -11,6 +11,29 @@ type SentoriNativeModule = {
     release: string
     token: string
   }) => void
+  /**
+   * v0.9.4 #1 — cold start measurement. iOS:
+   * `mach_absolute_time` from `applicationDidFinishLaunching` to first
+   * JS bridge ready. Android: `Process.getStartElapsedRealtime()`.
+   * Returns null when native side hasn't captured yet.
+   */
+  getColdStartMs?: () => null | number
+  /**
+   * v0.9.4 #1 — call once at JS init() to finalize the cold-start
+   * measurement. iOS subtracts from the app-delegate anchor;
+   * Android uses Process.getStartElapsedRealtime() so the call is
+   * idempotent if missed.
+   */
+  markJsBridgeReady?: () => void
+  /**
+   * v0.9.4 #1 — slow/frozen frame counters since the most recent
+   * navigation transition. Native side hooks `CADisplayLink` (iOS)
+   * / `Choreographer.FrameCallback` (Android). Frame > 16.67ms =
+   * slow; > 700ms = frozen.
+   */
+  getFrameCounters?: () => null | { frozen: number; slow: number }
+  /** Reset counters on navigation transition (called by useTraceNavigation). */
+  resetFrameCounters?: () => void
   /**
    * v0.7.3 — JS-triggered screenshot with consumer-supplied mask IDs.
    * `maskedIds` are RN `nativeID` strings; native walks the view
@@ -127,6 +150,43 @@ export function stopAnrWatchdog(): void {
   }
 }
 
+/** v0.9.4 #1 — finalize cold-start measurement. Idempotent. */
+export function markNativeJsBridgeReady(): void {
+  try {
+    native()?.markJsBridgeReady?.()
+  } catch {
+    // ignore
+  }
+}
+
+/** v0.9.4 #1 — read cold start ms once. null when native unavailable. */
+export function getNativeColdStartMs(): null | number {
+  try {
+    const v = native()?.getColdStartMs?.()
+    return typeof v === 'number' && Number.isFinite(v) ? v : null
+  } catch {
+    return null
+  }
+}
+
+/** v0.9.4 #1 — read slow/frozen frame counters since last reset. */
+export function getNativeFrameCounters(): null | { frozen: number; slow: number } {
+  try {
+    return native()?.getFrameCounters?.() ?? null
+  } catch {
+    return null
+  }
+}
+
+/** v0.9.4 #1 — reset frame counters on navigation transition. */
+export function resetNativeFrameCounters(): void {
+  try {
+    native()?.resetFrameCounters?.()
+  } catch {
+    // ignore
+  }
+}
+
 /**
  * v0.7.3 — drives the native screenshot path. JS side passes the
  * current list of mask `nativeID`s (read from the consumer's

package/src/navigation.ts

@@ -24,6 +24,10 @@ import { useEffect, useRef } from 'react';
 
 import { setActiveSpan, startSpan, type SpanHandle } from '@goliapkg/sentori-core';
 
+import {
+  getNativeFrameCounters,
+  resetNativeFrameCounters,
+} from './native';
 import { captureStep } from './trail';
 
 /** Minimal contract: anything with `addListener('state', cb)` and
@@ -101,11 +105,21 @@ export function useTraceNavigation(navigationRef: NavigationRefLike): void {
       const enteredAt = lastRouteEnteredAtRef.current;
       if (!span) return null;
       const dwellMs = enteredAt !== null ? Math.max(0, Date.now() - enteredAt) : null;
+      // v0.9.4 #1 — drain native frame counters at screen-leave.
+      // Empty/null when native module not linked; tags omitted.
+      const fc = getNativeFrameCounters();
+      const finishTags: Record<string, string> = {};
+      if (dwellMs !== null) finishTags['nav.dwell_ms'] = String(dwellMs);
+      if (fc) {
+        finishTags['vital.slow_frames'] = String(fc.slow);
+        finishTags['vital.frozen_frames'] = String(fc.frozen);
+      }
       span.finish({
         status: 'ok',
-        // Tag values are strings on the wire — cast at finish-time.
-        tags: dwellMs !== null ? { 'nav.dwell_ms': String(dwellMs) } : undefined,
+        tags: Object.keys(finishTags).length > 0 ? finishTags : undefined,
       });
+      // Reset counters for the next screen.
+      resetNativeFrameCounters();
       return dwellMs;
     };
 

package/src/netinfo.ts

@@ -16,6 +16,8 @@
 
 import type { Device } from '@goliapkg/sentori-core';
 
+import { isNativeModuleLinked } from './native-loader';
+
 type NetworkType = Device['networkType'];
 
 type NetInfoState = {
@@ -55,20 +57,11 @@ export function startNetworkTypeWatch(): void {
   if (_started) return;
   _started = true;
   try {
-    // v0.8.4 hotfix — when the host has `@react-native-community/netinfo`
-    // in package.json but the *native* module isn't linked (Expo Go,
-    // pod install never ran, RN autolink turned off, etc.) the JS
-    // package still imports fine but calling addEventListener throws
-    // "NativeModule.RNCNetInfo is null" from inside the lib's async
-    // emitter — past where this try/catch can reach. Gate on the
-    // NativeModules entry first so we no-op cleanly in that case.
-    // eslint-disable-next-line @typescript-eslint/no-require-imports
-    const RN = require('react-native') as {
-      NativeModules?: Record<string, unknown>;
-    };
-    const native = RN.NativeModules?.RNCNetInfo;
-    if (native == null) {
-      // JS package present but native module isn't linked. Skip.
+    // v0.8.4 hotfix → v0.8.5 generalised via isNativeModuleLinked.
+    // host may have the JS package via hoisted node_modules but
+    // never ran pod install / prebuild → calling addEventListener
+    // crashes deep inside the lib's emitter past try/catch reach.
+    if (!isNativeModuleLinked('RNCNetInfo')) {
       return;
     }
     // eslint-disable-next-line @typescript-eslint/no-require-imports

package/src/transport.ts

@@ -1,6 +1,7 @@
 import { drainSpans } from '@goliapkg/sentori-core';
 
 import { getConfig } from './config';
+import { isAnyNativeModuleLinked } from './native-loader';
 import type { Event } from './types';
 
 const FLUSH_INTERVAL_MS = 5_000;
@@ -166,6 +167,11 @@ type AsyncStorageLike = {
 };
 
 const getAsyncStorage = async (): Promise<AsyncStorageLike | null> => {
+  // v0.8.5 — host may have the JS package without pod install /
+  // prebuild → getItem crashes from a microtask outside our reach.
+  if (!isAnyNativeModuleLinked(['RNCAsyncStorage', 'AsyncStorageModule'])) {
+    return null;
+  }
   try {
     const mod = (await import(
       '@react-native-async-storage/async-storage'