@scalebun-release/react-native 2.5.0

package/lib/commonjs/debug/configBuilder.js

@@ -0,0 +1,70 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.applyFeatureGatesToDebugConfig = applyFeatureGatesToDebugConfig;
+exports.buildDebugConfigFromInitConfig = buildDebugConfigFromInitConfig;
+/**
+ * Converts DebugConnectionConfig (public init API) to DebugConfig (internal debug API).
+ * Returns null if the config should not trigger a debug connection.
+ */
+function buildDebugConfigFromInitConfig(debugConfig) {
+  if (debugConfig === true) {
+    return {
+      port: 9333
+    };
+  }
+  if (typeof debugConfig === 'object') {
+    return {
+      ...(debugConfig.host ? {
+        host: debugConfig.host
+      } : {}),
+      port: debugConfig.port ?? 9333,
+      ...(debugConfig.appName ? {
+        appName: debugConfig.appName
+      } : {}),
+      ...(debugConfig.bundleId ? {
+        bundleId: debugConfig.bundleId
+      } : {}),
+      ...(debugConfig.secret ? {
+        secret: debugConfig.secret
+      } : {})
+    };
+  }
+  return null;
+}
+
+/**
+ * Applies feature flag opt-outs to a DebugConfig, producing a gated copy.
+ * Called before enableDebug() to ensure feature flags are respected.
+ */
+function applyFeatureGatesToDebugConfig(config, features) {
+  const gated = {
+    ...config
+  };
+
+  // Replay: default ON
+  if (features.replay === false) {
+    gated.replay = undefined;
+  } else if (!gated.replay) {
+    gated.replay = {};
+  }
+  // Session: default ON
+  if (features.session === false) {
+    gated._sessionDisabled = true;
+  }
+  // Journey: default OFF
+  if (features.journey === false) {
+    gated.journey = {
+      ...gated.journey,
+      enabled: false
+    };
+  }
+  // Performance: default ON
+  if (features.performance === false) {
+    gated._performanceDisabled = true;
+  }
+  return gated;
+}
+//# sourceMappingURL=configBuilder.js.map

package/lib/commonjs/debug/exportBridge.js

@@ -0,0 +1,155 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.handleExportResult = handleExportResult;
+exports.requestExport = requestExport;
+exports.teardownExports = teardownExports;
+var _internalLogger = require("../core/logger/internalLogger");
+/**
+ * ScaleBun Debug — Export Bridge
+ *
+ * SDK→Desktop export request with typed protocol, correlation IDs,
+ * timeout handling, and pending-request deduplication.
+ */
+
+// ─── Types ──────────────────────────────────────────────────────────────────
+
+// ─── State ──────────────────────────────────────────────────────────────────
+
+const _pendingExports = new Map();
+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
+ */
+function requestExport(transport, enabled, presetOrOptions) {
+  return new Promise((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 = {
+        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',
+        protocolVersion: PROTOCOL_VERSION,
+        deviceId: transport.deviceId,
+        sessionId: transport.sessionId,
+        timestamp: Date.now(),
+        sequence: transport.nextSequence(),
+        payload: {
+          id: requestId,
+          category: 'export',
+          name: 'export:request',
+          data: payload
+        }
+      });
+      __DEV__ && _internalLogger.logger.info(`[ExportBridge] Export request sent: ${requestId}`);
+    } catch (err) {
+      resolve({
+        success: false,
+        error: `Export request failed: ${err?.message || 'unknown error'}`
+      });
+    }
+  });
+}
+
+/**
+ * Handle export result from desktop (called by CommandRegistry).
+ * @internal
+ */
+function handleExportResult(args) {
+  try {
+    const requestId = args.requestId;
+    if (!requestId) return;
+    const pending = _pendingExports.get(requestId);
+    if (!pending) {
+      _internalLogger.logger.warn(`[ExportBridge] Received result for unknown requestId: ${requestId}`);
+      return;
+    }
+    clearTimeout(pending.timer);
+    _pendingExports.delete(requestId);
+    pending.resolve({
+      success: args.success ?? false,
+      filePath: args.filePath,
+      error: args.error,
+      cancelled: args.cancelled
+    });
+    __DEV__ && _internalLogger.logger.info(`[ExportBridge] Export result received: ${requestId} success=${args.success}`);
+  } catch {/* no-throw */}
+}
+
+// ─── Teardown ───────────────────────────────────────────────────────────────
+
+/**
+ * Reject all pending exports and clear state.
+ */
+function teardownExports() {
+  for (const [, pending] of _pendingExports) {
+    clearTimeout(pending.timer);
+    pending.reject(new Error('Debug disabled — export cancelled'));
+  }
+  _pendingExports.clear();
+}
+//# sourceMappingURL=exportBridge.js.map

package/lib/commonjs/debug/hostResolver.js

@@ -0,0 +1,42 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.resolveDebugHost = resolveDebugHost;
+var _internalLogger = require("../core/logger/internalLogger");
+/**
+ * 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.
+ */
+
+/**
+ * Resolve the debug host address.
+ * If explicit host is provided, uses that directly.
+ * Otherwise auto-resolves based on platform.
+ */
+function resolveDebugHost(explicit) {
+  if (explicit) {
+    __DEV__ && _internalLogger.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__ && _internalLogger.logger.debug(`Debug host: auto → ${host}`);
+  return host;
+}
+//# sourceMappingURL=hostResolver.js.map

package/lib/commonjs/debug/index.js

@@ -0,0 +1,141 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+Object.defineProperty(exports, "_getAutoScreenDetector", {
+  enumerable: true,
+  get: function () {
+    return _bootstrap._getAutoScreenDetector;
+  }
+});
+Object.defineProperty(exports, "_getCommands", {
+  enumerable: true,
+  get: function () {
+    return _bootstrap._getCommands;
+  }
+});
+Object.defineProperty(exports, "_getJourneyConfig", {
+  enumerable: true,
+  get: function () {
+    return _bootstrap._getJourneyConfig;
+  }
+});
+Object.defineProperty(exports, "_getReplaySdk", {
+  enumerable: true,
+  get: function () {
+    return _bootstrap._getReplaySdk;
+  }
+});
+Object.defineProperty(exports, "_getSessionManager", {
+  enumerable: true,
+  get: function () {
+    return _bootstrap._getSessionManager;
+  }
+});
+Object.defineProperty(exports, "_getStream", {
+  enumerable: true,
+  get: function () {
+    return _bootstrap._getStream;
+  }
+});
+Object.defineProperty(exports, "_getTransport", {
+  enumerable: true,
+  get: function () {
+    return _bootstrap._getTransport;
+  }
+});
+Object.defineProperty(exports, "_handleExportResult", {
+  enumerable: true,
+  get: function () {
+    return _bootstrap._handleExportResult;
+  }
+});
+Object.defineProperty(exports, "_isJourneyEnabled", {
+  enumerable: true,
+  get: function () {
+    return _bootstrap._isJourneyEnabled;
+  }
+});
+Object.defineProperty(exports, "_isReplaySdkInitialized", {
+  enumerable: true,
+  get: function () {
+    return _bootstrap._isReplaySdkInitialized;
+  }
+});
+Object.defineProperty(exports, "_setDebugReady", {
+  enumerable: true,
+  get: function () {
+    return _bootstrap._setDebugReady;
+  }
+});
+Object.defineProperty(exports, "_setFlushFn", {
+  enumerable: true,
+  get: function () {
+    return _bootstrap._setFlushFn;
+  }
+});
+Object.defineProperty(exports, "addBreadcrumb", {
+  enumerable: true,
+  get: function () {
+    return _bootstrap.addBreadcrumb;
+  }
+});
+Object.defineProperty(exports, "applyFeatureGatesToDebugConfig", {
+  enumerable: true,
+  get: function () {
+    return _configBuilder.applyFeatureGatesToDebugConfig;
+  }
+});
+Object.defineProperty(exports, "buildDebugConfigFromInitConfig", {
+  enumerable: true,
+  get: function () {
+    return _configBuilder.buildDebugConfigFromInitConfig;
+  }
+});
+Object.defineProperty(exports, "disableDebug", {
+  enumerable: true,
+  get: function () {
+    return _bootstrap.disableDebug;
+  }
+});
+Object.defineProperty(exports, "enableDebug", {
+  enumerable: true,
+  get: function () {
+    return _bootstrap.enableDebug;
+  }
+});
+Object.defineProperty(exports, "getPerformanceFeature", {
+  enumerable: true,
+  get: function () {
+    return _bootstrap.getPerformanceFeature;
+  }
+});
+Object.defineProperty(exports, "isDebugEnabled", {
+  enumerable: true,
+  get: function () {
+    return _bootstrap.isDebugEnabled;
+  }
+});
+Object.defineProperty(exports, "ping", {
+  enumerable: true,
+  get: function () {
+    return _bootstrap.ping;
+  }
+});
+Object.defineProperty(exports, "requestExport", {
+  enumerable: true,
+  get: function () {
+    return _bootstrap.requestExport;
+  }
+});
+Object.defineProperty(exports, "sendDebugMetric", {
+  enumerable: true,
+  get: function () {
+    return _metrics.sendDebugMetric;
+  }
+});
+var _bootstrap = require("./bootstrap");
+var _configBuilder = require("./configBuilder");
+var _metrics = require("./metrics");
+//# sourceMappingURL=index.js.map

package/lib/commonjs/debug/metrics.js

@@ -0,0 +1,39 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.sendDebugMetric = sendDebugMetric;
+var _bootstrap = require("./bootstrap");
+function sendDebugMetric(name, value, unit, tags) {
+  try {
+    const transport = (0, _bootstrap._getTransport)();
+    if (!transport) {
+      console.warn('[ScaleBun] debug.sendMetric: no transport — is debug enabled and connected?');
+      return;
+    }
+    const msg = {
+      type: 'metric',
+      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);
+  } catch (err) {
+    console.warn('[ScaleBun] debug.sendMetric failed:', err?.message);
+  }
+}
+//# sourceMappingURL=metrics.js.map

package/lib/commonjs/debug/perf.js

@@ -0,0 +1,186 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.PerfMonitor = void 0;
+var _protocol = require("./protocol");
+/**
+ * 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
+ */
+
+// ─── Types ──────────────────────────────────────────────────────────────────
+
+// ─── Performance Monitor ────────────────────────────────────────────────────
+
+class PerfMonitor {
+  stallTimer = null;
+  reportTimer = null;
+  lastTick = 0;
+  stalls = [];
+  stallCount = 0;
+  maxStallMs = 0;
+  totalStallMs = 0;
+  running = false;
+  constructor(transport, config = {}) {
+    this.transport = transport;
+    this.config = {
+      stallThresholdMs: 32,
+      reportIntervalMs: 5000,
+      enableStallDetection: true,
+      ...config
+    };
+  }
+
+  /** Start monitoring */
+  start() {
+    if (this.running) return;
+    this.running = true;
+    if (this.config.enableStallDetection) {
+      this._startStallDetection();
+    }
+    this._startReportInterval();
+  }
+
+  /** Stop monitoring and clean up */
+  stop() {
+    this.running = false;
+    if (this.stallTimer) {
+      clearInterval(this.stallTimer);
+      this.stallTimer = null;
+    }
+    if (this.reportTimer) {
+      clearInterval(this.reportTimer);
+      this.reportTimer = null;
+    }
+  }
+
+  // ─── Stall Detection ─────────────────────────────────────────────────
+
+  _startStallDetection() {
+    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 = {
+            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 ───────────────────────────────────────────────
+
+  _startReportInterval() {
+    this.reportTimer = setInterval(() => {
+      try {
+        this._reportAggregateMetrics();
+      } catch {
+        // No-throw
+      }
+    }, this.config.reportIntervalMs);
+  }
+  _reportAggregateMetrics() {
+    // 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;
+      }, {}));
+    }
+
+    // Reset counters for next period
+    this.stallCount = 0;
+    this.maxStallMs = 0;
+    this.totalStallMs = 0;
+    this.stalls = [];
+  }
+
+  // ─── Metric Sender ───────────────────────────────────────────────────
+
+  _sendMetric(name, value, unit, tags) {
+    try {
+      const metric = {
+        type: 'metric',
+        protocolVersion: _protocol.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
+    }
+  }
+}
+exports.PerfMonitor = PerfMonitor;
+//# sourceMappingURL=perf.js.map