@barrysolomon/mobile-react-native 0.1.0-alpha

package/lib/src/bridge/types.d.ts

@@ -0,0 +1,166 @@
+/**
+ * Bridge payload contract between the JS layer and the native modules.
+ *
+ * This is the stable seam. Any change here is a cross-repo breaking change
+ * (JS package + Android module + iOS module must all move together).
+ *
+ * Values crossing the RN bridge must be JSON-serializable primitives.
+ * No Date, no Map, no Symbol, no functions.
+ */
+export type SeverityNumber = 1 | 5 | 9 | 13 | 17 | 21;
+export type SpanKind = 'INTERNAL' | 'CLIENT' | 'SERVER' | 'PRODUCER' | 'CONSUMER';
+export type SpanStatus = 'UNSET' | 'OK' | 'ERROR';
+export type AttrValue = string | number | boolean | null;
+export type Attributes = Record<string, AttrValue>;
+/**
+ * Per-trigger flags for the native screenshot module. Field names and
+ * defaults mirror Android's `ScreenshotConfig` and iOS's `ScreenshotConfig`
+ * one-to-one. All fields optional; absent fields fall through to native
+ * defaults.
+ */
+export interface ScreenshotAutoCapture {
+    /** Master on/off. Required when passing an object form. Default `true` when present. */
+    enabled?: boolean;
+    /** Capture on every screen transition. Default `false` (high payload volume). */
+    captureOnScreenView?: boolean;
+    /** Capture when an uncaught exception occurs. Default `true`. */
+    captureOnError?: boolean;
+    /** Capture whenever a buffered-export policy fires (crash-recovery, ui-freeze, http-error). Default `true`. */
+    captureOnPolicyMatch?: boolean;
+}
+/**
+ * Per-trigger flags for the native wireframe module. Field names and
+ * defaults mirror Android's `WireframeConfig` and iOS's `WireframeConfig`
+ * one-to-one. All fields optional; absent fields fall through to native
+ * defaults.
+ */
+export interface WireframeAutoCapture {
+    /** Master on/off. Required when passing an object form. Default `true` when present. */
+    enabled?: boolean;
+    /** Capture on every screen transition. Default `true` (primary journey trigger). */
+    captureOnScreenView?: boolean;
+    /** Capture on every tap. Default `false` — taps rarely change the view hierarchy; dedup absorbs the case anyway. */
+    captureOnTap?: boolean;
+    /** Capture when an uncaught exception occurs. Default `true`. */
+    captureOnError?: boolean;
+    /** Capture whenever a buffered-export policy fires. Default `true`. */
+    captureOnPolicyMatch?: boolean;
+    /** Emit `ui.wireframe.ref` with `mobile.wireframe.id` instead of the full JSON when content matches the last capture. Default `true`. */
+    dedupeByContentHash?: boolean;
+}
+export interface StartConfig {
+    serviceName: string;
+    serviceVersion?: string;
+    endpoint: string;
+    authToken?: string;
+    dataset?: string;
+    bufferConfig?: {
+        ramEvents?: number;
+        diskBytes?: number;
+    };
+    enablePolicyPolling?: boolean;
+    /**
+     * Toggles for JS-side auto-instrumentation (fetch/XHR spans, JS error +
+     * unhandled rejection logs). Defaults to all-on. RN bridge uses the same
+     * flags to decide which native iOS/Android auto-capture suites to enable
+     * via `nativeAutoCapture`, so e.g. `autoCapture: { network: true }`
+     * enables the iOS `URLProtocol` swizzle in addition to the JS fetch/XHR
+     * wrappers. The default is OFF on the native side for `network`/`errors`
+     * — RN host apps typically don't want the native iOS URLProtocol swizzle
+     * or NSException handlers because they collide with RN's new-arch JS
+     * event loop (touch responder goes dormant).
+     *
+     * Lifecycle (`app.foreground` / `app.background` / `app.start`) is
+     * always-on via native instrumentation (Android ProcessLifecycleOwner,
+     * iOS NotificationCenter); there is no JS or per-flag knob for it.
+     */
+    autoCapture?: {
+        network?: boolean;
+        errors?: boolean;
+        /** Native iOS/Android-only capability — captures UI taps via swizzle/recognizer. Off by default on RN. */
+        tap?: boolean;
+        /** Native-only — scroll spans. Off by default on RN. */
+        scroll?: boolean;
+        /** Native-only — text input spans. Off by default on RN. */
+        textInput?: boolean;
+        /** Native-only — SwiftUI/Fragment screen tracking. Off by default on RN (use react-navigation helper instead). */
+        screen?: boolean;
+        /** Native-only — main-thread freeze detection. Off by default on RN. */
+        freeze?: boolean;
+        /** Native-only — app.start + jank + memory gauges. Off by default on RN. */
+        vitals?: boolean;
+        /** Native-only — periodic device health gauges (battery/thermal/network). Off by default on RN. */
+        deviceStats?: boolean;
+        /**
+         * Native-only — screenshot capture at journey boundaries + errors. Off
+         * by default on RN. Accepts either a bare boolean (`true` enables with
+         * native defaults) or an options object exposing the per-trigger flags
+         * mirrored from Android's `ScreenshotConfig` and iOS's `ScreenshotConfig`.
+         *
+         * NOTE: the per-trigger fields are forward-compatible. Today's bridge
+         * carries only the `enabled` bit through to native. Passing an object
+         * is equivalent to passing `true` until the bridge grows per-module
+         * options in a follow-up. Set the trigger flags natively (Android: in
+         * `MobileConfig.screenshotConfig`, iOS: in `MobileConfig`'s
+         * `screenshotConfig` param) until then.
+         */
+        screenshot?: boolean | ScreenshotAutoCapture;
+        /**
+         * Native-only — wireframe capture at screen transitions, optional taps,
+         * errors, and policy matches. Same shape rules as `screenshot` above.
+         */
+        wireframe?: boolean | WireframeAutoCapture;
+    };
+    /**
+     * Extra resource attributes merged into the native SDK's resource. Used by
+     * the RN bridge to inject `telemetry.distro.name` / `telemetry.distro.version`
+     * so Dash0 knows the telemetry came through the React Native distribution
+     * rather than direct Kotlin/Swift SDK usage. Caller-overridable for apps
+     * that want to add their own build/deployment tags.
+     */
+    extraResourceAttributes?: Record<string, string>;
+}
+export interface LogPayload {
+    kind: 'log';
+    name: string;
+    severity: SeverityNumber;
+    attributes: Attributes;
+    timeUnixNano: string;
+}
+export interface SpanStartPayload {
+    kind: 'spanStart';
+    spanId: string;
+    parentSpanId?: string;
+    name: string;
+    spanKind: SpanKind;
+    attributes: Attributes;
+    startTimeUnixNano: string;
+}
+export interface SpanEndPayload {
+    kind: 'spanEnd';
+    spanId: string;
+    status: SpanStatus;
+    statusMessage?: string;
+    attributes: Attributes;
+    endTimeUnixNano: string;
+}
+export interface MetricPayload {
+    kind: 'metric';
+    name: string;
+    instrumentType: 'counter' | 'histogram' | 'gauge';
+    value: number;
+    attributes: Attributes;
+    timeUnixNano: string;
+}
+export type BridgePayload = LogPayload | SpanStartPayload | SpanEndPayload | MetricPayload;
+export interface NativeDash0MobileModule {
+    start(config: StartConfig): Promise<void>;
+    emitBatch(payloads: BridgePayload[]): Promise<void>;
+    flushWindow(minutes: number): Promise<void>;
+    shutdown(): Promise<void>;
+    startJourney(name: string): Promise<string>;
+    endJourney(journeyId: string): Promise<void>;
+    captureScreenshot(trigger: string): Promise<void>;
+    captureWireframe(trigger: string): Promise<void>;
+}
+//# sourceMappingURL=types.d.ts.map

package/lib/src/bridge/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/bridge/types.ts"],"names":[],"mappings":"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"}

package/lib/src/bridge/types.js

@@ -0,0 +1,10 @@
+/**
+ * Bridge payload contract between the JS layer and the native modules.
+ *
+ * This is the stable seam. Any change here is a cross-repo breaking change
+ * (JS package + Android module + iOS module must all move together).
+ *
+ * Values crossing the RN bridge must be JSON-serializable primitives.
+ * No Date, no Map, no Symbol, no functions.
+ */
+export {};

package/lib/src/index.d.ts

@@ -0,0 +1,35 @@
+/**
+ * @dash0/mobile-react-native — public API
+ *
+ * Thin JS facade. All buffering, policy, OTLP export, crash recovery happen
+ * in the native modules. This file only marshals calls onto a NativeBridge.
+ *
+ * See docs/epics/REACT_NATIVE_EPIC.md.
+ */
+import type { Attributes, NativeDash0MobileModule, SeverityNumber, SpanKind, StartConfig } from './bridge/types';
+export type { Attributes, SeverityNumber, StartConfig } from './bridge/types';
+export { installReactNavigationInstrumentation } from './instrumentation/navigation';
+export { withTapTelemetry } from './instrumentation/touch';
+export { otel } from './otel-compat';
+export interface SpanHandle {
+    setAttribute(key: string, value: string | number | boolean): void;
+    setStatus(status: 'OK' | 'ERROR', message?: string): void;
+    end(): void;
+}
+export declare function __resetTimestampAnchorForTests__(): void;
+export declare const Dash0Mobile: {
+    start(config: StartConfig): Promise<void>;
+    log(name: string, attributes?: Attributes, severity?: SeverityNumber): void;
+    startSpan(name: string, attributes?: Attributes, spanKind?: SpanKind): SpanHandle;
+    span<T>(name: string, fn: (handle: SpanHandle) => Promise<T> | T, attributes?: Attributes): Promise<T>;
+    recordMetric(name: string, value: number, instrumentType?: "counter" | "histogram" | "gauge", attributes?: Attributes): void;
+    flushWindow(minutes: number): Promise<void>;
+    startJourney(name: string): Promise<string | null>;
+    endJourney(journeyId: string): Promise<void>;
+    captureScreenshot(trigger?: string): Promise<void>;
+    captureWireframe(trigger?: string): Promise<void>;
+    shutdown(): Promise<void>;
+};
+export declare function __setNativeForTesting(native: NativeDash0MobileModule | null): void;
+export declare function __resetForTesting(): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/src/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAOH,OAAO,KAAK,EACV,UAAU,EAEV,uBAAuB,EACvB,cAAc,EACd,QAAQ,EAER,WAAW,EACZ,MAAM,gBAAgB,CAAC;AAExB,YAAY,EAAE,UAAU,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC9E,OAAO,EAAE,qCAAqC,EAAE,MAAM,8BAA8B,CAAC;AACrF,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAC3D,OAAO,EAAE,IAAI,EAAE,MAAM,eAAe,CAAC;AAErC,MAAM,WAAW,UAAU;IACzB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,CAAC;IAClE,SAAS,CAAC,MAAM,EAAE,IAAI,GAAG,OAAO,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1D,GAAG,IAAI,IAAI,CAAC;CACb;AA8ED,wBAAgB,gCAAgC,IAAI,IAAI,CAGvD;AAyCD,eAAO,MAAM,WAAW;kBACF,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;cA6DrC,MAAM,eAAc,UAAU,aAAiB,cAAc,GAAO,IAAI;oBAwBlE,MAAM,eAAc,UAAU,aAAiB,QAAQ,GAAgB,UAAU;SAsDtF,CAAC,QACJ,MAAM,MACR,CAAC,MAAM,EAAE,UAAU,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,eAC7B,UAAU,GACtB,OAAO,CAAC,CAAC,CAAC;uBAeL,MAAM,SACL,MAAM,mBACG,SAAS,GAAG,WAAW,GAAG,OAAO,eACrC,UAAU,GACrB,IAAI;yBAYoB,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;uBAYxB,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;0BAO5B,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;gCAOjB,MAAM,GAAc,OAAO,CAAC,IAAI,CAAC;+BAOlC,MAAM,GAAc,OAAO,CAAC,IAAI,CAAC;gBAO/C,OAAO,CAAC,IAAI,CAAC;CAgBhC,CAAC;AA4DF,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,uBAAuB,GAAG,IAAI,GAAG,IAAI,CAElF;AAED,wBAAgB,iBAAiB,IAAI,IAAI,CAKxC"}

package/lib/src/index.js

@@ -0,0 +1,408 @@
+/**
+ * @dash0/mobile-react-native — public API
+ *
+ * Thin JS facade. All buffering, policy, OTLP export, crash recovery happen
+ * in the native modules. This file only marshals calls onto a NativeBridge.
+ *
+ * See docs/epics/REACT_NATIVE_EPIC.md.
+ */
+import { NativeBridge } from './bridge/NativeBridge';
+import { installFetchInstrumentation } from './instrumentation/fetch';
+import { installXhrInstrumentation } from './instrumentation/xhr';
+import { installErrorInstrumentation } from './instrumentation/errors';
+import { installUnhandledRejectionInstrumentation } from './instrumentation/unhandledRejection';
+export { installReactNavigationInstrumentation } from './instrumentation/navigation';
+export { withTapTelemetry } from './instrumentation/touch';
+export { otel } from './otel-compat';
+let injectedNative = null;
+let bridge = null;
+let started = false;
+let autoInstrUninstallers = [];
+// Ambient parent-span stack. Each `startSpan` pushes the new spanId; each
+// `.end()` pops. Children emitted while an outer span is live pick up the
+// top of the stack as their `parentSpanId`, so Dash0 renders proper
+// waterfalls without callers threading parent handles manually.
+//
+// Limitation: a single global stack is only correct for strictly-nested
+// (LIFO) span work — sufficient for `Dash0Mobile.span('x', async () => { ... })`
+// and sequential `startSpan/.end()` pairs. Concurrent async span trees would
+// need AsyncLocalStorage / Hermes async-hooks; RN doesn't expose those
+// cleanly, so we accept the limitation and document it on the public API.
+const spanStack = [];
+/// Anchor pair used by `nowUnixNano` to combine an absolute-epoch
+/// base (from `Date.now()`) with a sub-ms monotonic delta (from
+/// `performance.now()`). Initialized lazily on the first timestamp
+/// request so we don't pay the cost for consumers who never emit.
+///
+/// Why the anchor pattern: `performance.now()` gives sub-ms precision
+/// but returns time-since-an-arbitrary-origin, not wall-clock epoch.
+/// `Date.now()` gives wall-clock but only ms resolution. Capturing
+/// both once, then deriving each timestamp as `epochAnchor + perfDelta`
+/// yields sub-ms wall-clock nanoseconds without per-call drift.
+let _epochAnchorMs = null;
+let _perfAnchorMs = null;
+function perfNow() {
+    // RN 0.85 new-arch ships `global.performance.now` via JSI. Older
+    // runtimes (Hermes < 0.12, some test harnesses) may not. Fall back
+    // gracefully — callers still get correct ms-resolution nanoseconds
+    // in that case, just not the sub-ms fidelity.
+    const g = globalThis;
+    if (typeof g.performance?.now === 'function') {
+        return g.performance.now();
+    }
+    return Date.now();
+}
+function nowUnixNano() {
+    // Initialize anchor lazily. The offset between the two reads is at
+    // most one JS tick — negligible for observability purposes.
+    if (_epochAnchorMs === null || _perfAnchorMs === null) {
+        _epochAnchorMs = Date.now();
+        _perfAnchorMs = perfNow();
+    }
+    const elapsedMs = perfNow() - _perfAnchorMs;
+    // Sub-ms fraction; convert to nanoseconds as an integer.
+    const extraNanos = Math.floor(elapsedMs * 1000000);
+    // BigInt is required for correctness. Unix nanoseconds in 2026
+    // are ~1.77e18, well past JS `Number.MAX_SAFE_INTEGER` (2^53 ≈
+    // 9.01e15). The previous `Date.now() * 1_000_000` implementation
+    // lost precision on every call (rounding to ~128-nanosecond bands),
+    // which collapsed nested child spans' start+end timestamps to
+    // identical values and surfaced as `duration=0ms` in Dash0.
+    const totalNanos = BigInt(_epochAnchorMs) * 1000000n + BigInt(extraNanos);
+    return totalNanos.toString();
+}
+/// Test-only: reset the anchors so each test case starts fresh.
+/// Not exported from the public entry point — accessed in Jest via
+/// the internal require path.
+export function __resetTimestampAnchorForTests__() {
+    _epochAnchorMs = null;
+    _perfAnchorMs = null;
+}
+function randomSpanId() {
+    let id = '';
+    for (let i = 0; i < 16; i++) {
+        id += Math.floor(Math.random() * 16).toString(16);
+    }
+    return id;
+}
+function resolveNative() {
+    if (injectedNative)
+        return injectedNative;
+    // Production path: lazily require react-native to avoid pulling it into
+    // tests that stub at the unit level. If RN isn't present we return null
+    // and pre-start calls become no-ops.
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-var-requires
+        const rn = require('react-native');
+        return rn?.NativeModules?.Dash0Mobile ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+// Version of this RN bridge package. Sent as `telemetry.distro.version` so
+// Dash0 can distinguish RN-originated telemetry from direct native SDK
+// callers and correlate issues to a specific bridge release. Keep this in
+// sync with package.json on each release.
+const DISTRO_NAME = 'dash0-react-native';
+const DISTRO_VERSION = '0.1.0-alpha';
+function resolveReactNativeVersion() {
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-var-requires
+        const rn = require('react-native/package.json');
+        return typeof rn?.version === 'string' ? rn.version : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export const Dash0Mobile = {
+    async start(config) {
+        const native = resolveNative();
+        if (!native) {
+            // No native module wired. Stay quiet — caller is likely in a non-RN
+            // environment (Jest, SSR) and shouldn't crash.
+            started = false;
+            return;
+        }
+        bridge = new NativeBridge(native);
+        // Inject RN distribution attributes as OTel-spec resource attributes.
+        // Caller-provided extras win (lets apps override for testing/tagging).
+        const rnVersion = resolveReactNativeVersion();
+        // Translate the `autoCapture` flags into a native-capability token list the
+        // bridge (iOS/Android) can use to build `AutoCaptureOptions`. Native
+        // default is OFF for everything — callers must explicitly set a flag to
+        // `true` to enable the native suite on that capability. This avoids the
+        // iOS URLProtocol / NSException / signal-handler swizzles by default,
+        // which collide with RN's new-arch JS event loop.
+        const nativeAutoCapture = buildNativeAutoCaptureTokens(config.autoCapture);
+        const mergedConfig = {
+            ...config,
+            extraResourceAttributes: {
+                'telemetry.distro.name': DISTRO_NAME,
+                'telemetry.distro.version': DISTRO_VERSION,
+                ...(rnVersion ? { 'app.framework': 'react-native', 'app.framework.version': rnVersion } : {}),
+                ...(config.extraResourceAttributes ?? {}),
+            },
+            nativeAutoCapture,
+        };
+        await native.start(mergedConfig);
+        started = true;
+        const auto = config.autoCapture ?? {};
+        if (auto.network !== false) {
+            const collectorHost = hostFromEndpoint(config.endpoint);
+            const ignoredHosts = collectorHost ? [collectorHost] : [];
+            // On React Native, `fetch` is implemented on top of XHR, so every
+            // fetch() call also fires the XHR instrumentation — installing both
+            // produces two spans per request. XHR is the authoritative layer
+            // because it also captures direct XHR callers (axios, Apollo HTTP
+            // link, legacy code) that don't go through fetch. In non-RN JS
+            // environments (future web/SSR use) fetch is native and independent
+            // of XHR, so both shims are needed.
+            if (!isReactNative()) {
+                autoInstrUninstallers.push(installFetchInstrumentation({ ignoredHosts }));
+            }
+            autoInstrUninstallers.push(installXhrInstrumentation({ ignoredHosts }));
+        }
+        if (auto.errors !== false) {
+            autoInstrUninstallers.push(installErrorInstrumentation());
+            autoInstrUninstallers.push(installUnhandledRejectionInstrumentation());
+        }
+        // Lifecycle (`app.foreground` / `app.background` / `app.start`) is now
+        // emitted by native instrumentation on both platforms — Android via
+        // ProcessLifecycleOwner, iOS via NotificationCenter with applicationState
+        // late-init synthesis. The previous JS-side AppState shim was deleted
+        // because RN 0.85 new-arch made it unreliable (TurboModule init race).
+    },
+    log(name, attributes = {}, severity = 9) {
+        if (!started || !bridge)
+            return;
+        const payload = {
+            kind: 'log',
+            name,
+            severity,
+            attributes,
+            timeUnixNano: nowUnixNano(),
+        };
+        // FATAL-severity logs bypass the 50ms debounce via `emitSync`, which
+        // calls `native.emitBatch` without any `await`. The payload crosses
+        // the RN bridge in the current stack frame — critical on crash paths
+        // because any microtask boundary (including the `await` inside
+        // `flush()`) loses the race against the handler's continuation into
+        // RN's fatal reporter. Once the payload is on the native side, the
+        // iOS SDK's willTerminate auto-forceFlush (commit 1a69c7e) persists
+        // it to disk and attempts OTLP export before process exit.
+        if (severity >= 21) {
+            bridge.emitSync(payload);
+        }
+        else {
+            bridge.emit(payload);
+        }
+    },
+    startSpan(name, attributes = {}, spanKind = 'INTERNAL') {
+        const spanId = randomSpanId();
+        const parentSpanId = spanStack.length > 0 ? spanStack[spanStack.length - 1] : undefined;
+        const startPayload = {
+            kind: 'spanStart',
+            spanId,
+            parentSpanId,
+            name,
+            spanKind,
+            attributes: { ...attributes },
+            startTimeUnixNano: nowUnixNano(),
+        };
+        const active = {
+            payload: startPayload,
+            attrs: {},
+            status: 'UNSET',
+            ended: false,
+        };
+        spanStack.push(spanId);
+        if (started && bridge) {
+            bridge.emit(startPayload);
+        }
+        return {
+            setAttribute(key, value) {
+                active.attrs[key] = value;
+            },
+            setStatus(status, message) {
+                active.status = status;
+                active.statusMessage = message;
+            },
+            end() {
+                if (active.ended)
+                    return;
+                active.ended = true;
+                // Pop this spanId off the stack. Tolerate out-of-order ends by
+                // scanning from the top — the common case is LIFO, but mis-ordered
+                // ends (e.g. a long-lived outer span that ends after an inner
+                // one that was itself popped correctly) shouldn't corrupt the stack.
+                const idx = spanStack.lastIndexOf(spanId);
+                if (idx >= 0)
+                    spanStack.splice(idx, 1);
+                if (!started || !bridge)
+                    return;
+                bridge.emit({
+                    kind: 'spanEnd',
+                    spanId,
+                    status: active.status === 'UNSET' ? 'OK' : active.status,
+                    statusMessage: active.statusMessage,
+                    attributes: active.attrs,
+                    endTimeUnixNano: nowUnixNano(),
+                });
+            },
+        };
+    },
+    async span(name, fn, attributes) {
+        const handle = this.startSpan(name, attributes);
+        try {
+            const result = await fn(handle);
+            handle.setStatus('OK');
+            return result;
+        }
+        catch (err) {
+            handle.setStatus('ERROR', err instanceof Error ? err.message : String(err));
+            throw err;
+        }
+        finally {
+            handle.end();
+        }
+    },
+    recordMetric(name, value, instrumentType = 'counter', attributes = {}) {
+        if (!started || !bridge)
+            return;
+        bridge.emit({
+            kind: 'metric',
+            name,
+            instrumentType,
+            value,
+            attributes,
+            timeUnixNano: nowUnixNano(),
+        });
+    },
+    async flushWindow(minutes) {
+        if (!started || !bridge)
+            return;
+        await bridge.flush();
+        const native = resolveNative();
+        if (native)
+            await native.flushWindow(minutes);
+    },
+    // ─── User Journey API (UJ-020) ──────────────────────────────────────────
+    // Thin passthrough to native `OTelMobile.startJourney/endJourney`. The
+    // native side creates the journey span and triggers screenshot + wireframe
+    // captures at start/end boundaries.
+    async startJourney(name) {
+        if (!started)
+            return null;
+        const native = resolveNative();
+        if (!native)
+            return null;
+        return native.startJourney(name);
+    },
+    async endJourney(journeyId) {
+        if (!started)
+            return;
+        const native = resolveNative();
+        if (!native)
+            return;
+        await native.endJourney(journeyId);
+    },
+    async captureScreenshot(trigger = 'manual') {
+        if (!started)
+            return;
+        const native = resolveNative();
+        if (!native)
+            return;
+        await native.captureScreenshot(trigger);
+    },
+    async captureWireframe(trigger = 'manual') {
+        if (!started)
+            return;
+        const native = resolveNative();
+        if (!native)
+            return;
+        await native.captureWireframe(trigger);
+    },
+    async shutdown() {
+        for (const uninstall of autoInstrUninstallers) {
+            try {
+                uninstall();
+            }
+            catch {
+                // Swallow — shutdown should never throw.
+            }
+        }
+        autoInstrUninstallers = [];
+        if (!bridge)
+            return;
+        await bridge.flush();
+        const native = resolveNative();
+        if (native)
+            await native.shutdown();
+        started = false;
+        bridge = null;
+    },
+};
+const ENDPOINT_HOST_RE = /^[a-z][a-z0-9+.-]*:\/\/([^/:?#]+)/i;
+function hostFromEndpoint(endpoint) {
+    const match = ENDPOINT_HOST_RE.exec(endpoint);
+    return match ? match[1].toLowerCase() : null;
+}
+// React Native sets `navigator.product === 'ReactNative'` — the standard
+// public signal for code that wants to differ by JS environment. This is
+// the same check used by Sentry, Datadog, and RN itself internally. Jest
+// / Node / SSR won't match, so test and non-RN environments still
+// exercise both network shims.
+function isReactNative() {
+    const nav = globalThis.navigator;
+    return nav?.product === 'ReactNative';
+}
+const NATIVE_AUTO_CAPTURE_FLAGS = [
+    ['network', 'network'],
+    ['errors', 'errors'],
+    ['tap', 'tap'],
+    ['scroll', 'scroll'],
+    ['textInput', 'textInput'],
+    ['screen', 'screen'],
+    ['freeze', 'freeze'],
+    ['vitals', 'vitals'],
+    ['deviceStats', 'deviceStats'],
+    ['screenshot', 'screenshot'],
+    ['wireframe', 'wireframe'],
+];
+function buildNativeAutoCaptureTokens(ac) {
+    if (!ac)
+        return [];
+    const out = [];
+    for (const [flag, token] of NATIVE_AUTO_CAPTURE_FLAGS) {
+        const value = ac[flag];
+        // Object form (screenshot / wireframe per-trigger): treat as enabled
+        // unless `enabled` is explicitly `false`. The bridge protocol carries
+        // only this on/off bit today — per-trigger fields are forward-compatible
+        // and currently must be configured natively. See ScreenshotAutoCapture /
+        // WireframeAutoCapture doc comments in bridge/types.ts.
+        if (value === true) {
+            out.push(token);
+        }
+        else if (typeof value === 'object' && value !== null) {
+            const enabled = value.enabled;
+            if (enabled !== false)
+                out.push(token);
+        }
+    }
+    return out;
+}
+// ─── test hooks ──────────────────────────────────────────────────────────────
+// These are intentionally exported but prefixed __ to signal "not for app use."
+// Native-module tests inject a mock here; a CI lint rule should ban callers
+// outside __tests__/ from importing them.
+export function __setNativeForTesting(native) {
+    injectedNative = native;
+}
+export function __resetForTesting() {
+    injectedNative = null;
+    bridge = null;
+    started = false;
+    spanStack.length = 0;
+}

package/lib/src/instrumentation/errors.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Error auto-instrumentation for React Native.
+ *
+ * Chains our handler into RN's `ErrorUtils.setGlobalHandler`, emits an
+ * `app.error` log with OTel `exception.*` semconv attributes, then delegates
+ * to the previous handler so Sentry/Bugsnag/redbox keep working.
+ *
+ * Deduplication: identical (type + message) errors inside a 5-minute window
+ * collapse to a single log, matching the Android ErrorInstrumentation
+ * policy (loops that throw on every frame shouldn't DoS the collector).
+ */
+export declare const DEDUPE_WINDOW_MS: number;
+export declare function installErrorInstrumentation(): () => void;
+//# sourceMappingURL=errors.d.ts.map

package/lib/src/instrumentation/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../../src/instrumentation/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH,eAAO,MAAM,gBAAgB,QAAgB,CAAC;AAsB9C,wBAAgB,2BAA2B,IAAI,MAAM,IAAI,CA+CxD"}