@scalebun/react-native 1.0.2 → 1.0.4

package/lib/module/public/ScaleBunFacade.js

@@ -1,21 +1,24 @@
-/**
- * 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 }`.
+/**
+ * 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 } 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';
@@ -67,10 +70,10 @@ class ScaleBunFacade {
   /** 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.
+  /**
+   * 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,
@@ -94,21 +97,21 @@ class ScaleBunFacade {
 
   // ─── 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.
+  /**
+   * 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;
@@ -212,7 +215,9 @@ class ScaleBunFacade {
       const appId = rawConfig?.appId;
       const enabled = rawConfig?.eventTracking !== false;
       const clientKey = this._clientKey ?? rawConfig?.clientKey;
-      const apiBaseUrl = this._apiBaseUrl ?? rawConfig?.apiBaseUrl;
+      // 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.');
@@ -243,7 +248,16 @@ class ScaleBunFacade {
         // to true unless the integrator explicitly disables it.
         automaticEventTracking: rawConfig?.automaticEventTracking === true,
         flushIntervalMs: rawConfig?.flushIntervalMs,
-        context: rawConfig?.context,
+        /**
+         * 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.
+         */
+        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.
@@ -281,12 +295,12 @@ class ScaleBunFacade {
     }
   }
 
-  /**
-   * 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.
+  /**
+   * 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 {
@@ -316,9 +330,9 @@ class ScaleBunFacade {
     }
   }
 
-  /**
-   * Phase 1 envelope event tracking API (POST /v1/batch).
-   * Methods are no-ops (never throw) until init() is called with an `appId`.
+  /**
+   * 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;
@@ -337,14 +351,14 @@ class ScaleBunFacade {
     };
   }
 
-  /**
-   * 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
+  /**
+   * 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;
@@ -377,9 +391,9 @@ class ScaleBunFacade {
     noThrow(() => this._eventTracker?.trackPurchase(input));
   }
 
-  /**
-   * Phase 3: set the SKAdNetwork fine conversion value (0–63), optionally with a
-   * SKAN 4.0 coarse value and window-lock. iOS only — a no-op on Android / Expo Go.
+  /**
+   * 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(() => {
@@ -436,10 +450,10 @@ class ScaleBunFacade {
     });
   }
 
-  /**
-   * 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.
+  /**
+   * 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);
@@ -490,10 +504,10 @@ class ScaleBunFacade {
     });
   }
 
-  /**
-   * Submit in-app rating (1-5 stars).
-   * Attaches to current session when available; otherwise sends standalone.
-   * Never throws.
+  /**
+   * Submit in-app rating (1-5 stars).
+   * Attaches to current session when available; otherwise sends standalone.
+   * Never throws.
    */
   submitRating(input) {
     return safeAsync(async () => {
@@ -559,13 +573,132 @@ class ScaleBunFacade {
     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.
+  /**
+   * 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;
@@ -578,22 +711,22 @@ class ScaleBunFacade {
     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 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.
+    /**
+     * 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();
@@ -629,21 +762,21 @@ class ScaleBunFacade {
     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).
+    /**
+     * 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.
+    /**
+     * 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
@@ -652,20 +785,20 @@ class ScaleBunFacade {
       // (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.
+    /**
+     * 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.
+    /**
+     * 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));
@@ -678,23 +811,23 @@ class ScaleBunFacade {
     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.
+    /**
+     * [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.
+    /**
+     * [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();
@@ -732,11 +865,11 @@ class ScaleBunFacade {
     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.
+    /**
+     * 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(() => {
@@ -749,31 +882,31 @@ class ScaleBunFacade {
         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.
+    /**
+     * 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.
+    /**
+     * 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.
+    /**
+     * 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 () => {
@@ -803,11 +936,11 @@ class ScaleBunFacade {
 
   // ─── 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).
+  /**
+   * 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) {
@@ -836,58 +969,58 @@ class ScaleBunFacade {
     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) => {},
-   * });
-   * ```
+  /**
+   * 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.)
+  /**
+   * 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.
+  /**
+   * 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 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. */
@@ -916,24 +1049,24 @@ class ScaleBunFacade {
 
   // ─── 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.
+  /**
+   * 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(() => {
@@ -1019,12 +1152,12 @@ class ScaleBunFacade {
     });
   }
 
-  /**
-   * 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).
+  /**
+   * 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(() => {
@@ -1045,10 +1178,10 @@ class ScaleBunFacade {
     });
   }
 
-  /**
-   * 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.
+  /**
+   * 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());
@@ -1056,6 +1189,21 @@ class ScaleBunFacade {
 
   /** 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
@@ -1093,11 +1241,11 @@ class ScaleBunFacade {
     });
   }
 
-  /**
-   * Enable the debug subsystem.
-   *
-   * @deprecated Use `ScaleBun.init({ debug: true })` instead.
-   * This method still works for backward compatibility.
+  /**
+   * Enable the debug subsystem.
+   *
+   * @deprecated Use `ScaleBun.init({ debug: true })` instead.
+   * This method still works for backward compatibility.
    */
   enableDebug(config) {
     return noThrow(() => {
@@ -1123,12 +1271,12 @@ class ScaleBunFacade {
     });
   }
 
-  /**
-   * 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.
+  /**
+   * 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(() => {
@@ -1137,9 +1285,9 @@ class ScaleBunFacade {
     });
   }
 
-  /**
-   * Debug utilities namespace.
-   * All methods are no-op if debug is not enabled.
+  /**
+   * Debug utilities namespace.
+   * All methods are no-op if debug is not enabled.
    */
   debug = {
     addBreadcrumb: (message, data) => {
@@ -1156,11 +1304,11 @@ class ScaleBunFacade {
 
   // ─── 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.
+  /**
+   * 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(),
@@ -1187,11 +1335,11 @@ class ScaleBunFacade {
 
   // ─── 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 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. */
@@ -1230,9 +1378,9 @@ class ScaleBunFacade {
     isActive: () => {
       return this._performanceFeature?.isActive ?? false;
     },
-    /**
-     * Send a raw performance metric through the transport.
-     * Used for manual/simulated performance metrics.
+    /**
+     * Send a raw performance metric through the transport.
+     * Used for manual/simulated performance metrics.
      */
     sendMetric: (name, value, unit, tags) => {
       if (!this._performanceFeature) {
@@ -1245,10 +1393,10 @@ class ScaleBunFacade {
 
   // ─── Unified Session ────────────────────────────────────────────────
 
-  /**
-   * Unified Session namespace.
-   * Provides access to the unified SessionManager.
-   * Sessions auto-start on desktop connect.
+  /**
+   * Unified Session namespace.
+   * Provides access to the unified SessionManager.
+   * Sessions auto-start on desktop connect.
    */
   session = {
     get isActive() {
@@ -1295,30 +1443,30 @@ class ScaleBunFacade {
 
   // ─── 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 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.
+    /**
+     * 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);
@@ -1351,32 +1499,32 @@ class ScaleBunFacade {
 
   // ─── 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>
-   *   );
-   * }
-   * ```
+  /**
+   * 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(() => {