@scalebun-release/react-native 2.5.0

package/src/bootstrap/SDKBootstrapper.ts

@@ -0,0 +1,769 @@
+/**
+ * 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, type ScaleBunConfig } 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 { Dispatcher } from '../pipeline/dispatcher/dispatcher';
+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 type { SessionReplayConfig } from '../features/session/sessionTypes';
+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 type { FeatureContext } from '../core/contracts/IFeature';
+import type { ScaleBunFeatures } from '../public/types';
+import { emitAutomaticEvent } from '../analytics/automaticEvents';
+import { quotaState } from '../config/quotaState';
+
+export interface BootstrapResult {
+    config: ScaleBunConfig;
+    featureRegistry: FeatureRegistry;
+}
+
+export class SDKBootstrapper {
+    private featureRegistry = new FeatureRegistry();
+    private config: ScaleBunConfig | null = 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.
+    private _backgroundedAt: number | null = null;
+    private _orientationSub: { remove?: () => void } | null = null;
+    /** quotaState subscription that re-opens a session when a `sessions` block lifts. */
+    private _sessionsQuotaUnsub: (() => void) | null = 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.
+     */
+    private _recordAfterSessionsUnblock = false;
+    /** Whether cold-launch auto-record applies (replay.record !== false); set when the adapter is built. */
+    private _autoRecord = false;
+    private _lastOrientation: 'portrait' | 'landscape' | null = null;
+    private _memorySub: { remove?: () => void } | null = null;
+    private _deepLinkUnsubscribe: (() => void) | null = 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: unknown,
+        trackFn: (name: string, payload?: Record<string, unknown>) => void,
+        flushFn: () => Promise<void>,
+        features: ScaleBunFeatures = {},
+    ): Promise<BootstrapResult | null> {
+        // ── 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 as { replay?: { captureMode?: string } } | null | undefined;
+        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 as object), 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 as any)?.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: string, initial = false): void => {
+            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: any) {
+            logger.warn('[Bootstrap] Failed to start deep-link collection:', err?.message);
+        }
+
+        // ── Start auto-flush ───────────────────────────────────
+        scheduler.start(this.config.flushIntervalMs);
+
+        // ── Register features ──────────────────────────────────
+        const featureContext: 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: Record<string, unknown> = { ...(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 as Partial<SessionReplayConfig>,
+                        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 = (): void => {
+                        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: string, source: string) => {
+                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 as any).onScreenChange) {
+                        (sm as any).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 as any).setCurrentScreen(screenName);
+                        (pf as any).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 as unknown as { unref?: () => void }).unref?.();
+        } catch (err: any) {
+            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.
+     */
+    private installOrientationTracking(): void {
+        if (this._orientationSub) return; // idempotent — bootstrap can run more than once
+        try {
+            const { Dimensions } = require('react-native');
+            const verdict = (w: number, h: number): 'portrait' | 'landscape' => (w > h ? 'landscape' : 'portrait');
+            const win = Dimensions.get('window');
+            this._lastOrientation = verdict(win.width, win.height);
+            this._orientationSub = Dimensions.addEventListener('change', ({ window }: { window: { width: number; height: number } }) => {
+                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.
+     */
+    private installMemoryWarningTracking(): void {
+        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 */ }
+    }
+
+    private _buildAnalyticsSession() {
+        return {
+            sessionId: generateSessionId(),
+            deviceId: getDeviceId(),
+            startedAt: Date.now(),
+            idleThresholdMs: this.config?.idleThresholdMs,
+            metadata: { buildType: (__DEV__ ? 'debug' : 'release') as 'debug' | 'release' },
+        };
+    }
+
+    /** Get the validated config */
+    getConfig(): ScaleBunConfig | null {
+        return this.config;
+    }
+
+    /** Tear down all features */
+    teardown(): void {
+        this._sessionsQuotaUnsub?.();
+        this._sessionsQuotaUnsub = null;
+        this._deepLinkUnsubscribe?.();
+        this._deepLinkUnsubscribe = null;
+        uninstallAlertInstrumentation();
+        uninstallConsoleIntegration();
+        this.featureRegistry.teardownAll();
+    }
+}