@obsrviq/react-native 0.3.1

package/ios/LumeraReplayModule.h

@@ -0,0 +1,20 @@
+#import <Foundation/Foundation.h>
+#import <React/RCTBridgeModule.h>
+
+NS_ASSUME_NONNULL_BEGIN
+
+/**
+ * The native screenshot-capture TurboModule, exposed to JS as "LumeraReplay".
+ *
+ * This thin ObjC++ shell exists only to satisfy React Native's codegen'd New-Arch
+ * protocol (NativeLumeraReplaySpec, generated from src/spec/NativeLumeraReplay.ts via
+ * the `LumeraReplaySpec` codegen target) and to forward each call to the shared Swift
+ * engine `LumeraReplay`, which owns the entire capture → mask → encode → upload loop.
+ *
+ * No capture logic lives here. The implementation (.mm) conforms to the generated
+ * <NativeLumeraReplaySpec> protocol and implements `getTurboModule:` for the New Arch.
+ */
+@interface LumeraReplayModule : NSObject <RCTBridgeModule>
+@end
+
+NS_ASSUME_NONNULL_END

package/ios/LumeraReplayModule.mm

@@ -0,0 +1,93 @@
+#import "LumeraReplayModule.h"
+
+// The Swift engine (LumeraReplay, @objc-exposed) is surfaced to ObjC++ through the
+// pod's auto-generated Swift umbrella header. CocoaPods names it
+// "<module_name>-Swift.h"; for this pod (`lumera-react-native`) Clang sanitizes that
+// to `lumera_react_native-Swift.h`. We tolerate either spelling so the bridge builds
+// whether the host app links us as a pod (umbrella under the pod name) or compiles the
+// sources into the app target (umbrella under the app's product module name).
+#if __has_include(<lumera_react_native/lumera_react_native-Swift.h>)
+#import <lumera_react_native/lumera_react_native-Swift.h>
+#elif __has_include("lumera_react_native-Swift.h")
+#import "lumera_react_native-Swift.h"
+#elif __has_include("LumeraReactNative-Swift.h")
+#import "LumeraReactNative-Swift.h"
+#else
+// Fallback: forward-declare the @objc surface we call so the bridge still compiles if
+// the umbrella header name differs in a given app. The linker resolves it from the
+// Swift object at link time.
+@interface LumeraReplay : NSObject
+@property (class, nonatomic, readonly, strong) LumeraReplay *shared;
+- (void)startWithOptions:(NSDictionary *)options;
+- (void)stopObjc;
+- (void)configureWithOptions:(NSDictionary *)options;
+- (void)setViewMasked:(NSNumber *)reactTag masked:(NSNumber *)masked;
+- (NSDictionary *)getDiagnosticsObjc;
+@end
+#endif
+
+// The codegen'd New-Arch spec header (target name `LumeraReplaySpec`, from
+// package.json → codegenConfig.name). Present only when codegen has run (i.e. inside a
+// real app build with the New Architecture). Guarded so this file also compiles on the
+// old architecture, where the RCT_EXPORT_METHOD declarations below carry the module.
+#ifdef RCT_NEW_ARCH_ENABLED
+#import <LumeraReplaySpec/LumeraReplaySpec.h>
+#endif
+
+@implementation LumeraReplayModule
+
+// Registers this as the TurboModule/NativeModule named "LumeraReplay" — the exact name
+// TurboModuleRegistry.getEnforcing<Spec>('LumeraReplay') resolves on the JS side.
+RCT_EXPORT_MODULE(LumeraReplay)
+
+// All forwarding is trivial (dispatch onto the engine, which owns its own threads); no
+// reason to hop onto a method queue.
++ (BOOL)requiresMainQueueSetup { return NO; }
+
+#pragma mark - Spec methods (forward to the shared Swift engine)
+
+// `start(options)` — object arg arrives as NSDictionary at the ObjC boundary.
+RCT_EXPORT_METHOD(start:(NSDictionary *)options)
+{
+  [LumeraReplay.shared startWithOptions:options];
+}
+
+// `stop()`
+RCT_EXPORT_METHOD(stop)
+{
+  [LumeraReplay.shared stopObjc];
+}
+
+// `configure(options)`
+RCT_EXPORT_METHOD(configure:(NSDictionary *)options)
+{
+  [LumeraReplay.shared configureWithOptions:options];
+}
+
+// `setViewMasked(reactTag, masked)` — numbers cross as `double`/`BOOL` on New Arch.
+RCT_EXPORT_METHOD(setViewMasked:(double)reactTag masked:(BOOL)masked)
+{
+  [LumeraReplay.shared setViewMasked:@(reactTag) masked:@(masked)];
+}
+
+// `getDiagnostics(): Promise<NativeDiagnostics>` — resolves with the counters snapshot.
+RCT_EXPORT_METHOD(getDiagnostics:(RCTPromiseResolveBlock)resolve
+                  reject:(RCTPromiseRejectBlock)reject)
+{
+  resolve([LumeraReplay.shared getDiagnosticsObjc]);
+}
+
+#pragma mark - New Architecture (TurboModule) wiring
+
+#ifdef RCT_NEW_ARCH_ENABLED
+// Hands the runtime the C++ JSI binding generated for our spec. `NativeLumeraReplaySpecJSI`
+// is emitted by codegen from src/spec/NativeLumeraReplay.ts (spec target `LumeraReplaySpec`)
+// and dispatches each JSI call to the RCT_EXPORT_METHOD implementations above.
+- (std::shared_ptr<facebook::react::TurboModule>)getTurboModule:
+    (const facebook::react::ObjCTurboModule::InitParams &)params
+{
+  return std::make_shared<facebook::react::NativeLumeraReplaySpecJSI>(params);
+}
+#endif
+
+@end

package/lumera-react-native.podspec

@@ -0,0 +1,19 @@
+require "json"
+
+package = JSON.parse(File.read(File.join(__dir__, "package.json")))
+
+Pod::Spec.new do |s|
+  s.name         = "lumera-react-native"
+  s.version      = package["version"]
+  s.summary      = package["description"]
+  s.homepage     = "https://lumera.app"
+  s.license      = "MIT"
+  s.authors      = "Lumera"
+  s.platforms    = { :ios => "13.4" }
+  s.source       = { :git => "https://github.com/TedoraTech/lumera.git", :tag => "#{s.version}" }
+
+  s.source_files = "ios/**/*.{h,m,mm,swift}"
+
+  # Pulls in React-Core, and (on New Arch) the codegen'd LumeraReplaySpec + RN-Core deps.
+  install_modules_dependencies(s)
+end

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@obsrviq/react-native",
+  "version": "0.3.1",
+  "publishConfig": {
+    "access": "public"
+  },
+  "description": "Lumera mobile capture SDK for React Native — privacy-first screenshot session replay + network/error/custom-event recording, engineered for zero added latency on device.",
+  "main": "src/index.ts",
+  "module": "src/index.ts",
+  "react-native": "src/index.ts",
+  "types": "src/index.ts",
+  "source": "src/index.ts",
+  "files": [
+    "src",
+    "ios",
+    "android",
+    "lumera-react-native.podspec",
+    "!**/__tests__"
+  ],
+  "dependencies": {
+    "@obsrviq/types": "0.4.0"
+  },
+  "peerDependencies": {
+    "react": "*",
+    "react-native": ">=0.76",
+    "@react-native-async-storage/async-storage": ">=1.21"
+  },
+  "devDependencies": {
+    "@react-native-async-storage/async-storage": "^2.1.0",
+    "@types/react": "^19.0.0",
+    "react": "^19.1.1",
+    "react-native": "0.82.0",
+    "typescript": "^5.7.2"
+  },
+  "codegenConfig": {
+    "name": "LumeraReplaySpec",
+    "type": "modules",
+    "jsSrcsDir": "src/spec",
+    "android": {
+      "javaPackageName": "app.lumera.replay"
+    }
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit"
+  }
+}

package/src/LumeraMask.tsx

@@ -0,0 +1,52 @@
+import React from 'react';
+import { Platform, View, type ViewProps, requireNativeComponent } from 'react-native';
+
+/**
+ * <LumeraMask> — privacy-by-region wrapper for the native screenshot replay.
+ *
+ * Wrap any subtree to control whether it is redacted in captured frames:
+ *
+ *   <LumeraMask>            …</LumeraMask>   // force-mask this subtree
+ *   <LumeraMask unmask>     …</LumeraMask>   // force-UNMASK (overrides maskAllText/Images)
+ *
+ * Under the hood the native view (un)registers its reactTag with the capture engine via
+ * `setViewMasked(reactTag, …)`. Masking is composited natively, off the UI thread, during
+ * capture — this component renders its children verbatim and adds no per-frame cost.
+ *
+ * The native view exists on iOS (and Android, task #96). On unsupported platforms /
+ * unlinked builds (e.g. Expo Go) it degrades to a plain <View> so layout is unaffected.
+ */
+export interface LumeraMaskProps extends ViewProps {
+  /** Force-unmask this subtree (overrides the global maskAllText/maskAllImages defaults). */
+  unmask?: boolean;
+  children?: React.ReactNode;
+}
+
+interface NativeMaskProps extends ViewProps {
+  masked: boolean;
+  children?: React.ReactNode;
+}
+
+// Resolve the native component lazily + defensively: if the native module isn't linked
+// the require throws, and we fall back to a plain View (capture simply won't mask here).
+const NativeLumeraMask: React.ComponentType<NativeMaskProps> | null = (() => {
+  if (Platform.OS !== 'ios' && Platform.OS !== 'android') return null;
+  try {
+    return requireNativeComponent<NativeMaskProps>('LumeraMaskView');
+  } catch {
+    return null;
+  }
+})();
+
+export function LumeraMask({ unmask, children, ...rest }: LumeraMaskProps): React.ReactElement {
+  if (!NativeLumeraMask) {
+    return <View {...rest}>{children}</View>;
+  }
+  return (
+    <NativeLumeraMask masked={!unmask} {...rest}>
+      {children}
+    </NativeLumeraMask>
+  );
+}
+
+export default LumeraMask;

package/src/config.ts

@@ -0,0 +1,96 @@
+import type { IngestBatch } from '@obsrviq/types';
+
+/**
+ * Public init config for the Lumera React Native SDK. Mirrors the web tracker's
+ * `ObsrviqInitConfig` where it makes sense, swapping DOM-specific privacy knobs for
+ * the native screenshot-replay knobs (fps / jpegQuality / maskAll*).
+ */
+export interface LumeraConfig {
+  /** REQUIRED — your ingest key (pk_…). */
+  siteKey: string;
+
+  // ── Identity (optional; can also be set later via identify()/setMetadata()) ──
+  userId?: string;
+  metadata?: Record<string, unknown>;
+
+  // ── Screenshot replay capture (native) ──
+  /** Record the screen (native screenshot stream). Default true. */
+  enableReplay?: boolean;
+  /** Capture cadence cap, frames/sec. Change-driven underneath. Default 1. */
+  fps?: number;
+  /** JPEG quality 0..1 on the encode path. Default 0.4 (~good/small, à la PostHog 0.3). */
+  jpegQuality?: number;
+  /** Cap the longer edge of each frame to this many px (downscaled on device before
+   *  encode). THE storage/bandwidth lever: full native res (~1080×2400) is ~4× bigger
+   *  for no replay gain. Default 1200 (≈ half res, ~25KB/frame). 0 = full native res. */
+  maxCaptureDim?: number;
+  /** Privacy-by-default: mask all text. Default true. */
+  maskAllText?: boolean;
+  /** Mask all images/media. Default true. */
+  maskAllImages?: boolean;
+  /** Capture taps + swipes as a touch overlay on the replay (native, non-blocking
+   *  gesture observer — does not interfere with the app's own gestures). Default true. */
+  captureTouches?: boolean;
+
+  // ── Network capture (pure JS: fetch + XHR) ──
+  /** Capture request/response bodies (masked, size-capped). Default false. */
+  captureNetworkBodies?: boolean;
+  /** Header allowlist redaction. Default ['authorization','cookie','set-cookie']. */
+  redactHeaders?: string[];
+
+  // ── Console + error capture (pure JS) ──
+  /** Mirror console.* into the session. Default true. */
+  captureConsole?: boolean;
+
+  // ── Sampling / lifecycle ──
+  /** 0..1 — fraction of sessions recorded. Default 1. */
+  sampleRate?: number;
+  /** Resume the same session across app foreground/background within the window. Default false. */
+  continueSession?: boolean;
+  /** Inactivity window for continueSession, ms. Default 30 min. */
+  sessionTimeoutMs?: number;
+
+  // ── Transport ──
+  /** Ingest base URL. Default 'https://in.lumera.app'. */
+  endpoint?: string;
+  /** Flush cadence for the structured-event stream, ms. Default 5000. */
+  flushIntervalMs?: number;
+
+  // ── Consent ──
+  /** Gate all recording until setConsent(true). Default false. */
+  requireConsent?: boolean;
+
+  // ── Hooks ──
+  /** Inspect/drop/modify each outgoing batch (structured-event stream). Return null to drop. */
+  beforeSend?: (batch: IngestBatch) => IngestBatch | null;
+}
+
+export type ResolvedConfig = Required<
+  Omit<LumeraConfig, 'userId' | 'metadata' | 'beforeSend'>
+> &
+  Pick<LumeraConfig, 'userId' | 'metadata' | 'beforeSend'>;
+
+export const DEFAULTS: Omit<ResolvedConfig, 'siteKey' | 'userId' | 'metadata' | 'beforeSend'> = {
+  enableReplay: true,
+  fps: 1,
+  jpegQuality: 0.4,
+  maxCaptureDim: 1200,
+  maskAllText: true,
+  maskAllImages: true,
+  captureTouches: true,
+  captureNetworkBodies: false,
+  redactHeaders: ['authorization', 'cookie', 'set-cookie'],
+  captureConsole: true,
+  sampleRate: 1,
+  continueSession: false,
+  sessionTimeoutMs: 30 * 60 * 1000,
+  endpoint: 'https://in.lumera.app',
+  flushIntervalMs: 5000,
+  requireConsent: false,
+};
+
+export function resolveConfig(config: LumeraConfig): ResolvedConfig {
+  const clean: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(config)) if (v !== undefined) clean[k] = v;
+  return { ...DEFAULTS, ...(clean as Partial<ResolvedConfig>), siteKey: config.siteKey };
+}

package/src/emit.ts

@@ -0,0 +1,5 @@
+/** A type-specific event WITHOUT the envelope — the SDK stamps id/sessionId/t/ts. */
+export type RawEvent = { type: string } & Record<string, unknown>;
+
+/** Hand a raw event to the SDK's queue. */
+export type Emit = (raw: RawEvent) => void;

package/src/index.ts

@@ -0,0 +1,292 @@
+import { Dimensions, Platform } from 'react-native';
+import type { IngestBatch, IngestSessionMeta, ObsrviqEvent } from '@obsrviq/types';
+import NativeLumeraReplay from './spec/NativeLumeraReplay';
+import { type LumeraConfig, type ResolvedConfig, resolveConfig } from './config';
+import { Clock, uuid } from './util';
+import { clearSession, persistProgress, resolveSession, type ResolvedSession } from './session';
+import { Transport } from './transport';
+import { installNetwork } from './instrument/network';
+import { installErrors } from './instrument/errors';
+import { installConsole } from './instrument/console';
+import type { RawEvent } from './emit';
+
+export interface Diagnostics {
+  recording: boolean;
+  sessionId: string | null;
+  flushes: number;
+  eventsSent: number;
+  eventsQueued: number;
+}
+
+/**
+ * Lumera React Native capture SDK. Mirrors the web tracker's public API 1:1, so app
+ * code reads the same on web and mobile. The pure-JS side here owns identity, the
+ * structured-event stream (network / error / console / custom), and transport; the
+ * heavy screenshot replay stream is owned end-to-end by the native TurboModule
+ * (capture → mask → encode → upload), which never blocks the JS thread.
+ */
+class LumeraReplayClient {
+  private cfg: ResolvedConfig | null = null;
+  private clock: Clock | null = null;
+  private transport: Transport | null = null;
+  private _sessionId: string | null = null;
+  private seq = 0;
+  private meta: IngestSessionMeta | null = null;
+  private events: ObsrviqEvent[] = [];
+  private uninstalls: Array<() => void> = [];
+  private flushTimer: ReturnType<typeof setInterval> | null = null;
+  private recording = false;
+  private consent = true;
+  private ready = false;
+  private diag = { flushes: 0, eventsSent: 0 };
+
+  /** Current session id (null until init resolves). */
+  get sessionId(): string | null {
+    return this._sessionId;
+  }
+
+  /** Initialize the SDK. Idempotent. Session resolution is async (AsyncStorage); any
+   *  events emitted before it resolves are buffered and timestamped correctly. */
+  init(config: LumeraConfig): void {
+    if (this.cfg) return;
+    const cfg = resolveConfig(config);
+    // Sampling: decide once, up front. A sampled-out session records nothing.
+    if (Math.random() >= cfg.sampleRate) return;
+    this.cfg = cfg;
+    this.consent = !cfg.requireConsent;
+    void this.bootstrap();
+  }
+
+  private async bootstrap(): Promise<void> {
+    const cfg = this.cfg!;
+    const resolved = await resolveSession({
+      continueSession: cfg.continueSession,
+      timeoutMs: cfg.sessionTimeoutMs,
+      userId: cfg.userId,
+    });
+    this._sessionId = resolved.id;
+    this.seq = resolved.seq;
+    this.clock = new Clock(resolved.startedAt);
+    this.transport = new Transport(cfg.endpoint, cfg.siteKey);
+    this.meta = this.buildMeta(resolved);
+    this.ready = true;
+
+    // Backfill `t`/sessionId for events emitted before resolution completed.
+    for (const e of this.events) {
+      if (e.t < 0) {
+        (e as { t: number }).t = Math.max(0, e.ts - resolved.startedAt);
+        (e as { sessionId: string }).sessionId = resolved.id;
+      }
+    }
+    if (this.consent) this.startRecording();
+  }
+
+  private buildMeta(r: ResolvedSession): IngestSessionMeta {
+    const cfg = this.cfg!;
+    const win = Dimensions.get('window');
+    return {
+      startedAt: r.startedAt,
+      entryUrl: '', // native app — no URL; left blank (server tolerates)
+      device: {
+        type: 'mobile',
+        os: Platform.OS === 'ios' ? 'iOS' : Platform.OS === 'android' ? 'Android' : Platform.OS,
+        viewport: { w: Math.round(win.width), h: Math.round(win.height) },
+      },
+      userId: cfg.userId,
+      metadata: cfg.metadata,
+      visitorId: r.visitorId,
+      visitCount: r.visitCount,
+      firstSeenAt: r.firstSeenAt,
+    };
+  }
+
+  private startRecording(): void {
+    if (this.recording || !this.cfg || !this.clock) return;
+    const cfg = this.cfg;
+    this.recording = true;
+
+    // ── Pure-JS instrumentation (runs on the JS thread, off the capture path) ──
+    const now = () => this.clock!.now();
+    this.uninstalls.push(
+      installNetwork(this.enqueue, {
+        skipUrl: this.transport!.batchUrl,
+        captureBodies: cfg.captureNetworkBodies,
+        redactHeaders: cfg.redactHeaders,
+        now,
+      }),
+    );
+    this.uninstalls.push(installErrors(this.enqueue));
+    if (cfg.captureConsole) this.uninstalls.push(installConsole(this.enqueue));
+
+    // ── Native screenshot capture (owns capture + encode + upload, off the UI/JS thread) ──
+    if (cfg.enableReplay) {
+      try {
+        NativeLumeraReplay.start({
+          endpoint: cfg.endpoint,
+          siteKey: cfg.siteKey,
+          sessionId: this._sessionId!,
+          startedAtMs: this.clock.startedAt,
+          fps: cfg.fps,
+          jpegQuality: cfg.jpegQuality,
+          maxCaptureDim: cfg.maxCaptureDim,
+          maskAllText: cfg.maskAllText,
+          maskAllImages: cfg.maskAllImages,
+          captureTouches: cfg.captureTouches,
+          flushIntervalMs: cfg.flushIntervalMs,
+        });
+      } catch {
+        /* native module not linked (e.g. Expo Go) — structured capture still works */
+      }
+    }
+
+    this.flushTimer = setInterval(() => void this.flush(), cfg.flushIntervalMs);
+  }
+
+  /** Stamp the envelope + queue an event (arrow fn so instruments can pass it directly). */
+  private enqueue = (raw: RawEvent): void => {
+    if (this.ready && !this.recording) return; // recording stopped → drop
+    const ts = Date.now();
+    const t = this.clock ? this.clock.now() : -1; // -1 = backfilled on ready
+    this.events.push({
+      id: uuid(),
+      sessionId: this._sessionId ?? '',
+      t,
+      ts,
+      ...raw,
+    } as unknown as ObsrviqEvent);
+  };
+
+  // ─────────────────────────── Public API (mirrors web) ───────────────────────────
+
+  identify(userId: string, traits?: Record<string, unknown>): void {
+    if (this.meta) {
+      this.meta.userId = userId;
+      if (traits) this.meta.metadata = { ...(this.meta.metadata ?? {}), ...traits };
+    } else if (this.cfg) {
+      this.cfg = { ...this.cfg, userId, metadata: { ...(this.cfg.metadata ?? {}), ...traits } };
+    }
+    this.enqueue({ type: 'custom', name: 'identify', props: { userId, ...traits } });
+    void this.flush();
+  }
+
+  setMetadata(props: Record<string, unknown>): void {
+    if (this.meta) this.meta.metadata = { ...(this.meta.metadata ?? {}), ...props };
+    this.enqueue({ type: 'custom', name: 'metadata', props });
+    void this.flush();
+  }
+
+  track(name: string, props?: Record<string, unknown>): void {
+    this.enqueue({ type: 'custom', name, props });
+  }
+
+  /** Record a screen/route view — the mobile analog of a web pageview. Call from your
+   *  navigation listener (e.g. React Navigation's onStateChange). Drives
+   *  pages-per-session and path/journey analysis; `name` is the path key. */
+  screen(name: string, props?: Record<string, unknown>): void {
+    const clean = String(name || '').trim();
+    if (!clean) return;
+    this.enqueue({ type: 'pageview', url: clean, path: clean, title: clean, ...(props ? { props } : {}) });
+  }
+
+  conversion(name: string, props?: Record<string, unknown>): void {
+    this.enqueue({ type: 'custom', name, props: { ...props, conversion: true } });
+  }
+
+  tag(...names: string[]): void {
+    if (names.length) this.enqueue({ type: 'custom', name: '_tag', props: { tags: names } });
+  }
+
+  startTask(name: string, props?: Record<string, unknown>): { end: (endProps?: Record<string, unknown>) => void } {
+    const spanId = uuid();
+    this.enqueue({ type: 'custom', name: `${name}:started`, props: { ...props, spanId } });
+    return {
+      end: (endProps?: Record<string, unknown>) =>
+        this.enqueue({ type: 'custom', name: `${name}:ended`, props: { ...endProps, spanId } }),
+    };
+  }
+
+  endTask(name: string, props?: Record<string, unknown>): void {
+    this.enqueue({ type: 'custom', name: `${name}:ended`, props });
+  }
+
+  setConsent(granted: boolean): void {
+    this.consent = granted;
+    if (granted && this.ready && !this.recording) this.startRecording();
+    else if (!granted) this.stop();
+  }
+
+  /** Logout: drop identity + the continuation record, then start a fresh session. */
+  reset(): void {
+    void clearSession();
+    this.stop();
+    if (this.cfg) {
+      this.cfg = { ...this.cfg, userId: undefined, metadata: undefined };
+      this._sessionId = null;
+      this.seq = 0;
+      this.ready = false;
+      this.events = [];
+      void this.bootstrap();
+    }
+  }
+
+  stop(): void {
+    if (this.flushTimer) {
+      clearInterval(this.flushTimer);
+      this.flushTimer = null;
+    }
+    for (const u of this.uninstalls.splice(0)) u();
+    if (this.cfg?.enableReplay) {
+      try {
+        NativeLumeraReplay.stop();
+      } catch {
+        /* not linked */
+      }
+    }
+    this.recording = false;
+    void this.flush();
+  }
+
+  /** Force-send the structured-event stream now. */
+  async flush(): Promise<boolean> {
+    if (!this.transport || !this._sessionId || this.events.length === 0) return true;
+    const events = this.events.splice(0);
+    const seq = this.seq;
+    let batch: IngestBatch | null = {
+      siteKey: this.cfg!.siteKey,
+      sessionId: this._sessionId,
+      seq,
+      meta: this.meta ?? undefined,
+      events,
+    };
+    if (this.cfg!.beforeSend) batch = this.cfg!.beforeSend(batch);
+    if (!batch) return true;
+
+    const ok = await this.transport.send(batch);
+    if (ok) {
+      this.seq = seq + 1;
+      this.diag.flushes += 1;
+      this.diag.eventsSent += events.length;
+      void persistProgress(this._sessionId, this.seq, this.meta?.userId);
+    } else {
+      this.events.unshift(...events); // re-queue on failure
+    }
+    return ok;
+  }
+
+  getDiagnostics(): Diagnostics {
+    return {
+      recording: this.recording,
+      sessionId: this._sessionId,
+      flushes: this.diag.flushes,
+      eventsSent: this.diag.eventsSent,
+      eventsQueued: this.events.length,
+    };
+  }
+}
+
+export const LumeraReplay = new LumeraReplayClient();
+export default LumeraReplay;
+export type { LumeraConfig };
+
+// Privacy-by-region component for the native screenshot replay (<LumeraMask> / <LumeraMask unmask>).
+export { LumeraMask, type LumeraMaskProps } from './LumeraMask';

package/src/instrument/console.ts

@@ -0,0 +1,46 @@
+import type { ConsoleLevel, SerializedArg } from '@obsrviq/types';
+import type { Emit } from '../emit';
+
+const LEVELS: ConsoleLevel[] = ['log', 'info', 'warn', 'error', 'debug'];
+const CAP = 2000;
+
+function serializeArg(a: unknown): SerializedArg {
+  if (typeof a === 'string') return { kind: 'string', value: a.slice(0, CAP), truncated: a.length > CAP };
+  if (a === null || typeof a === 'number' || typeof a === 'boolean')
+    return { kind: 'primitive', value: a as string | number | boolean | null };
+  if (a instanceof Error) return { kind: 'error', name: a.name, message: a.message, stack: a.stack };
+  try {
+    const json = JSON.stringify(a) ?? String(a);
+    return {
+      kind: 'object',
+      preview: Array.isArray(a) ? `Array(${a.length})` : 'Object',
+      json: json.slice(0, CAP),
+      truncated: json.length > CAP,
+    };
+  } catch {
+    return { kind: 'object', preview: String(a) };
+  }
+}
+
+/** Mirrors console.* into the session as `console` events. Pure JS. */
+export function installConsole(emit: Emit): () => void {
+  const c = console as unknown as Record<string, (...args: unknown[]) => void>;
+  const orig: Record<string, (...args: unknown[]) => void> = {};
+  for (const level of LEVELS) {
+    const o = c[level];
+    if (typeof o !== 'function') continue;
+    const bound = o.bind(console);
+    orig[level] = bound;
+    c[level] = (...args: unknown[]) => {
+      try {
+        emit({ type: 'console', level, args: args.map(serializeArg) });
+      } catch {
+        /* noop */
+      }
+      bound(...args);
+    };
+  }
+  return () => {
+    for (const level of LEVELS) if (orig[level]) c[level] = orig[level];
+  };
+}