@scalebun-release/react-native 2.5.0

package/src/features/performance/PerformanceFeature.ts

@@ -0,0 +1,729 @@
+/**
+ * ScaleBun SDK — Performance Feature
+ *
+ * Main orchestrator implementing IFeature.
+ * Manages the lifecycle of all performance collectors,
+ * metrics aggregation, and transport.
+ *
+ * This is the single entry point registered with the FeatureRegistry.
+ */
+
+import { Platform } from 'react-native';
+import type { IFeature, FeatureContext } from '../../core/contracts/IFeature';
+import type { PerformanceConfig } from './config';
+import { mergePerformanceConfig } from './config';
+import type { AnyPerfEvent, PerfContext, PerfDeviceMeta } from './models';
+import { JsStallCollector } from './collectors/JsStallCollector';
+import { AppLaunchCollector } from './collectors/AppLaunchCollector';
+import { ScreenLoadCollector } from './collectors/ScreenLoadCollector';
+import { AutoScreenLoadCollector } from './collectors/AutoScreenLoadCollector';
+import { FrameMetricsCollector } from './collectors/FrameMetricsCollector';
+import { UiHangCollector } from './collectors/UiHangCollector';
+import { NetworkPerfCollector } from './collectors/NetworkPerfCollector';
+import { CustomTraceCollector } from './collectors/CustomTraceCollector';
+import { PerformanceTransport, type PerfTransportSink } from './transport/PerformanceTransport';
+import { MetricKeys } from './metrics/MetricsEngine';
+import { SessionManager } from '../session/SessionManager';
+import { logger } from '../../core/logger/internalLogger';
+
+/** 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;
+    private config: PerformanceConfig;
+
+    // Collectors
+    private jsStallCollector: JsStallCollector;
+    private appLaunchCollector: AppLaunchCollector;
+    private screenLoadCollector: ScreenLoadCollector;
+    private autoScreenLoadCollector: AutoScreenLoadCollector;
+    private frameMetricsCollector: FrameMetricsCollector;
+    private uiHangCollector: UiHangCollector;
+    private networkPerfCollector: NetworkPerfCollector;
+    private customTraceCollector: CustomTraceCollector;
+
+    // Transport
+    private transport: PerformanceTransport;
+
+    // Session context
+    private sessionId: string = '';
+    private currentScreen: string = '';
+
+    // Device metadata (set once on init)
+    private deviceMeta: PerfDeviceMeta = {};
+
+    // ─── Auto-capture state ─────────────────────────────────────────────
+    /** Generation counter — incremented only on NEW screen navigation */
+    private _captureGen = 0;
+    /** Timestamp of last *successful* capture send (for throttle) */
+    private _lastCaptureTs = 0;
+    /** Map of dedupKey → timestamp of last successful delivery. Key = `screenName\x00visitId` or `screenName\x00b{1s-bucket}`. */
+    private _recentCaptures = new Map<string, number>();
+    /** Active retry timer handle (cleared on navigation) */
+    private _captureTimer: ReturnType<typeof setTimeout> | null = null;
+
+    // ─── Auto-capture constants ─────────────────────────────────────────
+    /** Min time between successful captures */
+    private static readonly CAPTURE_THROTTLE_MS = 800;
+    /** Min time before re-capturing the same screen */
+    private static readonly CAPTURE_DEDUP_MS = 10_000;
+    /** Max retry attempts per capture window */
+    private static readonly CAPTURE_MAX_RETRIES = 3;
+    /** Delay schedule for each attempt (ms) — escalating to let views settle */
+    private static readonly CAPTURE_DELAYS = [300, 600, 1200];
+
+    // ─── 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);
+        this.transport = new PerformanceTransport(this.config);
+
+        // Populate device metadata once (immutable per session)
+        this.deviceMeta = {
+            platform: Platform.OS as 'android' | 'ios',
+            osVersion: `${Platform.Version}`,
+            buildType: __DEV__ ? 'debug' : 'release',
+        };
+
+        const getContext = (): PerfContext => ({
+            sessionId: this.sessionId || 'unknown',
+            screenKey: this.currentScreen || undefined,
+            device: this.deviceMeta,
+        });
+
+        // Wire up collectors
+        this.jsStallCollector = new JsStallCollector(
+            this.config,
+            (event) => {
+                this._handleEvent(event);
+                // RC-2 fix: also send individual severe stalls as metrics
+                // so desktop's perfSelectors can find them under perf.js.stall
+                this.transport.sendMetric('perf.js.stall', event.durationMs, 'ms', {
+                    severity: event.severity,
+                });
+            },
+            (summary) => this.transport.sendStallSummary(summary),
+            getContext,
+        );
+
+        this.appLaunchCollector = new AppLaunchCollector(
+            this.config,
+            (event) => {
+                this._handleEvent(event);
+                this.transport.sendMetric(
+                    event.launchType === 'cold' ? MetricKeys.APP_LAUNCH_COLD : MetricKeys.APP_LAUNCH_WARM,
+                    event.durationMs,
+                    'ms',
+                );
+            },
+            getContext,
+        );
+
+        this.screenLoadCollector = new ScreenLoadCollector(
+            this.config,
+            (event) => {
+                this._handleEvent(event);
+                this.transport.sendMetric(
+                    MetricKeys.SCREEN_LOAD,
+                    event.durationMs,
+                    'ms',
+                    { screen: event.screenName },
+                );
+            },
+            getContext,
+        );
+
+        this.autoScreenLoadCollector = new AutoScreenLoadCollector(
+            this.config,
+            (event) => {
+                this._handleEvent(event);
+                this.transport.sendMetric(
+                    MetricKeys.SCREEN_LOAD,
+                    event.durationMs,
+                    'ms',
+                    { screen: event.screenName },
+                );
+                // Update current screen from auto-detection
+                this.currentScreen = event.screenName;
+
+                // ─── Auto-capture screenshot for performance preview ────────
+                // This fires AFTER screen load timing completes, using the
+                // correct screen name from React Navigation's route state.
+                // This is the most truthful "screen settled" moment.
+                this._triggerAutoCapture(event.screenName, event.id);
+            },
+            getContext,
+        );
+
+        this.frameMetricsCollector = new FrameMetricsCollector(
+            this.config,
+            (event) => {
+                this._handleEvent(event);
+                this.transport.sendMetric(MetricKeys.FPS_ESTIMATED, event.estimatedFps, 'fps');
+                this.transport.sendMetric(MetricKeys.FRAMES_DROPPED, event.droppedFrames, 'count');
+                this.transport.sendMetric(MetricKeys.FRAMES_SLOW, event.slowFrames, 'count');
+                this.transport.sendMetric(MetricKeys.FRAMES_FROZEN, event.frozenFrames, 'count');
+            },
+            getContext,
+        );
+
+        this.uiHangCollector = new UiHangCollector(
+            this.config,
+            (event) => {
+                this._handleEvent(event);
+                this.transport.sendMetric(MetricKeys.UI_HANG_COUNT, 1, 'count');
+                this.transport.sendMetric(MetricKeys.UI_HANG_MAX, event.durationMs, 'ms');
+            },
+            getContext,
+        );
+
+        this.networkPerfCollector = new NetworkPerfCollector(
+            this.config,
+            (event) => {
+                this._handleEvent(event);
+                if (event.failed) {
+                    this.transport.sendMetric(MetricKeys.NETWORK_FAIL_COUNT, 1, 'count');
+                } else {
+                    this.transport.sendMetric(MetricKeys.NETWORK_SLOW_COUNT, 1, 'count');
+                }
+            },
+            getContext,
+        );
+
+        this.customTraceCollector = new CustomTraceCollector(
+            this.config,
+            (event) => {
+                this._handleEvent(event);
+                this.transport.sendMetric(
+                    `${MetricKeys.CUSTOM_TRACE}.${event.name}`,
+                    event.durationMs,
+                    'ms',
+                );
+            },
+            getContext,
+        );
+    }
+
+    // ─── IFeature Lifecycle ─────────────────────────────────────────────
+
+    async initialize(context: FeatureContext): Promise<void> {
+        if (this.active || !this.config.enabled) return;
+
+        this.active = true;
+
+        // Activate native performance collectors (Android AppStart/Frame/ANR,
+        // iOS launch/frame/hang). Without this, native getAppStartInfo() returns
+        // null and frame/hang bridges stay inert. Must run BEFORE appLaunch.collect().
+        // Guarded — native module may be absent (e.g. Expo Go); init must never throw.
+        await this._initializeNative();
+
+        // Install automatic screen load detection (allows screenshot capture on navigate)
+        this.autoScreenLoadCollector.install();
+
+        // Collect app launch (one-shot) — Tier-1
+        this.appLaunchCollector.collect();
+
+        // Tier-1 UI hang / ANR watchdog. Emits only on a real hang.
+        // ON by default (config.uiHangs); host can disable via config.
+        if (this.config.uiHangs) {
+            this.uiHangCollector.start();
+        }
+
+        // Tier-2 (frame_metrics + js_stall): heavy, continuous. Run only on a
+        // sampled fraction of sessions. Default 10% (DEFAULT_TIER2_SAMPLE_RATE);
+        // host sets sampleRate 0 to disable.
+        if (this.config.tier2Enabled && this._shouldSampleTier2()) {
+            this.startSampledCollection();
+        }
+    }
+
+    /** Activate native performance module once (no-throw if unavailable). */
+    private async _initializeNative(): Promise<void> {
+        try {
+            const { NativeModules } = require('react-native');
+            await NativeModules?.ScaleBunPerformance?.initialize?.();
+        } catch { /* no-throw — native perf is optional */ }
+    }
+
+    /**
+     * Deterministic per-session Tier-2 sampling decision.
+     * Same sessionId always yields the same result (no mid-session flip).
+     * Falls back to RNG only when no sessionId is available yet.
+     */
+    private _shouldSampleTier2(): boolean {
+        const rate = this.config.tier2SampleRate ?? 0;
+        if (rate <= 0) return false;
+        if (rate >= 1) return true;
+        const id = this.sessionId;
+        if (!id) return Math.random() < rate;
+        // FNV-1a hash → fraction in [0,1)
+        let h = 2166136261;
+        for (let i = 0; i < id.length; i++) {
+            h ^= id.charCodeAt(i);
+            h = Math.imul(h, 16777619);
+        }
+        return (h >>> 0) / 4294967296 < rate;
+    }
+
+    /** Start ONLY the Tier-2 sampled collectors (uiHang is a Tier-1 watchdog, not started here). */
+    startSampledCollection(): void {
+        this.frameMetricsCollector.start();
+        this.jsStallCollector.start();
+    }
+
+    /** Start continuous collectors on-demand */
+    startContinuousCollection(): void {
+        this.jsStallCollector.start();
+        this.frameMetricsCollector.start();
+        this.uiHangCollector.start();
+    }
+
+    /** Stop continuous collectors */
+    stopContinuousCollection(): void {
+        this.jsStallCollector.stop();
+        this.frameMetricsCollector.stop();
+        this.uiHangCollector.stop();
+    }
+
+    teardown(): void {
+        this.jsStallCollector.stop();
+        this.frameMetricsCollector.stop();
+        this.uiHangCollector.stop();
+        this.autoScreenLoadCollector.stop();
+        this.screenLoadCollector.reset();
+        this.customTraceCollector.reset();
+        this.transport.reset();
+        this.active = false;
+        // Clear any pending capture timer
+        if (this._captureTimer) {
+            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 {
+        return this.active;
+    }
+
+    // ─── Transport Integration ──────────────────────────────────────────
+
+    /** Connect the debug transport for sending metrics to desktop */
+    setTransportSink(sink: PerfTransportSink | null): void {
+        this.transport.setSink(sink);
+    }
+
+    // ─── Session Integration ────────────────────────────────────────────
+
+    setSessionId(sessionId: string): void {
+        this.sessionId = sessionId;
+    }
+
+    setCurrentScreen(screenName: string): void {
+        this.currentScreen = screenName;
+    }
+
+    // ─── Auto-Capture for Performance Preview ───────────────────────────
+    //
+    // Triggered from autoScreenLoadCollector callback — the only place where:
+    //   1) The correct screen name is known (from React Navigation route state)
+    //   2) The screen has actually settled (timing just completed)
+    //   3) No screen name mismatch can occur
+    //
+    // Stability policy:
+    //   - Bounded retry window: up to 3 attempts with escalating delays (300/600/1200ms)
+    //   - Generation-based cancellation ONLY on new screen navigation
+    //   - Throttle only blocks if a *successful* capture happened recently
+    //   - Dedup key is (screenName, visitId) — each navigation visit is distinct,
+    //     so revisiting the same screen does NOT suppress a new capture
+    //   - Fallback dedup key uses a 1s timestamp bucket when visitId is unavailable
+    //   - CAPTURE_DEDUP_MS (10s) is the TTL for dedup entries, not a per-screen cooldown
+    //   - Dedup only records after confirmed successful send
+    //   - Failed/null captures trigger retry, do NOT count toward dedup or throttle
+    //   - All retries cancelled immediately on screen change
+
+    private _triggerAutoCapture(screenName: string, visitId?: string): void {
+        // Cancel any pending capture window from a previous screen
+        if (this._captureTimer) {
+            clearTimeout(this._captureTimer);
+            this._captureTimer = null;
+        }
+
+        // New generation — invalidates any in-flight async captures for old screens
+        const gen = ++this._captureGen;
+
+        // Build dedup key: (screenName, visitId) so each navigation visit is distinct.
+        // Falls back to a 1s timestamp bucket when no visitId is available (e.g. manual callers).
+        const now = Date.now();
+        const dedupKey = visitId !== undefined
+            ? `${screenName}\x00${visitId}`
+            : `${screenName}\x00b${Math.floor(now / 1000)}`;
+
+        // Dedup: skip only if this exact visit was *successfully* captured within CAPTURE_DEDUP_MS.
+        // Different visitIds for the same screenName are NOT suppressed — revisits are legitimate.
+        const lastSuccess = this._recentCaptures.get(dedupKey);
+        if (lastSuccess !== undefined && now - lastSuccess < PerformanceFeature.CAPTURE_DEDUP_MS) {
+            return;
+        }
+
+        // Start bounded retry window — attempt 0
+        this._scheduleCaptureAttempt(screenName, gen, 0, dedupKey);
+    }
+
+    /**
+     * Schedules a single capture attempt within the bounded retry window.
+     * On failure, schedules the next retry up to CAPTURE_MAX_RETRIES.
+     */
+    private _scheduleCaptureAttempt(screenName: string, gen: number, attempt: number, dedupKey: string): void {
+        if (attempt >= PerformanceFeature.CAPTURE_MAX_RETRIES) return;
+        if (gen !== this._captureGen) return;
+
+        const delay = PerformanceFeature.CAPTURE_DELAYS[attempt] ?? 1200;
+        this._captureTimer = setTimeout(() => {
+            this._captureTimer = null;
+            this._executeAutoCapture(screenName, gen, attempt, dedupKey);
+        }, delay);
+    }
+
+    private async _executeAutoCapture(screenName: string, gen: number, attempt: number, dedupKey: string): Promise<void> {
+        try {
+            // Cancelled — screen changed since this was scheduled
+            if (gen !== this._captureGen) return;
+
+            // Throttle: only skip if a *successful* capture happened very recently
+            const now = Date.now();
+            if (this._lastCaptureTs > 0 && now - this._lastCaptureTs < PerformanceFeature.CAPTURE_THROTTLE_MS) {
+                // Throttled — retry later if budget remains
+                this._scheduleCaptureAttempt(screenName, gen, attempt + 1, dedupKey);
+                return;
+            }
+
+            // Get transport sink
+            const sink = this.transport.getSink();
+            if (!sink) {
+                // Sink not ready — retry
+                this._scheduleCaptureAttempt(screenName, gen, attempt + 1, dedupKey);
+                return;
+            }
+
+            // Load bridgeAdapter
+            let bridgeAdapter: any;
+            try {
+                bridgeAdapter = require('../../features/replay/bridge/adapters/bridgeAdapter').bridgeAdapter;
+            } catch {
+                this._scheduleCaptureAttempt(screenName, gen, attempt + 1, dedupKey);
+                return;
+            }
+
+            if (!bridgeAdapter?.isAvailable()) {
+                this._scheduleCaptureAttempt(screenName, gen, attempt + 1, dedupKey);
+                return;
+            }
+
+            // Final stale check before async native call
+            if (gen !== this._captureGen) return;
+
+            const result = await bridgeAdapter.captureScreenshot('auto-perf');
+
+            // Post-capture stale check
+            if (gen !== this._captureGen) return;
+
+            // Validate result
+            if (!result?.base64) {
+                // Native capture failed — retry
+                this._scheduleCaptureAttempt(screenName, gen, attempt + 1, dedupKey);
+                return;
+            }
+
+            // ── SUCCESS — only now record throttle + dedup ──
+            this._lastCaptureTs = Date.now();
+            this._recentCaptures.set(dedupKey, this._lastCaptureTs);
+
+            // Prune dedup entries older than CAPTURE_DEDUP_MS (TTL-based — no size cap needed)
+            const pruneOlderThan = this._lastCaptureTs - PerformanceFeature.CAPTURE_DEDUP_MS;
+            for (const [key, ts] of this._recentCaptures) {
+                if (ts < pruneOlderThan) this._recentCaptures.delete(key);
+            }
+
+            // Send via transport as proper event envelope
+            const frameId = `auto-perf-${Date.now()}-${Math.random().toString(36).substring(2, 8)}`;
+            sink.send({
+                type: 'event',
+                protocolVersion: 1,
+                deviceId: sink.deviceId,
+                sessionId: sink.sessionId,
+                timestamp: result.timestamp || Date.now(),
+                sequence: sink.nextSequence(),
+                payload: {
+                    id: frameId,
+                    category: 'session',
+                    name: 'session:frame',
+                    data: {
+                        frameId,
+                        sessionId: sink.sessionId,
+                        sequenceNumber: 0,
+                        screenName,
+                        trigger: 'auto-perf',
+                        format: result.format || 'jpeg',
+                        sizeBytes: result.sizeBytes || 0,
+                        width: result.width || 0,
+                        height: result.height || 0,
+                        imageData: result.base64,
+                        source: 'auto-perf',
+                    },
+                },
+            } as any);
+        } catch { /* no-throw — auto-capture must never affect app */ }
+    }
+
+    // ─── Navigation Integration ─────────────────────────────────────────
+
+    /**
+     * Called from the app's NavigationContainer onStateChange.
+     * Routes to AutoScreenLoadCollector for automatic timing.
+     */
+    onNavigationStateChange(state: unknown): void {
+        this.autoScreenLoadCollector.onNavigationStateChange(state);
+    }
+
+    /**
+     * Called from AutoScreenDetector's screen-change emission (navRef/heuristic).
+     * Reuses the detector's already-resolved screen name to time screen loads in
+     * SaaS — avoids attaching a second navigation listener on the app's nav ref.
+     */
+    onScreenChange(screenName: string): void {
+        this.autoScreenLoadCollector.onScreenDetected(screenName);
+    }
+
+    // ─── Screen Load API (manual) ───────────────────────────────────────
+
+    markScreenLoadStart(screenName: string): void {
+        // Register manual override so auto-detection skips this screen
+        this.autoScreenLoadCollector.registerManualOverride(screenName);
+        this.screenLoadCollector.markStart(screenName);
+    }
+
+    markScreenLoadEnd(screenName: string): void {
+        this.screenLoadCollector.markEnd(screenName);
+        this.autoScreenLoadCollector.clearManualOverride(screenName);
+    }
+
+    // ─── Custom Trace API ───────────────────────────────────────────────
+
+    startTrace(name: string): string | null {
+        return this.customTraceCollector.startTrace(name);
+    }
+
+    stopTrace(traceId: string): void {
+        this.customTraceCollector.stopTrace(traceId);
+    }
+
+    addTraceSpan(traceId: string, name: string, durationMs: number, data?: Record<string, unknown>): void {
+        this.customTraceCollector.addSpan(traceId, name, durationMs, data);
+    }
+
+    addTraceMeasurement(traceId: string, name: string, value: number, unit: string): void {
+        this.customTraceCollector.addMeasurement(traceId, name, value, unit);
+    }
+
+    // ─── Public Metric Sending ──────────────────────────────────────────
+
+    /**
+     * Send a raw performance metric through the transport.
+     * Used by demo/debug screens to inject simulated metrics
+     * through the same proven pipeline that PerfMonitor uses.
+     */
+    sendMetric(name: string, value: number, unit?: string, tags?: Record<string, string>): void {
+        this.transport.sendMetric(name, value, unit, tags);
+    }
+
+    // ─── Network Event Tap ──────────────────────────────────────────────
+
+    /** Called by the SDK when a $network_request event occurs */
+    processNetworkEvent(data: Record<string, unknown>): void {
+        this.networkPerfCollector.processNetworkEvent(data);
+    }
+
+    // ─── Internal ───────────────────────────────────────────────────────
+
+    private _handleEvent(event: AnyPerfEvent): void {
+        // Send to debug transport
+        this.transport.sendEvent(event);
+
+        /**
+         * REMOVED: a duplicate `$perf_event` through the analytics/event pipeline.
+         *
+         * This claimed to be "for backend ingestion", but the `queuePerformanceMetric` call below is
+         * the backend ingestion path — it writes the dedicated `performance_metrics` table, and that
+         * is what EVERY consumer reads: `perf-aggregate.ch.ts` (FPS, frameMetricsSessions), the
+         * Monitor low-FPS KPI, the page-load RenderingPanel and the Replay Inspector's FPS readout.
+         * Nothing in the backend or the dashboard reads `$perf_event` — verified by search.
+         *
+         * So this line wrote every perf sample a SECOND time, into the event lane, where it landed as
+         * `USER_ACTION` and was counted as a user interaction. Measured in production:
+         *
+         *     performance_metrics.frame_metrics   75,278   ← read by everything
+         *     replay_events (as USER_ACTION)      47,019   ← read by nothing
+         *
+         * `USER_ACTION` was 99% of all mobile events (62,026 of ~62,600), and only 980 of those
+         * carried real gesture data. One session showed 4,735 events against SIX real gestures. That
+         * made session event counts meaningless and polluted anything counting user interactions.
+         *
+         * Dropping it loses no data and no feature — the perf lane's copy is the more complete one —
+         * and it costs a duplicate serialize + upload per sample on every session.
+         */
+
+        // 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,
+            // The backend perf insights count `value` (count(pm.value)), not `duration`.
+            // js_stall/ui_hang events carry only `durationMs` (no `value`/`estimatedFps`),
+            // so this landed NULL and every stall/hang row read as "recorded without a
+            // duration" — nothing rankable, Performance Insights showed 0. Fall back to
+            // durationMs so the magnitude reaches the column the engine measures.
+            value: e.estimatedFps ?? e.value ?? e.durationMs,
+            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 sm = SessionManager.getExistingInstance();
+        const backendTransport = sm?.getBackendTransport();
+        // [perf.trace] diagnostic (warn so it survives the default release log level).
+        // This is THE bridge datum: does the SessionManager singleton this module
+        // sees have a backend transport attached when a perf metric is forwarded?
+        logger.debug('[perf.trace] forwardMetricToBackend', {
+            type: metric.type,
+            hasSessionManager: !!sm,
+            hasBackendTransport: !!backendTransport,
+            buffered: this._pendingBackendMetrics.length,
+        });
+        if (backendTransport) {
+            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);
+        }
+        logger.debug('[perf.trace] drained buffered metrics to backend', { count: buffered.length });
+        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) {
+            logger.warn('[perf.trace] drain gave up — buffered metrics never reached the backend', {
+                attempts: this._backendDrainAttempts, dropped: this._pendingBackendMetrics.length,
+            });
+            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();
+            }
+        }, delay);
+    }
+
+    private _clearBackendDrainTimer(): void {
+        if (this._backendDrainTimer) {
+            clearTimeout(this._backendDrainTimer);
+            this._backendDrainTimer = null;
+        }
+    }
+}