@scalebun-release/react-native 2.5.0

package/src/debug/exportBridge.ts

@@ -0,0 +1,155 @@
+/**
+ * ScaleBun Debug — Export Bridge
+ *
+ * SDK→Desktop export request with typed protocol, correlation IDs,
+ * timeout handling, and pending-request deduplication.
+ */
+
+import type { DebugTransport } from './transport';
+import type { SimplifiedExportOptions, ExportResult, ExportPresetName } from '../public/types';
+import { logger } from '../core/logger/internalLogger';
+
+// ─── Types ──────────────────────────────────────────────────────────────────
+
+interface PendingExport {
+    requestId: string;
+    resolve: (result: ExportResult) => void;
+    reject: (err: Error) => void;
+    timer: ReturnType<typeof setTimeout>;
+}
+
+// ─── State ──────────────────────────────────────────────────────────────────
+
+const _pendingExports = new Map<string, PendingExport>();
+const EXPORT_TIMEOUT_MS = 120_000; // 2 minutes
+
+// ─── Request Export ─────────────────────────────────────────────────────────
+
+/**
+ * Request an export from the desktop application.
+ *
+ * Protocol:
+ *   1. SDK sends event { category: 'export', name: 'export:request', data: { requestId, preset?, options? } }
+ *   2. Desktop receives event, runs export pipeline, sends back command { name: 'exportReportResult', args: { requestId, success, filePath?, error?, cancelled? } }
+ *   3. SDK resolves/rejects the Promise based on the command result
+ */
+export function requestExport(
+    transport: DebugTransport | null,
+    enabled: boolean,
+    presetOrOptions?: ExportPresetName | SimplifiedExportOptions,
+): Promise<ExportResult> {
+    return new Promise<ExportResult>((resolve, reject) => {
+        try {
+            if (!enabled || !transport) {
+                resolve({
+                    success: false,
+                    error: 'Desktop debug connection not active. Call ScaleBun.init({ desktopDebug: true }) first.',
+                });
+                return;
+            }
+
+            // Build request payload
+            const requestId = `export-${Date.now()}-${Math.random().toString(36).substring(2, 8)}`;
+            let payload: Record<string, unknown> = { requestId };
+
+            if (typeof presetOrOptions === 'string') {
+                payload.preset = presetOrOptions;
+            } else if (presetOrOptions && typeof presetOrOptions === 'object') {
+                payload = { ...payload, ...presetOrOptions };
+            }
+
+            // Deduplication: reject if there's already a pending export
+            if (_pendingExports.size > 0) {
+                resolve({
+                    success: false,
+                    error: 'An export is already in progress. Wait for it to complete.',
+                });
+                return;
+            }
+
+            // Set up timeout
+            const timer = setTimeout(() => {
+                const pending = _pendingExports.get(requestId);
+                if (pending) {
+                    _pendingExports.delete(requestId);
+                    pending.resolve({
+                        success: false,
+                        error: `Export timed out after ${EXPORT_TIMEOUT_MS / 1000}s`,
+                    });
+                }
+            }, EXPORT_TIMEOUT_MS);
+
+            // Store pending export
+            _pendingExports.set(requestId, { requestId, resolve, reject, timer });
+
+            // Send export request event to desktop
+            // From the SDK-owned constants module — requiring './protocol' here would statically
+            // drag the vendored schema module into every bundle, even devtools-excluded ones.
+            const { PROTOCOL_VERSION } = require('../core/constants/protocol');
+            transport.send({
+                type: 'event' as const,
+                protocolVersion: PROTOCOL_VERSION,
+                deviceId: transport.deviceId,
+                sessionId: transport.sessionId,
+                timestamp: Date.now(),
+                sequence: transport.nextSequence(),
+                payload: {
+                    id: requestId,
+                    category: 'export' as any,
+                    name: 'export:request',
+                    data: payload,
+                },
+            } as any);
+
+            __DEV__ && logger.info(`[ExportBridge] Export request sent: ${requestId}`);
+
+        } catch (err: any) {
+            resolve({
+                success: false,
+                error: `Export request failed: ${err?.message || 'unknown error'}`,
+            });
+        }
+    });
+}
+
+/**
+ * Handle export result from desktop (called by CommandRegistry).
+ * @internal
+ */
+export function handleExportResult(args: Record<string, unknown>): void {
+    try {
+        const requestId = args.requestId as string;
+        if (!requestId) return;
+
+        const pending = _pendingExports.get(requestId);
+        if (!pending) {
+            logger.warn(`[ExportBridge] Received result for unknown requestId: ${requestId}`);
+            return;
+        }
+
+        clearTimeout(pending.timer);
+        _pendingExports.delete(requestId);
+
+        pending.resolve({
+            success: (args.success as boolean) ?? false,
+            filePath: args.filePath as string | undefined,
+            error: args.error as string | undefined,
+            cancelled: args.cancelled as boolean | undefined,
+        });
+
+        __DEV__ && logger.info(`[ExportBridge] Export result received: ${requestId} success=${args.success}`);
+    } catch { /* no-throw */ }
+}
+
+// ─── Teardown ───────────────────────────────────────────────────────────────
+
+/**
+ * Reject all pending exports and clear state.
+ */
+export function teardownExports(): void {
+    for (const [, pending] of _pendingExports) {
+        clearTimeout(pending.timer);
+        pending.reject(new Error('Debug disabled — export cancelled'));
+    }
+    _pendingExports.clear();
+}

package/src/debug/hostResolver.ts

@@ -0,0 +1,34 @@
+/**
+ * ScaleBun Debug — Host Resolver
+ *
+ * Resolves the debug host address for WebSocket connection.
+ * Android emulator uses 10.0.2.2 to reach host machine's loopback.
+ * iOS simulator / physical devices / web use localhost.
+ */
+
+import { logger } from '../core/logger/internalLogger';
+
+/**
+ * Resolve the debug host address.
+ * If explicit host is provided, uses that directly.
+ * Otherwise auto-resolves based on platform.
+ */
+export function resolveDebugHost(explicit?: string): string {
+    if (explicit) {
+        __DEV__ && logger.debug(`Debug host: explicit → ${explicit}`);
+        return explicit;
+    }
+    // Android emulator needs 10.0.2.2 to reach host machine's loopback.
+    // iOS simulator / physical devices / web use localhost.
+    let host = 'localhost';
+    try {
+        const { Platform } = require('react-native');
+        if (Platform.OS === 'android') {
+            host = '10.0.2.2';
+        }
+    } catch {
+        // Fallback to localhost if Platform is unavailable
+    }
+    __DEV__ && logger.debug(`Debug host: auto → ${host}`);
+    return host;
+}

package/src/debug/index.ts

@@ -0,0 +1,25 @@
+/**
+ * ScaleBun Debug — Public API
+ *
+ * Re-exports the public-facing debug API.
+ * Internal modules should import from specific files directly.
+ */
+
+export { enableDebug, disableDebug, isDebugEnabled, addBreadcrumb, ping, _getStream, _setFlushFn, _getCommands, _getReplaySdk, _isReplaySdkInitialized, _getTransport, _getJourneyConfig, _isJourneyEnabled, _setDebugReady, _getSessionManager, getPerformanceFeature, _getAutoScreenDetector, requestExport, _handleExportResult } from './bootstrap';
+export type { DebugConfig } from './bootstrap';
+export { buildDebugConfigFromInitConfig, applyFeatureGatesToDebugConfig } from './configBuilder';
+export { sendDebugMetric } from './metrics';
+
+// Re-export protocol types for consumers who need them
+export type {
+    DebugMessage,
+    EventMessage,
+    MetricMessage,
+    CommandMessage,
+    CommandResultMessage,
+    HelloMessage,
+    ErrorMessage,
+    EventCategory,
+    LogLevel as DebugLogLevel,
+    CommandName,
+} from './protocol';

package/src/debug/metrics.ts

@@ -0,0 +1,29 @@
+import { _getTransport } from './bootstrap';
+
+export function sendDebugMetric(
+    name: string,
+    value: number,
+    unit?: string,
+    tags?: Record<string, string>,
+): void {
+    try {
+        const transport = _getTransport();
+        if (!transport) {
+            console.warn('[ScaleBun] debug.sendMetric: no transport — is debug enabled and connected?');
+            return;
+        }
+        const msg = {
+            type: 'metric' as const,
+            protocolVersion: 1,
+            deviceId: transport.deviceId || 'unknown',
+            sessionId: transport.sessionId || 'unknown',
+            timestamp: Date.now(),
+            sequence: transport.nextSequence(),
+            payload: { name, value, ...(unit ? { unit } : {}), ...(tags ? { tags } : {}) },
+        };
+        console.log(`[ScaleBun] debug.sendMetric → ${name}=${value} ${unit || ''}`);
+        transport.send(msg as any);
+    } catch (err: any) {
+        console.warn('[ScaleBun] debug.sendMetric failed:', err?.message);
+    }
+}

package/src/debug/perf.ts

@@ -0,0 +1,212 @@
+/**
+ * ScaleBun Debug — Performance Monitoring
+ *
+ * Captures JS event-loop stalls and frame drop signals.
+ * Uses setInterval drift detection to measure event-loop blocking.
+ *
+ * Approach:
+ *   1. Run a 16ms interval timer (one frame budget at 60fps)
+ *   2. Measure actual elapsed time vs expected
+ *   3. If drift > threshold, report a "stall" event
+ *   4. Periodically send aggregate metrics to desktop
+ */
+
+import { type DebugTransport } from './transport';
+import { type MetricMessage, PROTOCOL_VERSION } from './protocol';
+
+// ─── Types ──────────────────────────────────────────────────────────────────
+
+export interface PerfConfig {
+    /** Stall detection threshold in ms. Default: 32 (two frames) */
+    stallThresholdMs?: number;
+    /** How often to report aggregate metrics in ms. Default: 5000 */
+    reportIntervalMs?: number;
+    /** Enable stall detection. Default: true */
+    enableStallDetection?: boolean;
+}
+
+interface StallRecord {
+    timestamp: number;
+    durationMs: number;
+}
+
+// ─── Performance Monitor ────────────────────────────────────────────────────
+
+export class PerfMonitor {
+    private transport: DebugTransport;
+    private config: Required<PerfConfig>;
+    private stallTimer: ReturnType<typeof setInterval> | null = null;
+    private reportTimer: ReturnType<typeof setInterval> | null = null;
+    private lastTick = 0;
+    private stalls: StallRecord[] = [];
+    private stallCount = 0;
+    private maxStallMs = 0;
+    private totalStallMs = 0;
+    private running = false;
+
+    constructor(transport: DebugTransport, config: PerfConfig = {}) {
+        this.transport = transport;
+        this.config = {
+            stallThresholdMs: 32,
+            reportIntervalMs: 5000,
+            enableStallDetection: true,
+            ...config,
+        };
+    }
+
+    /** Start monitoring */
+    start(): void {
+        if (this.running) return;
+        this.running = true;
+
+        if (this.config.enableStallDetection) {
+            this._startStallDetection();
+        }
+
+        this._startReportInterval();
+    }
+
+    /** Stop monitoring and clean up */
+    stop(): void {
+        this.running = false;
+
+        if (this.stallTimer) {
+            clearInterval(this.stallTimer);
+            this.stallTimer = null;
+        }
+        if (this.reportTimer) {
+            clearInterval(this.reportTimer);
+            this.reportTimer = null;
+        }
+    }
+
+    // ─── Stall Detection ─────────────────────────────────────────────────
+
+    private _startStallDetection(): void {
+        const intervalMs = 16; // ~60fps frame budget
+        this.lastTick = Date.now();
+
+        this.stallTimer = setInterval(() => {
+            try {
+                const now = Date.now();
+                const elapsed = now - this.lastTick;
+                const drift = elapsed - intervalMs;
+
+                if (drift > this.config.stallThresholdMs) {
+                    const stall: StallRecord = {
+                        timestamp: now,
+                        durationMs: drift,
+                    };
+                    this.stalls.push(stall);
+                    this.stallCount++;
+                    this.totalStallMs += drift;
+                    if (drift > this.maxStallMs) {
+                        this.maxStallMs = drift;
+                    }
+
+                    // Keep only last 100 stall records in memory
+                    if (this.stalls.length > 100) {
+                        this.stalls = this.stalls.slice(-50);
+                    }
+
+                    // Send individual stall event if very severe (>100ms)
+                    if (drift > 100) {
+                        this._sendMetric('perf.js.stall', drift, 'ms', {
+                            severity: drift > 500 ? 'critical' : drift > 200 ? 'warning' : 'info',
+                        });
+                    }
+                }
+
+                this.lastTick = now;
+            } catch {
+                // No-throw — never break the interval
+            }
+        }, intervalMs);
+    }
+
+    // ─── Periodic Reporting ───────────────────────────────────────────────
+
+    private _startReportInterval(): void {
+        this.reportTimer = setInterval(() => {
+            try {
+                this._reportAggregateMetrics();
+            } catch {
+                // No-throw
+            }
+        }, this.config.reportIntervalMs);
+    }
+
+    private _reportAggregateMetrics(): void {
+        // JS event-loop stall count
+        this._sendMetric('perf.js.stall_count', this.stallCount, 'count');
+
+        // Max stall in reporting period
+        this._sendMetric('perf.js.stall_max', this.maxStallMs, 'ms');
+
+        // Average stall (avoid division by zero)
+        const avgStall = this.stallCount > 0
+            ? Math.round(this.totalStallMs / this.stallCount)
+            : 0;
+        this._sendMetric('perf.js.stall_avg', avgStall, 'ms');
+
+        // Estimated FPS based on stall time
+        // In a perfect 60fps world, 5000ms = 300 frames
+        // Each ms of stall = roughly one dropped frame at 60fps
+        const expectedFrames = Math.round(this.config.reportIntervalMs / 16.67);
+        const droppedFrames = Math.round(this.totalStallMs / 16.67);
+        const actualFrames = Math.max(0, expectedFrames - droppedFrames);
+        const estimatedFps = Math.round((actualFrames / expectedFrames) * 60);
+        this._sendMetric('perf.fps.estimated', Math.min(60, Math.max(0, estimatedFps)), 'fps');
+        this._sendMetric('perf.frames.dropped', droppedFrames, 'count');
+
+        // Top stalls (worst 5)
+        const worstStalls = [...this.stalls]
+            .sort((a, b) => b.durationMs - a.durationMs)
+            .slice(0, 5);
+
+        if (worstStalls.length > 0) {
+            this._sendMetric('perf.js.worst_stalls', worstStalls.length, 'count',
+                worstStalls.reduce((acc, s, i) => {
+                    acc[`stall_${i}_ts`] = String(s.timestamp);
+                    acc[`stall_${i}_ms`] = String(s.durationMs);
+                    return acc;
+                }, {} as Record<string, string>),
+            );
+        }
+
+        // Reset counters for next period
+        this.stallCount = 0;
+        this.maxStallMs = 0;
+        this.totalStallMs = 0;
+        this.stalls = [];
+    }
+
+    // ─── Metric Sender ───────────────────────────────────────────────────
+
+    private _sendMetric(
+        name: string,
+        value: number,
+        unit?: string,
+        tags?: Record<string, string>,
+    ): void {
+        try {
+            const metric: MetricMessage = {
+                type: 'metric',
+                protocolVersion: PROTOCOL_VERSION,
+                deviceId: this.transport.deviceId,
+                sessionId: this.transport.sessionId,
+                timestamp: Date.now(),
+                sequence: this.transport.nextSequence(),
+                payload: {
+                    name,
+                    value,
+                    ...(unit ? { unit } : {}),
+                    ...(tags ? { tags } : {}),
+                },
+            };
+            this.transport.send(metric);
+        } catch {
+            // No-throw
+        }
+    }
+}

package/src/debug/perfWiring.ts

@@ -0,0 +1,119 @@
+/**
+ * ScaleBun Debug — Performance & Profiler Wiring
+ *
+ * Initializes PerformanceFeature and ProfilerFeature for debug mode.
+ * Falls back to legacy PerfMonitor if PerformanceFeature fails.
+ */
+
+import { PerformanceFeature } from '../features/performance/PerformanceFeature';
+import { ProfilerFeature } from '../features/profiler/ProfilerFeature';
+import type { PerfTransportSink } from '../features/performance/transport/PerformanceTransport';
+import { PerfMonitor } from './perf';
+import type { DebugTransport } from './transport';
+import type { DebugEventStream } from './stream';
+import { logger } from '../core/logger/internalLogger';
+
+export interface PerfWiringResult {
+    performanceFeature: PerformanceFeature | null;
+    profilerFeature: ProfilerFeature | null;
+    perfMonitor: PerfMonitor | null;
+}
+
+/**
+ * Initialize PerformanceFeature with debug transport.
+ * Falls back to legacy PerfMonitor if PerformanceFeature fails.
+ */
+export function initPerformance(
+    transport: DebugTransport,
+    stream: DebugEventStream | null,
+    config: {
+        performanceDisabled?: boolean;
+        enablePerf?: boolean;
+        stallThresholdMs?: number;
+    },
+): { performanceFeature: PerformanceFeature | null; perfMonitor: PerfMonitor | null } {
+    if (config.performanceDisabled) {
+        __DEV__ && logger.debug('Performance feature disabled — skipping PerformanceFeature init');
+        return { performanceFeature: null, perfMonitor: null };
+    }
+
+    try {
+        const performanceFeature = new PerformanceFeature();
+        performanceFeature.setTransportSink(transport as unknown as PerfTransportSink);
+        performanceFeature.setSessionId(transport.sessionId);
+
+        const initPromise = performanceFeature.initialize({
+            trackEvent: (name: string, payload?: Record<string, unknown>) => {
+                if (transport) {
+                    try {
+                        const { PROTOCOL_VERSION } = require('./protocol');
+                        transport.send({
+                            type: 'event' as const,
+                            protocolVersion: PROTOCOL_VERSION,
+                            deviceId: transport.deviceId,
+                            sessionId: transport.sessionId,
+                            timestamp: Date.now(),
+                            sequence: transport.nextSequence(),
+                            payload: {
+                                id: `${Date.now().toString(36)}-${Math.random().toString(36).substring(2, 8)}`,
+                                category: 'performance' as const,
+                                name,
+                                data: payload,
+                            },
+                        });
+                    } catch { /* no-throw */ }
+                }
+            },
+            getDebugStream: () => stream,
+            getAppState: () => 'active',
+        });
+
+        initPromise.then(() => {
+            __DEV__ && logger.info('PerformanceFeature initialized successfully');
+        }).catch((perfErr: any) => {
+            logger.warn('PerformanceFeature async init failed:', perfErr?.message);
+        });
+
+        return { performanceFeature, perfMonitor: null };
+    } catch (perfErr: any) {
+        logger.warn('PerformanceFeature init failed, falling back to legacy PerfMonitor:', perfErr?.message);
+
+        let perfMonitor: PerfMonitor | null = null;
+        if (config.enablePerf !== false) {
+            perfMonitor = new PerfMonitor(transport, {
+                stallThresholdMs: config.stallThresholdMs,
+            });
+        }
+        return { performanceFeature: null, perfMonitor };
+    }
+}
+
+/**
+ * Initialize ProfilerFeature for debug mode.
+ */
+export function initProfiler(
+    transport: DebugTransport,
+    enableProfiler?: boolean,
+): ProfilerFeature | null {
+    if (enableProfiler === false) {
+        __DEV__ && logger.debug('Profiler feature disabled — skipping ProfilerFeature init');
+        return null;
+    }
+
+    try {
+        const profilerFeature = new ProfilerFeature();
+        profilerFeature.setTransportSink(transport as any);
+        profilerFeature.setSessionId(transport.sessionId);
+
+        profilerFeature.initialize().then(() => {
+            __DEV__ && logger.info('ProfilerFeature initialized successfully (idle state)');
+        }).catch((initErr: any) => {
+            logger.warn('ProfilerFeature init failed (non-fatal, native module may not be present):', initErr?.message);
+        });
+
+        return profilerFeature;
+    } catch (profErr: any) {
+        logger.warn('ProfilerFeature creation failed (non-fatal):', profErr?.message);
+        return null;
+    }
+}

package/src/debug/protocol.ts

@@ -0,0 +1,58 @@
+/**
+ * ScaleBun Debug Protocol — re-export shim
+ *
+ * All schemas and types now live in the canonical package:
+ *   @scalebun/protocol
+ *
+ * This file is a thin re-export so that every import path inside the SDK
+ * (e.g. `import { ... } from './protocol'`) continues to resolve without
+ * any changes to callers.
+ *
+ * Do NOT add new schema logic here. Edit @scalebun/protocol/src/index.ts.
+ */
+
+export {
+    PROTOCOL_VERSION,
+    DEFAULT_HEARTBEAT_INTERVAL_MS,
+
+    // Schemas
+    HelloMessageSchema,
+    EventCategorySchema,
+    LogLevelSchema,
+    EventMessageSchema,
+    MetricMessageSchema,
+    CommandNameSchema,
+    CommandMessageSchema,
+    CommandResultMessageSchema,
+    ErrorMessageSchema,
+    PingMessageSchema,
+    PongMessageSchema,
+    AckMessageSchema,
+    DebugMessageSchema,
+
+    // Parsers / serializers
+    parseDebugMessage,
+    parseAnyMessage,
+    serializeMessage,
+    deserializeMessage,
+} from '../vendor/protocol';
+
+export type {
+    HelloMessage,
+    EventMessage,
+    MetricMessage,
+    CommandMessage,
+    CommandResultMessage,
+    ErrorMessage,
+    PingMessage,
+    PongMessage,
+    AckMessage,
+    DebugMessage,
+    AnyScaleBunMessage,
+    EventCategory,
+    LogLevel,
+    CommandName,
+    ParseResult,
+    DeviceInfo,
+    DeviceStatus,
+} from '../vendor/protocol';