@scalebun-release/react-native 2.5.0

package/lib/module/public/ScaleBunFacade.js

@@ -0,0 +1,2038 @@
+/**
+ * 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 { BugReportFeature } from '../features/bugreport/BugReportFeature';
+import { PersistentQueue } from '../pipeline/queue/persistentQueue';
+import { MemoryBackend, createStorageBackend } from '../storage/StorageBackend';
+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, getPerformanceFeature as _getPerformanceFeature, requestExport as _requestExport, buildDebugConfigFromInitConfig, applyFeatureGatesToDebugConfig, sendDebugMetric } from '../debug';
+import { ReplaySdk } from '../features/replay/public/api';
+import { SDKBootstrapper } from '../bootstrap/SDKBootstrapper';
+import { EventTracker } from '../analytics/EventTracker';
+import { bridgeAdapter } from '../features/replay/bridge/adapters/bridgeAdapter';
+import { emitAutomaticEvent } 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 } from '../features/engage/EngageTransport';
+import { getNativePushToken, subscribeNativePushTokenRefresh } from '../features/engage/engagePushTokenBridge';
+import { requestNativeStoreReview } from '../features/engage/engageStoreReviewBridge';
+import { PushManager } from '../push/PushManager';
+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 { PerformanceFeature } from '../features/performance/PerformanceFeature';
+import { SessionManager } from '../features/session/SessionManager';
+import { getCrashReporter } from '../features/crash/CrashReporter';
+import { triggerNativeCrash } from '../features/crash/nativeCrashBridge';
+import { updateSkanConversionValue, isSkanAvailable } from '../features/skan/skanBridge';
+import { SkanConversionManager } from '../features/skan/skanConversionManager';
+import { isInstallReferrerAvailable, getInstallReferrer, captureInstallReferrerOnce } from '../features/install-referrer/installReferrer';
+class ScaleBunFacade {
+  initialized = false;
+  /** In-flight init promise — guards against a second init() racing before the first resolves. */
+  _initInFlight = null;
+  bootstrapper = new SDKBootstrapper();
+  _features = {};
+  _performanceFeature = null;
+  _privacyConfig = {};
+  _brandingConfig = {};
+  _clientKey = undefined;
+  _apiBaseUrl = undefined;
+  _engageTransport = null;
+  _engageTokenUnsubscribe = null;
+  _pushManager = null;
+  /** Phase 1 envelope event-tracking lane (POST /v1/batch). Null until init with appId. */
+  _eventTracker = null;
+  /** External identity last supplied through identify(); used by config targeting. */
+  _identifiedUserId = null;
+  /** Identity supplied while async initialization is still in flight. */
+  _pendingIdentity = null;
+  _configManager = 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.
+   */
+  _configRefresher = null;
+  _configForegroundListener = 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. */
+  _devCaptureMode = 'interactions';
+  /** True while an admin frequency override from /config is applied, so we know to revert. */
+  _replayOverrideActive = false;
+  /** Signature of the last identity POSTed to the ingestion identify endpoint, to skip redundant re-sends. */
+  _lastIngestionIdentityKey = null;
+  /** Phase 3: auto-applies SKAN conversion values from the server schema (iOS only). */
+  _skanManager = null;
+
+  /**
+   * Pre-init memory buffer.
+   * Events tracked before init() completes are buffered here,
+   * then drained into the real persistent queue post-init.
+   */
+  _preInitBuffer = 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) */
+  _getQueue() {
+    if (this.initialized) {
+      try {
+        return coreContainer.get('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.
+   */
+  async init(rawConfig) {
+    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 = {
+        ...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(), 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');
+          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) {
+        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;
+      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.
+   */
+  _maybeStartOta(rawConfig) {
+    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 = 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) {
+      logger.warn(`[ScaleBun] OTA init failed: ${err?.message ?? err}`);
+    }
+  }
+
+  /** Guards against overlapping config-driven OTA checks. */
+  _otaCheckInFlight = false;
+  /** Wall clock of the last config-driven check, for the foreground floor. */
+  _otaLastCheckAt = 0;
+  _otaForegroundListener = 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.
+   */
+  static 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.
+   */
+  _startOtaChecks(ota) {
+    // 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 => {
+      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?.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) {
+        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 => {
+        if (state === 'active') void runCheck('foreground');
+      };
+      appLifecycle.addListener(this._otaForegroundListener);
+    } catch {
+      // Lifecycle unavailable (tests, exotic hosts) — the startup check stands.
+      this._otaForegroundListener = null;
+    }
+  }
+  _autoEnableDebug(debugConfig) {
+    try {
+      const dbgConfig = buildDebugConfigFromInitConfig(debugConfig);
+      if (!dbgConfig) return;
+      dbgConfig.__skipDeprecationWarning = true;
+      this.enableDebug(dbgConfig);
+      logger.info('[ScaleBun] Debug auto-connected via init({ debug }).');
+    } catch (err) {
+      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).
+   */
+  _startConfigLifecycle() {
+    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 => {
+        if (state === 'active') this._configRefresher?.maybeRefresh();
+      };
+      appLifecycle.addListener(this._configForegroundListener);
+    } catch (err) {
+      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.
+   */
+  _stopConfigLifecycle() {
+    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. */
+  _maybeStartEventTracker(rawConfig) {
+    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) {
+      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.
+   */
+  _applyNativeDeviceContext(tracker) {
+    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.
+   */
+  _applyReplayCaptureOverride(override) {
+    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.
+   */
+  _captureInstallReferrer(tracker) {
+    try {
+      if (!isInstallReferrerAvailable()) return;
+      const storage = createStorageBackend();
+      const KEY = 'scalebun_install_referrer_done';
+      const sink = {
+        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),
+        fetch: () => getInstallReferrer()
+      };
+      void captureInstallReferrerOnce(sink);
+    } catch (err) {
+      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`.
+   */
+  get events() {
+    const tracker = this._eventTracker;
+    return {
+      track: (eventName, properties) => tracker?.track(eventName, properties),
+      identify: (userId, traits) => tracker?.identify(userId, traits),
+      trackPurchase: input => tracker?.trackPurchase(input),
+      trackSubscription: input => tracker?.trackSubscription(input),
+      setIdentifiers: ids => tracker?.setIdentifiers(ids),
+      // Phase 2: record a deferred deep-link click token for deterministic install attribution.
+      setAttributionClickId: clickId => 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, coarseValue, lockWindow) => 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
+   */
+  get config() {
+    const cm = this._configManager;
+    return {
+      get: (key, fallback) => cm ? cm.get(key, fallback) : fallback,
+      refresh: () => cm?.refresh() ?? Promise.resolve()
+    };
+  }
+  get flags() {
+    const cm = this._configManager;
+    return {
+      isEnabled: key => cm?.isEnabled(key) ?? false
+    };
+  }
+  get rollouts() {
+    const cm = this._configManager;
+    return {
+      isOn: key => cm?.rolloutIsOn(key) ?? false
+    };
+  }
+  get experiments() {
+    const cm = this._configManager;
+    return {
+      variant: key => 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.
+   */
+  setUiState(name, value) {
+    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.
+   */
+  clearUiState(name) {
+    try {
+      const {
+        clearUiState
+      } = require('../features/journey/uiState');
+      clearUiState(name);
+    } catch {/* no-throw */}
+  }
+  trackPurchase(input) {
+    noThrow(() => this._eventTracker?.trackPurchase(input));
+  }
+
+  /** Record a trial, renewal, plan change or cancellation in the subscription ledger. */
+  trackSubscription(input) {
+    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.
+   */
+  updateSkanConversionValue(value, coarseValue, lockWindow) {
+    noThrow(() => {
+      void updateSkanConversionValue(value, coarseValue, lockWindow);
+    });
+  }
+
+  // ─── Feature Flags ──────────────────────────────────────────────────
+
+  /** Get the current feature flags (consumed by enableDebug) */
+  getFeatureFlags() {
+    return this._features;
+  }
+
+  // ─── Identity ───────────────────────────────────────────────────────
+
+  /** Identify a user by ID and optional traits */
+  identify(userId, traits) {
+    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 = {
+            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.
+   */
+  identifyUser(userId, traits) {
+    return this.identify(userId, traits);
+  }
+
+  /** POST user identity to the SaaS ingestion identify endpoint */
+  async _callIngestionIdentify(sessionId, user) {
+    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) {
+      logger.warn('[ScaleBun] ingestion identify failed:', err?.message);
+    }
+  }
+
+  /** Set user identity (for session context) */
+  setUser(user) {
+    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).
+   */
+  clearUser(options) {
+    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.
+   */
+  async eraseLocalData() {
+    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.
+   */
+  setConsent(enabled, options) {
+    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.
+   */
+  getEffectivePrivacyPolicy() {
+    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.
+   */
+  submitRating(input) {
+    return safeAsync(async () => {
+      if (!this._clientKey || !this._apiBaseUrl) return {
+        ok: false,
+        reason: 'sdk_not_configured'
+      };
+      const rating = Math.round(Number(input?.rating));
+      if (!Number.isFinite(rating) || rating < 1 || rating > 5) {
+        return {
+          ok: false,
+          reason: 'invalid_rating'
+        };
+      }
+      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',
+            status: res.status
+          };
+        }
+        return {
+          ok: true
+        };
+      } catch (err) {
+        logger.warn('[ScaleBun] submitRating failed:', err?.message);
+        return {
+          ok: false,
+          reason: 'network_error'
+        };
+      }
+    });
+  }
+  getActiveSessionId() {
+    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.
+   */
+  _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.
+   */
+  async reportBugDetailed(input) {
+    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) {
+      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.
+   */
+  _replayCoord() {
+    return null;
+  }
+  /** Recent console breadcrumbs for quick triage. The full set already travels with the session. */
+  _recentBreadcrumbs() {
+    try {
+      const f = this._loggerFeature ?? this._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.
+   */
+  _getEngageTransport() {
+    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.
+   */
+  engage = {
+    /** Current external identity, forwarded by the provider for segment targeting. */
+    getIdentifiedUserId: () => 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 => {
+      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',
+        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, properties) => {
+      this.track(name, properties);
+    },
+    /**
+     * 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: () => {
+      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: () => {
+      // 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: () => {
+      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 => {
+      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 => {
+      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, attachments) => {
+      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, attachments, opts) => {
+      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 => {
+      noThrow(() => {
+        const automaticName = {
+          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 => {
+      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 => {
+      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 () => {
+      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 => {
+      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 () => {
+      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'
+          });
+        });
+      });
+    }
+  };
+
+  // ─── 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).
+   */
+  _getPushManager() {
+    if (!this._pushManager) {
+      this._pushManager = new PushManager({
+        registerToken: async input => {
+          const transport = this._getEngageTransport();
+          if (!transport) return {
+            ok: false,
+            reason: 'sdk_not_configured'
+          };
+          transport.registerDeviceToken({
+            pushToken: input.pushToken,
+            platform: input.platform,
+            pushProvider: input.pushProvider,
+            sdkVersion: SDK_VERSION,
+            ...(this._eventTracker ? {
+              installationId: this._eventTracker.getInstallationId()
+            } : {})
+          });
+          return {
+            ok: true
+          };
+        }
+      });
+    }
+    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) => {},
+   * });
+   * ```
+   */
+  enablePush(options) {
+    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.)
+   */
+  onForegroundNotification(cb) {
+    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.
+   */
+  onNotificationOpened(cb) {
+    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.
+   */
+  push = {
+    /** Inject/rotate a token (manual provider) — syncs to the backend. */
+    setToken: token => {
+      noThrow(() => this._getPushManager().setToken(token));
+    },
+    /** Current push token, if acquired. */
+    getToken: () => {
+      return noThrow(() => this._getPushManager().getToken()) ?? null;
+    },
+    /** Deliver a foreground notification to registered callbacks (manual provider). */
+    emitForeground: message => {
+      noThrow(() => this._getPushManager().emitForeground(message));
+    },
+    /** Deliver a notification-open event to registered callbacks (manual provider). */
+    emitNotificationOpened: message => {
+      noThrow(() => this._getPushManager().emitNotificationOpened(message));
+    },
+    /** Current push status: selected adapter, usability, reason, token. */
+    status: () => this._getPushManager().status(),
+    /** Tear down all push listeners. */
+    teardown: () => {
+      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.
+   */
+  trackPermission(permission, status, details) {
+    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 */
+  track(name, payload) {
+    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.
+   */
+  log(level, message, data) {
+    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).
+   */
+  captureError(error, context) {
+    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.
+   */
+  nativeCrash() {
+    return noThrow(() => triggerNativeCrash());
+  }
+
+  /** Report a bug (convenience wrapper over track) */
+  reportBug(description, metadata) {
+    // 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 : undefined,
+        email: typeof metadata?.email === 'string' ? metadata.email : 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 */
+  setAttribute(key, value) {
+    return this.track('$set_attribute', {
+      key,
+      value
+    });
+  }
+
+  // ─── Flush ──────────────────────────────────────────────────────────
+
+  /** Force-flush all pending events */
+  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');
+      await flushQueue(this._getQueue(), httpClient, getDeviceId());
+    });
+  }
+
+  /**
+   * Enable the debug subsystem.
+   *
+   * @deprecated Use `ScaleBun.init({ debug: true })` instead.
+   * This method still works for backward compatibility.
+   */
+  enableDebug(config) {
+    return noThrow(() => {
+      if (!config.__skipDeprecationWarning) {
+        logger.warn('[ScaleBun] enableDebug() is deprecated. ' + 'Use ScaleBun.init({ ..., debug: true }) instead.');
+      }
+      const gatedConfig = applyFeatureGatesToDebugConfig(config, this._features);
+      _enableDebug(gatedConfig);
+      _setFlushFn(() => this.flush());
+      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 */
+  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.
+   */
+  setCalibrationTarget(target) {
+    noThrow(() => {
+      const mod = require('../features/journey/calibrationContext');
+      mod.setCalibrationTarget(target);
+    });
+  }
+
+  /**
+   * Debug utilities namespace.
+   * All methods are no-op if debug is not enabled.
+   */
+  debug = {
+    addBreadcrumb: (message, data) => {
+      noThrow(() => _addBreadcrumb(message, data));
+    },
+    ping: () => {
+      noThrow(() => _ping());
+    },
+    isEnabled: () => isDebugEnabled(),
+    sendMetric: (name, value, unit, tags) => {
+      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.
+   */
+  replay = {
+    start: () => ReplaySdk.start(),
+    stop: () => ReplaySdk.stop(),
+    pause: () => ReplaySdk.pause(),
+    resume: () => ReplaySdk.resume(),
+    captureFrame: () => ReplaySdk.captureManualFrame(),
+    setUser: user => ReplaySdk.setUser(user),
+    clearUser: () => ReplaySdk.clearUser(),
+    addBreadcrumb: breadcrumb => ReplaySdk.addBreadcrumb(breadcrumb),
+    setPrivacy: opts => ReplaySdk.setPrivacyOptions(opts),
+    setEnabled: enabled => ReplaySdk.setEnabled(enabled),
+    setQuality: quality => ReplaySdk.setScreenshotQuality(quality),
+    setCaptureMode: mode => ReplaySdk.setCapturingMode(mode),
+    setScreen: name => ReplaySdk.setCurrentScreen(name),
+    flush: () => ReplaySdk.flush(),
+    get isRecording() {
+      return ReplaySdk.isRecording;
+    },
+    get sessionId() {
+      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.
+   */
+  performance = {
+    /** Start a custom trace. Returns traceId or null. */
+    startTrace: name => {
+      return this._performanceFeature?.startTrace(name) ?? null;
+    },
+    /** Stop a custom trace by ID. */
+    stopTrace: traceId => {
+      this._performanceFeature?.stopTrace(traceId);
+    },
+    /** Add a span to an active custom trace. */
+    addTraceSpan: (traceId, name, durationMs, data) => {
+      this._performanceFeature?.addTraceSpan(traceId, name, durationMs, data);
+    },
+    /** Attach a measurement to an active custom trace. */
+    addTraceMeasurement: (traceId, name, value, unit) => {
+      this._performanceFeature?.addTraceMeasurement(traceId, name, value, unit);
+    },
+    /** Mark the start of a screen load. */
+    markScreenLoadStart: screenName => {
+      this._performanceFeature?.markScreenLoadStart(screenName);
+    },
+    /** Mark the end of a screen load. */
+    markScreenLoadEnd: screenName => {
+      this._performanceFeature?.markScreenLoadEnd(screenName);
+    },
+    /** Set the current screen for context correlation. */
+    setCurrentScreen: screenName => {
+      this._performanceFeature?.setCurrentScreen(screenName);
+    },
+    /** Forward navigation state changes for auto screen load detection. */
+    onNavigationStateChange: state => {
+      this._performanceFeature?.onNavigationStateChange(state);
+    },
+    /** Check if performance monitoring is active */
+    isActive: () => {
+      return this._performanceFeature?.isActive ?? false;
+    },
+    /**
+     * Send a raw performance metric through the transport.
+     * Used for manual/simulated performance metrics.
+     */
+    sendMetric: (name, value, unit, tags) => {
+      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.
+   */
+  session = {
+    get isActive() {
+      return SessionManager.getExistingInstance()?.isActive ?? false;
+    },
+    get currentSessionId() {
+      return SessionManager.getExistingInstance()?.currentSessionId ?? null;
+    },
+    start: metadata => {
+      const sm = SessionManager.getExistingInstance();
+      if (!sm) {
+        logger.warn('session.start() — SessionManager not available.');
+        return false;
+      }
+      sm.startSession(metadata);
+      logger.info('session.start() ✅ sessionId:', sm.currentSessionId);
+      return true;
+    },
+    end: reason => {
+      const sm = SessionManager.getExistingInstance();
+      if (!sm || !sm.isActive) return false;
+      sm.endSession(reason);
+      logger.info('session.end() ✅');
+      return true;
+    },
+    emitEvent: (type, data) => {
+      const sm = SessionManager.getExistingInstance();
+      if (!sm || !sm.isActive) return;
+      sm.emitEvent(type, data);
+    }
+  };
+
+  // ─── Session Convenience Methods ────────────────────────────────────
+
+  /** Start a session (delegates to session namespace) */
+  startSession(metadata) {
+    return this.session.start(metadata);
+  }
+
+  /** Stop the current session (delegates to session namespace) */
+  stopSession(reason) {
+    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).
+   */
+  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 => {
+      return _requestExport(presetOrOptions);
+    },
+    /** Set SDK-wide privacy settings for report generation. */
+    setPrivacy: config => {
+      this._privacyConfig = {
+        ...this._privacyConfig,
+        ...config
+      };
+      logger.debug('[report] Privacy config updated');
+    },
+    /** Set branding for exported reports. */
+    setBranding: config => {
+      this._brandingConfig = {
+        ...this._brandingConfig,
+        ...config
+      };
+      logger.debug('[report] Branding config updated');
+    },
+    /** Get current privacy config. */
+    getPrivacy: () => ({
+      ...this._privacyConfig
+    }),
+    /** Get current branding config. */
+    getBranding: () => ({
+      ...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>
+   *   );
+   * }
+   * ```
+   */
+  setNavigationRef(ref) {
+    noThrow(() => {
+      // Always stash on the global so heuristic polling / late consumers resolve it.
+      globalThis.__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) {
+        logger.debug('[ScaleBun] Navigation ref stashed (detector not ready):', err?.message);
+      }
+    });
+  }
+}
+
+/** Singleton Facade instance */
+const instance = new ScaleBunFacade();
+export default instance;
+export { ScaleBunFacade };
+//# sourceMappingURL=ScaleBunFacade.js.map