@scalebun-release/react-native 2.5.0

package/src/public/ScaleBunFacade.ts

@@ -0,0 +1,2129 @@
+/**
+ * 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 { buildBugReportPayload } from '../features/bugreport/buildPayload';
+import type { BugSubmitResult } from '../features/bugreport/BugReportFeature';
+import { BugReportFeature } from '../features/bugreport/BugReportFeature';
+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 { mergeDeviceContext, nativeDeviceContext, resolveEventPlatform } from '../core/context/device';
+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 type { SubscriptionInput } from '../analytics/subscription';
+import type { RevenueInput } from '../analytics/revenue';
+import { bridgeAdapter } from '../features/replay/bridge/adapters/bridgeAdapter';
+import {
+    emitAutomaticEvent,
+    type AutomaticEventName,
+} from '../analytics/automaticEvents';
+import { resolveEventLane, isUploadedSessionEvent } from '../analytics/eventLane';
+import { ConfigManager } from '../config/ConfigManager';
+import { quotaState } from '../config/quotaState';
+import { resolveInstallationId } from '../core/id/installationId';
+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;
+    /**
+     * The ConfigManager that owns /config refreshes for quota: `_configManager` when the event
+     * tracker created one, else a quota-only instance (no appId → no tracker, but a clientKey still
+     * has a plan with limits). Never exposed through the flags/experiments API.
+     */
+    private _configRefresher: ConfigManager | null = null;
+    private _configForegroundListener: ((state: string) => void) | null = null;
+    /** The developer's locally-configured replay captureMode — the value to revert to when an
+     *  admin-forced frequency override (from /config) is withdrawn. Default matches the SDK default. */
+    private _devCaptureMode: string = 'interactions';
+    /** True while an admin frequency override from /config is applied, so we know to revert. */
+    private _replayOverrideActive = false;
+    /** 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 ?? {};
+            // Remember the developer's local replay captureMode so we can revert to it if an
+            // admin-forced frequency override (delivered via /config) is later withdrawn.
+            this._devCaptureMode = rawConfig?.replay?.captureMode ?? 'interactions';
+            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);
+                    // Quota (contract v1): /config must be live whenever a clientKey is configured,
+                    // not only when the appId-gated event tracker created a ConfigManager above.
+                    this._startConfigLifecycle();
+                    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
+            }
+
+            // OTA from init config. Without this the whole `ota` config block was
+            // inert: `otaOrchestrator.init()` was reachable only by importing the
+            // orchestrator directly, so an app that followed the documented
+            // `ota: { enabled: true }` path silently got no updates AND no
+            // signature enforcement (sync() gates on the flag init() sets).
+            this._maybeStartOta(rawConfig);
+
+            // 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;
+        }
+    }
+
+    /**
+     * Boot the OTA orchestrator when the init config asks for it.
+     *
+     * Signature enforcement is no longer configured from JS. Signed releases are
+     * verified and staged in NATIVE code against RSA keys embedded in the app
+     * package (SB-OTA-RSA-SHA256-V1); unsigned releases keep working on SHA-256
+     * integrity. There are no signing-key or `verifySignature` options to pass
+     * through — the host embeds its trusted keys natively.
+     */
+    private _maybeStartOta(rawConfig: any): void {
+        const ota = rawConfig?.ota;
+        if (!ota?.enabled) return;
+        try {
+            // Required lazily: hosts that never enable OTA should not pay for the
+            // module (or touch the native spec) at import time.
+            // eslint-disable-next-line @typescript-eslint/no-var-requires
+            const { otaOrchestrator } = require('../features/ota/OtaOrchestrator');
+            // `healthyAfterMs` is the field BootGuardConfig actually declares.
+            // This passed `healthyTimeoutMs`, which nothing reads, so a host that
+            // tuned the boot-guard window silently got the 10s default instead.
+            // Both spellings are accepted so the older one keeps working.
+            const healthyAfterMs =
+                typeof ota.healthyAfterMs === 'number'
+                    ? ota.healthyAfterMs
+                    : typeof ota.healthyTimeoutMs === 'number'
+                      ? ota.healthyTimeoutMs
+                      : undefined;
+
+            // Root/jailbreak policy. ONLY the literal string 'withhold' opts in;
+            // anything else (absent, a typo, a truthy object) falls through to
+            // 'allow', which is the behaviour every existing app already has.
+            // A config typo must never be able to stop a fleet's updates.
+            const onCompromisedDevice: 'allow' | 'withhold' =
+                ota.onCompromisedDevice === 'withhold' ? 'withhold' : 'allow';
+
+            otaOrchestrator.init({
+                ...(healthyAfterMs !== undefined ? { healthyAfterMs } : {}),
+                onCompromisedDevice,
+            });
+            if (onCompromisedDevice === 'withhold') {
+                logger.info(
+                    "[ScaleBun] OTA will be WITHHELD on devices reporting root/jailbreak indicators (ota.onCompromisedDevice: 'withhold').",
+                );
+            }
+            logger.info('[ScaleBun] OTA enabled from init config.');
+
+            // Run the checks the config asked for. Until this existed, `ota.enabled`
+            // initialised the orchestrator and then never checked anything: the
+            // documented `checkOnForeground` and `channelOverride` options were read
+            // by no code at all, and an app following the documented config received
+            // updates only if it ALSO drove `useOtaUpdate` or the CodePush shim by
+            // hand. Nothing logged, because "no update available" and "never asked"
+            // look identical from the outside.
+            this._startOtaChecks(ota);
+        } catch (err: any) {
+            logger.warn(`[ScaleBun] OTA init failed: ${err?.message ?? err}`);
+        }
+    }
+
+    /** Guards against overlapping config-driven OTA checks. */
+    private _otaCheckInFlight = false;
+    /** Wall clock of the last config-driven check, for the foreground floor. */
+    private _otaLastCheckAt = 0;
+    private _otaForegroundListener: ((state: string) => void) | null = null;
+
+    /**
+     * Minimum gap between config-driven checks.
+     *
+     * A foreground transition is cheap to trigger — app switchers, permission
+     * dialogs and share sheets all produce one — so an unthrottled check would
+     * put a request on the hot path every time the user glanced away. Ten
+     * minutes is well below any realistic release cadence and well above that
+     * noise. A host that wants a check on demand calls `useOtaUpdate().sync()`,
+     * which is never throttled.
+     */
+    private static readonly OTA_MIN_CHECK_INTERVAL_MS = 10 * 60 * 1000;
+
+    /**
+     * Drive OTA checks from init config: once at startup, then on each
+     * foreground when `checkOnForeground` is on (the schema default).
+     *
+     * `appVersion` is resolved from the native bridge rather than asked of the
+     * integrator, because it gates the server's `targetAppVersion` semver check
+     * — sending a wrong or invented value is worse than sending none, and there
+     * is no honest default. If it cannot be resolved, the check is skipped with
+     * a warning instead of guessing.
+     */
+    private _startOtaChecks(ota: any): void {
+        // Never in a debug build. `ScaleBunOtaModule.getJSBundleFile()` returns null
+        // there on purpose so Metro keeps ownership of the bundle — so a bundle
+        // downloaded in dev is installed into a slot that will never be loaded, and
+        // the identity check on the next launch then correctly observes that the
+        // running code is not what was installed and reports APPLY_FAILED. Checking
+        // at all in dev buys nothing and manufactures that false alarm. A developer
+        // testing the OTA path drives `useOtaUpdate().sync()` explicitly.
+        if (__DEV__) {
+            logger.info('[ScaleBun] OTA checks are skipped in debug builds (Metro owns the bundle).');
+            return;
+        }
+
+        const runCheck = async (trigger: 'startup' | 'foreground'): Promise<void> => {
+            if (this._otaCheckInFlight) return;
+            if (
+                trigger === 'foreground' &&
+                Date.now() - this._otaLastCheckAt < ScaleBunFacade.OTA_MIN_CHECK_INTERVAL_MS
+            ) {
+                return;
+            }
+            const clientKey = this._clientKey;
+            const apiUrl = this._apiBaseUrl;
+            if (!clientKey || !apiUrl) {
+                return;
+            }
+
+            this._otaCheckInFlight = true;
+            try {
+                const info = await bridgeAdapter.getDeviceInfo();
+                const appVersion = (info as { appVersion?: string } | null)?.appVersion;
+                if (!appVersion) {
+                    logger.warn(
+                        '[ScaleBun] OTA check skipped — the app version could not be read from the ' +
+                            'native bridge. Rebuild the native app, or drive checks yourself with ' +
+                            'useOtaUpdate({ appVersion }).',
+                    );
+                    return;
+                }
+                this._otaLastCheckAt = Date.now();
+                // eslint-disable-next-line @typescript-eslint/no-var-requires
+                const { otaOrchestrator } = require('../features/ota/OtaOrchestrator');
+                await otaOrchestrator.sync({
+                    apiUrl,
+                    clientKey,
+                    appVersion,
+                    // The documented option, finally connected. Omitted means the
+                    // server's `default` channel, exactly as before.
+                    channelName: typeof ota.channelOverride === 'string' ? ota.channelOverride : undefined,
+                    // Never forced from config: the release's own installMode
+                    // decides when the app restarts, and yanking the screen out
+                    // from under a user is not a decision this switch should make.
+                });
+            } catch (err: any) {
+                logger.warn(`[ScaleBun] OTA check failed: ${err?.message ?? err}`);
+            } finally {
+                this._otaCheckInFlight = false;
+            }
+        };
+
+        void runCheck('startup');
+
+        if (ota.checkOnForeground === false) return;
+        if (this._otaForegroundListener) return; // idempotent across repeated init()
+        try {
+            // Through `appLifecycle`, not a second AppState subscription: the SDK
+            // already owns one and fanning out from it keeps every consumer on the
+            // same transition sequence.
+            // eslint-disable-next-line @typescript-eslint/no-var-requires
+            const { appLifecycle } = require('../core/lifecycle/appLifecycle');
+            this._otaForegroundListener = (state: string) => {
+                if (state === 'active') void runCheck('foreground');
+            };
+            appLifecycle.addListener(this._otaForegroundListener);
+        } catch {
+            // Lifecycle unavailable (tests, exotic hosts) — the startup check stands.
+            this._otaForegroundListener = 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);
+        }
+    }
+
+    /**
+     * Keep /config (and with it the per-feature quota state) live for any clientKey-configured app.
+     *
+     *  - Creates a quota-only ConfigManager when the appId-gated event tracker did not create one.
+     *    Its exposure/stamp hooks are inert; it is not the flags API's manager.
+     *  - Registers the FORCED refresh quotaState runs when a block's refresh time is reached (the
+     *    only way a block is lifted — never the device clock alone).
+     *  - Refreshes on foreground, throttled by ConfigManager's 5-minute TTL (ETag-aware), which is how
+     *    a raised limit reaches a long-lived app.
+     *
+     * BEHAVIOUR CHANGE, deliberate (quota contract v1): apps WITHOUT an appId now fetch /config once
+     * per launch, and every clientKey app re-fetches it on foreground after 5 minutes. That fetch is
+     * how a block — and the raising of a limit — reaches the device; it is not an ingestion request.
+     * The quota-only manager applies NOTHING else from /config: no flags API, no experiment
+     * exposure, and no admin replayCapture override (that stays an appId-app behaviour, as before).
+     */
+    private _startConfigLifecycle(): void {
+        try {
+            const clientKey = this._clientKey;
+            const apiBaseUrl = this._apiBaseUrl;
+            if (!clientKey || !apiBaseUrl) return;
+            let mgr = this._configManager;
+            // Repeat init() without an appId: reuse the quota-only manager instead of stacking one
+            // ConfigManager (and one /config fetch) per call.
+            if (!mgr && this._configRefresher) mgr = this._configRefresher;
+            if (!mgr) {
+                mgr = new ConfigManager({
+                    apiBaseUrl,
+                    clientKey,
+                    installationId: resolveInstallationId(),
+                    emitExposure: () => {},
+                    stamp: () => {},
+                    // Quota only: no onReplayCapture — an app without appId never honored the admin
+                    // capture override before, and fetching /config for quota must not change that.
+                });
+                mgr.refresh().catch(() => {});
+            }
+            this._configRefresher = mgr;
+            const refresher = mgr;
+            quotaState.setRefresher(() => refresher.refresh({ force: true }));
+
+            if (this._configForegroundListener) return; // idempotent across repeated init()
+            // eslint-disable-next-line @typescript-eslint/no-var-requires
+            const { appLifecycle } = require('../core/lifecycle/appLifecycle');
+            this._configForegroundListener = (state: string) => {
+                if (state === 'active') this._configRefresher?.maybeRefresh();
+            };
+            appLifecycle.addListener(this._configForegroundListener);
+        } catch (err: any) {
+            logger.warn('[ScaleBun] Config lifecycle unavailable:', err?.message);
+        }
+    }
+
+    /**
+     * Release what _startConfigLifecycle registered (the forced-refresh hook and the foreground
+     * listener). The facade has no teardown path today; this is the one to call when it gets one.
+     */
+    private _stopConfigLifecycle(): void {
+        try {
+            quotaState.setRefresher(null);
+            if (this._configForegroundListener) {
+                // eslint-disable-next-line @typescript-eslint/no-var-requires
+                const { appLifecycle } = require('../core/lifecycle/appLifecycle');
+                appLifecycle.removeListener(this._configForegroundListener);
+            }
+        } catch { /* no-throw */ }
+        this._configForegroundListener = null;
+        this._configRefresher = null;
+    }
+
+    /** 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;
+            // apiBaseUrl is LOCKED — use only the bootstrapped value, never fall back to raw
+            // integrator input, so the event-tracker/SKAdNetwork lane can't be repointed either.
+            const apiBaseUrl = this._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,
+                // Auto-detected (Platform.OS) unless the integration overrides it — see resolveEventPlatform.
+                platform: rawConfig?.platform ?? resolveEventPlatform(),
+                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,
+                /**
+                 * DETECTED, not configured.
+                 *
+                 * This was `rawConfig?.context` — whatever the app typed. Production carries
+                 * `device_model: "android"` and `manufacturer: "android"` from a hand-written
+                 * literal, while the replay lane was reading the real values off the native bridge
+                 * the whole time. The SDK knows the device; the integrator is guessing at it.
+                 * Everything outside the detected keys is still theirs.
+                 */
+                // Everything Platform.constants knows. On iOS that is neither the model nor the
+                // manufacturer, so the bridge completes it below once it answers.
+                context: mergeDeviceContext(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.');
+
+            // Complete the device context from the native bridge.
+            //
+            // `Platform.constants` answers Android synchronously — model and manufacturer ride the
+            // first event. It answers NEITHER on iOS, so without this every iOS installation
+            // reported no device model at all: `nativeDeviceContext` existed for exactly this and
+            // had no caller, and the bridge's own answer was `UIDevice.current.model` — the string
+            // "iPhone", identical on every iPhone ever made.
+            //
+            // Fire-and-forget on purpose. The bridge is async and absent entirely on Expo Go or an
+            // older native binary; waiting on it would delay the first event, and failing on it
+            // would take analytics down over a nice-to-have field.
+            this._applyNativeDeviceContext(this._eventTracker);
+
+            // 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),
+                // Admin-controlled replay capture override: apply/revert timer capture as the
+                // server dictates, overriding the developer's local captureMode.
+                onReplayCapture: (override) => this._applyReplayCaptureOverride(override),
+            });
+            // Apply any cached override immediately (offline / pre-first-fetch); refresh() then
+            // re-applies with the latest value once /config responds.
+            this._applyReplayCaptureOverride(this._configManager.getReplayCapture());
+            this._configManager.refresh().catch(() => {});
+        } catch (err: any) {
+            logger.warn('[ScaleBun] Failed to start envelope event tracking:', err?.message);
+        }
+    }
+
+
+    /**
+     * Fold the native bridge's device facts into the analytics context once it answers.
+     *
+     * Detected values never overwrite a populated one with an empty one — `nativeDeviceContext`
+     * drops absent keys and `applyDetectedContext` ignores an empty patch — so a bridge that
+     * cannot answer leaves whatever `Platform.constants` already found.
+     */
+    private _applyNativeDeviceContext(tracker: EventTracker): void {
+        Promise.resolve()
+            .then(() => bridgeAdapter.getDeviceInfo())
+            .then(info => {
+                if (!info) return;
+                tracker.applyDetectedContext(
+                    nativeDeviceContext({
+                        osVersion: info.osVersion,
+                        deviceModel: info.deviceModel,
+                        // iOS ships no manufacturer over the bridge; it is a constant there and the
+                        // static path already set it. Android's arrives via Platform.constants.
+                    }),
+                );
+            })
+            .catch(() => { /* bridge unavailable — the static context stands */ });
+    }
+
+    /**
+     * Apply (or revert) the admin-controlled replay capture override delivered via GET /config.
+     *
+     * When the super-admin has forced timer capture, `override` is `{ mode: 'frequency', intervalMs }`
+     * and we switch replay to frequency at that interval — overriding the developer's local
+     * captureMode (which Part 1 restricts to navigation/interactions). When the override is withdrawn
+     * (`null`) AND we had previously applied one, we revert to the developer's configured mode.
+     *
+     * Non-throwing and a no-op when replay is disabled. Idempotent — re-applying the same override
+     * just re-asserts the native state, which is harmless.
+     */
+    private _applyReplayCaptureOverride(
+        override: { mode: 'frequency'; intervalMs: number } | null,
+    ): void {
+        try {
+            if (this._features.replay === false) return; // replay off — nothing to drive
+            if (override && override.mode === 'frequency') {
+                this._replayOverrideActive = true;
+                this.replay.setCaptureMode('frequency').catch(() => {});
+                ReplaySdk.setScreenshotCaptureInterval(override.intervalMs).catch(() => {});
+            } else if (this._replayOverrideActive) {
+                // Override withdrawn — restore the developer's configured captureMode.
+                this._replayOverrideActive = false;
+                this.replay.setCaptureMode(this._devCaptureMode).catch(() => {});
+            }
+        } catch { /* no-throw */ }
+    }
+    /**
+     * 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: RevenueInput) =>
+                tracker?.trackPurchase(input),
+            trackSubscription: (input: SubscriptionInput) =>
+                tracker?.trackSubscription(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,
+            /** Pending and dropped event counts for host diagnostics. */
+            stats: () => tracker?.stats ?? 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). */
+    /**
+     * Declare which UI state the user is looking at, so taps are attributed to the surface they
+     * happened on rather than averaged across every variant of the screen.
+     *
+     *     ScaleBun.setUiState('filter-sheet', 'open');
+     *     ScaleBun.setUiState('checkout-step', 'payment');
+     *
+     * Call it when the state CHANGES — the value is read at tap time, so it only has to be right by
+     * the time the next tap lands. On React Native this is the ONLY source of UI state: unlike the web,
+     * there is no queryable accessibility tree that says a sheet is up, and guessing would produce a
+     * state key that is right on some apps and silently wrong on others.
+     *
+     * Names and values are identifiers, not content: they become query keys in the dashboard, so a
+     * person's name or a cart total does not belong in one. `;`, `:` and `|` are stripped and both
+     * halves are capped at 32 characters.
+     */
+    public setUiState(name: string, value: string): void {
+        try {
+            const { setUiState } = require('../features/journey/uiState');
+            setUiState(name, value);
+        } catch { /* no-throw: a state declaration must never break the host */ }
+    }
+
+    /**
+     * Stop reporting a UI state dimension — or, with no argument, all of them.
+     *
+     * Clear on screen unmount. A declaration left behind follows the user onto a surface where it means
+     * nothing, and every tap there is filed under a state that was not on screen.
+     */
+    public clearUiState(name?: string): void {
+        try {
+            const { clearUiState } = require('../features/journey/uiState');
+            clearUiState(name);
+        } catch { /* no-throw */ }
+    }
+
+    public trackPurchase(input: RevenueInput): void {
+        noThrow(() => this._eventTracker?.trackPurchase(input));
+    }
+
+    /** Record a trial, renewal, plan change or cancellation in the subscription ledger. */
+    public trackSubscription(input: SubscriptionInput): void {
+        noThrow(() => this._eventTracker?.trackSubscription(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);
+            /**
+             * The session marker carries the user id ONLY — never the traits.
+             *
+             * This used to spread `...traits` into the event, and `track()` uploads it as a
+             * `USER_ACTION` on the session lane, unredacted. Production held 751 such rows in 7
+             * days with name/email/phone-verified fields in `replay_events.data`, shown in the
+             * replay timeline as user actions. Traits already travel on the lanes built for them:
+             * `_eventTracker.identify` above and the ingestion identify POST below.
+             */
+            this.track('$identify', { id: userId });
+            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.
+     *
+     * SB-11: pass `{ purgeLocal: true }` on logout / consent withdrawal to also
+     * erase all locally-stored SDK data (see {@link eraseLocalData}). Without it,
+     * behaviour is unchanged (identity-only clear).
+     */
+    public clearUser(options?: { purgeLocal?: boolean }) {
+        return noThrow(() => {
+            this._identifiedUserId = null;
+            this._pendingIdentity = null;
+            if (!this.initialized) return;
+            this._eventTracker?.clearIdentity();
+            this.track('$clear_user', {});
+            if (options?.purgeLocal) void this.eraseLocalData();
+        });
+    }
+
+    /**
+     * SB-11: erase all locally-stored SDK data from the device — the durable event
+     * queue, the pre-init buffer, and the first-party KV store (cached install /
+     * anonymous / session IDs, plus any queued payloads including SB-26 disk data).
+     *
+     * Order matters: capture is stopped FIRST so nothing is written back in behind
+     * the delete. Best-effort and never throws.
+     *
+     * Note: native replay frames written to disk on iOS are addressed separately
+     * (SB-15); this covers every store reachable from JS today.
+     */
+    public async eraseLocalData(): Promise<void> {
+        try {
+            // 1) Stop capture so no new frames/events are produced mid-erase.
+            try {
+                SessionManager.getExistingInstance()?.endSession('ended');
+            } catch { /* best-effort */ }
+            // 2) Clear the durable queue and the pre-init buffer.
+            try {
+                this._getQueue().clear();
+            } catch { /* best-effort */ }
+            try {
+                this._preInitBuffer.clear();
+            } catch { /* best-effort */ }
+            // 3) Wipe the first-party KV store (cached IDs + any on-disk queue
+            //    residue) by removing every key through the backend interface.
+            try {
+                const store = createStorageBackend();
+                for (const key of store.getAllKeys()) {
+                    store.delete(key);
+                }
+            } catch { /* best-effort */ }
+        } catch {
+            // Never throw — erasure is a safety operation on a best-effort basis.
+        }
+    }
+
+    /**
+     * SB-11: record the user's data-collection consent. When `enabled` is false,
+     * capture is stopped immediately; pass `{ purgeLocal: true }` to also erase
+     * everything already stored locally. Never throws.
+     */
+    public setConsent(enabled: boolean, options?: { purgeLocal?: boolean }): void {
+        noThrow(() => {
+            if (enabled) return;
+            try {
+                SessionManager.getExistingInstance()?.endSession('ended');
+            } catch { /* best-effort */ }
+            if (options?.purgeLocal) void this.eraseLocalData();
+        });
+    }
+
+    /**
+     * SB-10: return the effective privacy policy actually in force, resolving the
+     * public config against the SDK's safe defaults. Lets callers and tests assert
+     * what is active rather than guessing from the (previously dead) config object.
+     */
+    public getEffectivePrivacyPolicy(): Required<
+        Pick<PrivacyConfig, 'maskTextInputs' | 'maskImages' | 'redactAuth' | 'redactCookies' | 'redactBodies'>
+    > {
+        const p = this._privacyConfig ?? {};
+        return {
+            // Real default is true (matches the replay capture default) — the old
+            // doc comment claiming "false" was both wrong and less safe.
+            maskTextInputs: p.maskTextInputs ?? true,
+            maskImages: p.maskImages ?? false,
+            redactAuth: p.redactAuth ?? true,
+            redactCookies: p.redactCookies ?? true,
+            redactBodies: p.redactBodies ?? false,
+        };
+    }
+
+    /**
+     * 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;
+    }
+
+    // ─── Bug reports (F-BUG) ────────────────────────────────────────────
+
+    /**
+     * Thin feature object; the facade owns the HTTP, mirroring the web SDK split.
+     * Its only job here is raising the 'report' capture signal so replay flushes.
+     */
+    private readonly _bugReport = new BugReportFeature();
+
+    /**
+     * Submit a bug report against the CURRENT session.
+     *
+     * Mirrors the web SDK's `reportBugDetailed` ordering, which is load-bearing rather than
+     * incidental:
+     *
+     *   1. resolve the session   — a report with no session cannot be joined to its evidence
+     *   2. signal 'report'       — replay flushes its buffer so the report has visual context
+     *   3. snapshot the anchor   — BEFORE the POST. A flush asks the recorder to deliver pending
+     *                              bytes; it cannot retroactively manufacture a frame, so an absent
+     *                              coordinate must stay absent rather than becoming a misleading
+     *                              "start of session" link in the dashboard
+     *   4. build + POST          — bounds enforced by buildBugReportPayload against the server DTO
+     *
+     * Returns the report id, or `{ e }` naming which branch failed — 'init' (SDK not configured)
+     * reads differently from 'send' (network), and that difference is what tells an integrator
+     * whether to check their setup or their connection. It never throws: this is called from a UI
+     * the host app renders, usually from a user gesture, and an exception escaping into a React
+     * Native render tree is a redbox shown to the customer's user over a report they were sending us.
+     */
+    public async reportBugDetailed(input: {
+        message: string;
+        title?: string;
+        email?: string;
+        clientReportId?: string;
+    }): Promise<BugSubmitResult> {
+        if (!input || !input.message || input.message.trim().length === 0) {
+            logger.warn('[ScaleBun] reportBug: a message is required');
+            return { e: 'empty' };
+        }
+        if (!this._clientKey || !this._apiBaseUrl) {
+            logger.warn('[ScaleBun] reportBug: SDK is not configured (clientKey/apiBaseUrl)');
+            return { e: 'init' };
+        }
+
+        const sessionId = this.getActiveSessionId();
+        if (!sessionId) {
+            // No session means no row to attach to, and the ingestion route is session-scoped.
+            logger.warn('[ScaleBun] reportBug: no active session');
+            return { e: 'init' };
+        }
+
+        try {
+            // Flush replay into the session BEFORE reading the anchor below.
+            this._bugReport.signalReport();
+
+            const coord = this._replayCoord();
+            const payload = buildBugReportPayload(input, this._recentBreadcrumbs(), {
+                replayCoord: coord,
+                timestamp: Date.now(),
+            });
+
+            const res = await fetch(
+                `${this._apiBaseUrl}/ingestion/sessions/${sessionId}/bug-reports`,
+                {
+                    method: 'POST',
+                    headers: {
+                        'Content-Type': 'application/json',
+                        'x-scalebun-client-key': this._clientKey,
+                    },
+                    body: JSON.stringify(payload),
+                },
+            );
+            if (!res.ok) {
+                logger.warn('[ScaleBun] reportBug: server rejected the report', res.status);
+                return { e: 'send' };
+            }
+            const body = await res.json().catch(() => null);
+            return body?.id ?? { e: 'send' };
+        } catch (err: any) {
+            logger.warn('[ScaleBun] reportBug failed:', err?.message);
+            return { e: 'send' };
+        }
+    }
+
+    /**
+     * The replay coordinate at submit time, or null.
+     *
+     * Deliberately returns null rather than a zeroed coordinate when replay is disabled, paused, or
+     * has not produced a frame yet — see the anchor note on reportBug.
+     */
+    /**
+     * The replay coordinate at submit time.
+     *
+     * ALWAYS null today, deliberately and visibly.
+     *
+     * The web SDK reads this from its recorder, but the RN replay subsystem exposes no sequence or
+     * segment accessor on its public API (features/replay/public/api.ts) -- there is currently no
+     * supported way to ask it where playback is. Probing for it through an `any` cast would compile,
+     * miss, and leave every report anchor-less while looking wired: the same defect as the existing
+     * reportBug(), which emits an analytics event and looks like it files a report.
+     *
+     * Returning null keeps the payload HONEST -- buildBugReportPayload omits replaySeq entirely, so
+     * the dashboard shows no anchor rather than a false one pointing at the start of the session.
+     * To finish this: expose the current seq + segment id from the replay recorder, then read them
+     * here. The payload builder and its contract tests already handle a real coordinate, including
+     * a genuine seq of 0.
+     */
+    private _replayCoord(): { seq?: number | null; segmentId?: string | null } | null {
+        return null;
+    }
+    /** Recent console breadcrumbs for quick triage. The full set already travels with the session. */
+    private _recentBreadcrumbs(): readonly unknown[] {
+        try {
+            const f = (this as any)._loggerFeature ?? (this as any)._consoleFeature;
+            return f?.getRecent?.() ?? [];
+        } catch {
+            return [];
+        }
+    }
+
+    // ─── 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();
+            // Internal-only signals ($network_request, …) fan out to engage/perf/debug below but
+            // are never uploaded as session events — their data already travels on a dedicated
+            // lane (see INTERNAL_ONLY_SIGNALS in analytics/eventLane). The uploaded copy was pure
+            // duplication: ~15% of measured mobile event volume, filtered out as noise by every
+            // dashboard reader.
+            if (!isUploadedSessionEvent(name)) {
+                // fall through to the in-process consumers
+            } else 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. Delivered to BOTH lanes:
+     *  - the Diagnose → Logs lane (tagged `source: 'sdk'`), so an explicit `log()` call shows
+     *    up where a developer looks for logs. The method name promised this, but it previously
+     *    only emitted a `$log` analytics EVENT and never reached the Logs page.
+     *  - the analytics `$log` event (unchanged), so anything already built on it keeps working.
+     * `queueLog` self-gates on `clientKey`, so the Logs-lane write is a no-op outside SaaS mode.
+     */
+    public log(level: 'debug' | 'info' | 'warn' | 'error', message: string, data?: Record<string, unknown>) {
+        try {
+            const transport = SessionManager.getExistingInstance()?.getBackendTransport();
+            transport?.queueLog({
+                level,
+                message,
+                source: 'sdk',
+                platform: 'js',
+                timestamp: new Date().toISOString(),
+                ...(data ? { metadata: data } : {}),
+            });
+        } catch { /* no-throw: a logging call must never break the host app */ }
+        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>) {
+        // D11: this used to be ONLY `track('$bug_report')` — an analytics event
+        // with zero consumers (no mapper, no handler, no BugReport row), so
+        // /diagnose/bug-reports stayed empty forever for RN apps while the web
+        // SDK used the real ingest. Route to the same endpoint the web SDK
+        // uses; the analytics event is kept as a breadcrumb, not the delivery.
+        try {
+            const transport = SessionManager.getExistingInstance()?.getBackendTransport();
+            transport?.submitBugReport({
+                message: description,
+                title:
+                    typeof metadata?.title === 'string' ? (metadata.title as string) : undefined,
+                email:
+                    typeof metadata?.email === 'string' ? (metadata.email as string) : undefined,
+            });
+        } catch {
+            /* delivery is best-effort; the track below still records intent */
+        }
+        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 };