@barrysolomon/mobile-react-native 0.1.0-alpha

package/react-native.config.js

@@ -0,0 +1,17 @@
+// Autolinking config for @dash0/mobile-react-native.
+// Consumed by `react-native config` during build of host apps.
+
+module.exports = {
+  dependency: {
+    platforms: {
+      ios: {
+        podspecPath: require('path').join(__dirname, 'Dash0Mobile.podspec'),
+      },
+      android: {
+        sourceDir: './android',
+        packageImportPath: 'import com.dash0.mobile.reactnative.Dash0MobilePackage;',
+        packageInstance: 'new Dash0MobilePackage()',
+      },
+    },
+  },
+};

package/src/NativeDash0Mobile.ts

@@ -0,0 +1,29 @@
+/**
+ * TurboModule codegen spec for @dash0/mobile-react-native.
+ *
+ * This file is intentionally NOT imported by `src/index.ts` — it exists
+ * solely to drive RN codegen (0.68+ / Fabric). The runtime code path goes
+ * through `require('react-native').NativeModules.Dash0Mobile` so we keep
+ * working on both old-arch and new-arch.
+ *
+ * Codegen constraints (from React Native docs):
+ *   - methods must return `Promise<T>` or `void`
+ *   - parameters must be primitives, `Object`, `Array`, or `{ readonly ... }`
+ *   - no union types as parameters (codegen rejects)
+ *
+ * The shapes below are deliberately looser than `bridge/types.ts` (Object
+ * instead of discriminated unions) because codegen can't narrow on `kind`.
+ * The native side runtime-dispatches on the `kind` string.
+ */
+
+import type { TurboModule } from 'react-native';
+import { TurboModuleRegistry } from 'react-native';
+
+export interface Spec extends TurboModule {
+  start(config: Object): Promise<void>;
+  emitBatch(payloads: Object[]): Promise<void>;
+  flushWindow(minutes: number): Promise<void>;
+  shutdown(): Promise<void>;
+}
+
+export default TurboModuleRegistry.getEnforcing<Spec>('Dash0Mobile');

package/src/bridge/NativeBridge.ts

@@ -0,0 +1,101 @@
+import type { BridgePayload, NativeDash0MobileModule } from './types';
+
+export const DEBOUNCE_MS = 50;
+export const MAX_QUEUE = 10_000;
+const RETRY_BASE_MS = 100;
+const RETRY_MAX_ATTEMPTS = 5;
+
+export class NativeBridge {
+  private readonly native: NativeDash0MobileModule;
+  private queue: BridgePayload[] = [];
+  private timer: ReturnType<typeof setTimeout> | null = null;
+  private inFlight: Promise<void> | null = null;
+
+  constructor(native: NativeDash0MobileModule) {
+    this.native = native;
+  }
+
+  emit(payload: BridgePayload): void {
+    this.queue.push(payload);
+    if (this.queue.length > MAX_QUEUE) {
+      this.queue.splice(0, this.queue.length - MAX_QUEUE);
+    }
+    if (this.timer === null) {
+      this.timer = setTimeout(() => {
+        this.timer = null;
+        void this.drain();
+      }, DEBOUNCE_MS);
+    }
+  }
+
+  /**
+   * Synchronous fast-path for FATAL-severity payloads. Cancels any pending
+   * debounce, drains the queue + the new payload in a single
+   * `native.emitBatch` call made SYNCHRONOUSLY on the current stack frame.
+   *
+   * Why not just `emit(); flush()`? Because `flush()` is `async`, and its
+   * `await this.drain()` places the call to `native.emitBatch` on the
+   * microtask queue. On a crash path (JS throw → ErrorUtils global handler
+   * → previous(error, isFatal) → RN fatal reporter → process exit) the
+   * handler's synchronous continuation wins the race against the
+   * microtask — the payload never crosses the bridge.
+   *
+   * This method is intentionally fire-and-forget: per the RN bridge
+   * contract, argument marshaling is synchronous, so the payload arrives
+   * on the native side by the time `native.emitBatch(...)` returns. The
+   * Promise resolution (native-side completion signal) is async and we
+   * don't await it — we only need the payload to cross the bridge before
+   * the process dies. `.catch(() => {})` prevents unhandledRejection
+   * warnings if the native side fails.
+   *
+   * See docs/superpowers/specs/2026-04-22-rn-fatal-bridge-bypass-design.md.
+   */
+  emitSync(payload: BridgePayload): void {
+    if (this.timer !== null) {
+      clearTimeout(this.timer);
+      this.timer = null;
+    }
+    const batch = this.queue.length > 0 ? [...this.queue, payload] : [payload];
+    this.queue = [];
+    this.native.emitBatch(batch).catch(() => {
+      // Swallow — on the crash path, the process is dying anyway and
+      // there's no caller alive to observe the error. On non-crash paths
+      // (if any caller uses emitSync for non-FATAL severity) the payload
+      // is lost on failure, which matches the implicit "best-effort"
+      // contract of the RN bridge under adverse conditions.
+    });
+  }
+
+  async flush(): Promise<void> {
+    if (this.timer !== null) {
+      clearTimeout(this.timer);
+      this.timer = null;
+    }
+    await this.drain();
+  }
+
+  private async drain(): Promise<void> {
+    if (this.queue.length === 0) return;
+    const batch = this.queue;
+    this.queue = [];
+    this.inFlight = this.sendWithRetry(batch);
+    try {
+      await this.inFlight;
+    } finally {
+      this.inFlight = null;
+    }
+  }
+
+  private async sendWithRetry(batch: BridgePayload[]): Promise<void> {
+    for (let attempt = 0; attempt < RETRY_MAX_ATTEMPTS; attempt++) {
+      try {
+        await this.native.emitBatch(batch);
+        return;
+      } catch {
+        if (attempt === RETRY_MAX_ATTEMPTS - 1) return;
+        const delay = RETRY_BASE_MS * Math.pow(2, attempt);
+        await new Promise<void>(resolve => setTimeout(resolve, delay));
+      }
+    }
+  }
+}

package/src/bridge/types.ts

@@ -0,0 +1,188 @@
+/**
+ * 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  // TRACE
+  | 5  // DEBUG
+  | 9  // INFO
+  | 13 // WARN
+  | 17 // ERROR
+  | 21; // FATAL
+
+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; // string to preserve precision across bridge
+}
+
+export interface SpanStartPayload {
+  kind: 'spanStart';
+  spanId: string;        // JS-generated; native echoes back to correlate
+  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>;
+}