@scalebun-release/react-native 2.5.0

package/lib/module/features/performance/PerformanceFeature.js

@@ -0,0 +1,643 @@
+/**
+ * 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 { mergePerformanceConfig } from './config';
+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 } from './transport/PerformanceTransport';
+import { MetricKeys } from './metrics/MetricsEngine';
+import { SessionManager } from '../session/SessionManager';
+import { logger } from '../../core/logger/internalLogger';
+
+/** Shape accepted by BackendSessionAdapter.queuePerformanceMetric. */
+
+export class PerformanceFeature {
+  name = 'performance';
+  active = false;
+
+  // Collectors
+
+  // Transport
+
+  // Session context
+  sessionId = '';
+  currentScreen = '';
+
+  // Device metadata (set once on init)
+  deviceMeta = {};
+
+  // ─── Auto-capture state ─────────────────────────────────────────────
+  /** Generation counter — incremented only on NEW screen navigation */
+  _captureGen = 0;
+  /** Timestamp of last *successful* capture send (for throttle) */
+  _lastCaptureTs = 0;
+  /** Map of dedupKey → timestamp of last successful delivery. Key = `screenName\x00visitId` or `screenName\x00b{1s-bucket}`. */
+  _recentCaptures = new Map();
+  /** Active retry timer handle (cleared on navigation) */
+  _captureTimer = null;
+
+  // ─── Auto-capture constants ─────────────────────────────────────────
+  /** Min time between successful captures */
+  static CAPTURE_THROTTLE_MS = 800;
+  /** Min time before re-capturing the same screen */
+  static CAPTURE_DEDUP_MS = 10_000;
+  /** Max retry attempts per capture window */
+  static CAPTURE_MAX_RETRIES = 3;
+  /** Delay schedule for each attempt (ms) — escalating to let views settle */
+  static 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. */
+  _pendingBackendMetrics = [];
+  /** Retry timer that drains the buffer once the transport attaches. */
+  _backendDrainTimer = null;
+  /** Number of drain attempts made for the current buffered batch. */
+  _backendDrainAttempts = 0;
+  /** Hard cap on buffered metrics — bounds memory if a transport never attaches (non-SaaS). */
+  static BACKEND_BUFFER_MAX = 64;
+  /** Max drain retries before giving up (non-SaaS mode never attaches a transport). */
+  static BACKEND_DRAIN_MAX_ATTEMPTS = 6;
+  /** Escalating retry delays (ms); last value repeats. Covers the startup attach race. */
+  static BACKEND_DRAIN_DELAYS = [250, 500, 1000, 2000, 4000];
+  constructor(config) {
+    this.config = mergePerformanceConfig(config);
+    this.transport = new PerformanceTransport(this.config);
+
+    // Populate device metadata once (immutable per session)
+    this.deviceMeta = {
+      platform: Platform.OS,
+      osVersion: `${Platform.Version}`,
+      buildType: __DEV__ ? 'debug' : 'release'
+    };
+    const getContext = () => ({
+      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) {
+    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). */
+  async _initializeNative() {
+    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.
+   */
+  _shouldSampleTier2() {
+    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() {
+    this.frameMetricsCollector.start();
+    this.jsStallCollector.start();
+  }
+
+  /** Start continuous collectors on-demand */
+  startContinuousCollection() {
+    this.jsStallCollector.start();
+    this.frameMetricsCollector.start();
+    this.uiHangCollector.start();
+  }
+
+  /** Stop continuous collectors */
+  stopContinuousCollection() {
+    this.jsStallCollector.stop();
+    this.frameMetricsCollector.stop();
+    this.uiHangCollector.stop();
+  }
+  teardown() {
+    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() {
+    return this.active;
+  }
+
+  // ─── Transport Integration ──────────────────────────────────────────
+
+  /** Connect the debug transport for sending metrics to desktop */
+  setTransportSink(sink) {
+    this.transport.setSink(sink);
+  }
+
+  // ─── Session Integration ────────────────────────────────────────────
+
+  setSessionId(sessionId) {
+    this.sessionId = sessionId;
+  }
+  setCurrentScreen(screenName) {
+    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
+
+  _triggerAutoCapture(screenName, visitId) {
+    // 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.
+   */
+  _scheduleCaptureAttempt(screenName, gen, attempt, dedupKey) {
+    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);
+  }
+  async _executeAutoCapture(screenName, gen, attempt, dedupKey) {
+    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;
+      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'
+          }
+        }
+      });
+    } 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) {
+    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) {
+    this.autoScreenLoadCollector.onScreenDetected(screenName);
+  }
+
+  // ─── Screen Load API (manual) ───────────────────────────────────────
+
+  markScreenLoadStart(screenName) {
+    // Register manual override so auto-detection skips this screen
+    this.autoScreenLoadCollector.registerManualOverride(screenName);
+    this.screenLoadCollector.markStart(screenName);
+  }
+  markScreenLoadEnd(screenName) {
+    this.screenLoadCollector.markEnd(screenName);
+    this.autoScreenLoadCollector.clearManualOverride(screenName);
+  }
+
+  // ─── Custom Trace API ───────────────────────────────────────────────
+
+  startTrace(name) {
+    return this.customTraceCollector.startTrace(name);
+  }
+  stopTrace(traceId) {
+    this.customTraceCollector.stopTrace(traceId);
+  }
+  addTraceSpan(traceId, name, durationMs, data) {
+    this.customTraceCollector.addSpan(traceId, name, durationMs, data);
+  }
+  addTraceMeasurement(traceId, name, value, unit) {
+    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, value, unit, tags) {
+    this.transport.sendMetric(name, value, unit, tags);
+  }
+
+  // ─── Network Event Tap ──────────────────────────────────────────────
+
+  /** Called by the SDK when a $network_request event occurs */
+  processNetworkEvent(data) {
+    this.networkPerfCollector.processNetworkEvent(data);
+  }
+
+  // ─── Internal ───────────────────────────────────────────────────────
+
+  _handleEvent(event) {
+    // 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. */
+  _toBackendMetric(event) {
+    const e = event;
+    // 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 = {
+      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.
+   */
+  _forwardMetricToBackend(metric) {
+    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. */
+  _drainPendingBackendMetrics(backendTransport) {
+    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.
+   */
+  _scheduleBackendDrain() {
+    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);
+  }
+  _clearBackendDrainTimer() {
+    if (this._backendDrainTimer) {
+      clearTimeout(this._backendDrainTimer);
+      this._backendDrainTimer = null;
+    }
+  }
+}
+//# sourceMappingURL=PerformanceFeature.js.map