@scalebun/react-native 1.1.0 → 1.2.1

package/src/features/engage/engagePushTokenBridge.ts

@@ -44,14 +44,14 @@ export async function getNativePushToken(): Promise<NativePushToken | null> {
     try {
         const mod = getEngageModule();
         if (!mod?.getPushToken) {
-            logger.debug('[Engage] ScaleBunEngage native module unavailable — skipping push token');
+            __DEV__ && logger.debug('[Engage] ScaleBunEngage native module unavailable — skipping push token');
             return null;
         }
         const result = await mod.getPushToken();
         if (!result?.token || !result?.platform) return null;
         return result;
     } catch (err: any) {
-        logger.debug(`[Engage] getPushToken failed (fail-soft): ${err?.message}`);
+        __DEV__ && logger.debug(`[Engage] getPushToken failed (fail-soft): ${err?.message}`);
         return null;
     }
 }
@@ -66,7 +66,7 @@ export function subscribeNativePushTokenRefresh(
     try {
         const nativeModule = NativeModules?.ScaleBunEngage;
         if (!nativeModule) {
-            logger.debug('[Engage] ScaleBunEngage native module unavailable — no token-refresh listener');
+            __DEV__ && logger.debug('[Engage] ScaleBunEngage native module unavailable — no token-refresh listener');
             return () => {};
         }
         const emitter = new NativeEventEmitter(nativeModule);
@@ -78,7 +78,7 @@ export function subscribeNativePushTokenRefresh(
         );
         return () => subscription.remove();
     } catch (err: any) {
-        logger.debug(`[Engage] token-refresh subscription failed (fail-soft): ${err?.message}`);
+        __DEV__ && logger.debug(`[Engage] token-refresh subscription failed (fail-soft): ${err?.message}`);
         return () => {};
     }
 }

package/src/features/engage/engageShakeBridge.ts

@@ -39,7 +39,7 @@ export function installEngageShakeBridge(): () => void {
     try {
         const mod = getModule();
         if (!mod?.startShakeDetection) {
-            logger.debug('[Engage] ScaleBunEngage shake detection unavailable — skipping');
+            __DEV__ && logger.debug('[Engage] ScaleBunEngage shake detection unavailable — skipping');
             return () => {};
         }
 
@@ -61,7 +61,7 @@ export function installEngageShakeBridge(): () => void {
             } catch { /* no-throw */ }
         };
     } catch (err: any) {
-        logger.debug(`[Engage] shake bridge install failed (fail-soft): ${err?.message}`);
+        __DEV__ && logger.debug(`[Engage] shake bridge install failed (fail-soft): ${err?.message}`);
         return () => {};
     }
 }

package/src/features/engage/engageSignals.ts

@@ -31,7 +31,7 @@ class EngageSignalBus {
             try {
                 l(signal);
             } catch (err) {
-                logger.debug('[Engage] signal listener threw:', (err as Error)?.message);
+                __DEV__ && logger.debug('[Engage] signal listener threw:', (err as Error)?.message);
             }
         }
     }

package/src/features/engage/engageStoreReviewBridge.ts

@@ -36,13 +36,13 @@ export async function requestNativeStoreReview(): Promise<boolean> {
     try {
         const mod = getEngageModule();
         if (!mod?.requestReview) {
-            logger.debug('[Engage] ScaleBunEngage native module unavailable — skipping store review');
+            __DEV__ && logger.debug('[Engage] ScaleBunEngage native module unavailable — skipping store review');
             return false;
         }
         const ran = await mod.requestReview();
         return ran === true;
     } catch (err: any) {
-        logger.debug(`[Engage] requestReview failed (fail-soft): ${err?.message}`);
+        __DEV__ && logger.debug(`[Engage] requestReview failed (fail-soft): ${err?.message}`);
         return false;
     }
 }

package/src/features/engage/engageTestSeenStore.ts

@@ -61,7 +61,7 @@ export class EngageTestSeenStore {
     markSeen(testRunId: string): void {
         if (!testRunId) return;
         this.backend.set(this.keyFor(testRunId), String(Date.now()));
-        logger.debug(`[Engage] test ${testRunId} marked displayed (persisted)`);
+        __DEV__ && logger.debug(`[Engage] test ${testRunId} marked displayed (persisted)`);
     }
 
     /**

package/src/features/engage/engageThrottle.ts

@@ -85,7 +85,7 @@ export class EngageThrottleStore {
                 };
             }
         } catch (err) {
-            logger.debug('[Engage] throttle state read failed:', (err as Error)?.message);
+            __DEV__ && logger.debug('[Engage] throttle state read failed:', (err as Error)?.message);
         }
         return { impressions: 0, lastShownAt: 0, completed: false };
     }
@@ -95,7 +95,7 @@ export class EngageThrottleStore {
         try {
             this.backend.delete(this.keyFor(campaignId));
         } catch (err) {
-            logger.debug('[Engage] throttle clearOne failed:', (err as Error)?.message);
+            __DEV__ && logger.debug('[Engage] throttle clearOne failed:', (err as Error)?.message);
         }
     }
 
@@ -115,7 +115,7 @@ export class EngageThrottleStore {
                 }
             }
         } catch (err) {
-            logger.debug('[Engage] throttle clearAll failed:', (err as Error)?.message);
+            __DEV__ && logger.debug('[Engage] throttle clearAll failed:', (err as Error)?.message);
         }
         return n;
     }
@@ -124,7 +124,7 @@ export class EngageThrottleStore {
         try {
             this.backend.set(this.keyFor(campaignId), JSON.stringify(state));
         } catch (err) {
-            logger.debug('[Engage] throttle state write failed:', (err as Error)?.message);
+            __DEV__ && logger.debug('[Engage] throttle state write failed:', (err as Error)?.message);
         }
     }
 

package/src/features/engage/engageTriggerEngine.ts

@@ -112,18 +112,18 @@ export function installEngageTriggerEngine(deps: EngageTriggerEngineDeps): () =>
             // Found live: a cold start with the screen off burned both a survey
             // and an in-app message before the phone was ever unlocked.
             if (appLifecycle.getCurrentState() !== 'active') {
-                logger.debug(
+                __DEV__ && logger.debug(
                     `[Engage] trigger suppressed (app ${appLifecycle.getCurrentState()}): ${options.trigger ?? 'manual'}`,
                 );
                 return;
             }
-            logger.debug(
+            __DEV__ && logger.debug(
                 `[Engage] trigger fire: ${options.trigger ?? 'manual'}` +
                     (options.screen ? ` screen=${options.screen}` : ''),
             );
             deps.fire(options);
         } catch (err) {
-            logger.debug('[Engage] trigger fire failed:', (err as Error)?.message);
+            __DEV__ && logger.debug('[Engage] trigger fire failed:', (err as Error)?.message);
         }
     };
 
@@ -297,7 +297,7 @@ export function installEngageTriggerEngine(deps: EngageTriggerEngineDeps): () =>
                 .filter((s): s is number => typeof s === 'number');
             if (targets.includes(next)) fire({ trigger: 'n_sessions' });
         } catch (err) {
-            logger.debug('[Engage] n_sessions check failed:', (err as Error)?.message);
+            __DEV__ && logger.debug('[Engage] n_sessions check failed:', (err as Error)?.message);
         }
     })();
 

package/src/features/engage/engageWindowInsets.ts

@@ -64,7 +64,7 @@ export async function readNativeWindowInsets(
         return normalizeWindowInsets(await module.getWindowInsets());
     } catch (error: unknown) {
         const reason = error instanceof Error ? error.message : String(error);
-        logger.debug(`[Engage] getWindowInsets failed (fail-soft): ${reason}`);
+        __DEV__ && logger.debug(`[Engage] getWindowInsets failed (fail-soft): ${reason}`);
         return null;
     }
 }

package/src/features/install-referrer/installReferrer.ts

@@ -40,7 +40,7 @@ export async function getInstallReferrer(): Promise<string | null> {
         const raw = await mod.getInstallReferrer();
         return typeof raw === 'string' ? raw : null;
     } catch (err) {
-        logger.debug(`[InstallReferrer] fetch failed: ${(err as Error)?.message}`);
+        __DEV__ && logger.debug(`[InstallReferrer] fetch failed: ${(err as Error)?.message}`);
         return null;
     }
 }
@@ -102,11 +102,11 @@ export async function captureInstallReferrerOnce(sink: InstallReferrerSink): Pro
         if (!parsed) return;
         if (parsed.clickId) sink.setClickId(parsed.clickId);
         sink.emit('install_referrer', { referrer: parsed.raw, ...parsed.params });
-        logger.debug(
+        __DEV__ && logger.debug(
             `[InstallReferrer] captured (clickId=${parsed.clickId ?? '-'}, ` +
                 `${Object.keys(parsed.params).length} params)`,
         );
     } catch (err) {
-        logger.debug(`[InstallReferrer] capture failed: ${(err as Error)?.message}`);
+        __DEV__ && logger.debug(`[InstallReferrer] capture failed: ${(err as Error)?.message}`);
     }
 }

package/src/features/journey/calibrationContext.ts

@@ -42,12 +42,3 @@ export function consumeCalibrationTarget(): CalibrationTarget | null {
     pending = null;
     return out;
 }
-
-export function peekCalibrationTarget(): CalibrationTarget | null {
-    if (!pending) return null;
-    if (Date.now() - pending.setAt > TTL_MS) {
-        pending = null;
-        return null;
-    }
-    return pending;
-}

package/src/features/journey/journeyManager.ts

@@ -21,7 +21,9 @@ import { GestureDetector } from './gestureDetector';
 import { NavDetector } from './navDetector';
 import { ScreenshotHelper } from './screenshotHelper';
 import { findTarget } from './targetRegistry';
-import { PROTOCOL_VERSION } from '../../debug/protocol';
+// The SDK-owned constant, not the debug/protocol shim — the shim re-exports from the vendored
+// schema module, which would pull every desktop wire-message schema into production bundles.
+import { PROTOCOL_VERSION } from '../../core/constants/protocol';
 
 // ─── Journey Event Names ────────────────────────────────────────────────────
 

package/src/features/navigation/AutoScreenDetector.ts

@@ -142,7 +142,7 @@ export class AutoScreenDetector {
             if (!ref) return;
             this._navigationRef = ref;
             this._wireNavigationListener();
-            logger.debug('[AutoScreenDetector] Navigation ref set');
+            __DEV__ && logger.debug('[AutoScreenDetector] Navigation ref set');
         } catch (err: any) {
             logger.warn('[AutoScreenDetector] setNavigationRef failed:', err?.message);
         }
@@ -310,7 +310,7 @@ export class AutoScreenDetector {
         this._started = true;
         this._autoHookReactNavigation();
         this._startHeuristicPolling();
-        logger.debug('[AutoScreenDetector] Started');
+        __DEV__ && logger.debug('[AutoScreenDetector] Started');
     }
 
     /**
@@ -432,7 +432,7 @@ export class AutoScreenDetector {
                     'ScaleBun.setNavigationRef(ref) to restore screen names.',
                 );
             } else {
-                logger.debug(`[AutoScreenDetector] React Navigation auto-hook installed (${installed}/3 entry points)`);
+                __DEV__ && logger.debug(`[AutoScreenDetector] React Navigation auto-hook installed (${installed}/3 entry points)`);
             }
         } catch { /* @react-navigation/native not installed — heuristic remains fallback */ }
     }
@@ -464,7 +464,7 @@ export class AutoScreenDetector {
         this._navListenerWired = false;
         this._started = false;
         this._lastEmittedScreen = null;
-        logger.debug('[AutoScreenDetector] Stopped');
+        __DEV__ && logger.debug('[AutoScreenDetector] Stopped');
     }
 
     /** Teardown completely (reset singleton) */

package/src/features/ota/OtaOrchestrator.ts

@@ -162,12 +162,12 @@ async function deliverOtaEvents(params: {
       },
     );
     if (!res.ok) throw new Error(`HTTP ${res.status}`);
-    logger.debug(`[OTA] Delivered ${items.length} telemetry event(s)`);
+    __DEV__ && logger.debug(`[OTA] Delivered ${items.length} telemetry event(s)`);
   } catch (err: any) {
     // Failed delivery must not fail the update — but the events must not be
     // lost either: requeue so the next sync retries them.
     for (const e of events) otaEventEmitter.emit(e);
-    logger.debug(`[OTA] Telemetry delivery failed (will retry next sync): ${err?.message}`);
+    __DEV__ && logger.debug(`[OTA] Telemetry delivery failed (will retry next sync): ${err?.message}`);
   }
 }
 
@@ -269,7 +269,7 @@ export class OtaOrchestrator {
         // We cannot see which form the host used — the identity check after
         // restart is what proves it — but naming the right fix up front turns
         // a confusing silent failure into a one-line correction.
-        logger.debug(
+        __DEV__ && logger.debug(
           '[OTA] React Native >= 0.82 detected. The only valid Android integration is ' +
             'getDefaultReactHost(..., jsBundleFilePath = ScaleBunOtaModule.getJSBundleFile(ctx)) — ' +
             'ReactNativeHost and its getJSBundleFile() override no longer exist.',
@@ -280,7 +280,7 @@ export class OtaOrchestrator {
       this.enabled = true;
       this.bootGuardConfig = config ?? {};
       this.signatureConfig = config?.signature;
-      logger.debug(
+      __DEV__ && logger.debug(
         `[OTA] Orchestrator initialized (RN ${this.environment.rnVersionString ?? 'unknown'}` +
           `${this.environment.bridgeless ? ', bridgeless' : ''}` +
           `${this.environment.hermes ? `, Hermes HBC v${this.environment.hermesBytecodeVersion ?? '?'}` : ''})`,
@@ -329,7 +329,7 @@ export class OtaOrchestrator {
           version: record.version,
           sha256: record.sha256,
         } as OtaBundlePayload;
-        logger.debug(`[OTA] Running bundle v${record.version} (${record.bundleId})`);
+        __DEV__ && logger.debug(`[OTA] Running bundle v${record.version} (${record.bundleId})`);
         return;
       }
 
@@ -337,7 +337,7 @@ export class OtaOrchestrator {
       // a reinstall of the app, cleared storage, or a bundle staged by an
       // older SDK. Report the hash so the server can still recognise it.
       this.currentBundle = { sha256: current.sha256 } as OtaBundlePayload;
-      logger.debug(
+      __DEV__ && logger.debug(
         `[OTA] Running an OTA bundle (sha ${String(current.sha256).slice(0, 12)}…) with no local install record.`,
       );
     } catch {
@@ -375,7 +375,7 @@ export class OtaOrchestrator {
     if (expected) {
       if (running === expected.identityToken) {
         // Proven: the bundle we installed is the bundle executing.
-        logger.debug('[OTA] Install verified — running bundle matches what was installed.');
+        __DEV__ && logger.debug('[OTA] Install verified — running bundle matches what was installed.');
         this.clearInstallExpectation();
         return;
       }
@@ -619,11 +619,11 @@ export class OtaOrchestrator {
         return { status: 'ERROR', error: 'OTA native module disabled or missing' };
       }
 
-      logger.debug('[OTA] Sync started…');
+      __DEV__ && logger.debug('[OTA] Sync started…');
       const checkRes = await this.checkForUpdate(params);
 
       if (checkRes.action === 'NONE') {
-        logger.debug('[OTA] App is up to date');
+        __DEV__ && logger.debug('[OTA] App is up to date');
         // If we booted from an OTA bundle and it's healthy, clear the boot guard
         this.startBootGuardHeartbeat();
         return { status: 'UP_TO_DATE' };
@@ -676,7 +676,7 @@ export class OtaOrchestrator {
       // ── DOWNLOAD ─────────────────────────────────────────────────────────
       otaEventEmitter.emitSimple('DOWNLOAD_STARTED', bundle.id, { version: bundle.version });
       const downloadStart = Date.now();
-      logger.debug(`[OTA] Downloading update v${bundle.version}…`);
+      __DEV__ && logger.debug(`[OTA] Downloading update v${bundle.version}…`);
 
       // Live progress: native tick → DOWNLOAD_PROGRESS (feeds useOtaUpdate) →
       // throttled POST to the live tracker. `bundle.size` is the authoritative
@@ -727,7 +727,7 @@ export class OtaOrchestrator {
 
       // Sprint 7: Try patch first if offered, fall back to full bundle
       if (bundle.patch && NativeScaleBunOta.stagePatch) {
-        logger.debug(
+        __DEV__ && logger.debug(
           `[OTA] Patch available (${(bundle.patch.size / 1024).toFixed(0)} KB vs ` +
             `${(bundle.size / 1024).toFixed(0)} KB full) — trying patch…`,
         );
@@ -739,7 +739,7 @@ export class OtaOrchestrator {
           );
           if (staged) {
             patchUsed = true;
-            logger.debug('[OTA] Patch applied successfully');
+            __DEV__ && logger.debug('[OTA] Patch applied successfully');
           } else {
             logger.warn('[OTA] Patch staging returned false — falling back to full bundle');
           }
@@ -821,7 +821,7 @@ export class OtaOrchestrator {
       this.recordInstallExpectation(bundle);
 
       otaEventEmitter.emitSimple('INSTALLED', bundle.id, { version: bundle.version });
-      logger.debug(`[OTA] Update v${bundle.version} installed successfully!`);
+      __DEV__ && logger.debug(`[OTA] Update v${bundle.version} installed successfully!`);
 
       // Deliver telemetry BEFORE a restart tears the JS runtime down —
       // an INSTALLED event queued but not sent would vanish with the process.
@@ -885,12 +885,12 @@ export class OtaOrchestrator {
       }
 
       const healthyMs = this.bootGuardConfig.healthyAfterMs ?? DEFAULT_HEALTHY_AFTER_MS;
-      logger.debug(`[OTA] Boot guard active — marking healthy after ${healthyMs}ms`);
+      __DEV__ && logger.debug(`[OTA] Boot guard active — marking healthy after ${healthyMs}ms`);
 
       this.healthyTimer = setTimeout(() => {
         noThrow(() => {
           NativeScaleBunOta?.markHealthy();
-          logger.info('[OTA] Boot guard cleared — bundle marked healthy ✓');
+          __DEV__ && logger.info('[OTA] Boot guard cleared — bundle marked healthy ✓');
           this.healthyTimer = null;
         });
       }, healthyMs);
@@ -933,11 +933,11 @@ export class OtaOrchestrator {
             /* the restart below makes cleanup moot */
           }
           this.resumeRestartArmed = false;
-          logger.info('[OTA] App resumed — activating the staged update now');
+          __DEV__ && logger.info('[OTA] App resumed — activating the staged update now');
           this.restart();
         }
       });
-      logger.debug('[OTA] Update staged — will activate on next resume (ON_NEXT_RESUME)');
+      __DEV__ && logger.debug('[OTA] Update staged — will activate on next resume (ON_NEXT_RESUME)');
     } catch {
       // AppState unavailable (tests, exotic hosts): the update still activates
       // on the next cold start, which is the documented fallback behaviour.
@@ -957,7 +957,7 @@ export class OtaOrchestrator {
    */
   restart(): void {
     noThrow(() => {
-      logger.info('[OTA] Triggering app restart…');
+      __DEV__ && logger.info('[OTA] Triggering app restart…');
       if (NativeScaleBunOta && typeof NativeScaleBunOta.restartApp === 'function') {
         NativeScaleBunOta.restartApp();
       } else if (DevSettings && typeof DevSettings.reload === 'function') {

package/src/features/ota/geoCountry.ts

@@ -73,9 +73,9 @@ export function prefetchDeviceCountry(): Promise<void> {
             memory = raw;
             storage.set(K_COUNTRY, raw);
             storage.set(K_FETCHED_AT, String(Date.now()));
-            logger.debug(`[OTA] Device country resolved: ${raw}`);
+            __DEV__ && logger.debug(`[OTA] Device country resolved: ${raw}`);
         } catch (err: any) {
-            logger.debug(`[OTA] Geo lookup skipped: ${err?.message ?? err}`);
+            __DEV__ && logger.debug(`[OTA] Geo lookup skipped: ${err?.message ?? err}`);
         } finally {
             clearTimeout(timer);
             inFlight = null;

package/src/features/ota/retry.ts

@@ -75,7 +75,7 @@ export async function retryWithBackoff<T>(
       lastError = err;
 
       if (!isRetryable(err)) {
-        logger.debug(`[OTA] ${label} failed with a non-retryable error — not retrying`);
+        __DEV__ && logger.debug(`[OTA] ${label} failed with a non-retryable error — not retrying`);
         throw err;
       }
 
@@ -83,7 +83,7 @@ export async function retryWithBackoff<T>(
       if (isLast) break;
 
       const delay = backoffDelay(attempt, baseDelayMs, maxDelayMs);
-      logger.debug(
+      __DEV__ && logger.debug(
         `[OTA] ${label} failed (attempt ${attempt + 1}/${attempts}) — retrying in ${delay}ms`,
       );
       await sleep(delay);

package/src/features/performance/PerformanceFeature.ts

@@ -25,6 +25,15 @@ import { PerformanceTransport, type PerfTransportSink } from './transport/Perfor
 import { MetricKeys } from './metrics/MetricsEngine';
 import { SessionManager } from '../session/SessionManager';
 
+/** Shape accepted by BackendSessionAdapter.queuePerformanceMetric. */
+type BackendPerfMetric = {
+    type: string;
+    screenName?: string;
+    duration?: number;
+    value?: number;
+    metadata?: Record<string, unknown>;
+};
+
 export class PerformanceFeature implements IFeature {
     readonly name = 'performance';
     private active = false;
@@ -70,7 +79,31 @@ export class PerformanceFeature implements IFeature {
     /** Delay schedule for each attempt (ms) — escalating to let views settle */
     private static readonly CAPTURE_DELAYS = [300, 600, 1200];
 
-    // Track event function from SDK pipeline
+    // ─── Early-metric buffering (backend) ───────────────────────────────
+    //
+    // Performance metrics reach the cloud via the SessionManager's backend
+    // transport. But the first metrics — most importantly app_launch — fire
+    // during PerformanceFeature.initialize() (appLaunchCollector.collect()),
+    // which runs from featureRegistry.initializeAll() BEFORE the bootstrap
+    // attaches the backend transport (SDKBootstrapper). In that window
+    // getBackendTransport() is null, so without buffering the metric is sent
+    // only to the desktop debugger and silently dropped from the cloud
+    // ("App start = 0" in Insights). We buffer such metrics locally and drain
+    // them the moment the transport appears (via subsequent events or a
+    // bounded retry). The backend adapter itself buffers again until the
+    // session row is ready, so ordering across the session boundary is safe.
+    /** Metrics captured before the backend transport was available. */
+    private _pendingBackendMetrics: BackendPerfMetric[] = [];
+    /** Retry timer that drains the buffer once the transport attaches. */
+    private _backendDrainTimer: ReturnType<typeof setTimeout> | null = null;
+    /** Number of drain attempts made for the current buffered batch. */
+    private _backendDrainAttempts = 0;
+    /** Hard cap on buffered metrics — bounds memory if a transport never attaches (non-SaaS). */
+    private static readonly BACKEND_BUFFER_MAX = 64;
+    /** Max drain retries before giving up (non-SaaS mode never attaches a transport). */
+    private static readonly BACKEND_DRAIN_MAX_ATTEMPTS = 6;
+    /** Escalating retry delays (ms); last value repeats. Covers the startup attach race. */
+    private static readonly BACKEND_DRAIN_DELAYS = [250, 500, 1000, 2000, 4000];
 
     constructor(config?: Partial<PerformanceConfig>) {
         this.config = mergePerformanceConfig(config);
@@ -297,6 +330,11 @@ export class PerformanceFeature implements IFeature {
             clearTimeout(this._captureTimer);
             this._captureTimer = null;
         }
+        // Stop the backend-drain retry loop (buffered metrics are dropped —
+        // the desktop transport already received them via sendEvent/sendMetric).
+        this._clearBackendDrainTimer();
+        this._backendDrainAttempts = 0;
+        this._pendingBackendMetrics = [];
     }
 
     get isActive(): boolean {
@@ -570,28 +608,100 @@ export class PerformanceFeature implements IFeature {
          * and it costs a duplicate serialize + upload per sample on every session.
          */
 
-        // Queue to SaaS backend dedicated performance endpoint
+        // Queue to SaaS backend dedicated performance endpoint. When the backend
+        // transport isn't attached yet (startup race — app_launch fires before
+        // SDKBootstrapper wires it), buffer locally and drain once it appears so
+        // the cloud gets the metric instead of only the desktop debugger.
+        this._forwardMetricToBackend(this._toBackendMetric(event));
+    }
+
+    /** Map a raw perf event onto the backend metric envelope. */
+    private _toBackendMetric(event: AnyPerfEvent): BackendPerfMetric {
+        const e = event as any;
+        // Forward structured launch fields so the backend can group by launch
+        // type and reconstruct the startup waterfall. Without this, only the
+        // raw duration reaches the analytics table and cold/warm/hot + phase
+        // timings are lost. Additive + forward-only: pre-existing rows stay as
+        // { id } and historical launch-type windows remain empty.
+        const metadata: Record<string, unknown> = { id: event.id };
+        if (event.type === 'app_launch') {
+            if (e.launchType) metadata.launchType = e.launchType;
+            if (e.breakdown) metadata.breakdown = e.breakdown;
+            if (e.phaseLabels) metadata.phaseLabels = e.phaseLabels;
+        }
+        return {
+            type: event.type,
+            screenName: e.screenName ?? e.context?.screenKey,
+            duration: e.durationMs,
+            value: e.estimatedFps ?? e.value,
+            metadata,
+        };
+    }
+
+    /**
+     * Hand a metric to the backend transport, or buffer it until one attaches.
+     * Every call first drains anything buffered, so a late-arriving transport
+     * flushes the backlog in the order the metrics were produced.
+     */
+    private _forwardMetricToBackend(metric: BackendPerfMetric): void {
         const backendTransport = SessionManager.getExistingInstance()?.getBackendTransport();
         if (backendTransport) {
-            const e = event as any;
-            // Forward structured launch fields so the backend can group by launch
-            // type and reconstruct the startup waterfall. Without this, only the
-            // raw duration reaches the analytics table and cold/warm/hot + phase
-            // timings are lost. Additive + forward-only: pre-existing rows stay as
-            // { id } and historical launch-type windows remain empty.
-            const metadata: Record<string, unknown> = { id: event.id };
-            if (event.type === 'app_launch') {
-                if (e.launchType) metadata.launchType = e.launchType;
-                if (e.breakdown) metadata.breakdown = e.breakdown;
-                if (e.phaseLabels) metadata.phaseLabels = e.phaseLabels;
+            this._drainPendingBackendMetrics(backendTransport);
+            backendTransport.queuePerformanceMetric(metric);
+            return;
+        }
+
+        // No transport yet — buffer (bounded, drop-oldest) and schedule a drain.
+        this._pendingBackendMetrics.push(metric);
+        if (this._pendingBackendMetrics.length > PerformanceFeature.BACKEND_BUFFER_MAX) {
+            this._pendingBackendMetrics.shift();
+        }
+        this._scheduleBackendDrain();
+    }
+
+    /** Flush all buffered metrics into the transport, preserving order. */
+    private _drainPendingBackendMetrics(
+        backendTransport: NonNullable<ReturnType<SessionManager['getBackendTransport']>>,
+    ): void {
+        if (this._pendingBackendMetrics.length === 0) return;
+        const buffered = this._pendingBackendMetrics;
+        this._pendingBackendMetrics = [];
+        for (const metric of buffered) {
+            backendTransport.queuePerformanceMetric(metric);
+        }
+        this._clearBackendDrainTimer();
+        this._backendDrainAttempts = 0;
+    }
+
+    /**
+     * Poll for the backend transport a bounded number of times so the sole
+     * early metric (app_launch) still reaches the cloud even when no later
+     * event arrives to trigger a drain. Gives up after BACKEND_DRAIN_MAX_ATTEMPTS
+     * (non-SaaS mode never attaches a transport — the desktop path already has
+     * the data), leaving the bounded buffer to be GC'd on teardown.
+     */
+    private _scheduleBackendDrain(): void {
+        if (this._backendDrainTimer) return;
+        if (this._backendDrainAttempts >= PerformanceFeature.BACKEND_DRAIN_MAX_ATTEMPTS) return;
+
+        const delays = PerformanceFeature.BACKEND_DRAIN_DELAYS;
+        const delay = delays[Math.min(this._backendDrainAttempts, delays.length - 1)];
+        this._backendDrainAttempts++;
+        this._backendDrainTimer = setTimeout(() => {
+            this._backendDrainTimer = null;
+            const backendTransport = SessionManager.getExistingInstance()?.getBackendTransport();
+            if (backendTransport) {
+                this._drainPendingBackendMetrics(backendTransport);
+            } else if (this._pendingBackendMetrics.length > 0) {
+                this._scheduleBackendDrain();
             }
-            backendTransport.queuePerformanceMetric({
-                type: event.type,
-                screenName: e.screenName ?? e.context?.screenKey,
-                duration: e.durationMs,
-                value: e.estimatedFps ?? e.value,
-                metadata,
-            });
+        }, delay);
+    }
+
+    private _clearBackendDrainTimer(): void {
+        if (this._backendDrainTimer) {
+            clearTimeout(this._backendDrainTimer);
+            this._backendDrainTimer = null;
         }
     }
 }

package/src/features/replay/core/logger/logger.ts

@@ -15,10 +15,6 @@ export function setVerbose(enabled: boolean): void {
     _verbose = enabled;
 }
 
-export function isVerbose(): boolean {
-    return _verbose;
-}
-
 export const logger = {
     debug(message: string, ...args: unknown[]): void {
         if (_verbose) {