@scalebun-release/react-native 2.5.0

package/src/features/performance/config.ts

@@ -0,0 +1,136 @@
+/**
+ * ScaleBun SDK — Performance Config
+ *
+ * Performance-specific configuration with sensible defaults.
+ * All thresholds are tuned for development debugging first,
+ * with hooks for production configuration later.
+ */
+
+// ─── Config Interface ───────────────────────────────────────────────────────
+
+export interface PerformanceConfig {
+    /** Enable/disable performance monitoring entirely. Default: true */
+    enabled: boolean;
+
+    // ─── JS Stall Detection ─────────────────────────────────────────────
+    /** Enable JS event-loop stall detection. Default: true */
+    jsStalls: boolean;
+    /** Stall threshold in ms (drift above this = stall). Default: 32 (2 frames) */
+    stallThresholdMs: number;
+    /** Stall sampling interval in ms. Default: 16 (~60fps frame budget) */
+    stallIntervalMs: number;
+
+    // ─── Frame Metrics ──────────────────────────────────────────────────
+    /** Enable native frame metrics collection. Default: true */
+    frameMetrics: boolean;
+    /** Slow frame threshold in ms. Default: 16.67 (below 60fps) */
+    slowFrameThresholdMs: number;
+    /** Frozen frame threshold in ms. Default: 700 */
+    frozenFrameThresholdMs: number;
+
+    // ─── App Launch ─────────────────────────────────────────────────────
+    /** Enable app launch timing. Default: true */
+    appLaunch: boolean;
+
+    // ─── Screen Load ────────────────────────────────────────────────────
+    /** Enable screen load timing. Default: true */
+    screenLoad: boolean;
+
+    // ─── UI Hang Detection (Tier-1 watchdog) ────────────────────────────
+    /**
+     * Enable native UI hang / ANR watchdog. Tier-1, emits only on a real hang.
+     * Default: true — additive (fires only on a real hang); forward-only since it
+     * needs the native module, so stale prebuilt binaries no-op until rebuilt.
+     * Disable via config (`performance.tier1.uiHang`) — no SDK release required.
+     */
+    uiHangs: boolean;
+    /** UI hang threshold in ms. Default: 2000 */
+    hangThresholdMs: number;
+
+    // ─── Tier-2 Sampled Collection (frame_metrics + js_stall) ───────────
+    /**
+     * Master enable for the Tier-2 (heavy, continuous) collectors.
+     * Even when true, a session only runs them if it passes tier2SampleRate.
+     * Default: true (gated by sampleRate below).
+     */
+    tier2Enabled: boolean;
+    /**
+     * Per-session sampling fraction (0..1) for Tier-2 collectors.
+     * Decision is deterministic per sessionId (same session never flips).
+     * Default: DEFAULT_TIER2_SAMPLE_RATE (10%) — conservative sample that keeps
+     * ingest ~1/10th of full-rate. Set 0 to disable via `performance.tier2.sampleRate`.
+     */
+    tier2SampleRate: number;
+
+    // ─── Network Performance ────────────────────────────────────────────
+    /** Enable network performance tracking. Default: true */
+    networkPerf: boolean;
+    /** Slow request threshold in ms. Default: 3000 */
+    slowRequestThresholdMs: number;
+
+    // ─── Custom Traces ──────────────────────────────────────────────────
+    /** Enable custom trace API. Default: true */
+    customTraces: boolean;
+    /** Maximum concurrent custom traces. Default: 20 */
+    maxConcurrentTraces: number;
+
+    // ─── Reporting ──────────────────────────────────────────────────────
+    /** How often to report aggregate metrics in ms. Default: 5000 */
+    reportIntervalMs: number;
+    /** Maximum buffered events before flush. Default: 200 */
+    maxBufferSize: number;
+
+    // ─── Safety ─────────────────────────────────────────────────────────
+    /** Sample rate (0.0 to 1.0). Default: 1.0 (collect everything in dev) */
+    sampleRate: number;
+}
+
+// ─── Defaults ───────────────────────────────────────────────────────────────
+
+/**
+ * Safe non-zero default for Tier-2 (frame_metrics + js_stall) per-session
+ * sampling. 0.1 = 10% of sessions run the heavy collectors — enough to surface
+ * FPS/jank/stall trends while keeping ingest volume ~1/10th of full-rate.
+ * Host-overridable via `performance.tier2.sampleRate` (set 0 to disable).
+ */
+export const DEFAULT_TIER2_SAMPLE_RATE = 0.1;
+
+export const DEFAULT_PERF_CONFIG: PerformanceConfig = {
+    enabled: true,
+
+    jsStalls: true,
+    stallThresholdMs: 32,
+    stallIntervalMs: 16,
+
+    frameMetrics: true,
+    slowFrameThresholdMs: 16.67,
+    frozenFrameThresholdMs: 700,
+
+    appLaunch: true,
+    screenLoad: true,
+
+    uiHangs: true,
+    hangThresholdMs: 2000,
+
+    tier2Enabled: true,
+    tier2SampleRate: DEFAULT_TIER2_SAMPLE_RATE,
+
+    networkPerf: true,
+    slowRequestThresholdMs: 3000,
+
+    customTraces: true,
+    maxConcurrentTraces: 20,
+
+    reportIntervalMs: 5000,
+    maxBufferSize: 200,
+
+    sampleRate: 1.0,
+};
+
+// ─── Merge helper ───────────────────────────────────────────────────────────
+
+export function mergePerformanceConfig(
+    partial?: Partial<PerformanceConfig>,
+): PerformanceConfig {
+    return { ...DEFAULT_PERF_CONFIG, ...partial };
+}

package/src/features/performance/getNativePerformanceModule.ts

@@ -0,0 +1,38 @@
+import { NativeModules } from 'react-native';
+
+import { nativeModuleVia } from '../../core/architecture';
+
+/**
+ * Resolve the native `ScaleBunPerformance` module.
+ *
+ * Prefers the codegen TurboModule on the New Architecture, and falls back to the
+ * legacy `NativeModules` lookup on the Old Architecture, the iOS
+ * `RCTEventEmitter` interop path, or when there is no native build (web/SSR).
+ * Returns `null` when unavailable — callers must null-check.
+ *
+ * The resolution is cached; the native module instance is stable for the app
+ * lifetime. The resolved module is safe to pass to `NativeEventEmitter` (it
+ * exposes `addListener` / `removeListeners`).
+ */
+let cached: { mod: any } | undefined;
+
+export function getNativePerformanceModule(): any {
+  if (cached) return cached.mod;
+
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    const turbo = require('../../specs/NativeScaleBunPerformance').default;
+    if (turbo) {
+      console.log(`[ScaleBun Performance] native module via ${nativeModuleVia()}`);
+      cached = { mod: turbo };
+      return turbo;
+    }
+  } catch {
+    // TurboModuleRegistry unavailable (web/SSR) — fall through.
+  }
+
+  const legacy = NativeModules?.ScaleBunPerformance ?? null;
+  if (legacy) console.log('[ScaleBun Performance] native module via legacy NativeModules');
+  cached = { mod: legacy };
+  return legacy;
+}

package/src/features/performance/index.ts

@@ -0,0 +1,28 @@
+/**
+ * ScaleBun SDK — Performance Feature Public Exports
+ */
+
+export { PerformanceFeature } from './PerformanceFeature';
+export type { PerformanceConfig } from './config';
+export { mergePerformanceConfig, DEFAULT_PERF_CONFIG } from './config';
+export type {
+    PerformanceEvent,
+    AnyPerfEvent,
+    AppLaunchEvent,
+    ScreenLoadEvent,
+    FrameMetricsEvent,
+    JsStallEvent,
+    UiHangEvent,
+    NetworkPerfEvent,
+    CustomTraceEvent,
+    PerformanceSummary,
+    PerfContext,
+    PerfDeviceMeta,
+    PerfSpan,
+    PerfMeasurement,
+    PerfEventType,
+    LaunchType,
+    Severity,
+} from './models';
+export { PERF_SCHEMA_VERSION } from './models';
+export { MetricKeys, computeStats, percentile, MetricWindow } from './metrics/MetricsEngine';

package/src/features/performance/metrics/MetricsEngine.ts

@@ -0,0 +1,152 @@
+/**
+ * ScaleBun SDK — Metrics Engine
+ *
+ * Aggregation, percentile calculation (p50/p95/p99),
+ * and summary generation for performance metrics.
+ */
+
+// ─── Metric Keys ────────────────────────────────────────────────────────────
+
+export const MetricKeys = {
+    // App launch
+    APP_LAUNCH_COLD: 'perf.app_launch.cold',
+    APP_LAUNCH_WARM: 'perf.app_launch.warm',
+
+    // Frame smoothness — NATIVE (from FrameMetrics API / CADisplayLink)
+    FPS_ESTIMATED: 'perf.fps.estimated',
+    FRAMES_TOTAL: 'perf.frames.total',
+    FRAMES_DROPPED: 'perf.frames.dropped',
+    FRAMES_SLOW: 'perf.frames.slow',
+    FRAMES_FROZEN: 'perf.frames.frozen',
+    FRAME_DROP_RATE: 'perf.frames.drop_rate',
+
+    // Frame smoothness — JS-DERIVED (synthetic from JsStallCollector)
+    // Separated from native FPS to avoid ambiguous data mixing.
+    // Old SDKs still emit under FPS_ESTIMATED — desktop handles this via
+    // source tagging and backward-compat normalization.
+    JS_ESTIMATED_FPS: 'perf.js.estimated_fps',
+    JS_FRAMES_DROPPED: 'perf.js.frames_dropped',
+
+    // JS stalls
+    JS_STALL_COUNT: 'perf.js.stall_count',
+    JS_STALL_MAX: 'perf.js.stall_max',
+    JS_STALL_TOTAL: 'perf.js.stall_total',
+    JS_STALL_AVG: 'perf.js.stall_avg',
+
+    // UI Hangs
+    UI_HANG_COUNT: 'perf.ui.hang_count',
+    UI_HANG_MAX: 'perf.ui.hang_max',
+
+    // Screen load
+    SCREEN_LOAD: 'perf.screen.load',
+
+    // Network
+    NETWORK_SLOW_COUNT: 'perf.network.slow_count',
+    NETWORK_FAIL_COUNT: 'perf.network.fail_count',
+
+    // Custom traces
+    CUSTOM_TRACE: 'perf.trace',
+} as const;
+
+// ─── Percentile Calculator ──────────────────────────────────────────────────
+
+/**
+ * Calculate a percentile value from a sorted array of numbers.
+ * Uses nearest-rank method.
+ */
+export function percentile(sorted: number[], p: number): number {
+    if (sorted.length === 0) return 0;
+    if (p <= 0) return sorted[0];
+    if (p >= 100) return sorted[sorted.length - 1];
+
+    const rank = Math.ceil((p / 100) * sorted.length) - 1;
+    return sorted[Math.max(0, rank)];
+}
+
+/**
+ * Calculate p50, p95, p99, avg, min, max from an array of values.
+ */
+export function computeStats(values: number[]): MetricStats {
+    if (values.length === 0) {
+        return { count: 0, avg: 0, min: 0, max: 0, p50: 0, p95: 0, p99: 0, sum: 0 };
+    }
+
+    const sorted = [...values].sort((a, b) => a - b);
+    const sum = sorted.reduce((a, b) => a + b, 0);
+
+    return {
+        count: sorted.length,
+        avg: Math.round(sum / sorted.length),
+        min: sorted[0],
+        max: sorted[sorted.length - 1],
+        p50: percentile(sorted, 50),
+        p95: percentile(sorted, 95),
+        p99: percentile(sorted, 99),
+        sum,
+    };
+}
+
+export interface MetricStats {
+    count: number;
+    avg: number;
+    min: number;
+    max: number;
+    p50: number;
+    p95: number;
+    p99: number;
+    sum: number;
+}
+
+// ─── Rolling Metric Window ──────────────────────────────────────────────────
+
+const MAX_WINDOW_SIZE = 500;
+
+/**
+ * Bounded rolling window for metric values.
+ * Supports time-based and count-based bounding.
+ */
+export class MetricWindow {
+    private values: Array<{ ts: number; value: number }> = [];
+    private maxSize: number;
+
+    constructor(maxSize = MAX_WINDOW_SIZE) {
+        this.maxSize = maxSize;
+    }
+
+    add(value: number, timestamp = Date.now()): void {
+        this.values.push({ ts: timestamp, value });
+        if (this.values.length > this.maxSize) {
+            this.values = this.values.slice(-Math.floor(this.maxSize / 2));
+        }
+    }
+
+    /** Get all values */
+    getAll(): number[] {
+        return this.values.map(v => v.value);
+    }
+
+    /** Get values within a time range */
+    getSince(sinceMs: number): number[] {
+        const cutoff = Date.now() - sinceMs;
+        return this.values.filter(v => v.ts >= cutoff).map(v => v.value);
+    }
+
+    /** Get stats for all values */
+    stats(): MetricStats {
+        return computeStats(this.getAll());
+    }
+
+    /** Get stats for a time range */
+    statsSince(sinceMs: number): MetricStats {
+        return computeStats(this.getSince(sinceMs));
+    }
+
+    /** Number of values stored */
+    get size(): number {
+        return this.values.length;
+    }
+
+    clear(): void {
+        this.values = [];
+    }
+}

package/src/features/performance/models.ts

@@ -0,0 +1,235 @@
+/**
+ * ScaleBun SDK — Performance Models
+ *
+ * Strong-typed domain models for all performance signals.
+ * Every model includes session/trace/screen/device context
+ * for cross-feature correlation.
+ *
+ * Schema version: 1
+ */
+
+// ─── Schema ─────────────────────────────────────────────────────────────────
+
+export const PERF_SCHEMA_VERSION = 1;
+
+// ─── Enums ──────────────────────────────────────────────────────────────────
+
+export type PerfEventType =
+    | 'app_launch'
+    | 'screen_load'
+    | 'frame_metrics'
+    | 'js_stall'
+    | 'ui_hang'
+    | 'network_perf'
+    | 'custom_trace'
+    | 'perf_summary';
+
+export type LaunchType = 'cold' | 'warm' | 'hot';
+
+export type Severity = 'info' | 'warning' | 'critical';
+
+export type FrameQuality = 'normal' | 'slow' | 'frozen';
+
+// ─── Base Context ───────────────────────────────────────────────────────────
+
+/** Context attached to every performance event for cross-feature correlation */
+export interface PerfContext {
+    sessionId: string;
+    traceId?: string;
+    screenKey?: string;
+    interactionId?: string;
+    /** Device/app/os metadata snapshot */
+    device?: PerfDeviceMeta;
+}
+
+export interface PerfDeviceMeta {
+    platform?: 'android' | 'ios';
+    osVersion?: string;
+    deviceModel?: string;
+    appVersion?: string;
+    buildType?: 'debug' | 'release';
+    bundleId?: string;
+    sdkVersion?: string;
+}
+
+// ─── Base Performance Event ─────────────────────────────────────────────────
+
+export interface PerformanceEvent {
+    id: string;
+    type: PerfEventType;
+    timestamp: number;
+    /** Monotonic clock timestamp for drift-free duration measurement */
+    monotonicMs?: number;
+    schemaVersion: number;
+    context: PerfContext;
+}
+
+// ─── App Launch ─────────────────────────────────────────────────────────────
+
+export interface AppLaunchEvent extends PerformanceEvent {
+    type: 'app_launch';
+    launchType: LaunchType;
+    durationMs: number;
+    /** Breakdown of launch phases (optional — depends on native granularity) */
+    breakdown?: {
+        processStartMs?: number;
+        nativeInitMs?: number;
+        contentProviderMs?: number;
+        activityCreateMs?: number;
+        firstFrameMs?: number;
+        jsReadyMs?: number;
+        firstScreenMs?: number;
+    };
+    /**
+     * Labels each breakdown phase as 'measured' or 'inferred'.
+     * Only phases present in `breakdown` should have entries.
+     */
+    phaseLabels?: Record<string, 'measured' | 'inferred'>;
+}
+
+// ─── Screen Load ────────────────────────────────────────────────────────────
+
+export interface ScreenLoadEvent extends PerformanceEvent {
+    type: 'screen_load';
+    screenName: string;
+    durationMs: number;
+    /** Previous screen (for transition measurement) */
+    previousScreen?: string;
+    /** Whether this load was captured automatically vs manual markers */
+    automatic?: boolean;
+}
+
+// ─── Frame Metrics ──────────────────────────────────────────────────────────
+
+export interface FrameMetricsEvent extends PerformanceEvent {
+    type: 'frame_metrics';
+    /** Window duration these metrics cover */
+    windowMs: number;
+    totalFrames: number;
+    droppedFrames: number;
+    slowFrames: number;
+    frozenFrames: number;
+    estimatedFps: number;
+    /** Worst single frame render time in this window */
+    maxFrameTimeMs: number;
+}
+
+// ─── JS Stall ───────────────────────────────────────────────────────────────
+
+export interface JsStallEvent extends PerformanceEvent {
+    type: 'js_stall';
+    /** Duration of this individual stall */
+    durationMs: number;
+    severity: Severity;
+}
+
+/** Aggregated JS stall summary for a reporting period */
+export interface JsStallSummary {
+    stallCount: number;
+    maxStallMs: number;
+    totalStallMs: number;
+    avgStallMs: number;
+}
+
+// ─── UI Hang / ANR ──────────────────────────────────────────────────────────
+
+export interface UiHangEvent extends PerformanceEvent {
+    type: 'ui_hang';
+    durationMs: number;
+    severity: Severity;
+}
+
+// ─── Network Performance ────────────────────────────────────────────────────
+
+export interface NetworkPerfEvent extends PerformanceEvent {
+    type: 'network_perf';
+    url: string;
+    method: string;
+    statusCode?: number;
+    durationMs: number;
+    /** Whether request is considered failed */
+    failed: boolean;
+    /** Byte size of response if available */
+    responseSize?: number;
+}
+
+// ─── Custom Trace ───────────────────────────────────────────────────────────
+
+export interface CustomTraceEvent extends PerformanceEvent {
+    type: 'custom_trace';
+    name: string;
+    durationMs: number;
+    spans?: PerfSpan[];
+    measurements?: Record<string, PerfMeasurement>;
+}
+
+export interface PerfSpan {
+    spanId: string;
+    name: string;
+    startMs: number;
+    endMs?: number;
+    durationMs?: number;
+    status?: 'ok' | 'error' | 'cancelled';
+    data?: Record<string, unknown>;
+}
+
+export interface PerfMeasurement {
+    value: number;
+    unit: string;
+}
+
+// ─── Summary / Aggregations ─────────────────────────────────────────────────
+
+export interface PerformanceSummary {
+    sessionId: string;
+    timestamp: number;
+    schemaVersion: number;
+
+    /** App launch timing */
+    launch?: {
+        type: LaunchType;
+        durationMs: number;
+    };
+
+    /** Frame quality summary */
+    frames?: {
+        avgFps: number;
+        totalFrames: number;
+        droppedFrames: number;
+        slowFrames: number;
+        frozenFrames: number;
+        dropRate: number;
+    };
+
+    /** JS stall summary */
+    jsStalls?: JsStallSummary;
+
+    /** UI hang summary */
+    uiHangs?: {
+        hangCount: number;
+        maxHangMs: number;
+        totalHangMs: number;
+    };
+
+    /** Screen load summary */
+    screenLoads?: Array<{
+        screenName: string;
+        avgMs: number;
+        p95Ms: number;
+        count: number;
+    }>;
+
+    /** Slow network requests */
+    slowNetworkRequests?: number;
+}
+
+// ─── Union ──────────────────────────────────────────────────────────────────
+
+export type AnyPerfEvent =
+    | AppLaunchEvent
+    | ScreenLoadEvent
+    | FrameMetricsEvent
+    | JsStallEvent
+    | UiHangEvent
+    | NetworkPerfEvent
+    | CustomTraceEvent;