@scalebun-release/react-native 2.5.0

package/lib/module/bootstrap/SDKBootstrapper.js

@@ -0,0 +1,742 @@
+/**
+ * ScaleBun SDK — SDK Bootstrapper
+ *
+ * Encapsulates the core SDK initialization sequence.
+ * Called by ScaleBunFacade.init() — this is the single real init path.
+ *
+ * Responsibilities:
+ * - Config validation and merge with defaults
+ * - Core service setup (HttpClient, Dispatcher, FlushScheduler)
+ * - Backend handshake
+ * - Feature registration and initialization via FeatureRegistry
+ * - App lifecycle wiring
+ *
+ * Returns null on failure (handshake fail, invalid config) to allow
+ * the Facade to handle gracefully without crashing.
+ */
+
+import { Linking, Platform } from 'react-native';
+import { ConfigSchema } from '../core/config/schema';
+import { DEFAULT_API_BASE_URL } from '../core/constants/endpoints';
+import { logger, LogLevel } from '../core/logger/internalLogger';
+import { coreContainer } from '../core/di/container';
+import { HttpClient } from '../transport/http/httpClient';
+import { ENDPOINTS } from '../transport/http/endpoints';
+import { sdkSession } from '../transport/auth/sdkSession';
+import { getDeviceId } from '../core/id/deviceId';
+import { FlushScheduler } from '../pipeline/scheduler/flushScheduler';
+import { appLifecycle } from '../core/lifecycle/appLifecycle';
+import { FeatureRegistry } from './FeatureRegistry';
+import { NetworkFeature } from '../features/network/NetworkFeature';
+import { CrashFeature } from '../features/crash/CrashFeature';
+import { NativeCrashFeature } from '../features/crash/NativeCrashFeature';
+import { getCrashReporter, DesktopEventSink, BackendErrorsSink } from '../features/crash/CrashReporter';
+import { PerformanceFeature } from '../features/performance/PerformanceFeature';
+import { PersistentQueue } from '../pipeline/queue/persistentQueue';
+import { createStorageBackend, MemoryBackend } from '../storage/StorageBackend';
+import { SessionManager } from '../features/session/SessionManager';
+import { nativeCapture } from '../features/session/nativeCapture';
+import { installAlertInstrumentation, uninstallAlertInstrumentation } from '../features/replay/integrations/alert/alertInstrumentation';
+import { installConsoleIntegration, uninstallConsoleIntegration } from '../features/replay/integrations/logs/consoleIntegration';
+import { BackendSessionAdapter } from '../features/session/BackendSessionAdapter';
+import { generateSessionId } from '../features/replay/core/ids/sessionId';
+import { emitAutomaticEvent } from '../analytics/automaticEvents';
+import { quotaState } from '../config/quotaState';
+export class SDKBootstrapper {
+  featureRegistry = new FeatureRegistry();
+  config = null;
+  // Wall-clock (ms) the app last went to background, or null while foregrounded.
+  // Read on the next foreground to decide whether the backgrounded span exceeded
+  // sessionBackgroundCapMs (→ finalize + new session) or stays within one session.
+  _backgroundedAt = null;
+  _orientationSub = null;
+  /** quotaState subscription that re-opens a session when a `sessions` block lifts. */
+  _sessionsQuotaUnsub = null;
+  /**
+   * Set when a `sessions` block lifted while the app was NOT in the foreground (or before the
+   * adapter could open a session). Honored on the next foreground: the analytics session opens there
+   * anyway, but recording would otherwise only restart with finalizeOnBackground.
+   */
+  _recordAfterSessionsUnblock = false;
+  /** Whether cold-launch auto-record applies (replay.record !== false); set when the adapter is built. */
+  _autoRecord = false;
+  _lastOrientation = null;
+  _memorySub = null;
+  _deepLinkUnsubscribe = null;
+
+  /**
+   * Run the full SDK initialization sequence.
+   *
+   * Returns BootstrapResult on success, null on failure.
+   * Never throws — all errors are caught and logged.
+   *
+   * @param rawConfig - Raw user-provided config (validated via the internal protocol validator)
+   * @param trackFn  - Function to track events (from Facade)
+   * @param flushFn  - Function to flush events (from Facade)
+   * @param features - Feature flags (all default true — opt-out model)
+   */
+  async bootstrap(rawConfig, trackFn, flushFn, features = {}) {
+    // ── Validate config ────────────────────────────────────
+    // `captureMode: 'frequency'` is no longer a developer-settable option — timer-based capture
+    // is reserved for ScaleBun-controlled (server/admin) activation. Coerce a legacy developer
+    // value to the default rather than hard-failing: an invalid config aborts the ENTIRE SDK
+    // boot (return null below), so silently downgrading is the safe, backward-compatible path.
+    let cfg = rawConfig;
+    const rc = rawConfig;
+    if (rc?.replay?.captureMode === 'frequency') {
+      logger.warn("replay.captureMode 'frequency' is no longer developer-settable; falling back to 'interactions'. Frequency capture is controlled by ScaleBun.");
+      cfg = {
+        ...rc,
+        replay: {
+          ...rc.replay,
+          captureMode: 'interactions'
+        }
+      };
+    }
+    const result = ConfigSchema.safeParse(cfg);
+    if (!result.success) {
+      logger.error('Invalid configuration:', result.error.format());
+      return null;
+    }
+    this.config = result.data;
+    // apiBaseUrl is LOCKED: whatever an integrator passed (or the schema default) is
+    // discarded here so the SDK can never be repointed away from the ScaleBun cloud.
+    // Change DEFAULT_API_BASE_URL at build time to target a different backend.
+    // Say so when we discard it. The value was accepted by the schema, silently
+    // overwritten here, and the SDK then talked to a different server than the
+    // integrator configured — with no log, no warning, and no error. Someone
+    // pointing the SDK at a staging or local backend would watch requests arrive
+    // at production and have nothing to go on.
+    const requestedApiBaseUrl = rawConfig?.apiBaseUrl;
+    if (typeof requestedApiBaseUrl === 'string' && requestedApiBaseUrl && requestedApiBaseUrl !== DEFAULT_API_BASE_URL) {
+      logger.warn(`[ScaleBun] Ignoring apiBaseUrl '${requestedApiBaseUrl}' — the endpoint is ` + `locked at build time and this build targets ${DEFAULT_API_BASE_URL}. To ` + `target another backend, change DEFAULT_API_BASE_URL in the SDK source and ` + `rebuild.`);
+    }
+    this.config.apiBaseUrl = DEFAULT_API_BASE_URL;
+    // Explicit logLevel wins; otherwise debug:true implies verbose 'debug'.
+    if (this.config.logLevel) {
+      logger.setLevelByName(this.config.logLevel);
+    } else if (this.config.debug) {
+      logger.setLevel(LogLevel.DEBUG);
+    }
+
+    // ── Core services ──────────────────────────────────────
+
+    // ── Persistent Queue ───────────────────────────────────
+    const persistenceConfig = this.config.persistence;
+    const storageBackend = persistenceConfig.enabled ? createStorageBackend() : new MemoryBackend();
+    const persistentQueue = coreContainer.register('PersistentQueue', new PersistentQueue(storageBackend, persistenceConfig));
+
+    // Drain leftover envelopes from previous run BEFORE accepting new ones.
+    // These are flushed immediately so crash-time events are not lost.
+    const leftovers = persistentQueue.drainLeftovers();
+    if (leftovers.length > 0) {
+      __DEV__ && logger.info(`[Bootstrap] ${leftovers.length} leftover envelopes from previous run — will flush`);
+      // Re-add to queue so the normal flush cycle picks them up
+      for (const envelope of leftovers) {
+        persistentQueue.add(envelope);
+      }
+    }
+    const httpClient = coreContainer.register('HttpClient', new HttpClient(this.config.apiBaseUrl));
+
+    // D1: a `Dispatcher` used to be registered here, draining `memoryQueue`
+    // to ENDPOINTS.EVENTS ('/sdk/events'). Removed on two grounds, both
+    // verified: nothing anywhere resolved 'Dispatcher' from the container
+    // (so its flush never ran and the queue was a black hole), and no
+    // backend controller has ever served '/sdk/events' — even a wired
+    // dispatcher would have 404'd forever. Every producer that wrote into
+    // that pipeline now rides a live lane instead (captureException →
+    // CrashReporter, native-crash detail → report metadata, metrics →
+    // queuePerformanceMetric). A decoy pipeline is worse than none: it
+    // makes the real path look redundant.
+
+    const scheduler = coreContainer.register('FlushScheduler', new FlushScheduler(flushFn));
+
+    // ── Backend handshake ──────────────────────────────────
+    if (this.config.clientKey) {
+      // SaaS mode: clientKey is resolved by SdkKeyGuard on each request — no token handshake needed
+      __DEV__ && logger.info('[Bootstrap] SaaS mode: clientKey auth active, skipping legacy handshake');
+    } else {
+      __DEV__ && logger.debug('Starting handshake...');
+      const response = await httpClient.post(ENDPOINTS.SESSIONS, {
+        projectId: this.config.projectId,
+        publishableKey: this.config.publishableKey,
+        deviceId: getDeviceId(),
+        platform: Platform.OS
+      });
+      if (response.status !== 201 || !response.data?.token) {
+        logger.error('Failed to establish SDK session:', response.data);
+        return null;
+      }
+      sdkSession.setSession(response.data.token, 900);
+    }
+
+    // ── App lifecycle ──────────────────────────────────────
+    appLifecycle.addListener(state => {
+      if (state === 'background') {
+        flushFn();
+      }
+      trackFn('$app_state_change', {
+        state
+      });
+      if (state === 'active') {
+        emitAutomaticEvent('app_foregrounded');
+      } else if (state === 'background') {
+        emitAutomaticEvent('app_backgrounded');
+      }
+
+      // Analytics ingestion session is foreground-scoped (SaaS mode):
+      // open on foreground if not already open, finalize on background.
+      // Resolved lazily — the adapter is created later in this bootstrap.
+      if (this.config?.clientKey) {
+        const sessionManager = SessionManager.getExistingInstance();
+        const adapter = sessionManager?.getBackendTransport();
+        if (adapter) {
+          if (state === 'active') {
+            // Reconcile-close any session left pending by a prior cap-driven
+            // finalize whose POST was suspended by iOS. No-op in the common
+            // path (below-cap background does NOT finalize), so this only
+            // fires after a real cap finalize or a legacy pending id.
+            adapter.reconcilePendingFinalize().catch(() => {});
+            const bgAt = this._backgroundedAt;
+            this._backgroundedAt = null;
+            const capMs = this.config?.sessionBackgroundCapMs ?? 30 * 60 * 1000;
+            const bgMs = bgAt ? Date.now() - bgAt : 0;
+            if (!adapter.analyticsSessionId) {
+              // Cold start, or the session was finalized (cap/kill) →
+              // open a fresh one.
+              const opened = adapter.startAnalyticsSession(this._buildAnalyticsSession());
+              opened.catch(() => {});
+              // Quota: a sessions block lifted while backgrounded — start the recording
+              // the cold launch could not (only when auto-record is on).
+              if (this._recordAfterSessionsUnblock && !quotaState.isBlocked('sessions')) {
+                this._recordAfterSessionsUnblock = false;
+                if (this._autoRecord && sessionManager) {
+                  opened.then(() => {
+                    if (!sessionManager.isActive) sessionManager.startSession();
+                  }).catch(() => {});
+                }
+              }
+            } else if (bgAt && bgMs > capMs) {
+              // Backgrounded past the cap → finalize the old session and
+              // open a new one (cap-then-reaper). The finalize POST runs
+              // live on foreground so it resolves; the new session opens
+              // immediately (disjoint fields).
+              adapter.finalizeAnalyticsSession().catch(() => {});
+              adapter.startAnalyticsSession(this._buildAnalyticsSession()).catch(() => {});
+            } else {
+              // Below the cap → KEEP one session across the app-switch.
+              // Mark the foreground boundary so the dashboard can shade the
+              // backgrounded span and exclude it from active duration.
+              adapter.emitLifecycleMarker('APP_FOREGROUND', {
+                at: Date.now(),
+                ...(bgAt ? {
+                  backgroundedAt: bgAt,
+                  backgroundMs: bgMs
+                } : {})
+              });
+            }
+            // Per-foreground recording sessions: reopen on foreground.
+            if (this.config?.finalizeOnBackground && sessionManager && !sessionManager.isActive) {
+              sessionManager.startSession();
+            }
+          } else if (state === 'background') {
+            this._backgroundedAt = Date.now();
+            // Mark the background boundary on the analytics lane BEFORE the
+            // flush so its accurate timestamp is captured even if the OS
+            // suspends the flush timer immediately after backgrounding.
+            adapter.emitLifecycleMarker('APP_BACKGROUND', {
+              at: this._backgroundedAt
+            });
+            // Snapshot unflushed frames to durable storage FIRST (sync) so a
+            // process kill during/after backgrounding can't lose the last
+            // frames — they replay to this session on the next launch. Runs
+            // before flushAll so it captures the buffer the network flush
+            // (which the OS may suspend) is about to try to send.
+            adapter.persistPendingFrames();
+            // Flush recording-lane queues so the server reaper computes
+            // endedAt from the freshest frames/events even if the OS
+            // suspends the flush timer right after backgrounding.
+            adapter.flushAll().catch(() => {});
+            // Push the marker + any buffered analytics events now (best-effort
+            // on iOS). Do NOT finalize — the session spans the background.
+            adapter.flushAnalytics().catch(() => {});
+            // Opt-in: hard-finalize the recording session on background.
+            if (this.config?.finalizeOnBackground && sessionManager?.isActive) {
+              sessionManager.endSession();
+            }
+          }
+        }
+      }
+    });
+
+    // ── Device-context collectors ──────────────────────────
+    // Installed ONCE, beside the lifecycle listener rather than inside it (a listener body runs on
+    // every foreground/background transition, which would stack a fresh subscription each time).
+    this.installOrientationTracking();
+    this.installMemoryWarningTracking();
+
+    // ── Deep-link collection ───────────────────────────────
+    // Capture routing structure only. Query values and fragments may contain
+    // credentials or PII, so they never enter the automatic event envelope.
+    const captureDeepLink = (url, initial = false) => {
+      if (!url) return;
+      try {
+        const parsed = new URL(url);
+        emitAutomaticEvent('deep_link_opened', {
+          initial,
+          scheme: parsed.protocol.replace(/:$/, ''),
+          host: parsed.host || undefined,
+          path: parsed.pathname || '/',
+          query_keys: Array.from(parsed.searchParams.keys()).sort()
+        });
+      } catch {
+        const safePath = url.split(/[?#]/, 1)[0];
+        emitAutomaticEvent('deep_link_opened', {
+          initial,
+          path: safePath
+        });
+      }
+    };
+    try {
+      const subscription = Linking.addEventListener('url', ({
+        url
+      }) => {
+        captureDeepLink(url);
+      });
+      this._deepLinkUnsubscribe = () => subscription.remove();
+      Linking.getInitialURL().then(url => {
+        if (url) captureDeepLink(url, true);
+      }).catch(() => {});
+    } catch (err) {
+      logger.warn('[Bootstrap] Failed to start deep-link collection:', err?.message);
+    }
+
+    // ── Start auto-flush ───────────────────────────────────
+    scheduler.start(this.config.flushIntervalMs);
+
+    // ── Register features ──────────────────────────────────
+    const featureContext = {
+      trackEvent: trackFn,
+      getDebugStream: () => null,
+      // Wired later if debug enabled
+      getAppState: () => 'active'
+    };
+
+    // Network monitoring (default: on)
+    if (features.network !== false && this.config.enableNetworkMonitoring !== false) {
+      this.featureRegistry.register(new NetworkFeature(trackFn, {
+        captureNetworkBodies: this.config.captureNetworkBodies ?? false,
+        // Opt-in only — must be explicitly enabled by caller
+        redactNetwork: true,
+        sdkBaseUrl: this.config.apiBaseUrl
+      }));
+    }
+
+    // Crash reporting (default: on)
+    if (features.crashes !== false) {
+      // Central reporter fans every crash origin (JS uncaught, handled,
+      // native drain) out to all sinks. Register delivery targets once;
+      // new targets can be added later without touching callers.
+      const crashReporter = getCrashReporter();
+      crashReporter.registerSink(new DesktopEventSink(trackFn));
+      crashReporter.registerSink(new BackendErrorsSink());
+      this.featureRegistry.register(new CrashFeature(flushFn));
+      this.featureRegistry.register(new NativeCrashFeature());
+    }
+
+    // Performance monitoring (default: on). Map the tiered, default-safe
+    // activation flags from validated config onto the collector config.
+    if (features.performance !== false) {
+      const perf = this.config.performance;
+      this.featureRegistry.register(new PerformanceFeature({
+        enabled: perf.enabled,
+        appLaunch: perf.tier1.appLaunch,
+        screenLoad: perf.tier1.screenLoad,
+        networkPerf: perf.tier1.network,
+        uiHangs: perf.tier1.uiHang,
+        tier2Enabled: perf.tier2.enabled,
+        tier2SampleRate: perf.tier2.sampleRate
+      }));
+    }
+    await this.featureRegistry.initializeAll(featureContext);
+
+    // ── Session Replay Initialization (Core) ───────────────
+    /**
+    * RN-3 zero-config scroll instrumentation, opt-in.
+    *
+    * Placed before replay init because it patches a module export and must be in place before the
+    * host renders its first scroll view. Reports rather than assumes: the equivalent React
+    * Navigation hook once claimed success it had not verified and left a whole pipeline silently
+    * empty, so a failure here is said out loud with a reason an integrator can act on.
+    */
+    if (this.config.autoInstrumentScrollViews === true) {
+      try {
+        const {
+          autoInstrumentScrollViews
+        } = require('../features/journey/autoInstrumentScroll');
+        const outcome = autoInstrumentScrollViews();
+        if (!outcome.installed) {
+          logger.warn('[Bootstrap] autoInstrumentScrollViews was requested but could not be ' + 'installed: ' + outcome.reason + ' — taps will carry no content depth.');
+        } else {
+          __DEV__ && logger.debug('[Bootstrap] ScrollView auto-instrumentation installed');
+        }
+      } catch {/* no-throw */}
+    }
+    if (features.replay !== false) {
+      try {
+        __DEV__ && logger.debug('[Bootstrap] Initializing unified SessionManager');
+        // SB-10: map the public top-level privacy config onto the replay
+        // privacy policy — the field the native capture path actually reads.
+        // Unspecified fields fall back to the SDK's safe defaults
+        // (redactTextInputs: true), so this only ever tightens masking.
+        const pub = this.config.privacy ?? {};
+        const sessionReplay = {
+          ...(this.config.replay ?? {})
+        };
+        if (typeof pub.maskTextInputs === 'boolean' || typeof pub.maskImages === 'boolean') {
+          sessionReplay.privacyPolicy = {
+            redactTextInputs: pub.maskTextInputs ?? true,
+            redactImages: pub.maskImages ?? false,
+            blockTestIds: [],
+            captureExclusions: []
+          };
+        }
+        const sessionManager = SessionManager.getInstance(null,
+        // No desktop transport initially
+        nativeCapture,
+        // Flow init `replay` capture config into the unified manager so
+        // captureMode/intervalMs are honored (without this it always uses
+        // the 'navigation' default → no frames on a static screen).
+        // Also flow the Feature #4 heatmap flag so tap/gesture coords
+        // route to the analytics lane even when no recording is active.
+        {
+          sessionReplay: sessionReplay,
+          captureInteractionHeatmap: this.config.captureInteractionHeatmap === true
+        });
+
+        // Attach backend upload transport since this is the primary telemetry sink for prod
+        if (this.config.apiBaseUrl) {
+          const backendAdapter = new BackendSessionAdapter({
+            endpoint: this.config.apiBaseUrl,
+            clientKey: this.config.clientKey,
+            idleThresholdMs: this.config.idleThresholdMs,
+            // Durable store for cross-kill frame recovery (respects the
+            // persistence gate). createStorageBackend() is a singleton, so
+            // this is the same instance the telemetry queue uses.
+            storage: this.config.persistence.enabled ? createStorageBackend() : undefined,
+            useObjectStorage: this.config.useObjectStorage,
+            enableNativeFileOutbox: this.config.enableNativeFileOutbox,
+            nativeOutboxUploadEnabled: this.config.nativeOutboxUploadEnabled,
+            nativeOutboxTuning: {
+              nativeOutboxRetryIntervalMs: this.config.nativeOutboxRetryIntervalMs,
+              nativeOutboxMaxUploadAttempts: this.config.nativeOutboxMaxUploadAttempts,
+              nativeOutboxPoisonMaxAttempts: this.config.nativeOutboxPoisonMaxAttempts,
+              nativeOutboxRespectRetryAfter: this.config.nativeOutboxRespectRetryAfter,
+              nativeOutboxStrictThreeSecondRetry: this.config.nativeOutboxStrictThreeSecondRetry,
+              nativeOutboxNetworkFailuresCountTowardDead: this.config.nativeOutboxNetworkFailuresCountTowardDead,
+              nativeOutboxMaxBytes: this.config.nativeOutboxMaxBytes,
+              nativeOutboxMaxAgeMs: this.config.nativeOutboxMaxAgeMs
+            }
+          });
+          sessionManager.setBackendTransport(backendAdapter);
+
+          // Re-drain recovered crashes now that a backend transport exists.
+          //
+          // drainNativeCrash already ran inside initializeAll — BEFORE this line — so a
+          // crash recovered from the previous run was reported into a NULL transport, the
+          // backend sink no-op'd, and the record was KEPT on disk. Next launch loses the
+          // identical race, so without this a recovered crash (JS or native) never reaches
+          // the dashboard. The record is durable (the persist fix), so re-draining here
+          // delivers it THIS launch; the adapter buffers the error until the session row
+          // exists, so it lands even though startSession may not have completed yet. A
+          // no-op when nothing is pending. Fire-and-forget — crash delivery must never
+          // block or fail session setup.
+          //
+          // In SaaS mode it waits for the analytics session ROW (below). Draining before
+          // that meant flushErrors had no session to send to, so delivery was never
+          // confirmed: each record was reported, kept on disk, and the loop stopped after
+          // the first — one crash per launch, re-sent forever. Legacy mode (no clientKey)
+          // has no such row and drains now, as before.
+          const drainRecoveredCrashes = () => {
+            import('../features/crash/nativeCrashBridge').then(m => m.drainNativeCrash()).catch(() => {});
+          };
+          if (!this.config.clientKey) drainRecoveredCrashes();
+
+          // Opt-in console → Logs lane. Armed here (not only in the desktop-debug
+          // replay orchestrator) so a stock SaaS app can capture console.* without
+          // pulling in the devTools bundle. Gated by clientKey (the backend transport
+          // forwardToLogsLane needs is now set above) AND the explicit
+          // captureConsoleLogs opt-in — console output can carry PII, so it stays off
+          // unless the host asks for it. queueLog itself no-ops without a clientKey.
+          if (this.config.clientKey && this.config.captureConsoleLogs) {
+            installConsoleIntegration();
+          }
+
+          // Cross-kill frame recovery: if a prior run was killed with
+          // unflushed frames, re-upload them linked to that PRIOR session
+          // before the new session takes over. Best-effort, independent of
+          // the new session id.
+          backendAdapter.recoverPersistedFrames().catch(() => {});
+
+          // Open the always-on analytics ingestion session (SaaS mode).
+          // Decoupled from recording: do NOT call SessionManager.startSession
+          // unconditionally, which would start frame capture + the recording
+          // timeout for every app even when frame recording is not wanted.
+          if (this.config.clientKey) {
+            const analyticsStarted = backendAdapter.startAnalyticsSession(this._buildAnalyticsSession());
+            // Resolves once INGESTION_START has answered (or failed — then the drain
+            // keeps the records for the next launch, exactly as before).
+            analyticsStarted.then(drainRecoveredCrashes, drainRecoveredCrashes);
+
+            // Cold-launch frame recording. The AppState listener only starts a
+            // recording session on a foreground TRANSITION, which never fires on the
+            // initial launch — so without this the first session uploads events but zero
+            // frames ("No screen recordings"). Auto-start recording by DEFAULT in SaaS mode
+            // so replays appear out of the box; hosts opt out with `replay: { record: false }`
+            // for events-only sessions (they can still record on demand via startSession()).
+            // Deliberately NOT gated by finalizeOnBackground (that flag only governs
+            // per-foreground session boundaries, not whether replay records at all).
+            // Started once the analytics session id exists so startSession adopts it
+            // (one-row merge) instead of minting an orphan row.
+            const shouldAutoRecord = this.config.replay?.record !== false;
+            this._autoRecord = shouldAutoRecord;
+            if (shouldAutoRecord) {
+              analyticsStarted.then(() => {
+                if (!sessionManager.isActive) {
+                  sessionManager.startSession();
+                }
+              }).catch(() => {});
+            } else {
+              analyticsStarted.catch(() => {});
+            }
+
+            // Quota (contract v1): while `sessions` is blocked no session opens — not at
+            // launch, not on foreground. When the block LIFTS mid-foreground (a /config
+            // refresh), open one now rather than waiting for the next app-switch, and
+            // start recording the same way the cold launch above does.
+            this._sessionsQuotaUnsub?.();
+            this._sessionsQuotaUnsub = quotaState.subscribe((feature, blocked) => {
+              if (feature !== 'sessions' || blocked) return;
+              try {
+                if (appLifecycle.getCurrentState() !== 'active') {
+                  // Backgrounded: the next foreground opens the session; remember to
+                  // start recording there too.
+                  if (shouldAutoRecord && !sessionManager.isActive) this._recordAfterSessionsUnblock = true;
+                  return;
+                }
+                if (backendAdapter.analyticsSessionId) return;
+                const reopened = backendAdapter.startAnalyticsSession(this._buildAnalyticsSession());
+                reopened.then(() => {
+                  if (shouldAutoRecord && !sessionManager.isActive) sessionManager.startSession();
+                }).catch(() => {});
+              } catch {/* no-throw */}
+            });
+          }
+        }
+
+        // Transport mode: backend always active when apiBaseUrl set.
+        // Desktop transport is attached lazily by sessionWiring.ts when
+        // enableDebug() is called (development only — production skips this).
+        const isSaaS = !!this.config.clientKey;
+        __DEV__ && logger.info(`[ScaleBun Session Wiring] mode=${isSaaS ? 'saas' : 'legacy'} ` + `backend=${!!this.config.apiBaseUrl} desktop=pending-debug-connect`);
+
+        // Patch RN Alert so native dialog lifecycle + button presses are
+        // recorded into this SessionManager. Installed here (not in the
+        // desktop-only replay orchestrator) so it runs for production /
+        // SaaS sessions too. Inert until a session is actively recording.
+        installAlertInstrumentation({
+          debug: !!this.config.debug
+        });
+      } catch (err) {
+        logger.warn('[Bootstrap] Failed to initialize SessionManager:', err);
+      }
+    }
+
+    // ── Auto Screen Detection for Core Telemetry ───────────
+    try {
+      const {
+        AutoScreenDetector
+      } = require('../features/navigation/AutoScreenDetector');
+      const detector = AutoScreenDetector.getInstance();
+      detector.onScreenChange((screenName, source) => {
+        emitAutomaticEvent('screen_viewed', {
+          screen_name: screenName,
+          detection_source: source
+        });
+
+        // Update cross-cutting screen tracker (used for breadcrumbs/logs)
+        try {
+          const {
+            setTrackedScreen
+          } = require('../debug/screenTracking');
+          setTrackedScreen(screenName);
+        } catch {/* no-throw */}
+
+        // Feed SessionManager (canonical SCREEN_VIEW)
+        try {
+          const {
+            SessionManager
+          } = require('../features/session/SessionManager');
+          const sm = SessionManager.getExistingInstance();
+          if (sm && sm.onScreenChange) {
+            sm.onScreenChange(screenName);
+          }
+        } catch {/* no-throw */}
+
+        // Feed PerformanceFeature: update current screen AND time the
+        // screen load. Reuses the detector's resolved name instead of
+        // attaching a second navigation listener on the app's nav ref.
+        try {
+          const pf = this.featureRegistry.get('performance');
+          if (pf) {
+            pf.setCurrentScreen(screenName);
+            pf.onScreenChange?.(screenName);
+          }
+        } catch {/* no-throw */}
+
+        // Feed ProfilerFeature
+        try {
+          const {
+            getProfilerFeature
+          } = require('../debug/bootstrap');
+          const prof = getProfilerFeature?.();
+          if (prof) {
+            prof.setCurrentScreen(screenName);
+          }
+        } catch {/* no-throw */}
+        __DEV__ && logger.debug(`[AutoScreen] Screen → '${screenName}' (source: ${source})`);
+      });
+      detector.start();
+      __DEV__ && logger.info('[Bootstrap] Auto screen detection started');
+
+      /**
+       * Screen detection that never resolves anything must SAY so.
+       *
+       * Wrapping React Navigation only helps a container that mounts afterwards, so an app that
+       * initialises the SDK late still ends up with no screen names — and until now that was
+       * indistinguishable from working. Everything downstream inherits the silence: no
+       * SCREEN_VIEW events, so every session's screens read "Unknown"; and no `screenName` on
+       * taps, which is the column heatmaps group by, so every route collapses into one bucket.
+       *
+       * One warning, once, naming the fix.
+       */
+      let sawScreen = false;
+      detector.onScreenChange(() => {
+        sawScreen = true;
+      });
+      const warnTimer = setTimeout(() => {
+        if (sawScreen) return;
+        logger.warn('[ScaleBun] No screen has been detected. Screens will show as "Unknown" and heatmaps ' + 'cannot be split by route. If you use React Navigation, pass your container ref to ' + 'ScaleBun.setNavigationRef(ref); otherwise mark screens with <ScaleBunScreen name="…">.');
+      }, 15_000);
+      // Never hold the JS timer queue open on a background/exiting app.
+      warnTimer.unref?.();
+    } catch (err) {
+      logger.warn('[Bootstrap] Failed to start AutoScreenDetector:', err?.message);
+    }
+
+    // ── Session start event ────────────────────────────────
+    trackFn('$session_start', {
+      platform: Platform.OS,
+      version: Platform.Version,
+      deviceId: getDeviceId()
+    });
+    __DEV__ && logger.info('SDK initialized and session established');
+    return {
+      config: this.config,
+      featureRegistry: this.featureRegistry
+    };
+  }
+
+  /**
+   * Build the minimal Session the analytics lane needs. sendSessionStart only
+   * reads sessionId/deviceId/startedAt/metadata; device detail is enriched from
+   * the native bridge at upload time, so this stays minimal.
+   */
+  /**
+   * Emit `orientation_changed` when the device actually rotates.
+   *
+   * There was no orientation signal at all, so a drop-off caused by a broken landscape layout was
+   * invisible — the funnel showed users leaving and nothing explained why. Dimensions fires on any
+   * metric change (keyboard, split-view, font scale), so the event is emitted only when the
+   * portrait/landscape VERDICT flips; otherwise a keyboard open would look like a rotation.
+   */
+  installOrientationTracking() {
+    if (this._orientationSub) return; // idempotent — bootstrap can run more than once
+    try {
+      const {
+        Dimensions
+      } = require('react-native');
+      const verdict = (w, h) => w > h ? 'landscape' : 'portrait';
+      const win = Dimensions.get('window');
+      this._lastOrientation = verdict(win.width, win.height);
+      this._orientationSub = Dimensions.addEventListener('change', ({
+        window
+      }) => {
+        try {
+          const next = verdict(window.width, window.height);
+          if (next === this._lastOrientation) return;
+          const from = this._lastOrientation;
+          this._lastOrientation = next;
+          emitAutomaticEvent('orientation_changed', {
+            orientation: next,
+            from,
+            width: Math.round(window.width),
+            height: Math.round(window.height)
+          });
+        } catch {/* no-throw: a collector must never break the host app */}
+      });
+    } catch {/* Dimensions unavailable (non-RN test env) — silently skip */}
+  }
+
+  /**
+   * Emit `memory_warning` when the OS signals memory pressure.
+   *
+   * This is the leading indicator before an OOM kill, and the crash side was already built — so the
+   * warning that precedes the crash was the missing half. Android-only via RN's `appState`-adjacent
+   * `memoryWarning` event; iOS surfaces it through the same emitter when the native module forwards it.
+   */
+  installMemoryWarningTracking() {
+    if (this._memorySub) return;
+    try {
+      const {
+        AppState
+      } = require('react-native');
+      if (typeof AppState.addEventListener !== 'function') return;
+      this._memorySub = AppState.addEventListener('memoryWarning', () => {
+        try {
+          emitAutomaticEvent('memory_warning', {
+            screen: SessionManager.getExistingInstance()?.getLastKnownScreen?.()
+          });
+        } catch {/* no-throw */}
+      });
+    } catch {/* AppState unavailable — skip */}
+  }
+  _buildAnalyticsSession() {
+    return {
+      sessionId: generateSessionId(),
+      deviceId: getDeviceId(),
+      startedAt: Date.now(),
+      idleThresholdMs: this.config?.idleThresholdMs,
+      metadata: {
+        buildType: __DEV__ ? 'debug' : 'release'
+      }
+    };
+  }
+
+  /** Get the validated config */
+  getConfig() {
+    return this.config;
+  }
+
+  /** Tear down all features */
+  teardown() {
+    this._sessionsQuotaUnsub?.();
+    this._sessionsQuotaUnsub = null;
+    this._deepLinkUnsubscribe?.();
+    this._deepLinkUnsubscribe = null;
+    uninstallAlertInstrumentation();
+    uninstallConsoleIntegration();
+    this.featureRegistry.teardownAll();
+  }
+}
+//# sourceMappingURL=SDKBootstrapper.js.map