@scalebun/react-native 1.0.0 → 1.0.2

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

@@ -1,98 +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);
-    }
-}
+/**
+ * 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);
+    }
+}

package/src/features/performance/config.ts

@@ -1,136 +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 };
-}
+/**
+ * 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

@@ -1,38 +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;
-}
+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

@@ -1,28 +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';
+/**
+ * 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';