@scalebun/react-native 1.0.2 → 1.0.3

package/src/bootstrap/SDKBootstrapper.ts

@@ -1,585 +1,609 @@
-/**
- * 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 { 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 { nativeCapture } from '../features/session/nativeCapture';
-import { installAlertInstrumentation, uninstallAlertInstrumentation } from '../features/replay/integrations/alert/alertInstrumentation';
-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';
-
-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;
-    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 ────────────────────────────────────
-        const result = ConfigSchema.safeParse(rawConfig);
-        if (!result.success) {
-            logger.error('Invalid configuration:', result.error.format());
-            return null;
-        }
-
-        this.config = result.data;
-        // 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) {
-            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),
-        );
-
-        const clientKey = this.config.clientKey;
-        coreContainer.register(
-            'Dispatcher',
-            new Dispatcher(async (batch) => {
-                const headers: Record<string, string> = {};
-                if (clientKey) {
-                    headers['x-scalebun-client-key'] = clientKey;
-                }
-                await httpClient.post(ENDPOINTS.EVENTS, {
-                    deviceId: getDeviceId(),
-                    events: batch,
-                }, headers);
-            }),
-        );
-
-        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
-            logger.info('[Bootstrap] SaaS mode: clientKey auth active, skipping legacy handshake');
-        } else {
-            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.
-                            adapter.startAnalyticsSession(this._buildAnalyticsSession()).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) ───────────────
-        if (features.replay !== false) {
-            try {
-                logger.debug('[Bootstrap] Initializing unified SessionManager');
-                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.
-                    {
-                        ...(this.config.replay ? { sessionReplay: this.config.replay } : {}),
-                        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);
-
-                    // 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());
-
-                        // 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").
-                        // Start it once the analytics session id exists so startSession
-                        // adopts it (one-row merge) instead of minting an orphan row.
-                        // Gated by the same finalizeOnBackground flag as the per-foreground
-                        // recording path above.
-                        if (this.config.finalizeOnBackground) {
-                            analyticsStarted
-                                .then(() => {
-                                    if (!sessionManager.isActive) {
-                                        sessionManager.startSession();
-                                    }
-                                })
-                                .catch(() => { });
-                        } else {
-                            analyticsStarted.catch(() => { });
-                        }
-                    }
-                }
-
-                // 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;
-                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 */ }
-
-                logger.debug(`[AutoScreen] Screen → '${screenName}' (source: ${source})`);
-            });
-            detector.start();
-            logger.info('[Bootstrap] Auto screen detection started');
-        } 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(),
-        });
-
-        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._deepLinkUnsubscribe?.();
-        this._deepLinkUnsubscribe = null;
-        uninstallAlertInstrumentation();
-        this.featureRegistry.teardownAll();
-    }
-}
+/**
+ * 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 { 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 { nativeCapture } from '../features/session/nativeCapture';
+import { installAlertInstrumentation, uninstallAlertInstrumentation } from '../features/replay/integrations/alert/alertInstrumentation';
+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';
+
+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;
+    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 ────────────────────────────────────
+        const result = ConfigSchema.safeParse(rawConfig);
+        if (!result.success) {
+            logger.error('Invalid configuration:', result.error.format());
+            return null;
+        }
+
+        this.config = result.data;
+        // 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) {
+            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),
+        );
+
+        const clientKey = this.config.clientKey;
+        coreContainer.register(
+            'Dispatcher',
+            new Dispatcher(async (batch) => {
+                const headers: Record<string, string> = {};
+                if (clientKey) {
+                    headers['x-scalebun-client-key'] = clientKey;
+                }
+                await httpClient.post(ENDPOINTS.EVENTS, {
+                    deviceId: getDeviceId(),
+                    events: batch,
+                }, headers);
+            }),
+        );
+
+        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
+            logger.info('[Bootstrap] SaaS mode: clientKey auth active, skipping legacy handshake');
+        } else {
+            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.
+                            adapter.startAnalyticsSession(this._buildAnalyticsSession()).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) ───────────────
+        if (features.replay !== false) {
+            try {
+                logger.debug('[Bootstrap] Initializing unified SessionManager');
+                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.
+                    {
+                        ...(this.config.replay ? { sessionReplay: this.config.replay } : {}),
+                        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);
+
+                    // 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());
+
+                        // 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").
+                        // Start it once the analytics session id exists so startSession
+                        // adopts it (one-row merge) instead of minting an orphan row.
+                        // Gated by the same finalizeOnBackground flag as the per-foreground
+                        // recording path above.
+                        if (this.config.finalizeOnBackground) {
+                            analyticsStarted
+                                .then(() => {
+                                    if (!sessionManager.isActive) {
+                                        sessionManager.startSession();
+                                    }
+                                })
+                                .catch(() => { });
+                        } else {
+                            analyticsStarted.catch(() => { });
+                        }
+                    }
+                }
+
+                // 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;
+                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 */ }
+
+                logger.debug(`[AutoScreen] Screen → '${screenName}' (source: ${source})`);
+            });
+            detector.start();
+            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(),
+        });
+
+        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._deepLinkUnsubscribe?.();
+        this._deepLinkUnsubscribe = null;
+        uninstallAlertInstrumentation();
+        this.featureRegistry.teardownAll();
+    }
+}