@scalebun/react-native 1.0.2 → 1.0.3

package/src/public/ScaleBunFacade.ts

@@ -1,1479 +1,1479 @@
-/**
- * ScaleBun SDK — Public Facade
- *
- * Single clean entry point for the ScaleBun SDK.
- * Delegates initialization to SDKBootstrapper, which handles config validation,
- * core service setup, handshake, and feature registration via FeatureRegistry.
- *
- * Config model preserved exactly: projectId, publishableKey, apiBaseUrl.
- * Features are default-on with explicit opt-out via `features: { replay: false }`.
- */
-
-import { noThrow, safeAsync } from '../core/lifecycle/crashSafe';
-import { logger } from '../core/logger/internalLogger';
-import { createEnvelope } from '../pipeline/envelope/envelope';
-import { generateEventId } from '../features/replay/core/ids/sessionId';
-import { PersistentQueue } from '../pipeline/queue/persistentQueue';
-import { MemoryBackend, createStorageBackend } from '../storage/StorageBackend';
-import { HttpClient } from '../transport/http/httpClient';
-import { getDeviceId } from '../core/id/deviceId';
-import { coreContainer } from '../core/di/container';
-import { flushQueue } from '../pipeline/queue/flushQueue';
-import {
-    enableDebug as _enableDebug,
-    disableDebug as _disableDebug,
-    isDebugEnabled,
-    addBreadcrumb as _addBreadcrumb,
-    ping as _ping,
-    _getStream,
-    _setFlushFn,
-    _getSessionManager,
-    _getAutoScreenDetector,
-    getPerformanceFeature as _getPerformanceFeature,
-    requestExport as _requestExport,
-    buildDebugConfigFromInitConfig,
-    applyFeatureGatesToDebugConfig,
-    sendDebugMetric,
-} from '../debug';
-import type { DebugConfig } from '../debug';
-import { ReplaySdk } from '../features/replay/public/api';
-import type {
-    ReplayUser,
-    ReplayBreadcrumb,
-    ReplayPrivacyOptions,
-} from '../features/replay/public/types';
-import { SDKBootstrapper } from '../bootstrap/SDKBootstrapper';
-import { EventTracker } from '../analytics/EventTracker';
-import {
-    emitAutomaticEvent,
-    type AutomaticEventName,
-} from '../analytics/automaticEvents';
-import { resolveEventLane } from '../analytics/eventLane';
-import { ConfigManager } from '../config/ConfigManager';
-import { SDK_VERSION } from '../core/constants/version';
-import { EngageTransport, type SubmitStage } from '../features/engage/EngageTransport';
-import {
-    getNativePushToken,
-    subscribeNativePushTokenRefresh,
-} from '../features/engage/engagePushTokenBridge';
-import { requestNativeStoreReview } from '../features/engage/engageStoreReviewBridge';
-import { PushManager } from '../push/PushManager';
-import type { EnablePushOptions, EnablePushResult, PushNotification } from '../push/types';
-import { ENGAGE_SCHEMA_VERSION } from '../features/engage/engageTypes';
-import { EngageThrottleStore } from '../features/engage/engageThrottle';
-import { EngageTestSeenStore } from '../features/engage/engageTestSeenStore';
-import { engageSignals } from '../features/engage/engageSignals';
-import type {
-    EngageAttachmentDraft,
-    EngageConfigContext,
-    EngageConfigResponse,
-    EngageEventInput,
-    EngageResponseInput,
-    RatingFunnelEventInput,
-    SurveyImpressionInput,
-} from '../features/engage/engageTypes';
-import { PerformanceFeature } from '../features/performance/PerformanceFeature';
-import { SessionManager } from '../features/session/SessionManager';
-import type { JourneyEventType } from '../features/session/sessionTypes';
-import { getCrashReporter } from '../features/crash/CrashReporter';
-import { triggerNativeCrash } from '../features/crash/nativeCrashBridge';
-import { updateSkanConversionValue, isSkanAvailable, type SkanCoarseValue } from '../features/skan/skanBridge';
-import { SkanConversionManager } from '../features/skan/skanConversionManager';
-import {
-    isInstallReferrerAvailable,
-    getInstallReferrer,
-    captureInstallReferrerOnce,
-    type InstallReferrerSink,
-} from '../features/install-referrer/installReferrer';
-import type {
-    ScaleBunInitConfig,
-    ScaleBunUser,
-    ScaleBunFeatures,
-    SimplifiedInitConfig,
-    DebugConnectionConfig,
-    PrivacyConfig,
-    BrandingConfig,
-    ExportPresetName,
-    SimplifiedExportOptions,
-    ExportResult,
-} from './types';
-
-class ScaleBunFacade {
-    private initialized = false;
-    /** In-flight init promise — guards against a second init() racing before the first resolves. */
-    private _initInFlight: Promise<void> | null = null;
-    private bootstrapper = new SDKBootstrapper();
-    private _features: ScaleBunFeatures = {};
-    private _performanceFeature: PerformanceFeature | null = null;
-    private _privacyConfig: PrivacyConfig = {};
-    private _brandingConfig: BrandingConfig = {};
-    private _clientKey: string | undefined = undefined;
-    private _apiBaseUrl: string | undefined = undefined;
-    private _engageTransport: EngageTransport | null = null;
-    private _engageTokenUnsubscribe: (() => void) | null = null;
-    private _pushManager: PushManager | null = null;
-    /** Phase 1 envelope event-tracking lane (POST /v1/batch). Null until init with appId. */
-    private _eventTracker: EventTracker | null = null;
-    /** External identity last supplied through identify(); used by config targeting. */
-    private _identifiedUserId: string | null = null;
-    /** Identity supplied while async initialization is still in flight. */
-    private _pendingIdentity: {
-        userId: string;
-        traits?: Record<string, any>;
-    } | null = null;
-    private _configManager: ConfigManager | null = null;
-    /** Signature of the last identity POSTed to the ingestion identify endpoint, to skip redundant re-sends. */
-    private _lastIngestionIdentityKey: string | null = null;
-    /** Phase 3: auto-applies SKAN conversion values from the server schema (iOS only). */
-    private _skanManager: SkanConversionManager | null = null;
-
-    /**
-     * Pre-init memory buffer.
-     * Events tracked before init() completes are buffered here,
-     * then drained into the real persistent queue post-init.
-     */
-    private _preInitBuffer: PersistentQueue = new PersistentQueue(new MemoryBackend(), {
-        enabled: false,
-        maxEntries: 500,
-        maxBytes: 1_048_576, // 1 MB
-        redactBeforeWrite: false, // No redaction for memory-only buffer
-    });
-
-    /** Resolve the active queue (DI container or pre-init buffer) */
-    private _getQueue(): PersistentQueue {
-        if (this.initialized) {
-            try {
-                return coreContainer.get<PersistentQueue>('PersistentQueue');
-            } catch {
-                // Container not ready yet — shouldn't happen post-init
-            }
-        }
-        return this._preInitBuffer;
-    }
-
-    // ─── Initialization ─────────────────────────────────────────────────
-
-    /**
-     * Initialize the ScaleBun SDK.
-     *
-     * **Simplified usage** (recommended):
-     * ```ts
-     * await ScaleBun.init({
-     *   projectId: 'proj_xxx',
-     *   publishableKey: 'pk_xxx',
-     *   apiBaseUrl: 'https://api.scalebun.com',
-     *   debug: true,
-     * });
-     * ```
-     *
-     * Accepts both `SimplifiedInitConfig` (new) and `ScaleBunInitConfig` (legacy).
-     * If `debug` key is present, auto-connects to the desktop debugger.
-     */
-    public async init(rawConfig: SimplifiedInitConfig | ScaleBunInitConfig | any) {
-        if (this.initialized) return;
-        // Coalesce concurrent init() calls: a second call before the first resolves
-        // must not run a second bootstrap (which would double-register lifecycle
-        // listeners and repeat the backend handshake).
-        if (this._initInFlight) return this._initInFlight;
-        this._initInFlight = safeAsync(async () => {
-            if (this.initialized) return;
-
-            // Store feature flags (all default true)
-            this._features = rawConfig?.features ?? {};
-            if (rawConfig?.sessionReplay !== undefined) {
-                this._features.replay = rawConfig.sessionReplay;
-            }
-
-            // Store privacy config if provided
-            if (rawConfig?.privacy) {
-                this._privacyConfig = rawConfig.privacy;
-            }
-
-            // Phase 3 (entitlements) — COST suppression: don't even register a
-            // collector the org isn't entitled to (no traffic → no server cost).
-            // Read from the cached /config (sync); first run has no cache → fail-open
-            // (all entitled), and the server still rejects a closed feature anyway.
-            const ent = ConfigManager.readCachedEntitlements();
-            const effectiveFeatures: ScaleBunFeatures = {
-                ...this._features,
-                replay: this._features.replay !== false && ent.replay !== false,
-                network: this._features.network !== false && ent.networkMonitoring !== false,
-                crashes: this._features.crashes !== false && ent.crashReporting !== false,
-                performance: this._features.performance !== false && ent.performanceMonitoring !== false,
-            };
-
-            // Backend bootstrap (non-blocking for debug connection)
-            // If the backend is unreachable, the debug WebSocket should still connect.
-            try {
-                const result = await this.bootstrapper.bootstrap(
-                    rawConfig,
-                    (name, payload) => this.track(name, payload),
-                    () => this.flush() as Promise<void>,
-                    effectiveFeatures,
-                );
-
-                if (result) {
-                    this.initialized = true;
-                    this._clientKey = result.config.clientKey;
-                    this._apiBaseUrl = result.config.apiBaseUrl;
-
-                    // Phase 1 envelope tracking lane. Enabled when an appId is supplied
-                    // (and not explicitly disabled). Runs alongside the replay lane.
-                    this._maybeStartEventTracker(rawConfig);
-                    if (this._pendingIdentity) {
-                        const pending = this._pendingIdentity;
-                        this._pendingIdentity = null;
-                        this.identify(pending.userId, pending.traits);
-                    }
-
-                    // Drain pre-init buffer into the real persistent queue
-                    const realQueue = coreContainer.get<PersistentQueue>('PersistentQueue');
-                    const buffered = this._preInitBuffer.popBatch(this._preInitBuffer.length());
-                    if (buffered.length > 0) {
-                        logger.debug(`[ScaleBun] Draining ${buffered.length} pre-init events into persistent queue`);
-                        for (const envelope of buffered) {
-                            realQueue.add(envelope);
-                        }
-                    }
-
-                    // Grab a reference to the PerformanceFeature for the public API
-                    const perfFeature = result.featureRegistry.get('performance');
-                    if (perfFeature && perfFeature instanceof PerformanceFeature) {
-                        this._performanceFeature = perfFeature;
-                    }
-                }
-            } catch (bootstrapErr: any) {
-                logger.warn('[ScaleBun] Backend bootstrap failed (non-blocking):', bootstrapErr?.message);
-                // Continue — debug connection is independent of backend API
-            }
-
-            // Auto debug connection from init config — runs regardless of backend status
-            const debugConfig = (rawConfig?.desktopDebug ?? rawConfig?.debug) as DebugConnectionConfig | undefined;
-            if (debugConfig) {
-                this._autoEnableDebug(debugConfig);
-            }
-        });
-        try {
-            return await this._initInFlight;
-        } finally {
-            this._initInFlight = null;
-        }
-    }
-
-    private _autoEnableDebug(debugConfig: DebugConnectionConfig): void {
-        try {
-            const dbgConfig = buildDebugConfigFromInitConfig(debugConfig);
-            if (!dbgConfig) return;
-            (dbgConfig as any).__skipDeprecationWarning = true;
-            this.enableDebug(dbgConfig);
-            logger.info('[ScaleBun] Debug auto-connected via init({ debug }).');
-        } catch (err: any) {
-            logger.warn('[ScaleBun] Auto debug connection failed:', err?.message);
-        }
-    }
-
-    /** Boot the Phase 1 envelope tracking lane if an appId is configured. */
-    private _maybeStartEventTracker(rawConfig: any): void {
-        try {
-            const appId = rawConfig?.appId;
-            const enabled = rawConfig?.eventTracking !== false;
-            const clientKey = this._clientKey ?? rawConfig?.clientKey;
-            const apiBaseUrl = this._apiBaseUrl ?? rawConfig?.apiBaseUrl;
-            if (!enabled || !appId || !clientKey || !apiBaseUrl) {
-                if (enabled && !appId) {
-                    logger.info('[ScaleBun] Envelope event tracking disabled — no appId in init config.');
-                }
-                return;
-            }
-            // Phase 3: auto-apply SKAdNetwork conversion values from the server-side
-            // CV schema (iOS only; no-op elsewhere). Created BEFORE the tracker so the
-            // onEvent hook is live for the very first event (first_open).
-            if (isSkanAvailable()) {
-                this._skanManager = new SkanConversionManager({ apiBaseUrl, clientKey });
-                this._skanManager.refreshSchema().catch(() => {});
-            }
-            this._eventTracker = new EventTracker({
-                appId,
-                clientKey,
-                apiBaseUrl,
-                platform: rawConfig?.platform ?? 'react_native',
-                appVersion: rawConfig?.appVersion,
-                osVersion: rawConfig?.osVersion,
-                autoLifecycleEvents: rawConfig?.autoLifecycleEvents !== false,
-                // Backward-compatible opt-in: existing init-only integrations do
-                // not begin uploading the new automatic collector stream merely
-                // because they upgraded the package. ScaleBunProvider sets this
-                // to true unless the integrator explicitly disables it.
-                automaticEventTracking:
-                    rawConfig?.automaticEventTracking === true,
-                flushIntervalMs: rawConfig?.flushIntervalMs,
-                context: rawConfig?.context,
-                // Use the same foreground id as replay/journey capture. The
-                // callback is resolved per event because the session subsystem
-                // may start after this tracker is constructed.
-                sessionIdProvider: () => {
-                    const manager = SessionManager.getExistingInstance();
-                    return manager?.currentSessionId
-                        ?? manager?.getBackendTransport()?.analyticsSessionId
-                        ?? null;
-                },
-                // Feed every tracked event to the SKAN CV manager (iOS; no-op otherwise).
-                onEvent: (eventName, revenue) => this._skanManager?.onEvent(eventName, revenue),
-            });
-            this._eventTracker.start();
-            logger.info('[ScaleBun] Envelope event tracking started → /v1/batch.');
-
-            // Android: capture the Play Install Referrer once per install → feeds the
-            // deterministic click_id path + a one-off install_referrer event (UTM/gclid).
-            // Fire-and-forget; no-op off Android.
-            this._captureInstallReferrer(this._eventTracker);
-
-            // Phase 4: runtime config (flags / remote config / experiments / rollouts).
-            // Resolves locally; exposure + stamps flow through the event lane above.
-            const tracker = this._eventTracker;
-            this._configManager = new ConfigManager({
-                apiBaseUrl,
-                clientKey,
-                installationId: tracker.ids.installationId,
-                emitExposure: (experiment, variant) => tracker.track('experiment_exposure', { experiment, variant }),
-                stamp: (key, value) => tracker.stamp(key, value),
-            });
-            this._configManager.refresh().catch(() => {});
-        } catch (err: any) {
-            logger.warn('[ScaleBun] Failed to start envelope event tracking:', err?.message);
-        }
-    }
-
-    /**
-     * Android-only: read the Play Install Referrer once per install and route it into
-     * attribution. `scalebun_click_id` → the deterministic click path; the full
-     * referrer (utm_source/gclid/…) rides on a one-off `install_referrer` event. A
-     * `null` fetch (Play unavailable/transient) is not marked captured, so a later
-     * launch retries while Play still has the referrer. Never throws.
-     */
-    private _captureInstallReferrer(tracker: EventTracker): void {
-        try {
-            if (!isInstallReferrerAvailable()) return;
-            const storage = createStorageBackend();
-            const KEY = 'scalebun_install_referrer_done';
-            const sink: InstallReferrerSink = {
-                alreadyCaptured: () => { try { return storage.get(KEY) === '1'; } catch { return false; } },
-                markCaptured: () => { try { storage.set(KEY, '1'); } catch { /* no-throw */ } },
-                setClickId: (id) => tracker.setAttributionClickId(id),
-                emit: (name, props) => tracker.track(name, props as Record<string, any>),
-                fetch: () => getInstallReferrer(),
-            };
-            void captureInstallReferrerOnce(sink);
-        } catch (err: any) {
-            logger.warn('[ScaleBun] Install Referrer capture failed:', err?.message);
-        }
-    }
-
-    /**
-     * Phase 1 envelope event tracking API (POST /v1/batch).
-     * Methods are no-ops (never throw) until init() is called with an `appId`.
-     */
-    public get events() {
-        const tracker = this._eventTracker;
-        return {
-            track: (eventName: string, properties?: Record<string, any>) => tracker?.track(eventName, properties),
-            identify: (userId: string, traits?: Record<string, any>) => tracker?.identify(userId, traits),
-            trackPurchase: (input: { revenue: number; currency: string; transactionId: string; [k: string]: any }) =>
-                tracker?.trackPurchase(input),
-            setIdentifiers: (ids: { idfa?: string; gaid?: string; idfv?: string }) => tracker?.setIdentifiers(ids),
-            // Phase 2: record a deferred deep-link click token for deterministic install attribution.
-            setAttributionClickId: (clickId: string) => tracker?.setAttributionClickId(clickId),
-            flush: () => tracker?.flush() ?? Promise.resolve(),
-            newSession: () => tracker?.newSession(),
-            ids: () => tracker?.ids ?? null,
-            // Phase 3: update the SKAdNetwork conversion value (iOS only; no-op elsewhere).
-            updateSkanConversionValue: (value: number, coarseValue?: SkanCoarseValue, lockWindow?: boolean) =>
-                updateSkanConversionValue(value, coarseValue, lockWindow),
-        };
-    }
-
-    /**
-     * Phase 4: runtime config delivered via GET /v1/config. All resolution is local
-     * and non-throwing; values default sensibly until init() runs / config is fetched.
-     *
-     *   ScaleBun.config.get('max_items', 10)
-     *   ScaleBun.flags.isEnabled('new_checkout')
-     *   ScaleBun.rollouts.isOn('beta_paywall')
-     *   ScaleBun.experiments.variant('checkout_cta')   // → 'control' | 'treatment' | null
-     */
-    public get config() {
-        const cm = this._configManager;
-        return {
-            get: <T = any>(key: string, fallback: T): T => (cm ? cm.get(key, fallback) : fallback),
-            refresh: () => cm?.refresh() ?? Promise.resolve(),
-        };
-    }
-
-    public get flags() {
-        const cm = this._configManager;
-        return { isEnabled: (key: string) => cm?.isEnabled(key) ?? false };
-    }
-
-    public get rollouts() {
-        const cm = this._configManager;
-        return { isOn: (key: string) => cm?.rolloutIsOn(key) ?? false };
-    }
-
-    public get experiments() {
-        const cm = this._configManager;
-        return { variant: (key: string): string | null => cm?.variant(key) ?? null };
-    }
-
-    /** Convenience: emit a Phase 1 purchase event (revenue + currency + transaction_id). */
-    public trackPurchase(input: { revenue: number; currency: string; transactionId: string; [k: string]: any }): void {
-        noThrow(() => this._eventTracker?.trackPurchase(input));
-    }
-
-    /**
-     * Phase 3: set the SKAdNetwork fine conversion value (0–63), optionally with a
-     * SKAN 4.0 coarse value and window-lock. iOS only — a no-op on Android / Expo Go.
-     */
-    public updateSkanConversionValue(value: number, coarseValue?: SkanCoarseValue, lockWindow?: boolean): void {
-        noThrow(() => { void updateSkanConversionValue(value, coarseValue, lockWindow); });
-    }
-
-    // ─── Feature Flags ──────────────────────────────────────────────────
-
-    /** Get the current feature flags (consumed by enableDebug) */
-    public getFeatureFlags(): ScaleBunFeatures {
-        return this._features;
-    }
-
-    // ─── Identity ───────────────────────────────────────────────────────
-
-    /** Identify a user by ID and optional traits */
-    public identify(userId: string, traits?: Record<string, any>) {
-        return noThrow(() => {
-            this._identifiedUserId = userId;
-            if (!this.initialized) {
-                this._pendingIdentity = { userId, traits };
-                return;
-            }
-            this._pendingIdentity = null;
-            // Forward to the Phase 1 envelope lane (sets user_id for subsequent events).
-            this._eventTracker?.identify(userId, traits);
-            this.track('$identify', { id: userId, ...traits });
-            const sessionId = SessionManager.getExistingInstance()?.currentSessionId;
-            if (this._clientKey && sessionId) {
-                // Skip the network POST when the same identity was already sent for this
-                // session (repeat identify() with identical traits is a no-op upsert).
-                const identityKey = `${sessionId}|${userId}|${JSON.stringify(traits ?? {})}`;
-                if (identityKey !== this._lastIngestionIdentityKey) {
-                    this._lastIngestionIdentityKey = identityKey;
-                    const user: ScaleBunUser = {
-                        id: userId,
-                        name: traits?.name,
-                        email: traits?.email,
-                        properties: traits,
-                    };
-                    this._callIngestionIdentify(sessionId, user).catch(() => {
-                        // Re-arm on failure so a later retry is not suppressed.
-                        this._lastIngestionIdentityKey = null;
-                    });
-                }
-            }
-        });
-    }
-
-    /**
-     * Stable public alias for {@link identify}. Part of the minimal public push
-     * API surface (ScaleBun.init / identifyUser / enablePush) that stays
-     * identical across RN versions and future platforms.
-     */
-    public identifyUser(userId: string, traits?: Record<string, any>) {
-        return this.identify(userId, traits);
-    }
-
-    /** POST user identity to the SaaS ingestion identify endpoint */
-    private async _callIngestionIdentify(sessionId: string, user: ScaleBunUser): Promise<void> {
-        if (!this._clientKey || !this._apiBaseUrl) return;
-        const url = `${this._apiBaseUrl}/ingestion/sessions/${sessionId}/identify`;
-        try {
-            await fetch(url, {
-                method: 'POST',
-                headers: {
-                    'Content-Type': 'application/json',
-                    'x-scalebun-client-key': this._clientKey,
-                },
-                body: JSON.stringify({
-                    userId: user.id,
-                    username: user.name,
-                    email: user.email,
-                    properties: user.properties,
-                }),
-            });
-        } catch (err: any) {
-            logger.warn('[ScaleBun] ingestion identify failed:', err?.message);
-        }
-    }
-
-    /** Set user identity (for session context) */
-    public setUser(user: ScaleBunUser) {
-        return noThrow(() => {
-            this.identify(user.id, {
-                name: user.name,
-                email: user.email,
-                ...user.attributes,
-            });
-        });
-    }
-
-    /** Clear user identity */
-    public clearUser() {
-        return noThrow(() => {
-            this._identifiedUserId = null;
-            this._pendingIdentity = null;
-            if (!this.initialized) return;
-            this._eventTracker?.clearIdentity();
-            this.track('$clear_user', {});
-        });
-    }
-
-    /**
-     * Submit in-app rating (1-5 stars).
-     * Attaches to current session when available; otherwise sends standalone.
-     * Never throws.
-     */
-    public submitRating(input: {
-        rating: number;
-        comment?: string;
-        source?: 'in_app' | 'prompt' | 'manual';
-        /** [ADDITIVE] client-generated UUID for app-rating idempotency (contract §1.4, D8). */
-        clientRatingId?: string;
-    }) {
-        return safeAsync(async () => {
-            if (!this._clientKey || !this._apiBaseUrl) return { ok: false, reason: 'sdk_not_configured' as const };
-            const rating = Math.round(Number(input?.rating));
-            if (!Number.isFinite(rating) || rating < 1 || rating > 5) {
-                return { ok: false, reason: 'invalid_rating' as const };
-            }
-
-            const sessionId = this.getActiveSessionId();
-            const meta = SessionManager.getExistingInstance()?.currentSessionMetadata;
-            const path = sessionId
-                ? `/ingestion/sessions/${sessionId}/rating`
-                : `/ingestion/ratings`;
-            const url = `${this._apiBaseUrl}${path}`;
-
-            try {
-                const res = await fetch(url, {
-                    method: 'POST',
-                    headers: {
-                        'Content-Type': 'application/json',
-                        'x-scalebun-client-key': this._clientKey,
-                    },
-                    body: JSON.stringify({
-                        rating,
-                        comment: input.comment,
-                        source: input.source ?? 'in_app',
-                        appVersion: meta?.appVersion,
-                        platform: meta?.platform,
-                        // [ADDITIVE] idempotency + versioning (contract §1.4); omitted when unset.
-                        ...(input.clientRatingId ? { clientRatingId: input.clientRatingId } : {}),
-                        schemaVersion: ENGAGE_SCHEMA_VERSION,
-                    }),
-                });
-                if (!res.ok) {
-                    logger.warn('[ScaleBun] submitRating non-ok', res.status);
-                    return { ok: false, reason: 'http_error' as const, status: res.status };
-                }
-                return { ok: true as const };
-            } catch (err: any) {
-                logger.warn('[ScaleBun] submitRating failed:', err?.message);
-                return { ok: false, reason: 'network_error' as const };
-            }
-        });
-    }
-
-    private getActiveSessionId(): string | null {
-        try {
-            return SessionManager.getExistingInstance()?.currentSessionId ?? null;
-        } catch {}
-        return null;
-    }
-
-    // ─── Engage ─────────────────────────────────────────────────────────
-
-    /**
-     * Lazily resolve the Engage transport. Requires a configured SaaS clientKey +
-     * apiBaseUrl (same gate as the rating/ingestion lanes); returns null otherwise.
-     * The transport mirrors the existing BackendSessionAdapter outbox: upload lanes
-     * batch-flush and re-queue on failure, the config GET is a direct fetch.
-     */
-    private _getEngageTransport(): EngageTransport | null {
-        if (!this._clientKey || !this._apiBaseUrl) return null;
-        if (!this._engageTransport) {
-            this._engageTransport = new EngageTransport({
-                endpoint: this._apiBaseUrl,
-                clientKey: this._clientKey,
-            });
-        }
-        return this._engageTransport;
-    }
-
-    /**
-     * Engage surface namespace (foundation: transport + native push-token plumbing).
-     *
-     * Rendering of campaigns/in-app messages is a SHARED cross-platform JS overlay
-     * (D4) built in a later stage. This namespace exposes only the foundation:
-     * versioned config fetch, idempotent response/event upload (via the existing
-     * outbox), and native push-token registration on both platforms.
-     */
-    public engage = {
-        /** Current external identity, forwarded by the provider for segment targeting. */
-        getIdentifiedUserId: (): string | undefined =>
-            this._identifiedUserId ?? undefined,
-
-        /**
-         * Fetch the versioned Engage config (campaigns + in-app messages).
-         *
-         * slice-agent: the shared cross-platform JS overlay renderer consumes this
-         * payload (EngageConfigResponse.campaigns / .inAppMessages) in a later stage.
-         */
-        fetchConfig: async (
-            context?: EngageConfigContext,
-        ): Promise<EngageConfigResponse | null> => {
-            const transport = this._getEngageTransport();
-            if (!transport) return null;
-            const [engageConfig, coachConfig] = await Promise.all([
-                transport.fetchEngageConfig(context),
-                transport.fetchCoachConfig(),
-            ]);
-            if (!engageConfig && !coachConfig) return null;
-            const coachMessages = (coachConfig?.tours ?? [])
-                .filter((tour) => Array.isArray(tour.steps) && tour.steps.length > 0)
-                .map((tour) => ({
-                    id: tour.id,
-                    layout: 'tooltip' as const,
-                    trigger: 'app_open',
-                    variantKey: 'coachmark_spotlight',
-                    revision: String(tour.version),
-                    preview: tour.preview === true,
-                    spec: {
-                        title: tour.name,
-                        body: tour.steps[0]?.body ?? tour.name,
-                        anchorKey: tour.steps[0]?.anchorKey,
-                        ext: {
-                            coachTourId: tour.id,
-                            coachTourVersion: tour.version,
-                            steps: tour.steps,
-                        },
-                    },
-                }));
-            return {
-                configVersion: engageConfig?.configVersion ?? 1,
-                serverTime: engageConfig?.serverTime ?? new Date().toISOString(),
-                campaigns: engageConfig?.campaigns ?? [],
-                inAppMessages: [...(engageConfig?.inAppMessages ?? []), ...coachMessages],
-            };
-        },
-
-        /** Internal bridge used by the shared renderer to feed standalone tour analytics. */
-        trackCoachmarkEvent: (name: string, properties: Record<string, unknown>): void => {
-            this.track(name, properties as Record<string, any>);
-        },
-
-        /**
-         * DEBUG/DEV ONLY — clear the persisted in-app/campaign frequency-cap state
-         * (every `scalebun_engage_throttle:*` key: impressions, showOnce/completed, cooldown).
-         * Lets a tester see throttled/dismissed messages again WITHOUT uninstalling the
-         * app. Does NOT change the device id (identity is preserved). Returns the number
-         * of cleared entries. NOT a substitute for the real fix (revision-scoped state +
-         * test-preview bypass already make normal Send Test work without this).
-         */
-        clearInAppMessageCache: (): number => {
-            return noThrow(() => new EngageThrottleStore().clearAll() + new EngageTestSeenStore().clear()) ?? 0;
-        },
-
-        /**
-         * DEBUG/DEV ONLY — alias of {@link clearInAppMessageCache} with the broader name
-         * used in docs. Resets all on-device in-app frequency/dismiss/impression state so
-         * the next config poll can show messages again. Identity (device id) is untouched.
-         */
-        resetInAppState: (): number => {
-            // Clears BOTH lanes: production frequency/dismiss/impression state (throttle
-            // store) AND the one-shot test-seen store — so a dismissed test reappears after
-            // a debug reset (the "block forever UNLESS debug reset" contract). Identity
-            // (device id) is a separate key and stays untouched.
-            return noThrow(() => new EngageThrottleStore().clearAll() + new EngageTestSeenStore().clear()) ?? 0;
-        },
-
-        /**
-         * Force an immediate flush of queued in-app events. The provider calls this right
-         * after a TEST preview's impression/dismiss ACK so the backend consumes the
-         * one-shot preview row promptly — a fast close→kill→reopen can't re-serve a
-         * still-`delivered` test. Best-effort, never throws.
-         */
-        flushEvents: (): void => {
-            noThrow(() => this._getEngageTransport()?.flushEventsNow());
-        },
-
-        /**
-         * DEBUG/DEV ONLY — force a fresh config fetch (deviceId in context) and return the
-         * in-app messages the backend is serving THIS device right now, including any
-         * queued test previews (`preview:true`). Use it to verify Send Test targeting/
-         * delivery without rendering. Logs a one-line summary for the dev console.
-         */
-        debugFetchInAppMessages: async (
-            context?: EngageConfigContext,
-        ): Promise<EngageConfigResponse['inAppMessages']> => {
-            const cfg = await (this._getEngageTransport()?.fetchEngageConfig(context) ?? Promise.resolve(null));
-            const messages = cfg?.inAppMessages ?? [];
-            const previews = messages.filter((m) => m.preview === true || m.isTest === true);
-            logger.info(
-                `[Engage] debugFetchInAppMessages → ${messages.length} message(s), ${previews.length} test preview(s)`,
-            );
-            return messages;
-        },
-
-        /** Upload a survey/NPS/feedback response (idempotent, rides the outbox). */
-        submitResponse: (input: EngageResponseInput): void => {
-            noThrow(() => this._getEngageTransport()?.uploadEngageResponse(input));
-        },
-
-        /**
-         * [P3-e] Submit a response carrying native attachments (screenshot/voice).
-         * Presigns + PUTs bytes direct to storage, then enqueues the response with
-         * key-only metadata linked by responseId. Falls back to a plain response
-         * (no media) when storage is disabled. Best-effort, never throws.
-         */
-        submitResponseWithAttachments: (
-            input: EngageResponseInput,
-            attachments: EngageAttachmentDraft[],
-        ): void => {
-            noThrow(() => {
-                void this._getEngageTransport()?.submitResponseWithAttachments(input, attachments);
-            });
-        },
-
-        /**
-         * [Slice D5] CONFIRMED response submit for the in-prompt submitting→success→error
-         * UI. UNLIKE submitResponse*, this AWAITS real server persistence (presign+PUT any
-         * audio/screenshot bytes, then a direct response POST) and REJECTS on failure so the
-         * caller can show a retryable error. Idempotent: pass the SAME `responseId` on retry
-         * — both response and attachments de-dupe server-side. Used by EVERY question type.
-         */
-        submitResponseConfirmed: (
-            input: EngageResponseInput,
-            attachments: EngageAttachmentDraft[],
-            opts: { responseId: string; onStage?: (stage: SubmitStage) => void },
-        ): Promise<void> => {
-            const transport = this._getEngageTransport();
-            if (!transport) return Promise.reject(new Error('sdk_not_configured'));
-            return transport.submitResponseConfirmed(input, attachments, opts);
-        },
-
-        /** Upload an in-app impression/click/dismiss event (idempotent, rides the outbox). */
-        trackEvent: (input: EngageEventInput): void => {
-            noThrow(() => {
-                const automaticName: Partial<Record<EngageEventInput['type'], AutomaticEventName>> = {
-                    impression: 'in_app_displayed',
-                    rendered: 'in_app_displayed',
-                    completion: 'in_app_completed',
-                    click: 'in_app_clicked',
-                    dismiss: 'in_app_dismissed',
-                    interaction: 'in_app_interaction',
-                    render_failed: 'in_app_render_failed',
-                    cta_open_failed: 'in_app_cta_open_failed',
-                };
-                const eventName = automaticName[input.type];
-                if (eventName) {
-                    emitAutomaticEvent(eventName, {
-                        campaign_id: input.campaignId,
-                        variant_id: input.variantId,
-                        preview_id: input.previewId,
-                        is_test: input.isTest,
-                        source: input.source,
-                        interaction_type:
-                            typeof input.meta?.type === 'string'
-                                ? input.meta.type
-                                : undefined,
-                    });
-                }
-                this._getEngageTransport()?.uploadEngageEvent(input);
-            });
-        },
-
-        /** Upload an idempotent survey shown/started funnel beacon. */
-        trackSurveyImpression: (input: SurveyImpressionInput): void => {
-            noThrow(() => this._getEngageTransport()?.uploadSurveyImpression(input));
-        },
-
-        /**
-         * Emit a rating-funnel tracking event (ratings-rebuild CONTRACT §1.2). These
-         * are dimensioned FACTS feeding the Overview funnel — NOT campaign responses
-         * (D1) — so they ride their own `/ingestion/rating-events` lane. Idempotent
-         * (client `eventId`, D8). Best-effort, never throws.
-         */
-        emitRatingEvent: (input: RatingFunnelEventInput): void => {
-            noThrow(() => {
-                emitAutomaticEvent(input.type, {
-                    prompt_id: input.promptId,
-                    trigger_id: input.triggerId,
-                    variant_id: input.variantId,
-                    stars: input.stars,
-                });
-                this._getEngageTransport()?.uploadRatingEvent(input);
-            });
-        },
-
-        /**
-         * Trigger the native in-app review sheet (Play In-App Review on Android,
-         * SKStoreReviewController on iOS) — the genuinely-native leg of the rating
-         * funnel (D5). Resolves `true` ONLY when the OS flow ran/resolved after a
-         * positive route, so the caller emits `store_redirect_clicked` solely on a
-         * `true` result. Fail-soft: resolves `false` when native review is unavailable.
-         */
-        requestStoreReview: async (): Promise<boolean> => {
-            return (await safeAsync(async () => requestNativeStoreReview())) ?? false;
-        },
-
-        /**
-         * Submit a 1–5 app-store rating via the EXISTING app-rating lane (D1 keeps
-         * ratings a distinct funnel — NOT submitResponse). Delegates to the
-         * facade's `submitRating`, threading the renderer's `clientRatingId` for
-         * idempotency (D8). Used by the RATING_PROMPT render branch.
-         */
-        submitRating: (input: {
-            rating: number;
-            comment?: string;
-            source?: 'in_app' | 'prompt' | 'manual';
-            clientRatingId?: string;
-        }): void => {
-            noThrow(() => {
-                void this.submitRating(input);
-            });
-        },
-
-        /**
-         * Acquire the native push token (FCM/APNs) and register it for delivery.
-         * Subscribes to native token-refresh (rotation) so the backend always holds
-         * the live token. Fail-soft: no-op when native push is unavailable.
-         */
-        registerForPush: async (): Promise<void> => {
-            return safeAsync(async () => {
-                const transport = this._getEngageTransport();
-                if (!transport) return;
-
-                const initial = await getNativePushToken();
-                if (initial) {
-                    transport.registerDeviceToken({
-                        pushToken: initial.token,
-                        platform: initial.platform,
-                        pushProvider: initial.platform === 'ios' ? 'apns' : 'fcm',
-                    });
-                }
-
-                // Avoid stacking listeners on repeated calls.
-                this._engageTokenUnsubscribe?.();
-                this._engageTokenUnsubscribe = subscribeNativePushTokenRefresh((refreshed) => {
-                    this._getEngageTransport()?.registerDeviceToken({
-                        pushToken: refreshed.token,
-                        platform: refreshed.platform,
-                        pushProvider: refreshed.platform === 'ios' ? 'apns' : 'fcm',
-                    });
-                });
-            }) as Promise<void>;
-        },
-    };
-
-    // ─── Push Notifications ─────────────────────────────────────────────
-
-    /**
-     * Lazily build the PushManager. Backend token registration is injected and
-     * routes through the existing Engage outbox (EngageTransport.registerDeviceToken),
-     * so push reuses the SDK's single device-token lane rather than a parallel
-     * fetch. Returns {ok:false} when the SDK isn't configured (clientKey absent).
-     */
-    private _getPushManager(): PushManager {
-        if (!this._pushManager) {
-            this._pushManager = new PushManager({
-                registerToken: async (input) => {
-                    const transport = this._getEngageTransport();
-                    if (!transport) return { ok: false, reason: 'sdk_not_configured' as const };
-                    transport.registerDeviceToken({
-                        pushToken: input.pushToken,
-                        platform: input.platform,
-                        pushProvider: input.pushProvider,
-                        sdkVersion: SDK_VERSION,
-                        ...(this._eventTracker
-                            ? { installationId: this._eventTracker.getInstallationId() }
-                            : {}),
-                    });
-                    return { ok: true as const };
-                },
-            });
-        }
-        return this._pushManager;
-    }
-
-    /**
-     * Enable push notifications with smart, version-aware adapter selection.
-     *
-     * Detects the RN version, architecture (legacy bridge vs New
-     * Architecture/bridgeless), whether @react-native-firebase/messaging is
-     * installed & compatible, and whether the ScaleBunEngage native token bridge is
-     * linked, then picks the safest supported path automatically: RNFirebase
-     * (full callbacks) → native ScaleBunEngage bridge (token-only fallback that works
-     * under bridgeless regardless of RNFirebase version) → manual → noop.
-     *
-     * Requests OS permission, creates the Android channel, acquires the push
-     * token, keeps it in sync on refresh, registers it with the ScaleBun backend
-     * (via the Engage outbox), and wires foreground/opened callbacks.
-     *
-     * Fails clearly (ok:false + actionable reason) when no usable provider
-     * exists — never silently breaks. Never throws.
-     *
-     * ```ts
-     * await ScaleBun.enablePush({
-     *   onForegroundNotification: (n) => {},
-     *   onNotificationOpened: (n) => {},
-     * });
-     * ```
-     */
-    public enablePush(options?: EnablePushOptions): Promise<EnablePushResult> {
-        return this._getPushManager().enable(options ?? {});
-    }
-
-    /**
-     * Subscribe to notifications received while the app is foregrounded. Thin,
-     * platform-agnostic alias for `enablePush({ onForegroundNotification })`; use it
-     * to attach a handler after enablePush. Returns an unsubscribe function. Inert
-     * until push is enabled. (iOS direct APNs delivers these via the native
-     * UNUserNotificationCenter surface.)
-     */
-    public onForegroundNotification(cb: (notification: PushNotification) => void): () => void {
-        return noThrow(() => this._getPushManager().onForegroundNotification(cb)) ?? (() => {});
-    }
-
-    /**
-     * Subscribe to the user tapping a notification (open / deep-link), including the
-     * cold-start notification that launched the app. Thin alias for
-     * `enablePush({ onNotificationOpened })`. Returns an unsubscribe function. The
-     * event shape ({ data, title?, body? }) matches across Android and iOS.
-     */
-    public onNotificationOpened(cb: (notification: PushNotification) => void): () => void {
-        return noThrow(() => this._getPushManager().onNotificationOpened(cb)) ?? (() => {});
-    }
-
-    /**
-     * Push control namespace. Most apps only need {@link enablePush}; these are
-     * for the manual/custom provider path and diagnostics.
-     */
-    public push = {
-        /** Inject/rotate a token (manual provider) — syncs to the backend. */
-        setToken: (token: string): void => {
-            noThrow(() => this._getPushManager().setToken(token));
-        },
-        /** Current push token, if acquired. */
-        getToken: (): string | null => {
-            return noThrow(() => this._getPushManager().getToken()) ?? null;
-        },
-        /** Deliver a foreground notification to registered callbacks (manual provider). */
-        emitForeground: (message: PushNotification): void => {
-            noThrow(() => this._getPushManager().emitForeground(message));
-        },
-        /** Deliver a notification-open event to registered callbacks (manual provider). */
-        emitNotificationOpened: (message: PushNotification): void => {
-            noThrow(() => this._getPushManager().emitNotificationOpened(message));
-        },
-        /** Current push status: selected adapter, usability, reason, token. */
-        status: () => this._getPushManager().status(),
-        /** Tear down all push listeners. */
-        teardown: (): void => {
-            noThrow(() => this._pushManager?.teardown());
-        },
-    };
-
-    // ─── Event Tracking ─────────────────────────────────────────────────
-
-    /**
-     * Report the outcome of an OS permission prompt.
-     *
-     * Permission results were state the SDK held privately and never an event, so the core mobile
-     * growth loop — "reached the paywall → was prompted → granted" — could not be expressed as a funnel.
-     *
-     * Notification permission is captured AUTOMATICALLY (the SDK runs that prompt itself, see
-     * PushManager). Every other permission belongs to the host app: the SDK never sees a camera or
-     * location request, so guessing at one would be inventing data. Call this right after the prompt
-     * resolves:
-     *
-     * ```ts
-     * const { status } = await Location.requestForegroundPermissionsAsync();
-     * ScaleBun.trackPermission('location', status === 'granted' ? 'granted' : 'denied');
-     * ```
-     *
-     * `permission` is free-form on purpose — platforms disagree on names and a fixed enum would go
-     * stale — but stick to one spelling per permission or the funnel splits in two.
-     */
-    public trackPermission(
-        permission: string,
-        status: 'granted' | 'denied' | 'blocked' | 'undetermined' | 'limited',
-        details?: Record<string, any>,
-    ) {
-        return noThrow(() => {
-            const name = String(permission || '').trim();
-            if (!name) return; // Nothing to attribute the result to — drop rather than emit a blank.
-            emitAutomaticEvent('permission_result', {
-                ...details,
-                permission: name,
-                status,
-                // Distinguishes a host-reported result from the SDK's own push prompt.
-                source: 'host',
-            });
-        });
-    }
-
-    /** Track a named event with optional payload */
-    public track(name: string, payload?: Record<string, any>) {
-        return noThrow(() => {
-            if (!this.initialized && !name.startsWith('$')) {
-                logger.warn('SDK not initialized. Event dropped:', name);
-                return;
-            }
-            logger.debug('Tracking event:', name);
-
-            // Fan this event out to the Engage trigger engine. Same single funnel,
-            // extra observer — lets behavioral triggers (custom_event, failed_action,
-            // after_crash, network_error, before_logout, …) fire off events the SDK
-            // already produces, without a parallel capture pipeline.
-            engageSignals.emit(name, payload);
-
-            const adapter = SessionManager.getExistingInstance()?.getBackendTransport();
-            if (this._clientKey && adapter) {
-                // SaaS mode → always-on analytics ingestion lane (NOT /sdk/events).
-                // sessionId is stamped by the lane at flush time, so the call-time
-                // value is a placeholder; endpoint id == body sessionId by construction.
-                adapter.trackEvent({
-                    eventId: generateEventId(),
-                    sessionId: adapter.analyticsSessionId ?? '',
-                    ts: Date.now(),
-                    type: name === '$log' ? 'LOG_EMITTED' : 'USER_ACTION',
-                    subtype: name,
-                    payload,
-                });
-            } else {
-                // Legacy mode (projectId/publishableKey): persistent queue → /sdk/events.
-                const envelope = createEnvelope('event', { name, ...payload });
-                this._getQueue().add(envelope);
-            }
-
-            // Phase 1 analytics envelope lane (/batch → raw_events → events).
-            // Runs alongside the session/replay lane above; only active when an
-            // appId was configured at init. SDK-internal ($-prefixed) signals stay
-            // on the session/debug lane and must not pollute the events table — the
-            // split is owned by resolveEventLane (see analytics/eventLane).
-            if (this._eventTracker && resolveEventLane(name) === 'analytics') {
-                this._eventTracker.track(name, payload);
-            }
-
-            // Tap into debug stream if enabled (non-blocking)
-            const stream = _getStream();
-            if (stream) {
-                stream.tapEnvelope(createEnvelope('event', { name, ...payload }));
-            }
-
-            // Tap network events into performance feature
-            if (name === '$network_request' && this._performanceFeature?.isActive && payload) {
-                this._performanceFeature.processNetworkEvent(payload);
-            }
-        });
-    }
-
-    /** Log a message (convenience wrapper over track) */
-    public log(level: 'debug' | 'info' | 'warn' | 'error', message: string, data?: Record<string, unknown>) {
-        return this.track('$log', { level, message, ...data });
-    }
-
-    /**
-     * Capture a handled error/exception and deliver it to the backend
-     * errors endpoint (shows up in the dashboard Crashes view).
-     *
-     * No-throw. Routes to: desktop debug stream ($crash event) + SaaS
-     * backend errors ingestion (when a clientKey session is active).
-     */
-    public captureError(
-        error: Error | string,
-        context?: { screenName?: string; fatal?: boolean; type?: string; metadata?: Record<string, unknown> },
-    ) {
-        return noThrow(() => {
-            const err = typeof error === 'string' ? new Error(error) : error;
-            const isFatal = context?.fatal ?? false;
-
-            getCrashReporter().report({
-                source: 'handled',
-                type: context?.type ?? (isFatal ? 'crash' : 'handled'),
-                isFatal,
-                message: err.message,
-                stack: err.stack,
-                screenName: context?.screenName,
-                metadata: context?.metadata,
-            });
-
-            // Flush the event queue (desktop $crash) too
-            this.flush().catch(() => {});
-        });
-    }
-
-    /**
-     * DEV/TEST ONLY — trigger a real native crash to validate the native
-     * capture → next-launch drain → backend pipeline. No-op when the native
-     * module is unavailable. Do not ship calls to this in production code.
-     */
-    public nativeCrash() {
-        return noThrow(() => triggerNativeCrash());
-    }
-
-    /** Report a bug (convenience wrapper over track) */
-    public reportBug(description: string, metadata?: Record<string, unknown>) {
-        return this.track('$bug_report', { description, ...metadata });
-    }
-
-    /** Set a custom attribute on the current session */
-    public setAttribute(key: string, value: string | number | boolean) {
-        return this.track('$set_attribute', { key, value });
-    }
-
-    // ─── Flush ──────────────────────────────────────────────────────────
-
-    /** Force-flush all pending events */
-    public async flush() {
-        return safeAsync(async () => {
-            if (!this.initialized) return;
-            // SaaS mode has two analytics lanes: EventTracker writes normalized
-            // product events to /batch, while BackendSessionAdapter writes the
-            // matching timeline events to /ingestion/sessions/:id/events. Drain
-            // both before an app background/navigation can suspend their timers.
-            // The legacy persistent queue posts to /sdk/events, which the SaaS
-            // backend does not serve, so it remains exclusive to legacy mode.
-            if (this._clientKey) {
-                const adapter = SessionManager.getExistingInstance()?.getBackendTransport();
-                await Promise.all([
-                    this._eventTracker?.flush() ?? Promise.resolve(),
-                    adapter?.flushAnalytics() ?? Promise.resolve(),
-                ]);
-                return;
-            }
-            logger.debug('Flushing events from persistent queue...');
-            const httpClient = coreContainer.get<HttpClient>('HttpClient');
-            await flushQueue(this._getQueue(), httpClient, getDeviceId());
-        });
-    }
-
-    /**
-     * Enable the debug subsystem.
-     *
-     * @deprecated Use `ScaleBun.init({ debug: true })` instead.
-     * This method still works for backward compatibility.
-     */
-    public enableDebug(config: DebugConfig) {
-        return noThrow(() => {
-            if (!(config as any).__skipDeprecationWarning) {
-                logger.warn(
-                    '[ScaleBun] enableDebug() is deprecated. ' +
-                    'Use ScaleBun.init({ ..., debug: true }) instead.',
-                );
-            }
-
-            const gatedConfig = applyFeatureGatesToDebugConfig(config, this._features);
-            _enableDebug(gatedConfig);
-            _setFlushFn(() => this.flush() as Promise<void>);
-
-            const bootstrapPerfFeature = _getPerformanceFeature();
-            if (bootstrapPerfFeature) {
-                this._performanceFeature = bootstrapPerfFeature;
-                logger.debug('Performance feature linked from bootstrap');
-            }
-
-            logger.info('Debug enabled');
-        });
-    }
-
-    /** Disable the debug subsystem and clean up */
-    public disableDebug() {
-        return noThrow(() => {
-            _disableDebug();
-        });
-    }
-
-    /**
-     * Diagnostic-only: stamp the *expected* target for the very next gesture
-     * event. Calibration screens call this immediately before their onPress
-     * fires so SessionManager merges expectedTargetId / expectedNX / expectedNY
-     * into the stored gesture payload. Pure observability — never affects
-     * capture, normalization, or marker placement. TTL ≈ 500 ms.
-     */
-    public setCalibrationTarget(target: { targetId: string; expectedNX: number; expectedNY: number }): void {
-        noThrow(() => {
-            const mod = require('../features/journey/calibrationContext') as
-                typeof import('../features/journey/calibrationContext');
-            mod.setCalibrationTarget(target);
-        });
-    }
-
-    /**
-     * Debug utilities namespace.
-     * All methods are no-op if debug is not enabled.
-     */
-    public debug = {
-        addBreadcrumb: (message: string, data?: Record<string, unknown>) => {
-            noThrow(() => _addBreadcrumb(message, data));
-        },
-        ping: () => {
-            noThrow(() => _ping());
-        },
-        isEnabled: () => isDebugEnabled(),
-        sendMetric: (name: string, value: number, unit?: string, tags?: Record<string, string>) => {
-            sendDebugMetric(name, value, unit, tags);
-        },
-    };
-
-    // ─── Replay ─────────────────────────────────────────────────────────
-
-    /**
-     * Session Replay namespace.
-     * Provides control over session replay: recording, capture,
-     * user identity, privacy, breadcrumbs, and transport.
-     * All methods are no-op if replay feature is disabled.
-     */
-    public replay = {
-        start: (): Promise<void> => ReplaySdk.start(),
-        stop: (): Promise<void> => ReplaySdk.stop(),
-        pause: (): Promise<void> => ReplaySdk.pause(),
-        resume: (): Promise<void> => ReplaySdk.resume(),
-        captureFrame: (): Promise<void> => ReplaySdk.captureManualFrame(),
-        setUser: (user: ReplayUser): Promise<void> => ReplaySdk.setUser(user),
-        clearUser: (): Promise<void> => ReplaySdk.clearUser(),
-        addBreadcrumb: (breadcrumb: ReplayBreadcrumb): Promise<void> =>
-            ReplaySdk.addBreadcrumb(breadcrumb),
-        setPrivacy: (opts: Partial<ReplayPrivacyOptions>): Promise<void> =>
-            ReplaySdk.setPrivacyOptions(opts),
-        setEnabled: (enabled: boolean): Promise<void> => ReplaySdk.setEnabled(enabled),
-        setQuality: (quality: any): Promise<void> => ReplaySdk.setScreenshotQuality(quality),
-        setCaptureMode: (mode: any): Promise<void> => ReplaySdk.setCapturingMode(mode),
-        setScreen: (name: string): Promise<void> => ReplaySdk.setCurrentScreen(name),
-        flush: (): Promise<void> => ReplaySdk.flush(),
-        get isRecording(): boolean {
-            return ReplaySdk.isRecording;
-        },
-        get sessionId(): string | null {
-            return ReplaySdk.sessionId;
-        },
-    };
-
-    // ─── Performance ────────────────────────────────────────────────────
-
-    /**
-     * Performance monitoring namespace.
-     * Provides control over custom traces, screen load markers,
-     * and access to captured metrics.
-     * All methods are no-op if performance feature is disabled.
-     */
-    public performance = {
-        /** Start a custom trace. Returns traceId or null. */
-        startTrace: (name: string): string | null => {
-            return this._performanceFeature?.startTrace(name) ?? null;
-        },
-        /** Stop a custom trace by ID. */
-        stopTrace: (traceId: string): void => {
-            this._performanceFeature?.stopTrace(traceId);
-        },
-        /** Add a span to an active custom trace. */
-        addTraceSpan: (traceId: string, name: string, durationMs: number, data?: Record<string, unknown>): void => {
-            this._performanceFeature?.addTraceSpan(traceId, name, durationMs, data);
-        },
-        /** Attach a measurement to an active custom trace. */
-        addTraceMeasurement: (traceId: string, name: string, value: number, unit: string): void => {
-            this._performanceFeature?.addTraceMeasurement(traceId, name, value, unit);
-        },
-        /** Mark the start of a screen load. */
-        markScreenLoadStart: (screenName: string): void => {
-            this._performanceFeature?.markScreenLoadStart(screenName);
-        },
-        /** Mark the end of a screen load. */
-        markScreenLoadEnd: (screenName: string): void => {
-            this._performanceFeature?.markScreenLoadEnd(screenName);
-        },
-        /** Set the current screen for context correlation. */
-        setCurrentScreen: (screenName: string): void => {
-            this._performanceFeature?.setCurrentScreen(screenName);
-        },
-        /** Forward navigation state changes for auto screen load detection. */
-        onNavigationStateChange: (state: unknown): void => {
-            this._performanceFeature?.onNavigationStateChange(state);
-        },
-        /** Check if performance monitoring is active */
-        isActive: (): boolean => {
-            return this._performanceFeature?.isActive ?? false;
-        },
-        /**
-         * Send a raw performance metric through the transport.
-         * Used for manual/simulated performance metrics.
-         */
-        sendMetric: (name: string, value: number, unit?: string, tags?: Record<string, string>): void => {
-            if (!this._performanceFeature) {
-                logger.warn('performance.sendMetric: PerformanceFeature not available — is debug enabled?');
-                return;
-            }
-            this._performanceFeature.sendMetric(name, value, unit, tags);
-        },
-    };
-
-    // ─── Unified Session ────────────────────────────────────────────────
-
-    /**
-     * Unified Session namespace.
-     * Provides access to the unified SessionManager.
-     * Sessions auto-start on desktop connect.
-     */
-    public session = {
-        get isActive(): boolean {
-            return SessionManager.getExistingInstance()?.isActive ?? false;
-        },
-        get currentSessionId(): string | null {
-            return SessionManager.getExistingInstance()?.currentSessionId ?? null;
-        },
-        start: (metadata?: Record<string, unknown>): boolean => {
-            const sm = SessionManager.getExistingInstance();
-            if (!sm) {
-                logger.warn('session.start() — SessionManager not available.');
-                return false;
-            }
-            sm.startSession(metadata as Parameters<SessionManager['startSession']>[0]);
-            logger.info('session.start() ✅ sessionId:', sm.currentSessionId);
-            return true;
-        },
-        end: (reason?: 'ended' | 'timeout'): boolean => {
-            const sm = SessionManager.getExistingInstance();
-            if (!sm || !sm.isActive) return false;
-            sm.endSession(reason);
-            logger.info('session.end() ✅');
-            return true;
-        },
-        emitEvent: (type: string, data?: Record<string, unknown>) => {
-            const sm = SessionManager.getExistingInstance();
-            if (!sm || !sm.isActive) return;
-            sm.emitEvent(type as JourneyEventType, data as Parameters<SessionManager['emitEvent']>[1]);
-        },
-    };
-
-    // ─── Session Convenience Methods ────────────────────────────────────
-
-    /** Start a session (delegates to session namespace) */
-    public startSession(metadata?: Record<string, unknown>): boolean {
-        return this.session.start(metadata);
-    }
-
-    /** Stop the current session (delegates to session namespace) */
-    public stopSession(reason?: 'ended' | 'timeout'): boolean {
-        return this.session.end(reason);
-    }
-
-    // ─── Report / Export ───────────────────────────────────────────
-
-    /**
-     * Report generation and export namespace.
-     *
-     * Usage:
-     * ```ts
-     * // Export with default preset
-     * const result = await ScaleBun.report.export();
-     *
-     * // Export with a named preset
-     * const result = await ScaleBun.report.export('engineering');
-     *
-     * // Export with custom options
-     * const result = await ScaleBun.report.export({ format: 'pdf', detail: 'detailed' });
-     * ```
-     *
-     * Requires an active desktop debug connection (`debug: true` in init).
-     */
-    public report = {
-        /**
-         * Trigger a report export on the desktop application.
-         *
-         * @param presetOrOptions - Optional. A preset name ('executive', 'engineering', 'qa',
-         *   'forensic', 'journey', 'compact') or a SimplifiedExportOptions object.
-         * @returns Promise<ExportResult> with success status, file path, or error.
-         */
-        export: (presetOrOptions?: ExportPresetName | SimplifiedExportOptions): Promise<ExportResult> => {
-            return _requestExport(presetOrOptions);
-        },
-
-        /** Set SDK-wide privacy settings for report generation. */
-        setPrivacy: (config: PrivacyConfig): void => {
-            this._privacyConfig = { ...this._privacyConfig, ...config };
-            logger.debug('[report] Privacy config updated');
-        },
-
-        /** Set branding for exported reports. */
-        setBranding: (config: BrandingConfig): void => {
-            this._brandingConfig = { ...this._brandingConfig, ...config };
-            logger.debug('[report] Branding config updated');
-        },
-
-        /** Get current privacy config. */
-        getPrivacy: (): PrivacyConfig => ({ ...this._privacyConfig }),
-
-        /** Get current branding config. */
-        getBranding: (): BrandingConfig => ({ ...this._brandingConfig }),
-    };
-
-    // ─── Navigation ───────────────────────────────────────────────
-
-    /**
-     * Set the React Navigation container ref for automatic screen detection.
-     *
-     * This is the **recommended** way to enable auto screen detection.
-     * Once set, the SDK automatically detects screen changes and feeds them
-     * to all subsystems (SessionManager, PerformanceFeature, ProfilerFeature).
-     * No per-screen `<ScaleBunScreen>` or `useScaleBunScreen()` needed.
-     *
-     * ```ts
-     * import { NavigationContainer } from '@react-navigation/native';
-     * import ScaleBun from '@scalebun/react-native';
-     *
-     * const navigationRef = React.createRef();
-     *
-     * function App() {
-     *   useEffect(() => {
-     *     ScaleBun.setNavigationRef(navigationRef);
-     *   }, []);
-     *
-     *   return (
-     *     <NavigationContainer ref={navigationRef}>
-     *       ...screens...
-     *     </NavigationContainer>
-     *   );
-     * }
-     * ```
-     */
-    public setNavigationRef(ref: any): void {
-        noThrow(() => {
-            // Always stash on the global so heuristic polling / late consumers resolve it.
-            (globalThis as any).__scalebun_navigationRef = ref;
-
-            // Wire the LIVE AutoScreenDetector singleton (started by SDKBootstrapper in
-            // production). _getAutoScreenDetector() is the debug-only handle and is null
-            // when desktopDebug is off, so relying on it alone never wires the explicit
-            // React-Navigation 'state' listener and degrades to slow heuristic polling.
-            try {
-                const { AutoScreenDetector } = require('../features/navigation/AutoScreenDetector');
-                AutoScreenDetector.getInstance().setNavigationRef(ref);
-                logger.info('[ScaleBun] Navigation ref set → auto screen detection active');
-            } catch (err: any) {
-                logger.debug('[ScaleBun] Navigation ref stashed (detector not ready):', err?.message);
-            }
-        });
-    }
-}
-
-/** Singleton Facade instance */
-const instance = new ScaleBunFacade();
-export default instance;
-export { ScaleBunFacade };
+/**
+ * ScaleBun SDK — Public Facade
+ *
+ * Single clean entry point for the ScaleBun SDK.
+ * Delegates initialization to SDKBootstrapper, which handles config validation,
+ * core service setup, handshake, and feature registration via FeatureRegistry.
+ *
+ * Config model preserved exactly: projectId, publishableKey, apiBaseUrl.
+ * Features are default-on with explicit opt-out via `features: { replay: false }`.
+ */
+
+import { noThrow, safeAsync } from '../core/lifecycle/crashSafe';
+import { logger } from '../core/logger/internalLogger';
+import { createEnvelope } from '../pipeline/envelope/envelope';
+import { generateEventId } from '../features/replay/core/ids/sessionId';
+import { PersistentQueue } from '../pipeline/queue/persistentQueue';
+import { MemoryBackend, createStorageBackend } from '../storage/StorageBackend';
+import { HttpClient } from '../transport/http/httpClient';
+import { getDeviceId } from '../core/id/deviceId';
+import { coreContainer } from '../core/di/container';
+import { flushQueue } from '../pipeline/queue/flushQueue';
+import {
+    enableDebug as _enableDebug,
+    disableDebug as _disableDebug,
+    isDebugEnabled,
+    addBreadcrumb as _addBreadcrumb,
+    ping as _ping,
+    _getStream,
+    _setFlushFn,
+    _getSessionManager,
+    _getAutoScreenDetector,
+    getPerformanceFeature as _getPerformanceFeature,
+    requestExport as _requestExport,
+    buildDebugConfigFromInitConfig,
+    applyFeatureGatesToDebugConfig,
+    sendDebugMetric,
+} from '../debug';
+import type { DebugConfig } from '../debug';
+import { ReplaySdk } from '../features/replay/public/api';
+import type {
+    ReplayUser,
+    ReplayBreadcrumb,
+    ReplayPrivacyOptions,
+} from '../features/replay/public/types';
+import { SDKBootstrapper } from '../bootstrap/SDKBootstrapper';
+import { EventTracker } from '../analytics/EventTracker';
+import {
+    emitAutomaticEvent,
+    type AutomaticEventName,
+} from '../analytics/automaticEvents';
+import { resolveEventLane } from '../analytics/eventLane';
+import { ConfigManager } from '../config/ConfigManager';
+import { SDK_VERSION } from '../core/constants/version';
+import { EngageTransport, type SubmitStage } from '../features/engage/EngageTransport';
+import {
+    getNativePushToken,
+    subscribeNativePushTokenRefresh,
+} from '../features/engage/engagePushTokenBridge';
+import { requestNativeStoreReview } from '../features/engage/engageStoreReviewBridge';
+import { PushManager } from '../push/PushManager';
+import type { EnablePushOptions, EnablePushResult, PushNotification } from '../push/types';
+import { ENGAGE_SCHEMA_VERSION } from '../features/engage/engageTypes';
+import { EngageThrottleStore } from '../features/engage/engageThrottle';
+import { EngageTestSeenStore } from '../features/engage/engageTestSeenStore';
+import { engageSignals } from '../features/engage/engageSignals';
+import type {
+    EngageAttachmentDraft,
+    EngageConfigContext,
+    EngageConfigResponse,
+    EngageEventInput,
+    EngageResponseInput,
+    RatingFunnelEventInput,
+    SurveyImpressionInput,
+} from '../features/engage/engageTypes';
+import { PerformanceFeature } from '../features/performance/PerformanceFeature';
+import { SessionManager } from '../features/session/SessionManager';
+import type { JourneyEventType } from '../features/session/sessionTypes';
+import { getCrashReporter } from '../features/crash/CrashReporter';
+import { triggerNativeCrash } from '../features/crash/nativeCrashBridge';
+import { updateSkanConversionValue, isSkanAvailable, type SkanCoarseValue } from '../features/skan/skanBridge';
+import { SkanConversionManager } from '../features/skan/skanConversionManager';
+import {
+    isInstallReferrerAvailable,
+    getInstallReferrer,
+    captureInstallReferrerOnce,
+    type InstallReferrerSink,
+} from '../features/install-referrer/installReferrer';
+import type {
+    ScaleBunInitConfig,
+    ScaleBunUser,
+    ScaleBunFeatures,
+    SimplifiedInitConfig,
+    DebugConnectionConfig,
+    PrivacyConfig,
+    BrandingConfig,
+    ExportPresetName,
+    SimplifiedExportOptions,
+    ExportResult,
+} from './types';
+
+class ScaleBunFacade {
+    private initialized = false;
+    /** In-flight init promise — guards against a second init() racing before the first resolves. */
+    private _initInFlight: Promise<void> | null = null;
+    private bootstrapper = new SDKBootstrapper();
+    private _features: ScaleBunFeatures = {};
+    private _performanceFeature: PerformanceFeature | null = null;
+    private _privacyConfig: PrivacyConfig = {};
+    private _brandingConfig: BrandingConfig = {};
+    private _clientKey: string | undefined = undefined;
+    private _apiBaseUrl: string | undefined = undefined;
+    private _engageTransport: EngageTransport | null = null;
+    private _engageTokenUnsubscribe: (() => void) | null = null;
+    private _pushManager: PushManager | null = null;
+    /** Phase 1 envelope event-tracking lane (POST /v1/batch). Null until init with appId. */
+    private _eventTracker: EventTracker | null = null;
+    /** External identity last supplied through identify(); used by config targeting. */
+    private _identifiedUserId: string | null = null;
+    /** Identity supplied while async initialization is still in flight. */
+    private _pendingIdentity: {
+        userId: string;
+        traits?: Record<string, any>;
+    } | null = null;
+    private _configManager: ConfigManager | null = null;
+    /** Signature of the last identity POSTed to the ingestion identify endpoint, to skip redundant re-sends. */
+    private _lastIngestionIdentityKey: string | null = null;
+    /** Phase 3: auto-applies SKAN conversion values from the server schema (iOS only). */
+    private _skanManager: SkanConversionManager | null = null;
+
+    /**
+     * Pre-init memory buffer.
+     * Events tracked before init() completes are buffered here,
+     * then drained into the real persistent queue post-init.
+     */
+    private _preInitBuffer: PersistentQueue = new PersistentQueue(new MemoryBackend(), {
+        enabled: false,
+        maxEntries: 500,
+        maxBytes: 1_048_576, // 1 MB
+        redactBeforeWrite: false, // No redaction for memory-only buffer
+    });
+
+    /** Resolve the active queue (DI container or pre-init buffer) */
+    private _getQueue(): PersistentQueue {
+        if (this.initialized) {
+            try {
+                return coreContainer.get<PersistentQueue>('PersistentQueue');
+            } catch {
+                // Container not ready yet — shouldn't happen post-init
+            }
+        }
+        return this._preInitBuffer;
+    }
+
+    // ─── Initialization ─────────────────────────────────────────────────
+
+    /**
+     * Initialize the ScaleBun SDK.
+     *
+     * **Simplified usage** (recommended):
+     * ```ts
+     * await ScaleBun.init({
+     *   projectId: 'proj_xxx',
+     *   publishableKey: 'pk_xxx',
+     *   apiBaseUrl: 'https://api.scalebun.com',
+     *   debug: true,
+     * });
+     * ```
+     *
+     * Accepts both `SimplifiedInitConfig` (new) and `ScaleBunInitConfig` (legacy).
+     * If `debug` key is present, auto-connects to the desktop debugger.
+     */
+    public async init(rawConfig: SimplifiedInitConfig | ScaleBunInitConfig | any) {
+        if (this.initialized) return;
+        // Coalesce concurrent init() calls: a second call before the first resolves
+        // must not run a second bootstrap (which would double-register lifecycle
+        // listeners and repeat the backend handshake).
+        if (this._initInFlight) return this._initInFlight;
+        this._initInFlight = safeAsync(async () => {
+            if (this.initialized) return;
+
+            // Store feature flags (all default true)
+            this._features = rawConfig?.features ?? {};
+            if (rawConfig?.sessionReplay !== undefined) {
+                this._features.replay = rawConfig.sessionReplay;
+            }
+
+            // Store privacy config if provided
+            if (rawConfig?.privacy) {
+                this._privacyConfig = rawConfig.privacy;
+            }
+
+            // Phase 3 (entitlements) — COST suppression: don't even register a
+            // collector the org isn't entitled to (no traffic → no server cost).
+            // Read from the cached /config (sync); first run has no cache → fail-open
+            // (all entitled), and the server still rejects a closed feature anyway.
+            const ent = ConfigManager.readCachedEntitlements();
+            const effectiveFeatures: ScaleBunFeatures = {
+                ...this._features,
+                replay: this._features.replay !== false && ent.replay !== false,
+                network: this._features.network !== false && ent.networkMonitoring !== false,
+                crashes: this._features.crashes !== false && ent.crashReporting !== false,
+                performance: this._features.performance !== false && ent.performanceMonitoring !== false,
+            };
+
+            // Backend bootstrap (non-blocking for debug connection)
+            // If the backend is unreachable, the debug WebSocket should still connect.
+            try {
+                const result = await this.bootstrapper.bootstrap(
+                    rawConfig,
+                    (name, payload) => this.track(name, payload),
+                    () => this.flush() as Promise<void>,
+                    effectiveFeatures,
+                );
+
+                if (result) {
+                    this.initialized = true;
+                    this._clientKey = result.config.clientKey;
+                    this._apiBaseUrl = result.config.apiBaseUrl;
+
+                    // Phase 1 envelope tracking lane. Enabled when an appId is supplied
+                    // (and not explicitly disabled). Runs alongside the replay lane.
+                    this._maybeStartEventTracker(rawConfig);
+                    if (this._pendingIdentity) {
+                        const pending = this._pendingIdentity;
+                        this._pendingIdentity = null;
+                        this.identify(pending.userId, pending.traits);
+                    }
+
+                    // Drain pre-init buffer into the real persistent queue
+                    const realQueue = coreContainer.get<PersistentQueue>('PersistentQueue');
+                    const buffered = this._preInitBuffer.popBatch(this._preInitBuffer.length());
+                    if (buffered.length > 0) {
+                        logger.debug(`[ScaleBun] Draining ${buffered.length} pre-init events into persistent queue`);
+                        for (const envelope of buffered) {
+                            realQueue.add(envelope);
+                        }
+                    }
+
+                    // Grab a reference to the PerformanceFeature for the public API
+                    const perfFeature = result.featureRegistry.get('performance');
+                    if (perfFeature && perfFeature instanceof PerformanceFeature) {
+                        this._performanceFeature = perfFeature;
+                    }
+                }
+            } catch (bootstrapErr: any) {
+                logger.warn('[ScaleBun] Backend bootstrap failed (non-blocking):', bootstrapErr?.message);
+                // Continue — debug connection is independent of backend API
+            }
+
+            // Auto debug connection from init config — runs regardless of backend status
+            const debugConfig = (rawConfig?.desktopDebug ?? rawConfig?.debug) as DebugConnectionConfig | undefined;
+            if (debugConfig) {
+                this._autoEnableDebug(debugConfig);
+            }
+        });
+        try {
+            return await this._initInFlight;
+        } finally {
+            this._initInFlight = null;
+        }
+    }
+
+    private _autoEnableDebug(debugConfig: DebugConnectionConfig): void {
+        try {
+            const dbgConfig = buildDebugConfigFromInitConfig(debugConfig);
+            if (!dbgConfig) return;
+            (dbgConfig as any).__skipDeprecationWarning = true;
+            this.enableDebug(dbgConfig);
+            logger.info('[ScaleBun] Debug auto-connected via init({ debug }).');
+        } catch (err: any) {
+            logger.warn('[ScaleBun] Auto debug connection failed:', err?.message);
+        }
+    }
+
+    /** Boot the Phase 1 envelope tracking lane if an appId is configured. */
+    private _maybeStartEventTracker(rawConfig: any): void {
+        try {
+            const appId = rawConfig?.appId;
+            const enabled = rawConfig?.eventTracking !== false;
+            const clientKey = this._clientKey ?? rawConfig?.clientKey;
+            const apiBaseUrl = this._apiBaseUrl ?? rawConfig?.apiBaseUrl;
+            if (!enabled || !appId || !clientKey || !apiBaseUrl) {
+                if (enabled && !appId) {
+                    logger.info('[ScaleBun] Envelope event tracking disabled — no appId in init config.');
+                }
+                return;
+            }
+            // Phase 3: auto-apply SKAdNetwork conversion values from the server-side
+            // CV schema (iOS only; no-op elsewhere). Created BEFORE the tracker so the
+            // onEvent hook is live for the very first event (first_open).
+            if (isSkanAvailable()) {
+                this._skanManager = new SkanConversionManager({ apiBaseUrl, clientKey });
+                this._skanManager.refreshSchema().catch(() => {});
+            }
+            this._eventTracker = new EventTracker({
+                appId,
+                clientKey,
+                apiBaseUrl,
+                platform: rawConfig?.platform ?? 'react_native',
+                appVersion: rawConfig?.appVersion,
+                osVersion: rawConfig?.osVersion,
+                autoLifecycleEvents: rawConfig?.autoLifecycleEvents !== false,
+                // Backward-compatible opt-in: existing init-only integrations do
+                // not begin uploading the new automatic collector stream merely
+                // because they upgraded the package. ScaleBunProvider sets this
+                // to true unless the integrator explicitly disables it.
+                automaticEventTracking:
+                    rawConfig?.automaticEventTracking === true,
+                flushIntervalMs: rawConfig?.flushIntervalMs,
+                context: rawConfig?.context,
+                // Use the same foreground id as replay/journey capture. The
+                // callback is resolved per event because the session subsystem
+                // may start after this tracker is constructed.
+                sessionIdProvider: () => {
+                    const manager = SessionManager.getExistingInstance();
+                    return manager?.currentSessionId
+                        ?? manager?.getBackendTransport()?.analyticsSessionId
+                        ?? null;
+                },
+                // Feed every tracked event to the SKAN CV manager (iOS; no-op otherwise).
+                onEvent: (eventName, revenue) => this._skanManager?.onEvent(eventName, revenue),
+            });
+            this._eventTracker.start();
+            logger.info('[ScaleBun] Envelope event tracking started → /v1/batch.');
+
+            // Android: capture the Play Install Referrer once per install → feeds the
+            // deterministic click_id path + a one-off install_referrer event (UTM/gclid).
+            // Fire-and-forget; no-op off Android.
+            this._captureInstallReferrer(this._eventTracker);
+
+            // Phase 4: runtime config (flags / remote config / experiments / rollouts).
+            // Resolves locally; exposure + stamps flow through the event lane above.
+            const tracker = this._eventTracker;
+            this._configManager = new ConfigManager({
+                apiBaseUrl,
+                clientKey,
+                installationId: tracker.ids.installationId,
+                emitExposure: (experiment, variant) => tracker.track('experiment_exposure', { experiment, variant }),
+                stamp: (key, value) => tracker.stamp(key, value),
+            });
+            this._configManager.refresh().catch(() => {});
+        } catch (err: any) {
+            logger.warn('[ScaleBun] Failed to start envelope event tracking:', err?.message);
+        }
+    }
+
+    /**
+     * Android-only: read the Play Install Referrer once per install and route it into
+     * attribution. `scalebun_click_id` → the deterministic click path; the full
+     * referrer (utm_source/gclid/…) rides on a one-off `install_referrer` event. A
+     * `null` fetch (Play unavailable/transient) is not marked captured, so a later
+     * launch retries while Play still has the referrer. Never throws.
+     */
+    private _captureInstallReferrer(tracker: EventTracker): void {
+        try {
+            if (!isInstallReferrerAvailable()) return;
+            const storage = createStorageBackend();
+            const KEY = 'scalebun_install_referrer_done';
+            const sink: InstallReferrerSink = {
+                alreadyCaptured: () => { try { return storage.get(KEY) === '1'; } catch { return false; } },
+                markCaptured: () => { try { storage.set(KEY, '1'); } catch { /* no-throw */ } },
+                setClickId: (id) => tracker.setAttributionClickId(id),
+                emit: (name, props) => tracker.track(name, props as Record<string, any>),
+                fetch: () => getInstallReferrer(),
+            };
+            void captureInstallReferrerOnce(sink);
+        } catch (err: any) {
+            logger.warn('[ScaleBun] Install Referrer capture failed:', err?.message);
+        }
+    }
+
+    /**
+     * Phase 1 envelope event tracking API (POST /v1/batch).
+     * Methods are no-ops (never throw) until init() is called with an `appId`.
+     */
+    public get events() {
+        const tracker = this._eventTracker;
+        return {
+            track: (eventName: string, properties?: Record<string, any>) => tracker?.track(eventName, properties),
+            identify: (userId: string, traits?: Record<string, any>) => tracker?.identify(userId, traits),
+            trackPurchase: (input: { revenue: number; currency: string; transactionId: string; [k: string]: any }) =>
+                tracker?.trackPurchase(input),
+            setIdentifiers: (ids: { idfa?: string; gaid?: string; idfv?: string }) => tracker?.setIdentifiers(ids),
+            // Phase 2: record a deferred deep-link click token for deterministic install attribution.
+            setAttributionClickId: (clickId: string) => tracker?.setAttributionClickId(clickId),
+            flush: () => tracker?.flush() ?? Promise.resolve(),
+            newSession: () => tracker?.newSession(),
+            ids: () => tracker?.ids ?? null,
+            // Phase 3: update the SKAdNetwork conversion value (iOS only; no-op elsewhere).
+            updateSkanConversionValue: (value: number, coarseValue?: SkanCoarseValue, lockWindow?: boolean) =>
+                updateSkanConversionValue(value, coarseValue, lockWindow),
+        };
+    }
+
+    /**
+     * Phase 4: runtime config delivered via GET /v1/config. All resolution is local
+     * and non-throwing; values default sensibly until init() runs / config is fetched.
+     *
+     *   ScaleBun.config.get('max_items', 10)
+     *   ScaleBun.flags.isEnabled('new_checkout')
+     *   ScaleBun.rollouts.isOn('beta_paywall')
+     *   ScaleBun.experiments.variant('checkout_cta')   // → 'control' | 'treatment' | null
+     */
+    public get config() {
+        const cm = this._configManager;
+        return {
+            get: <T = any>(key: string, fallback: T): T => (cm ? cm.get(key, fallback) : fallback),
+            refresh: () => cm?.refresh() ?? Promise.resolve(),
+        };
+    }
+
+    public get flags() {
+        const cm = this._configManager;
+        return { isEnabled: (key: string) => cm?.isEnabled(key) ?? false };
+    }
+
+    public get rollouts() {
+        const cm = this._configManager;
+        return { isOn: (key: string) => cm?.rolloutIsOn(key) ?? false };
+    }
+
+    public get experiments() {
+        const cm = this._configManager;
+        return { variant: (key: string): string | null => cm?.variant(key) ?? null };
+    }
+
+    /** Convenience: emit a Phase 1 purchase event (revenue + currency + transaction_id). */
+    public trackPurchase(input: { revenue: number; currency: string; transactionId: string; [k: string]: any }): void {
+        noThrow(() => this._eventTracker?.trackPurchase(input));
+    }
+
+    /**
+     * Phase 3: set the SKAdNetwork fine conversion value (0–63), optionally with a
+     * SKAN 4.0 coarse value and window-lock. iOS only — a no-op on Android / Expo Go.
+     */
+    public updateSkanConversionValue(value: number, coarseValue?: SkanCoarseValue, lockWindow?: boolean): void {
+        noThrow(() => { void updateSkanConversionValue(value, coarseValue, lockWindow); });
+    }
+
+    // ─── Feature Flags ──────────────────────────────────────────────────
+
+    /** Get the current feature flags (consumed by enableDebug) */
+    public getFeatureFlags(): ScaleBunFeatures {
+        return this._features;
+    }
+
+    // ─── Identity ───────────────────────────────────────────────────────
+
+    /** Identify a user by ID and optional traits */
+    public identify(userId: string, traits?: Record<string, any>) {
+        return noThrow(() => {
+            this._identifiedUserId = userId;
+            if (!this.initialized) {
+                this._pendingIdentity = { userId, traits };
+                return;
+            }
+            this._pendingIdentity = null;
+            // Forward to the Phase 1 envelope lane (sets user_id for subsequent events).
+            this._eventTracker?.identify(userId, traits);
+            this.track('$identify', { id: userId, ...traits });
+            const sessionId = SessionManager.getExistingInstance()?.currentSessionId;
+            if (this._clientKey && sessionId) {
+                // Skip the network POST when the same identity was already sent for this
+                // session (repeat identify() with identical traits is a no-op upsert).
+                const identityKey = `${sessionId}|${userId}|${JSON.stringify(traits ?? {})}`;
+                if (identityKey !== this._lastIngestionIdentityKey) {
+                    this._lastIngestionIdentityKey = identityKey;
+                    const user: ScaleBunUser = {
+                        id: userId,
+                        name: traits?.name,
+                        email: traits?.email,
+                        properties: traits,
+                    };
+                    this._callIngestionIdentify(sessionId, user).catch(() => {
+                        // Re-arm on failure so a later retry is not suppressed.
+                        this._lastIngestionIdentityKey = null;
+                    });
+                }
+            }
+        });
+    }
+
+    /**
+     * Stable public alias for {@link identify}. Part of the minimal public push
+     * API surface (ScaleBun.init / identifyUser / enablePush) that stays
+     * identical across RN versions and future platforms.
+     */
+    public identifyUser(userId: string, traits?: Record<string, any>) {
+        return this.identify(userId, traits);
+    }
+
+    /** POST user identity to the SaaS ingestion identify endpoint */
+    private async _callIngestionIdentify(sessionId: string, user: ScaleBunUser): Promise<void> {
+        if (!this._clientKey || !this._apiBaseUrl) return;
+        const url = `${this._apiBaseUrl}/ingestion/sessions/${sessionId}/identify`;
+        try {
+            await fetch(url, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    'x-scalebun-client-key': this._clientKey,
+                },
+                body: JSON.stringify({
+                    userId: user.id,
+                    username: user.name,
+                    email: user.email,
+                    properties: user.properties,
+                }),
+            });
+        } catch (err: any) {
+            logger.warn('[ScaleBun] ingestion identify failed:', err?.message);
+        }
+    }
+
+    /** Set user identity (for session context) */
+    public setUser(user: ScaleBunUser) {
+        return noThrow(() => {
+            this.identify(user.id, {
+                name: user.name,
+                email: user.email,
+                ...user.attributes,
+            });
+        });
+    }
+
+    /** Clear user identity */
+    public clearUser() {
+        return noThrow(() => {
+            this._identifiedUserId = null;
+            this._pendingIdentity = null;
+            if (!this.initialized) return;
+            this._eventTracker?.clearIdentity();
+            this.track('$clear_user', {});
+        });
+    }
+
+    /**
+     * Submit in-app rating (1-5 stars).
+     * Attaches to current session when available; otherwise sends standalone.
+     * Never throws.
+     */
+    public submitRating(input: {
+        rating: number;
+        comment?: string;
+        source?: 'in_app' | 'prompt' | 'manual';
+        /** [ADDITIVE] client-generated UUID for app-rating idempotency (contract §1.4, D8). */
+        clientRatingId?: string;
+    }) {
+        return safeAsync(async () => {
+            if (!this._clientKey || !this._apiBaseUrl) return { ok: false, reason: 'sdk_not_configured' as const };
+            const rating = Math.round(Number(input?.rating));
+            if (!Number.isFinite(rating) || rating < 1 || rating > 5) {
+                return { ok: false, reason: 'invalid_rating' as const };
+            }
+
+            const sessionId = this.getActiveSessionId();
+            const meta = SessionManager.getExistingInstance()?.currentSessionMetadata;
+            const path = sessionId
+                ? `/ingestion/sessions/${sessionId}/rating`
+                : `/ingestion/ratings`;
+            const url = `${this._apiBaseUrl}${path}`;
+
+            try {
+                const res = await fetch(url, {
+                    method: 'POST',
+                    headers: {
+                        'Content-Type': 'application/json',
+                        'x-scalebun-client-key': this._clientKey,
+                    },
+                    body: JSON.stringify({
+                        rating,
+                        comment: input.comment,
+                        source: input.source ?? 'in_app',
+                        appVersion: meta?.appVersion,
+                        platform: meta?.platform,
+                        // [ADDITIVE] idempotency + versioning (contract §1.4); omitted when unset.
+                        ...(input.clientRatingId ? { clientRatingId: input.clientRatingId } : {}),
+                        schemaVersion: ENGAGE_SCHEMA_VERSION,
+                    }),
+                });
+                if (!res.ok) {
+                    logger.warn('[ScaleBun] submitRating non-ok', res.status);
+                    return { ok: false, reason: 'http_error' as const, status: res.status };
+                }
+                return { ok: true as const };
+            } catch (err: any) {
+                logger.warn('[ScaleBun] submitRating failed:', err?.message);
+                return { ok: false, reason: 'network_error' as const };
+            }
+        });
+    }
+
+    private getActiveSessionId(): string | null {
+        try {
+            return SessionManager.getExistingInstance()?.currentSessionId ?? null;
+        } catch {}
+        return null;
+    }
+
+    // ─── Engage ─────────────────────────────────────────────────────────
+
+    /**
+     * Lazily resolve the Engage transport. Requires a configured SaaS clientKey +
+     * apiBaseUrl (same gate as the rating/ingestion lanes); returns null otherwise.
+     * The transport mirrors the existing BackendSessionAdapter outbox: upload lanes
+     * batch-flush and re-queue on failure, the config GET is a direct fetch.
+     */
+    private _getEngageTransport(): EngageTransport | null {
+        if (!this._clientKey || !this._apiBaseUrl) return null;
+        if (!this._engageTransport) {
+            this._engageTransport = new EngageTransport({
+                endpoint: this._apiBaseUrl,
+                clientKey: this._clientKey,
+            });
+        }
+        return this._engageTransport;
+    }
+
+    /**
+     * Engage surface namespace (foundation: transport + native push-token plumbing).
+     *
+     * Rendering of campaigns/in-app messages is a SHARED cross-platform JS overlay
+     * (D4) built in a later stage. This namespace exposes only the foundation:
+     * versioned config fetch, idempotent response/event upload (via the existing
+     * outbox), and native push-token registration on both platforms.
+     */
+    public engage = {
+        /** Current external identity, forwarded by the provider for segment targeting. */
+        getIdentifiedUserId: (): string | undefined =>
+            this._identifiedUserId ?? undefined,
+
+        /**
+         * Fetch the versioned Engage config (campaigns + in-app messages).
+         *
+         * slice-agent: the shared cross-platform JS overlay renderer consumes this
+         * payload (EngageConfigResponse.campaigns / .inAppMessages) in a later stage.
+         */
+        fetchConfig: async (
+            context?: EngageConfigContext,
+        ): Promise<EngageConfigResponse | null> => {
+            const transport = this._getEngageTransport();
+            if (!transport) return null;
+            const [engageConfig, coachConfig] = await Promise.all([
+                transport.fetchEngageConfig(context),
+                transport.fetchCoachConfig(),
+            ]);
+            if (!engageConfig && !coachConfig) return null;
+            const coachMessages = (coachConfig?.tours ?? [])
+                .filter((tour) => Array.isArray(tour.steps) && tour.steps.length > 0)
+                .map((tour) => ({
+                    id: tour.id,
+                    layout: 'tooltip' as const,
+                    trigger: 'app_open',
+                    variantKey: 'coachmark_spotlight',
+                    revision: String(tour.version),
+                    preview: tour.preview === true,
+                    spec: {
+                        title: tour.name,
+                        body: tour.steps[0]?.body ?? tour.name,
+                        anchorKey: tour.steps[0]?.anchorKey,
+                        ext: {
+                            coachTourId: tour.id,
+                            coachTourVersion: tour.version,
+                            steps: tour.steps,
+                        },
+                    },
+                }));
+            return {
+                configVersion: engageConfig?.configVersion ?? 1,
+                serverTime: engageConfig?.serverTime ?? new Date().toISOString(),
+                campaigns: engageConfig?.campaigns ?? [],
+                inAppMessages: [...(engageConfig?.inAppMessages ?? []), ...coachMessages],
+            };
+        },
+
+        /** Internal bridge used by the shared renderer to feed standalone tour analytics. */
+        trackCoachmarkEvent: (name: string, properties: Record<string, unknown>): void => {
+            this.track(name, properties as Record<string, any>);
+        },
+
+        /**
+         * DEBUG/DEV ONLY — clear the persisted in-app/campaign frequency-cap state
+         * (every `scalebun_engage_throttle:*` key: impressions, showOnce/completed, cooldown).
+         * Lets a tester see throttled/dismissed messages again WITHOUT uninstalling the
+         * app. Does NOT change the device id (identity is preserved). Returns the number
+         * of cleared entries. NOT a substitute for the real fix (revision-scoped state +
+         * test-preview bypass already make normal Send Test work without this).
+         */
+        clearInAppMessageCache: (): number => {
+            return noThrow(() => new EngageThrottleStore().clearAll() + new EngageTestSeenStore().clear()) ?? 0;
+        },
+
+        /**
+         * DEBUG/DEV ONLY — alias of {@link clearInAppMessageCache} with the broader name
+         * used in docs. Resets all on-device in-app frequency/dismiss/impression state so
+         * the next config poll can show messages again. Identity (device id) is untouched.
+         */
+        resetInAppState: (): number => {
+            // Clears BOTH lanes: production frequency/dismiss/impression state (throttle
+            // store) AND the one-shot test-seen store — so a dismissed test reappears after
+            // a debug reset (the "block forever UNLESS debug reset" contract). Identity
+            // (device id) is a separate key and stays untouched.
+            return noThrow(() => new EngageThrottleStore().clearAll() + new EngageTestSeenStore().clear()) ?? 0;
+        },
+
+        /**
+         * Force an immediate flush of queued in-app events. The provider calls this right
+         * after a TEST preview's impression/dismiss ACK so the backend consumes the
+         * one-shot preview row promptly — a fast close→kill→reopen can't re-serve a
+         * still-`delivered` test. Best-effort, never throws.
+         */
+        flushEvents: (): void => {
+            noThrow(() => this._getEngageTransport()?.flushEventsNow());
+        },
+
+        /**
+         * DEBUG/DEV ONLY — force a fresh config fetch (deviceId in context) and return the
+         * in-app messages the backend is serving THIS device right now, including any
+         * queued test previews (`preview:true`). Use it to verify Send Test targeting/
+         * delivery without rendering. Logs a one-line summary for the dev console.
+         */
+        debugFetchInAppMessages: async (
+            context?: EngageConfigContext,
+        ): Promise<EngageConfigResponse['inAppMessages']> => {
+            const cfg = await (this._getEngageTransport()?.fetchEngageConfig(context) ?? Promise.resolve(null));
+            const messages = cfg?.inAppMessages ?? [];
+            const previews = messages.filter((m) => m.preview === true || m.isTest === true);
+            logger.info(
+                `[Engage] debugFetchInAppMessages → ${messages.length} message(s), ${previews.length} test preview(s)`,
+            );
+            return messages;
+        },
+
+        /** Upload a survey/NPS/feedback response (idempotent, rides the outbox). */
+        submitResponse: (input: EngageResponseInput): void => {
+            noThrow(() => this._getEngageTransport()?.uploadEngageResponse(input));
+        },
+
+        /**
+         * [P3-e] Submit a response carrying native attachments (screenshot/voice).
+         * Presigns + PUTs bytes direct to storage, then enqueues the response with
+         * key-only metadata linked by responseId. Falls back to a plain response
+         * (no media) when storage is disabled. Best-effort, never throws.
+         */
+        submitResponseWithAttachments: (
+            input: EngageResponseInput,
+            attachments: EngageAttachmentDraft[],
+        ): void => {
+            noThrow(() => {
+                void this._getEngageTransport()?.submitResponseWithAttachments(input, attachments);
+            });
+        },
+
+        /**
+         * [Slice D5] CONFIRMED response submit for the in-prompt submitting→success→error
+         * UI. UNLIKE submitResponse*, this AWAITS real server persistence (presign+PUT any
+         * audio/screenshot bytes, then a direct response POST) and REJECTS on failure so the
+         * caller can show a retryable error. Idempotent: pass the SAME `responseId` on retry
+         * — both response and attachments de-dupe server-side. Used by EVERY question type.
+         */
+        submitResponseConfirmed: (
+            input: EngageResponseInput,
+            attachments: EngageAttachmentDraft[],
+            opts: { responseId: string; onStage?: (stage: SubmitStage) => void },
+        ): Promise<void> => {
+            const transport = this._getEngageTransport();
+            if (!transport) return Promise.reject(new Error('sdk_not_configured'));
+            return transport.submitResponseConfirmed(input, attachments, opts);
+        },
+
+        /** Upload an in-app impression/click/dismiss event (idempotent, rides the outbox). */
+        trackEvent: (input: EngageEventInput): void => {
+            noThrow(() => {
+                const automaticName: Partial<Record<EngageEventInput['type'], AutomaticEventName>> = {
+                    impression: 'in_app_displayed',
+                    rendered: 'in_app_displayed',
+                    completion: 'in_app_completed',
+                    click: 'in_app_clicked',
+                    dismiss: 'in_app_dismissed',
+                    interaction: 'in_app_interaction',
+                    render_failed: 'in_app_render_failed',
+                    cta_open_failed: 'in_app_cta_open_failed',
+                };
+                const eventName = automaticName[input.type];
+                if (eventName) {
+                    emitAutomaticEvent(eventName, {
+                        campaign_id: input.campaignId,
+                        variant_id: input.variantId,
+                        preview_id: input.previewId,
+                        is_test: input.isTest,
+                        source: input.source,
+                        interaction_type:
+                            typeof input.meta?.type === 'string'
+                                ? input.meta.type
+                                : undefined,
+                    });
+                }
+                this._getEngageTransport()?.uploadEngageEvent(input);
+            });
+        },
+
+        /** Upload an idempotent survey shown/started funnel beacon. */
+        trackSurveyImpression: (input: SurveyImpressionInput): void => {
+            noThrow(() => this._getEngageTransport()?.uploadSurveyImpression(input));
+        },
+
+        /**
+         * Emit a rating-funnel tracking event (ratings-rebuild CONTRACT §1.2). These
+         * are dimensioned FACTS feeding the Overview funnel — NOT campaign responses
+         * (D1) — so they ride their own `/ingestion/rating-events` lane. Idempotent
+         * (client `eventId`, D8). Best-effort, never throws.
+         */
+        emitRatingEvent: (input: RatingFunnelEventInput): void => {
+            noThrow(() => {
+                emitAutomaticEvent(input.type, {
+                    prompt_id: input.promptId,
+                    trigger_id: input.triggerId,
+                    variant_id: input.variantId,
+                    stars: input.stars,
+                });
+                this._getEngageTransport()?.uploadRatingEvent(input);
+            });
+        },
+
+        /**
+         * Trigger the native in-app review sheet (Play In-App Review on Android,
+         * SKStoreReviewController on iOS) — the genuinely-native leg of the rating
+         * funnel (D5). Resolves `true` ONLY when the OS flow ran/resolved after a
+         * positive route, so the caller emits `store_redirect_clicked` solely on a
+         * `true` result. Fail-soft: resolves `false` when native review is unavailable.
+         */
+        requestStoreReview: async (): Promise<boolean> => {
+            return (await safeAsync(async () => requestNativeStoreReview())) ?? false;
+        },
+
+        /**
+         * Submit a 1–5 app-store rating via the EXISTING app-rating lane (D1 keeps
+         * ratings a distinct funnel — NOT submitResponse). Delegates to the
+         * facade's `submitRating`, threading the renderer's `clientRatingId` for
+         * idempotency (D8). Used by the RATING_PROMPT render branch.
+         */
+        submitRating: (input: {
+            rating: number;
+            comment?: string;
+            source?: 'in_app' | 'prompt' | 'manual';
+            clientRatingId?: string;
+        }): void => {
+            noThrow(() => {
+                void this.submitRating(input);
+            });
+        },
+
+        /**
+         * Acquire the native push token (FCM/APNs) and register it for delivery.
+         * Subscribes to native token-refresh (rotation) so the backend always holds
+         * the live token. Fail-soft: no-op when native push is unavailable.
+         */
+        registerForPush: async (): Promise<void> => {
+            return safeAsync(async () => {
+                const transport = this._getEngageTransport();
+                if (!transport) return;
+
+                const initial = await getNativePushToken();
+                if (initial) {
+                    transport.registerDeviceToken({
+                        pushToken: initial.token,
+                        platform: initial.platform,
+                        pushProvider: initial.platform === 'ios' ? 'apns' : 'fcm',
+                    });
+                }
+
+                // Avoid stacking listeners on repeated calls.
+                this._engageTokenUnsubscribe?.();
+                this._engageTokenUnsubscribe = subscribeNativePushTokenRefresh((refreshed) => {
+                    this._getEngageTransport()?.registerDeviceToken({
+                        pushToken: refreshed.token,
+                        platform: refreshed.platform,
+                        pushProvider: refreshed.platform === 'ios' ? 'apns' : 'fcm',
+                    });
+                });
+            }) as Promise<void>;
+        },
+    };
+
+    // ─── Push Notifications ─────────────────────────────────────────────
+
+    /**
+     * Lazily build the PushManager. Backend token registration is injected and
+     * routes through the existing Engage outbox (EngageTransport.registerDeviceToken),
+     * so push reuses the SDK's single device-token lane rather than a parallel
+     * fetch. Returns {ok:false} when the SDK isn't configured (clientKey absent).
+     */
+    private _getPushManager(): PushManager {
+        if (!this._pushManager) {
+            this._pushManager = new PushManager({
+                registerToken: async (input) => {
+                    const transport = this._getEngageTransport();
+                    if (!transport) return { ok: false, reason: 'sdk_not_configured' as const };
+                    transport.registerDeviceToken({
+                        pushToken: input.pushToken,
+                        platform: input.platform,
+                        pushProvider: input.pushProvider,
+                        sdkVersion: SDK_VERSION,
+                        ...(this._eventTracker
+                            ? { installationId: this._eventTracker.getInstallationId() }
+                            : {}),
+                    });
+                    return { ok: true as const };
+                },
+            });
+        }
+        return this._pushManager;
+    }
+
+    /**
+     * Enable push notifications with smart, version-aware adapter selection.
+     *
+     * Detects the RN version, architecture (legacy bridge vs New
+     * Architecture/bridgeless), whether @react-native-firebase/messaging is
+     * installed & compatible, and whether the ScaleBunEngage native token bridge is
+     * linked, then picks the safest supported path automatically: RNFirebase
+     * (full callbacks) → native ScaleBunEngage bridge (token-only fallback that works
+     * under bridgeless regardless of RNFirebase version) → manual → noop.
+     *
+     * Requests OS permission, creates the Android channel, acquires the push
+     * token, keeps it in sync on refresh, registers it with the ScaleBun backend
+     * (via the Engage outbox), and wires foreground/opened callbacks.
+     *
+     * Fails clearly (ok:false + actionable reason) when no usable provider
+     * exists — never silently breaks. Never throws.
+     *
+     * ```ts
+     * await ScaleBun.enablePush({
+     *   onForegroundNotification: (n) => {},
+     *   onNotificationOpened: (n) => {},
+     * });
+     * ```
+     */
+    public enablePush(options?: EnablePushOptions): Promise<EnablePushResult> {
+        return this._getPushManager().enable(options ?? {});
+    }
+
+    /**
+     * Subscribe to notifications received while the app is foregrounded. Thin,
+     * platform-agnostic alias for `enablePush({ onForegroundNotification })`; use it
+     * to attach a handler after enablePush. Returns an unsubscribe function. Inert
+     * until push is enabled. (iOS direct APNs delivers these via the native
+     * UNUserNotificationCenter surface.)
+     */
+    public onForegroundNotification(cb: (notification: PushNotification) => void): () => void {
+        return noThrow(() => this._getPushManager().onForegroundNotification(cb)) ?? (() => {});
+    }
+
+    /**
+     * Subscribe to the user tapping a notification (open / deep-link), including the
+     * cold-start notification that launched the app. Thin alias for
+     * `enablePush({ onNotificationOpened })`. Returns an unsubscribe function. The
+     * event shape ({ data, title?, body? }) matches across Android and iOS.
+     */
+    public onNotificationOpened(cb: (notification: PushNotification) => void): () => void {
+        return noThrow(() => this._getPushManager().onNotificationOpened(cb)) ?? (() => {});
+    }
+
+    /**
+     * Push control namespace. Most apps only need {@link enablePush}; these are
+     * for the manual/custom provider path and diagnostics.
+     */
+    public push = {
+        /** Inject/rotate a token (manual provider) — syncs to the backend. */
+        setToken: (token: string): void => {
+            noThrow(() => this._getPushManager().setToken(token));
+        },
+        /** Current push token, if acquired. */
+        getToken: (): string | null => {
+            return noThrow(() => this._getPushManager().getToken()) ?? null;
+        },
+        /** Deliver a foreground notification to registered callbacks (manual provider). */
+        emitForeground: (message: PushNotification): void => {
+            noThrow(() => this._getPushManager().emitForeground(message));
+        },
+        /** Deliver a notification-open event to registered callbacks (manual provider). */
+        emitNotificationOpened: (message: PushNotification): void => {
+            noThrow(() => this._getPushManager().emitNotificationOpened(message));
+        },
+        /** Current push status: selected adapter, usability, reason, token. */
+        status: () => this._getPushManager().status(),
+        /** Tear down all push listeners. */
+        teardown: (): void => {
+            noThrow(() => this._pushManager?.teardown());
+        },
+    };
+
+    // ─── Event Tracking ─────────────────────────────────────────────────
+
+    /**
+     * Report the outcome of an OS permission prompt.
+     *
+     * Permission results were state the SDK held privately and never an event, so the core mobile
+     * growth loop — "reached the paywall → was prompted → granted" — could not be expressed as a funnel.
+     *
+     * Notification permission is captured AUTOMATICALLY (the SDK runs that prompt itself, see
+     * PushManager). Every other permission belongs to the host app: the SDK never sees a camera or
+     * location request, so guessing at one would be inventing data. Call this right after the prompt
+     * resolves:
+     *
+     * ```ts
+     * const { status } = await Location.requestForegroundPermissionsAsync();
+     * ScaleBun.trackPermission('location', status === 'granted' ? 'granted' : 'denied');
+     * ```
+     *
+     * `permission` is free-form on purpose — platforms disagree on names and a fixed enum would go
+     * stale — but stick to one spelling per permission or the funnel splits in two.
+     */
+    public trackPermission(
+        permission: string,
+        status: 'granted' | 'denied' | 'blocked' | 'undetermined' | 'limited',
+        details?: Record<string, any>,
+    ) {
+        return noThrow(() => {
+            const name = String(permission || '').trim();
+            if (!name) return; // Nothing to attribute the result to — drop rather than emit a blank.
+            emitAutomaticEvent('permission_result', {
+                ...details,
+                permission: name,
+                status,
+                // Distinguishes a host-reported result from the SDK's own push prompt.
+                source: 'host',
+            });
+        });
+    }
+
+    /** Track a named event with optional payload */
+    public track(name: string, payload?: Record<string, any>) {
+        return noThrow(() => {
+            if (!this.initialized && !name.startsWith('$')) {
+                logger.warn('SDK not initialized. Event dropped:', name);
+                return;
+            }
+            logger.debug('Tracking event:', name);
+
+            // Fan this event out to the Engage trigger engine. Same single funnel,
+            // extra observer — lets behavioral triggers (custom_event, failed_action,
+            // after_crash, network_error, before_logout, …) fire off events the SDK
+            // already produces, without a parallel capture pipeline.
+            engageSignals.emit(name, payload);
+
+            const adapter = SessionManager.getExistingInstance()?.getBackendTransport();
+            if (this._clientKey && adapter) {
+                // SaaS mode → always-on analytics ingestion lane (NOT /sdk/events).
+                // sessionId is stamped by the lane at flush time, so the call-time
+                // value is a placeholder; endpoint id == body sessionId by construction.
+                adapter.trackEvent({
+                    eventId: generateEventId(),
+                    sessionId: adapter.analyticsSessionId ?? '',
+                    ts: Date.now(),
+                    type: name === '$log' ? 'LOG_EMITTED' : 'USER_ACTION',
+                    subtype: name,
+                    payload,
+                });
+            } else {
+                // Legacy mode (projectId/publishableKey): persistent queue → /sdk/events.
+                const envelope = createEnvelope('event', { name, ...payload });
+                this._getQueue().add(envelope);
+            }
+
+            // Phase 1 analytics envelope lane (/batch → raw_events → events).
+            // Runs alongside the session/replay lane above; only active when an
+            // appId was configured at init. SDK-internal ($-prefixed) signals stay
+            // on the session/debug lane and must not pollute the events table — the
+            // split is owned by resolveEventLane (see analytics/eventLane).
+            if (this._eventTracker && resolveEventLane(name) === 'analytics') {
+                this._eventTracker.track(name, payload);
+            }
+
+            // Tap into debug stream if enabled (non-blocking)
+            const stream = _getStream();
+            if (stream) {
+                stream.tapEnvelope(createEnvelope('event', { name, ...payload }));
+            }
+
+            // Tap network events into performance feature
+            if (name === '$network_request' && this._performanceFeature?.isActive && payload) {
+                this._performanceFeature.processNetworkEvent(payload);
+            }
+        });
+    }
+
+    /** Log a message (convenience wrapper over track) */
+    public log(level: 'debug' | 'info' | 'warn' | 'error', message: string, data?: Record<string, unknown>) {
+        return this.track('$log', { level, message, ...data });
+    }
+
+    /**
+     * Capture a handled error/exception and deliver it to the backend
+     * errors endpoint (shows up in the dashboard Crashes view).
+     *
+     * No-throw. Routes to: desktop debug stream ($crash event) + SaaS
+     * backend errors ingestion (when a clientKey session is active).
+     */
+    public captureError(
+        error: Error | string,
+        context?: { screenName?: string; fatal?: boolean; type?: string; metadata?: Record<string, unknown> },
+    ) {
+        return noThrow(() => {
+            const err = typeof error === 'string' ? new Error(error) : error;
+            const isFatal = context?.fatal ?? false;
+
+            getCrashReporter().report({
+                source: 'handled',
+                type: context?.type ?? (isFatal ? 'crash' : 'handled'),
+                isFatal,
+                message: err.message,
+                stack: err.stack,
+                screenName: context?.screenName,
+                metadata: context?.metadata,
+            });
+
+            // Flush the event queue (desktop $crash) too
+            this.flush().catch(() => {});
+        });
+    }
+
+    /**
+     * DEV/TEST ONLY — trigger a real native crash to validate the native
+     * capture → next-launch drain → backend pipeline. No-op when the native
+     * module is unavailable. Do not ship calls to this in production code.
+     */
+    public nativeCrash() {
+        return noThrow(() => triggerNativeCrash());
+    }
+
+    /** Report a bug (convenience wrapper over track) */
+    public reportBug(description: string, metadata?: Record<string, unknown>) {
+        return this.track('$bug_report', { description, ...metadata });
+    }
+
+    /** Set a custom attribute on the current session */
+    public setAttribute(key: string, value: string | number | boolean) {
+        return this.track('$set_attribute', { key, value });
+    }
+
+    // ─── Flush ──────────────────────────────────────────────────────────
+
+    /** Force-flush all pending events */
+    public async flush() {
+        return safeAsync(async () => {
+            if (!this.initialized) return;
+            // SaaS mode has two analytics lanes: EventTracker writes normalized
+            // product events to /batch, while BackendSessionAdapter writes the
+            // matching timeline events to /ingestion/sessions/:id/events. Drain
+            // both before an app background/navigation can suspend their timers.
+            // The legacy persistent queue posts to /sdk/events, which the SaaS
+            // backend does not serve, so it remains exclusive to legacy mode.
+            if (this._clientKey) {
+                const adapter = SessionManager.getExistingInstance()?.getBackendTransport();
+                await Promise.all([
+                    this._eventTracker?.flush() ?? Promise.resolve(),
+                    adapter?.flushAnalytics() ?? Promise.resolve(),
+                ]);
+                return;
+            }
+            logger.debug('Flushing events from persistent queue...');
+            const httpClient = coreContainer.get<HttpClient>('HttpClient');
+            await flushQueue(this._getQueue(), httpClient, getDeviceId());
+        });
+    }
+
+    /**
+     * Enable the debug subsystem.
+     *
+     * @deprecated Use `ScaleBun.init({ debug: true })` instead.
+     * This method still works for backward compatibility.
+     */
+    public enableDebug(config: DebugConfig) {
+        return noThrow(() => {
+            if (!(config as any).__skipDeprecationWarning) {
+                logger.warn(
+                    '[ScaleBun] enableDebug() is deprecated. ' +
+                    'Use ScaleBun.init({ ..., debug: true }) instead.',
+                );
+            }
+
+            const gatedConfig = applyFeatureGatesToDebugConfig(config, this._features);
+            _enableDebug(gatedConfig);
+            _setFlushFn(() => this.flush() as Promise<void>);
+
+            const bootstrapPerfFeature = _getPerformanceFeature();
+            if (bootstrapPerfFeature) {
+                this._performanceFeature = bootstrapPerfFeature;
+                logger.debug('Performance feature linked from bootstrap');
+            }
+
+            logger.info('Debug enabled');
+        });
+    }
+
+    /** Disable the debug subsystem and clean up */
+    public disableDebug() {
+        return noThrow(() => {
+            _disableDebug();
+        });
+    }
+
+    /**
+     * Diagnostic-only: stamp the *expected* target for the very next gesture
+     * event. Calibration screens call this immediately before their onPress
+     * fires so SessionManager merges expectedTargetId / expectedNX / expectedNY
+     * into the stored gesture payload. Pure observability — never affects
+     * capture, normalization, or marker placement. TTL ≈ 500 ms.
+     */
+    public setCalibrationTarget(target: { targetId: string; expectedNX: number; expectedNY: number }): void {
+        noThrow(() => {
+            const mod = require('../features/journey/calibrationContext') as
+                typeof import('../features/journey/calibrationContext');
+            mod.setCalibrationTarget(target);
+        });
+    }
+
+    /**
+     * Debug utilities namespace.
+     * All methods are no-op if debug is not enabled.
+     */
+    public debug = {
+        addBreadcrumb: (message: string, data?: Record<string, unknown>) => {
+            noThrow(() => _addBreadcrumb(message, data));
+        },
+        ping: () => {
+            noThrow(() => _ping());
+        },
+        isEnabled: () => isDebugEnabled(),
+        sendMetric: (name: string, value: number, unit?: string, tags?: Record<string, string>) => {
+            sendDebugMetric(name, value, unit, tags);
+        },
+    };
+
+    // ─── Replay ─────────────────────────────────────────────────────────
+
+    /**
+     * Session Replay namespace.
+     * Provides control over session replay: recording, capture,
+     * user identity, privacy, breadcrumbs, and transport.
+     * All methods are no-op if replay feature is disabled.
+     */
+    public replay = {
+        start: (): Promise<void> => ReplaySdk.start(),
+        stop: (): Promise<void> => ReplaySdk.stop(),
+        pause: (): Promise<void> => ReplaySdk.pause(),
+        resume: (): Promise<void> => ReplaySdk.resume(),
+        captureFrame: (): Promise<void> => ReplaySdk.captureManualFrame(),
+        setUser: (user: ReplayUser): Promise<void> => ReplaySdk.setUser(user),
+        clearUser: (): Promise<void> => ReplaySdk.clearUser(),
+        addBreadcrumb: (breadcrumb: ReplayBreadcrumb): Promise<void> =>
+            ReplaySdk.addBreadcrumb(breadcrumb),
+        setPrivacy: (opts: Partial<ReplayPrivacyOptions>): Promise<void> =>
+            ReplaySdk.setPrivacyOptions(opts),
+        setEnabled: (enabled: boolean): Promise<void> => ReplaySdk.setEnabled(enabled),
+        setQuality: (quality: any): Promise<void> => ReplaySdk.setScreenshotQuality(quality),
+        setCaptureMode: (mode: any): Promise<void> => ReplaySdk.setCapturingMode(mode),
+        setScreen: (name: string): Promise<void> => ReplaySdk.setCurrentScreen(name),
+        flush: (): Promise<void> => ReplaySdk.flush(),
+        get isRecording(): boolean {
+            return ReplaySdk.isRecording;
+        },
+        get sessionId(): string | null {
+            return ReplaySdk.sessionId;
+        },
+    };
+
+    // ─── Performance ────────────────────────────────────────────────────
+
+    /**
+     * Performance monitoring namespace.
+     * Provides control over custom traces, screen load markers,
+     * and access to captured metrics.
+     * All methods are no-op if performance feature is disabled.
+     */
+    public performance = {
+        /** Start a custom trace. Returns traceId or null. */
+        startTrace: (name: string): string | null => {
+            return this._performanceFeature?.startTrace(name) ?? null;
+        },
+        /** Stop a custom trace by ID. */
+        stopTrace: (traceId: string): void => {
+            this._performanceFeature?.stopTrace(traceId);
+        },
+        /** Add a span to an active custom trace. */
+        addTraceSpan: (traceId: string, name: string, durationMs: number, data?: Record<string, unknown>): void => {
+            this._performanceFeature?.addTraceSpan(traceId, name, durationMs, data);
+        },
+        /** Attach a measurement to an active custom trace. */
+        addTraceMeasurement: (traceId: string, name: string, value: number, unit: string): void => {
+            this._performanceFeature?.addTraceMeasurement(traceId, name, value, unit);
+        },
+        /** Mark the start of a screen load. */
+        markScreenLoadStart: (screenName: string): void => {
+            this._performanceFeature?.markScreenLoadStart(screenName);
+        },
+        /** Mark the end of a screen load. */
+        markScreenLoadEnd: (screenName: string): void => {
+            this._performanceFeature?.markScreenLoadEnd(screenName);
+        },
+        /** Set the current screen for context correlation. */
+        setCurrentScreen: (screenName: string): void => {
+            this._performanceFeature?.setCurrentScreen(screenName);
+        },
+        /** Forward navigation state changes for auto screen load detection. */
+        onNavigationStateChange: (state: unknown): void => {
+            this._performanceFeature?.onNavigationStateChange(state);
+        },
+        /** Check if performance monitoring is active */
+        isActive: (): boolean => {
+            return this._performanceFeature?.isActive ?? false;
+        },
+        /**
+         * Send a raw performance metric through the transport.
+         * Used for manual/simulated performance metrics.
+         */
+        sendMetric: (name: string, value: number, unit?: string, tags?: Record<string, string>): void => {
+            if (!this._performanceFeature) {
+                logger.warn('performance.sendMetric: PerformanceFeature not available — is debug enabled?');
+                return;
+            }
+            this._performanceFeature.sendMetric(name, value, unit, tags);
+        },
+    };
+
+    // ─── Unified Session ────────────────────────────────────────────────
+
+    /**
+     * Unified Session namespace.
+     * Provides access to the unified SessionManager.
+     * Sessions auto-start on desktop connect.
+     */
+    public session = {
+        get isActive(): boolean {
+            return SessionManager.getExistingInstance()?.isActive ?? false;
+        },
+        get currentSessionId(): string | null {
+            return SessionManager.getExistingInstance()?.currentSessionId ?? null;
+        },
+        start: (metadata?: Record<string, unknown>): boolean => {
+            const sm = SessionManager.getExistingInstance();
+            if (!sm) {
+                logger.warn('session.start() — SessionManager not available.');
+                return false;
+            }
+            sm.startSession(metadata as Parameters<SessionManager['startSession']>[0]);
+            logger.info('session.start() ✅ sessionId:', sm.currentSessionId);
+            return true;
+        },
+        end: (reason?: 'ended' | 'timeout'): boolean => {
+            const sm = SessionManager.getExistingInstance();
+            if (!sm || !sm.isActive) return false;
+            sm.endSession(reason);
+            logger.info('session.end() ✅');
+            return true;
+        },
+        emitEvent: (type: string, data?: Record<string, unknown>) => {
+            const sm = SessionManager.getExistingInstance();
+            if (!sm || !sm.isActive) return;
+            sm.emitEvent(type as JourneyEventType, data as Parameters<SessionManager['emitEvent']>[1]);
+        },
+    };
+
+    // ─── Session Convenience Methods ────────────────────────────────────
+
+    /** Start a session (delegates to session namespace) */
+    public startSession(metadata?: Record<string, unknown>): boolean {
+        return this.session.start(metadata);
+    }
+
+    /** Stop the current session (delegates to session namespace) */
+    public stopSession(reason?: 'ended' | 'timeout'): boolean {
+        return this.session.end(reason);
+    }
+
+    // ─── Report / Export ───────────────────────────────────────────
+
+    /**
+     * Report generation and export namespace.
+     *
+     * Usage:
+     * ```ts
+     * // Export with default preset
+     * const result = await ScaleBun.report.export();
+     *
+     * // Export with a named preset
+     * const result = await ScaleBun.report.export('engineering');
+     *
+     * // Export with custom options
+     * const result = await ScaleBun.report.export({ format: 'pdf', detail: 'detailed' });
+     * ```
+     *
+     * Requires an active desktop debug connection (`debug: true` in init).
+     */
+    public report = {
+        /**
+         * Trigger a report export on the desktop application.
+         *
+         * @param presetOrOptions - Optional. A preset name ('executive', 'engineering', 'qa',
+         *   'forensic', 'journey', 'compact') or a SimplifiedExportOptions object.
+         * @returns Promise<ExportResult> with success status, file path, or error.
+         */
+        export: (presetOrOptions?: ExportPresetName | SimplifiedExportOptions): Promise<ExportResult> => {
+            return _requestExport(presetOrOptions);
+        },
+
+        /** Set SDK-wide privacy settings for report generation. */
+        setPrivacy: (config: PrivacyConfig): void => {
+            this._privacyConfig = { ...this._privacyConfig, ...config };
+            logger.debug('[report] Privacy config updated');
+        },
+
+        /** Set branding for exported reports. */
+        setBranding: (config: BrandingConfig): void => {
+            this._brandingConfig = { ...this._brandingConfig, ...config };
+            logger.debug('[report] Branding config updated');
+        },
+
+        /** Get current privacy config. */
+        getPrivacy: (): PrivacyConfig => ({ ...this._privacyConfig }),
+
+        /** Get current branding config. */
+        getBranding: (): BrandingConfig => ({ ...this._brandingConfig }),
+    };
+
+    // ─── Navigation ───────────────────────────────────────────────
+
+    /**
+     * Set the React Navigation container ref for automatic screen detection.
+     *
+     * This is the **recommended** way to enable auto screen detection.
+     * Once set, the SDK automatically detects screen changes and feeds them
+     * to all subsystems (SessionManager, PerformanceFeature, ProfilerFeature).
+     * No per-screen `<ScaleBunScreen>` or `useScaleBunScreen()` needed.
+     *
+     * ```ts
+     * import { NavigationContainer } from '@react-navigation/native';
+     * import ScaleBun from '@scalebun/react-native';
+     *
+     * const navigationRef = React.createRef();
+     *
+     * function App() {
+     *   useEffect(() => {
+     *     ScaleBun.setNavigationRef(navigationRef);
+     *   }, []);
+     *
+     *   return (
+     *     <NavigationContainer ref={navigationRef}>
+     *       ...screens...
+     *     </NavigationContainer>
+     *   );
+     * }
+     * ```
+     */
+    public setNavigationRef(ref: any): void {
+        noThrow(() => {
+            // Always stash on the global so heuristic polling / late consumers resolve it.
+            (globalThis as any).__scalebun_navigationRef = ref;
+
+            // Wire the LIVE AutoScreenDetector singleton (started by SDKBootstrapper in
+            // production). _getAutoScreenDetector() is the debug-only handle and is null
+            // when desktopDebug is off, so relying on it alone never wires the explicit
+            // React-Navigation 'state' listener and degrades to slow heuristic polling.
+            try {
+                const { AutoScreenDetector } = require('../features/navigation/AutoScreenDetector');
+                AutoScreenDetector.getInstance().setNavigationRef(ref);
+                logger.info('[ScaleBun] Navigation ref set → auto screen detection active');
+            } catch (err: any) {
+                logger.debug('[ScaleBun] Navigation ref stashed (detector not ready):', err?.message);
+            }
+        });
+    }
+}
+
+/** Singleton Facade instance */
+const instance = new ScaleBunFacade();
+export default instance;
+export { ScaleBunFacade };