@scalebun-release/react-native 2.5.0

package/src/features/performance/collectors/FrameMetricsCollector.ts

@@ -0,0 +1,210 @@
+/**
+ * ScaleBun SDK — Frame Metrics Collector
+ *
+ * Receives native frame metrics via bridge events and translates
+ * them into FrameMetricsEvent. The actual frame capture happens
+ * in native code (FrameMetrics API on Android, CADisplayLink on iOS).
+ *
+ * This collector:
+ * - Listens for native frame metric snapshots
+ * - Aggregates per-window frame quality
+ * - Emits FrameMetricsEvent for transport
+ */
+
+import { AppState, NativeEventEmitter, type NativeEventSubscription } from 'react-native';
+import { getNativePerformanceModule } from '../getNativePerformanceModule';
+import type { FrameMetricsEvent, PerfContext } from '../models';
+import { PERF_SCHEMA_VERSION } from '../models';
+import type { PerformanceConfig } from '../config';
+
+export type FrameMetricsCallback = (event: FrameMetricsEvent) => void;
+
+export class FrameMetricsCollector {
+    private config: PerformanceConfig;
+    private onFrameMetrics: FrameMetricsCallback;
+    private contextProvider: () => PerfContext;
+    private eventSubscription: any = null;
+    private running = false;
+    /** AppState subscription — see `_installAppStateGate`. */
+    private appStateSubscription: NativeEventSubscription | null = null;
+    /** True while the native sampler is actually running (i.e. armed AND foregrounded). */
+    private sampling = false;
+    /** Timestamp of the last emitted window — drives the healthy-window heartbeat below. */
+    private lastEmitTs = 0;
+
+    /**
+     * HEALTHY windows emit at a heartbeat, not per report interval.
+     *
+     * The native sampler reports every `reportIntervalMs` (5 s), and every window became a stored
+     * row — on a session hours long that is 720 rows/hour of "still 60 fps", which is how real
+     * sessions hit the dashboard's 2,000-row display cap with nothing to say. A window that shows
+     * ANY jank (dropped/frozen frames, meaningful slow-frame count, an FPS dip) always emits; a
+     * healthy window emits only when the heartbeat has elapsed, keeping the FPS series alive for
+     * the charts at 1/12th the volume. Capture cadence is unchanged — only identical-looking
+     * healthy rows are elided, and the first window after ANY emit gap states the recovery.
+     */
+    private static readonly HEALTHY_HEARTBEAT_MS = 60_000;
+
+    constructor(
+        config: PerformanceConfig,
+        onFrameMetrics: FrameMetricsCallback,
+        contextProvider: () => PerfContext,
+    ) {
+        this.config = config;
+        this.onFrameMetrics = onFrameMetrics;
+        this.contextProvider = contextProvider;
+    }
+
+    start(): void {
+        if (this.running || !this.config.frameMetrics) return;
+        this.running = true;
+
+        try {
+            const perfModule = getNativePerformanceModule();
+            if (!perfModule) return;
+
+            const emitter = new NativeEventEmitter(perfModule);
+            this.eventSubscription = emitter.addListener(
+                'ScaleBunPerformance_FrameMetrics',
+                (data: any) => {
+                    try {
+                        this._handleNativeFrameMetrics(data);
+                    } catch {
+                        // No-throw
+                    }
+                },
+            );
+
+            this._startNativeSampler();
+            this._installAppStateGate();
+        } catch {
+            // Native module not available — graceful degradation
+        }
+    }
+
+    /**
+     * Pause sampling while the app is backgrounded.
+     *
+     * THE BUG THIS FIXES. `startFrameMetrics` hands off to a native loop that runs until something
+     * calls `stopFrameMetrics`. Nothing did. The collector had no AppState awareness at all — unlike
+     * `AutoScreenLoadCollector`, which has subscribed to it since it was written — so once a session
+     * was sampled in, it kept sampling for as long as the PROCESS lived, not as long as the app was
+     * being used.
+     *
+     * Measured in production: sessions with `durationMs` of 86,400,000 (exactly 24h) and 70,797,000
+     * (~19.7h) carrying 39,766 and 3,709 frame samples against 0 and 6 real gestures respectively.
+     * `frame_metrics` was 75% of ALL mobile events for this reason.
+     *
+     * The `tier2SampleRate` knob does not help here: it gates WHICH sessions collect, not how long
+     * they collect for. A sampled-in session that gets backgrounded still samples for hours, which is
+     * why lowering it would have hidden the symptom while leaving the cause.
+     *
+     * It is also a DATA-QUALITY fix, not only a volume one. Frame timings from a backgrounded app
+     * describe a screen nobody is looking at, and they were feeding the low-FPS KPI and jank
+     * detection — so the noise was not merely stored, it was being reported as UI performance.
+     *
+     * NOTE: on iOS the OS already stops delivering CADisplayLink callbacks on background, so the
+     * practical effect is largest on Android. Gating in JS keeps the two platforms behaving the same
+     * either way, rather than relying on an OS side effect that is not part of any contract.
+     */
+    private _installAppStateGate(): void {
+        if (this.appStateSubscription) return;
+        this.appStateSubscription = AppState.addEventListener('change', (next) => {
+            if (!this.running) return; // stop() already tore us down
+            if (next === 'active') this._startNativeSampler();
+            else this._stopNativeSampler(); // 'background' and 'inactive' (iOS call/app-switcher)
+        });
+    }
+
+    /** Idempotent — AppState can fire 'active' more than once without an intervening background. */
+    private _startNativeSampler(): void {
+        if (this.sampling) return;
+        try {
+            const perfModule = getNativePerformanceModule();
+            if (typeof perfModule?.startFrameMetrics === 'function') {
+                perfModule.startFrameMetrics(this.config.reportIntervalMs);
+                this.sampling = true;
+            }
+        } catch {
+            // No-throw: a perf collector must never break the host app.
+        }
+    }
+
+    private _stopNativeSampler(): void {
+        if (!this.sampling) return;
+        this.sampling = false;
+        try {
+            const perfModule = getNativePerformanceModule();
+            if (typeof perfModule?.stopFrameMetrics === 'function') {
+                perfModule.stopFrameMetrics();
+            }
+        } catch {
+            // No-throw
+        }
+    }
+
+    stop(): void {
+        this.running = false;
+        if (this.eventSubscription) {
+            this.eventSubscription.remove();
+            this.eventSubscription = null;
+        }
+        // Remove the AppState listener BEFORE stopping the sampler: a 'change' arriving mid-teardown
+        // would otherwise restart the native loop on a collector that is being shut down, which is the
+        // same leak this gate exists to close.
+        if (this.appStateSubscription) {
+            this.appStateSubscription.remove();
+            this.appStateSubscription = null;
+        }
+        this._stopNativeSampler();
+    }
+
+    private _handleNativeFrameMetrics(data: any): void {
+        if (!data || typeof data.totalFrames !== 'number') return;
+
+        const totalFrames = data.totalFrames || 0;
+        const droppedFrames = data.droppedFrames || 0;
+        const slowFrames = data.slowFrames || 0;
+        const frozenFrames = data.frozenFrames || 0;
+        const windowMs = data.windowMs || this.config.reportIntervalMs;
+        const maxFrameTimeMs = data.maxFrameTimeMs || 0;
+
+        // Estimated FPS
+        const expectedFrames = Math.round(windowMs / 16.67);
+        const actualFrames = Math.max(0, totalFrames - droppedFrames);
+        const estimatedFps = expectedFrames > 0
+            ? Math.round((actualFrames / expectedFrames) * 60)
+            : 60;
+
+        const clampedFps = Math.min(60, Math.max(0, estimatedFps));
+
+        // Healthy-window heartbeat — see HEALTHY_HEARTBEAT_MS. Jank always emits.
+        const now = Date.now();
+        const healthy =
+            droppedFrames === 0 &&
+            frozenFrames === 0 &&
+            slowFrames <= 2 &&
+            clampedFps >= 55;
+        if (healthy && this.lastEmitTs !== 0 && now - this.lastEmitTs < FrameMetricsCollector.HEALTHY_HEARTBEAT_MS) {
+            return;
+        }
+        this.lastEmitTs = now;
+
+        const event: FrameMetricsEvent = {
+            id: `frames-${now}-${Math.random().toString(36).substring(2, 8)}`,
+            type: 'frame_metrics',
+            timestamp: now,
+            schemaVersion: PERF_SCHEMA_VERSION,
+            context: this.contextProvider(),
+            windowMs,
+            totalFrames,
+            droppedFrames,
+            slowFrames,
+            frozenFrames,
+            estimatedFps: clampedFps,
+            maxFrameTimeMs,
+        };
+
+        this.onFrameMetrics(event);
+    }
+}

package/src/features/performance/collectors/JsStallCollector.ts

@@ -0,0 +1,184 @@
+/**
+ * ScaleBun SDK — JS Stall Collector
+ *
+ * Detects event-loop stalls using setInterval drift detection.
+ * Migrated from debug/perf.ts and enhanced with severity bucketing,
+ * bounded memory, and proper lifecycle management.
+ *
+ * Approach:
+ *   1. Run a 16ms interval timer (one frame budget at ~60fps)
+ *   2. Measure actual elapsed time vs expected
+ *   3. If drift > threshold → record a stall event
+ *   4. Accumulate aggregated summary for periodic reporting
+ */
+
+import type { PerformanceConfig } from '../config';
+import type { JsStallEvent, JsStallSummary, Severity, PerfContext } from '../models';
+import { PERF_SCHEMA_VERSION } from '../models';
+
+export type StallEventCallback = (event: JsStallEvent) => void;
+export type StallSummaryCallback = (summary: JsStallSummary & { timestamp: number }) => void;
+
+const MAX_STALL_RECORDS = 100;
+
+export class JsStallCollector {
+    private config: PerformanceConfig;
+    private onStall: StallEventCallback;
+    private onSummary: StallSummaryCallback;
+    private contextProvider: () => PerfContext;
+
+    private pollTimer: ReturnType<typeof setInterval> | null = null;
+    private reportTimer: ReturnType<typeof setInterval> | null = null;
+    private lastTick = 0;
+    private running = false;
+
+    // Rolling aggregation state
+    private stallCount = 0;
+    private maxStallMs = 0;
+    private totalStallMs = 0;
+    private recentStalls: Array<{ timestamp: number; durationMs: number }> = [];
+    /** Per-run caps on INDIVIDUAL stall events — see the emit site. Summaries are uncapped. */
+    private static readonly EMITTED_STALLS_MAX = 200;
+    private static readonly CRITICAL_OVERFLOW_MAX = 100;
+    private emittedStalls = 0;
+    private emittedCriticalOverflow = 0;
+
+    constructor(
+        config: PerformanceConfig,
+        onStall: StallEventCallback,
+        onSummary: StallSummaryCallback,
+        contextProvider: () => PerfContext,
+    ) {
+        this.config = config;
+        this.onStall = onStall;
+        this.onSummary = onSummary;
+        this.contextProvider = contextProvider;
+    }
+
+    start(): void {
+        if (this.running || !this.config.jsStalls) return;
+        this.running = true;
+        this.lastTick = Date.now();
+
+        // Wall-clock checkpoint for detecting stalls that setInterval drift may miss
+        // In Hermes, queued setInterval callbacks may fire with minimal inter-callback gaps
+        // after a sync block, making per-callback drift tiny even though a real stall occurred.
+        // This checkpoint tracks the "last known live" time to catch the full block duration.
+        let wallCheckpoint = Date.now();
+
+        this.pollTimer = setInterval(() => {
+            try {
+                const now = Date.now();
+                const elapsed = now - this.lastTick;
+                const drift = elapsed - this.config.stallIntervalMs;
+
+                // Primary detection: standard drift check
+                if (drift > this.config.stallThresholdMs) {
+                    this._recordStall(now, drift);
+                }
+
+                // Secondary detection: wall-clock gap check
+                // If wallCheckpoint was set long ago, a sync block happened
+                const wallGap = now - wallCheckpoint;
+                if (wallGap > this.config.stallThresholdMs + this.config.stallIntervalMs * 2
+                    && drift <= this.config.stallThresholdMs) {
+                    // Wall clock shows a stall that per-callback drift missed
+                    this._recordStall(now, wallGap - this.config.stallIntervalMs);
+                    wallCheckpoint = now; // Reset to avoid double-counting
+                }
+
+                this.lastTick = now;
+                wallCheckpoint = now;
+            } catch {
+                // No-throw — never break the interval
+            }
+        }, this.config.stallIntervalMs);
+
+        this.reportTimer = setInterval(() => {
+            try {
+                this._flushSummary();
+            } catch {
+                // No-throw
+            }
+        }, this.config.reportIntervalMs);
+    }
+
+    stop(): void {
+        this.running = false;
+        if (this.pollTimer) {
+            clearInterval(this.pollTimer);
+            this.pollTimer = null;
+        }
+        if (this.reportTimer) {
+            clearInterval(this.reportTimer);
+            this.reportTimer = null;
+        }
+    }
+
+    private _recordStall(timestamp: number, durationMs: number): void {
+        this.stallCount++;
+        this.totalStallMs += durationMs;
+        if (durationMs > this.maxStallMs) this.maxStallMs = durationMs;
+
+        // Bounded memory: keep only last N stalls
+        this.recentStalls.push({ timestamp, durationMs });
+        if (this.recentStalls.length > MAX_STALL_RECORDS) {
+            this.recentStalls = this.recentStalls.slice(-MAX_STALL_RECORDS / 2);
+        }
+
+        // Emit individual stall events for severe stalls (>100ms) — per-run capped.
+        //
+        // On a chronically janky device this fired per stall for the whole session: hours of the
+        // same diagnosis, thousands of rows, and the session's perf tab pinned at its display cap.
+        // The first EMITTED_STALLS_MAX stalls carry the individual detail; after that only
+        // criticals (>500 ms) still emit, themselves capped, and everything keeps counting into
+        // the periodic summary (stallCount/maxStallMs/totalStallMs) so no stall goes unmeasured —
+        // only the thousandth copy of the same story goes unshipped.
+        if (durationMs > 100) {
+            const severity = this._classifySeverity(durationMs);
+            if (this.emittedStalls >= JsStallCollector.EMITTED_STALLS_MAX) {
+                if (severity !== 'critical') return;
+                if (this.emittedCriticalOverflow >= JsStallCollector.CRITICAL_OVERFLOW_MAX) return;
+                this.emittedCriticalOverflow++;
+            } else {
+                this.emittedStalls++;
+            }
+            const event: JsStallEvent = {
+                id: `stall-${timestamp}-${Math.random().toString(36).substring(2, 8)}`,
+                type: 'js_stall',
+                timestamp,
+                schemaVersion: PERF_SCHEMA_VERSION,
+                context: this.contextProvider(),
+                durationMs,
+                severity,
+            };
+            this.onStall(event);
+        }
+    }
+
+    private _classifySeverity(durationMs: number): Severity {
+        if (durationMs > 500) return 'critical';
+        if (durationMs > 200) return 'warning';
+        return 'info';
+    }
+
+    private _flushSummary(): void {
+        const summary: JsStallSummary & { timestamp: number } = {
+            timestamp: Date.now(),
+            stallCount: this.stallCount,
+            maxStallMs: this.maxStallMs,
+            totalStallMs: this.totalStallMs,
+            avgStallMs: this.stallCount > 0
+                ? Math.round(this.totalStallMs / this.stallCount)
+                : 0,
+        };
+
+        this.onSummary(summary);
+
+        // Reset for next period
+        this.stallCount = 0;
+        this.maxStallMs = 0;
+        this.totalStallMs = 0;
+        this.recentStalls = [];
+    }
+}

package/src/features/performance/collectors/NetworkPerfCollector.ts

@@ -0,0 +1,69 @@
+/**
+ * ScaleBun SDK — Network Performance Collector
+ *
+ * Taps into existing network events (from NetworkFeature) and extracts
+ * performance-relevant signals: slow requests, failed requests, latency.
+ * Does NOT duplicate network capture — reuses the existing pipeline.
+ */
+
+import type { NetworkPerfEvent, PerfContext } from '../models';
+import { PERF_SCHEMA_VERSION } from '../models';
+import type { PerformanceConfig } from '../config';
+
+export type NetworkPerfCallback = (event: NetworkPerfEvent) => void;
+
+export class NetworkPerfCollector {
+    private config: PerformanceConfig;
+    private onNetworkPerf: NetworkPerfCallback;
+    private contextProvider: () => PerfContext;
+
+    constructor(
+        config: PerformanceConfig,
+        onNetworkPerf: NetworkPerfCallback,
+        contextProvider: () => PerfContext,
+    ) {
+        this.config = config;
+        this.onNetworkPerf = onNetworkPerf;
+        this.contextProvider = contextProvider;
+    }
+
+    /**
+     * Process a network request completion event.
+     * Called by PerformanceFeature when a $network_request event arrives.
+     * Only emits a performance event for requests that are slow or failed.
+     */
+    processNetworkEvent(data: Record<string, unknown>): void {
+        if (!this.config.networkPerf) return;
+
+        const url = data.url as string;
+        const method = (data.method as string) || 'GET';
+        const status = (data.status as number) || 0;
+        const duration = (data.duration as number) || 0;
+        const error = data.error as string | undefined;
+        const responseSize = data.responseSize as number | undefined;
+
+        if (!url) return;
+
+        const failed = !!error || status >= 500 || status === 0;
+        const isSlow = duration > this.config.slowRequestThresholdMs;
+
+        // Only emit performance events for notable requests
+        if (!failed && !isSlow) return;
+
+        const event: NetworkPerfEvent = {
+            id: `netperf-${Date.now()}-${Math.random().toString(36).substring(2, 8)}`,
+            type: 'network_perf',
+            timestamp: Date.now(),
+            schemaVersion: PERF_SCHEMA_VERSION,
+            context: this.contextProvider(),
+            url,
+            method,
+            statusCode: status || undefined,
+            durationMs: duration,
+            failed,
+            responseSize,
+        };
+
+        this.onNetworkPerf(event);
+    }
+}

package/src/features/performance/collectors/ScreenLoadCollector.ts

@@ -0,0 +1,95 @@
+/**
+ * ScaleBun SDK — Screen Load Collector
+ *
+ * Tracks screen transition timing using a start/end marker pattern.
+ * Integrates with the existing ScaleBunScreen/useScaleBunScreen navigation system.
+ */
+
+import type { ScreenLoadEvent, PerfContext } from '../models';
+import { PERF_SCHEMA_VERSION } from '../models';
+import type { PerformanceConfig } from '../config';
+
+export type ScreenLoadCallback = (event: ScreenLoadEvent) => void;
+
+interface PendingScreenLoad {
+    screenName: string;
+    startMs: number;
+    previousScreen?: string;
+}
+
+const MAX_PENDING = 20;
+
+export class ScreenLoadCollector {
+    private config: PerformanceConfig;
+    private onScreenLoad: ScreenLoadCallback;
+    private contextProvider: () => PerfContext;
+    private pending: Map<string, PendingScreenLoad> = new Map();
+    private lastScreen: string | null = null;
+
+    constructor(
+        config: PerformanceConfig,
+        onScreenLoad: ScreenLoadCallback,
+        contextProvider: () => PerfContext,
+    ) {
+        this.config = config;
+        this.onScreenLoad = onScreenLoad;
+        this.contextProvider = contextProvider;
+    }
+
+    /**
+     * Mark the start of a screen load.
+     * Called when navigation to a new screen begins.
+     */
+    markStart(screenName: string): void {
+        if (!this.config.screenLoad) return;
+
+        // Bounded: evict oldest if too many pending
+        if (this.pending.size >= MAX_PENDING) {
+            const oldest = this.pending.keys().next().value;
+            if (oldest) this.pending.delete(oldest);
+        }
+
+        this.pending.set(screenName, {
+            screenName,
+            startMs: Date.now(),
+            previousScreen: this.lastScreen ?? undefined,
+        });
+    }
+
+    /**
+     * Mark the end of a screen load.
+     * Called when the screen is rendered and interactive.
+     */
+    markEnd(screenName: string): void {
+        if (!this.config.screenLoad) return;
+
+        const start = this.pending.get(screenName);
+        if (!start) return;
+
+        this.pending.delete(screenName);
+        const durationMs = Date.now() - start.startMs;
+        this.lastScreen = screenName;
+
+        const event: ScreenLoadEvent = {
+            id: `screen-${Date.now()}-${Math.random().toString(36).substring(2, 8)}`,
+            type: 'screen_load',
+            timestamp: Date.now(),
+            schemaVersion: PERF_SCHEMA_VERSION,
+            context: {
+                ...this.contextProvider(),
+                screenKey: screenName,
+            },
+            screenName,
+            durationMs,
+            previousScreen: start.previousScreen,
+        };
+
+        this.onScreenLoad(event);
+    }
+
+    /** Clear all pending loads (e.g., on teardown) */
+    reset(): void {
+        this.pending.clear();
+        this.lastScreen = null;
+    }
+}

package/src/features/performance/collectors/UiHangCollector.ts

@@ -0,0 +1,98 @@
+/**
+ * ScaleBun SDK — UI Hang Collector
+ *
+ * Receives native UI hang detection events from the platform bridge.
+ * Android uses a background watchdog thread; iOS uses a main thread ping.
+ */
+
+import { NativeEventEmitter } from 'react-native';
+import { getNativePerformanceModule } from '../getNativePerformanceModule';
+import type { UiHangEvent, PerfContext, Severity } from '../models';
+import { PERF_SCHEMA_VERSION } from '../models';
+import type { PerformanceConfig } from '../config';
+
+export type UiHangCallback = (event: UiHangEvent) => void;
+
+export class UiHangCollector {
+    private config: PerformanceConfig;
+    private onHang: UiHangCallback;
+    private contextProvider: () => PerfContext;
+    private eventSubscription: any = null;
+    private running = false;
+
+    constructor(
+        config: PerformanceConfig,
+        onHang: UiHangCallback,
+        contextProvider: () => PerfContext,
+    ) {
+        this.config = config;
+        this.onHang = onHang;
+        this.contextProvider = contextProvider;
+    }
+
+    start(): void {
+        if (this.running || !this.config.uiHangs) return;
+        this.running = true;
+
+        try {
+            const perfModule = getNativePerformanceModule();
+            if (!perfModule) return;
+
+            const emitter = new NativeEventEmitter(perfModule);
+            this.eventSubscription = emitter.addListener(
+                'ScaleBunPerformance_UiHang',
+                (data: any) => {
+                    try {
+                        this._handleNativeHang(data);
+                    } catch {
+                        // No-throw
+                    }
+                },
+            );
+
+            if (typeof perfModule.startHangDetection === 'function') {
+                perfModule.startHangDetection(this.config.hangThresholdMs);
+            }
+        } catch {
+            // Native module not available
+        }
+    }
+
+    stop(): void {
+        this.running = false;
+        if (this.eventSubscription) {
+            this.eventSubscription.remove();
+            this.eventSubscription = null;
+        }
+
+        try {
+            const perfModule = getNativePerformanceModule();
+            if (typeof perfModule?.stopHangDetection === 'function') {
+                perfModule.stopHangDetection();
+            }
+        } catch {
+            // No-throw
+        }
+    }
+
+    private _handleNativeHang(data: any): void {
+        if (!data || typeof data.durationMs !== 'number') return;
+
+        const durationMs = data.durationMs;
+        const severity: Severity = durationMs > 5000 ? 'critical'
+            : durationMs > this.config.hangThresholdMs ? 'warning'
+                : 'info';
+
+        const event: UiHangEvent = {
+            id: `hang-${Date.now()}-${Math.random().toString(36).substring(2, 8)}`,
+            type: 'ui_hang',
+            timestamp: Date.now(),
+            schemaVersion: PERF_SCHEMA_VERSION,
+            context: this.contextProvider(),
+            durationMs,
+            severity,
+        };
+
+        this.onHang(event);
+    }
+}