@scalebun-release/react-native 2.5.0

package/lib/module/features/performance/collectors/JsStallCollector.js

@@ -0,0 +1,158 @@
+/**
+ * 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 { PERF_SCHEMA_VERSION } from '../models';
+const MAX_STALL_RECORDS = 100;
+export class JsStallCollector {
+  pollTimer = null;
+  reportTimer = null;
+  lastTick = 0;
+  running = false;
+
+  // Rolling aggregation state
+  stallCount = 0;
+  maxStallMs = 0;
+  totalStallMs = 0;
+  recentStalls = [];
+  /** Per-run caps on INDIVIDUAL stall events — see the emit site. Summaries are uncapped. */
+  static EMITTED_STALLS_MAX = 200;
+  static CRITICAL_OVERFLOW_MAX = 100;
+  emittedStalls = 0;
+  emittedCriticalOverflow = 0;
+  constructor(config, onStall, onSummary, contextProvider) {
+    this.config = config;
+    this.onStall = onStall;
+    this.onSummary = onSummary;
+    this.contextProvider = contextProvider;
+  }
+  start() {
+    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() {
+    this.running = false;
+    if (this.pollTimer) {
+      clearInterval(this.pollTimer);
+      this.pollTimer = null;
+    }
+    if (this.reportTimer) {
+      clearInterval(this.reportTimer);
+      this.reportTimer = null;
+    }
+  }
+  _recordStall(timestamp, durationMs) {
+    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 = {
+        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);
+    }
+  }
+  _classifySeverity(durationMs) {
+    if (durationMs > 500) return 'critical';
+    if (durationMs > 200) return 'warning';
+    return 'info';
+  }
+  _flushSummary() {
+    const summary = {
+      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 = [];
+  }
+}
+//# sourceMappingURL=JsStallCollector.js.map

package/lib/module/features/performance/collectors/NetworkPerfCollector.js

@@ -0,0 +1,52 @@
+/**
+ * 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 { PERF_SCHEMA_VERSION } from '../models';
+export class NetworkPerfCollector {
+  constructor(config, onNetworkPerf, contextProvider) {
+    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) {
+    if (!this.config.networkPerf) return;
+    const url = data.url;
+    const method = data.method || 'GET';
+    const status = data.status || 0;
+    const duration = data.duration || 0;
+    const error = data.error;
+    const responseSize = data.responseSize;
+    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 = {
+      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);
+  }
+}
+//# sourceMappingURL=NetworkPerfCollector.js.map

package/lib/module/features/performance/collectors/ScreenLoadCollector.js

@@ -0,0 +1,71 @@
+/**
+ * ScaleBun SDK — Screen Load Collector
+ *
+ * Tracks screen transition timing using a start/end marker pattern.
+ * Integrates with the existing ScaleBunScreen/useScaleBunScreen navigation system.
+ */
+
+import { PERF_SCHEMA_VERSION } from '../models';
+const MAX_PENDING = 20;
+export class ScreenLoadCollector {
+  pending = new Map();
+  lastScreen = null;
+  constructor(config, onScreenLoad, contextProvider) {
+    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) {
+    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) {
+    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 = {
+      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() {
+    this.pending.clear();
+    this.lastScreen = null;
+  }
+}
+//# sourceMappingURL=ScreenLoadCollector.js.map

package/lib/module/features/performance/collectors/UiHangCollector.js

@@ -0,0 +1,71 @@
+/**
+ * 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 { PERF_SCHEMA_VERSION } from '../models';
+export class UiHangCollector {
+  eventSubscription = null;
+  running = false;
+  constructor(config, onHang, contextProvider) {
+    this.config = config;
+    this.onHang = onHang;
+    this.contextProvider = contextProvider;
+  }
+  start() {
+    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 => {
+        try {
+          this._handleNativeHang(data);
+        } catch {
+          // No-throw
+        }
+      });
+      if (typeof perfModule.startHangDetection === 'function') {
+        perfModule.startHangDetection(this.config.hangThresholdMs);
+      }
+    } catch {
+      // Native module not available
+    }
+  }
+  stop() {
+    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
+    }
+  }
+  _handleNativeHang(data) {
+    if (!data || typeof data.durationMs !== 'number') return;
+    const durationMs = data.durationMs;
+    const severity = durationMs > 5000 ? 'critical' : durationMs > this.config.hangThresholdMs ? 'warning' : 'info';
+    const event = {
+      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);
+  }
+}
+//# sourceMappingURL=UiHangCollector.js.map

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

@@ -0,0 +1,51 @@
+/**
+ * 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 ───────────────────────────────────────────────────────
+
+// ─── 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 = {
+  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) {
+  return {
+    ...DEFAULT_PERF_CONFIG,
+    ...partial
+  };
+}
+//# sourceMappingURL=config.js.map

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

@@ -0,0 +1,39 @@
+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;
+export function getNativePerformanceModule() {
+  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;
+}
+//# sourceMappingURL=getNativePerformanceModule.js.map

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

@@ -0,0 +1,9 @@
+/**
+ * ScaleBun SDK — Performance Feature Public Exports
+ */
+
+export { PerformanceFeature } from './PerformanceFeature';
+export { mergePerformanceConfig, DEFAULT_PERF_CONFIG } from './config';
+export { PERF_SCHEMA_VERSION } from './models';
+export { MetricKeys, computeStats, percentile, MetricWindow } from './metrics/MetricsEngine';
+//# sourceMappingURL=index.js.map

package/lib/module/features/performance/metrics/MetricsEngine.js

@@ -0,0 +1,139 @@
+/**
+ * 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'
+};
+
+// ─── Percentile Calculator ──────────────────────────────────────────────────
+
+/**
+ * Calculate a percentile value from a sorted array of numbers.
+ * Uses nearest-rank method.
+ */
+export function percentile(sorted, p) {
+  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) {
+  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
+  };
+}
+// ─── Rolling Metric Window ──────────────────────────────────────────────────
+
+const MAX_WINDOW_SIZE = 500;
+
+/**
+ * Bounded rolling window for metric values.
+ * Supports time-based and count-based bounding.
+ */
+export class MetricWindow {
+  values = [];
+  constructor(maxSize = MAX_WINDOW_SIZE) {
+    this.maxSize = maxSize;
+  }
+  add(value, timestamp = Date.now()) {
+    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() {
+    return this.values.map(v => v.value);
+  }
+
+  /** Get values within a time range */
+  getSince(sinceMs) {
+    const cutoff = Date.now() - sinceMs;
+    return this.values.filter(v => v.ts >= cutoff).map(v => v.value);
+  }
+
+  /** Get stats for all values */
+  stats() {
+    return computeStats(this.getAll());
+  }
+
+  /** Get stats for a time range */
+  statsSince(sinceMs) {
+    return computeStats(this.getSince(sinceMs));
+  }
+
+  /** Number of values stored */
+  get size() {
+    return this.values.length;
+  }
+  clear() {
+    this.values = [];
+  }
+}
+//# sourceMappingURL=MetricsEngine.js.map

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

@@ -0,0 +1,42 @@
+/**
+ * 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 ──────────────────────────────────────────────────────────────────
+
+// ─── Base Context ───────────────────────────────────────────────────────────
+
+/** Context attached to every performance event for cross-feature correlation */
+
+// ─── Base Performance Event ─────────────────────────────────────────────────
+
+// ─── App Launch ─────────────────────────────────────────────────────────────
+
+// ─── Screen Load ────────────────────────────────────────────────────────────
+
+// ─── Frame Metrics ──────────────────────────────────────────────────────────
+
+// ─── JS Stall ───────────────────────────────────────────────────────────────
+
+/** Aggregated JS stall summary for a reporting period */
+
+// ─── UI Hang / ANR ──────────────────────────────────────────────────────────
+
+// ─── Network Performance ────────────────────────────────────────────────────
+
+// ─── Custom Trace ───────────────────────────────────────────────────────────
+
+// ─── Summary / Aggregations ─────────────────────────────────────────────────
+
+// ─── Union ──────────────────────────────────────────────────────────────────
+//# sourceMappingURL=models.js.map