@scalebun/react-native 1.0.2 → 1.0.4

package/src/features/performance/PerformanceFeature.ts

@@ -1,584 +1,597 @@
-/**
- * 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';
-
-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];
-
-    // Track event function from SDK pipeline
-    private trackFn: ((name: string, payload?: Record<string, unknown>) => void) | null = null;
-
-    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.trackFn = context.trackEvent;
-        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;
-        }
-    }
-
-    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);
-
-        // Also track through SDK pipeline (for backend ingestion)
-        if (this.trackFn) {
-            this.trackFn('$perf_event', {
-                perfType: event.type,
-                ...event,
-            });
-        }
-
-        // Queue to SaaS backend dedicated performance endpoint
-        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;
-            }
-            backendTransport.queuePerformanceMetric({
-                type: event.type,
-                screenName: e.screenName ?? e.context?.screenKey,
-                duration: e.durationMs,
-                value: e.estimatedFps ?? e.value,
-                metadata,
-            });
-        }
-    }
-}
+/**
+ * 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';
+
+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];
+
+    // Track event function from SDK pipeline
+
+    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;
+        }
+    }
+
+    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
+        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;
+            }
+            backendTransport.queuePerformanceMetric({
+                type: event.type,
+                screenName: e.screenName ?? e.context?.screenKey,
+                duration: e.durationMs,
+                value: e.estimatedFps ?? e.value,
+                metadata,
+            });
+        }
+    }
+}