@scalebun/react-native 1.0.1 → 1.0.2

package/lib/module/public/ScaleBunFacade.js

@@ -1,12 +1,12 @@
-/**
- * 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';
@@ -67,10 +67,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 +94,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;
@@ -281,12 +281,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 +316,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 +337,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 +377,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 +436,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 +490,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 () => {
@@ -561,11 +561,11 @@ class ScaleBunFacade {
 
   // ─── 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 +578,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 +629,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 +652,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 +678,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 +732,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 +749,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 +803,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 +836,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 +916,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 +1019,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 +1045,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());
@@ -1093,11 +1093,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 +1123,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 +1137,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 +1156,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 +1187,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 +1230,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 +1245,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 +1295,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 +1351,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(() => {