@scalebun-release/react-native 2.5.0

package/lib/commonjs/features/journey/journeyManager.js

@@ -0,0 +1,466 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.JourneyManager = void 0;
+var _journeyTypes = require("./journeyTypes");
+var _gestureBuffer = require("./gestureBuffer");
+var _version = require("../../core/constants/version");
+var _gestureDetector = require("./gestureDetector");
+var _navDetector = require("./navDetector");
+var _screenshotHelper = require("./screenshotHelper");
+var _targetRegistry = require("./targetRegistry");
+var _protocol = require("../../core/constants/protocol");
+/**
+ * ScaleBun SDK — Journey Manager
+ *
+ * Core orchestrator for journey recording and running.
+ * Coordinates gesture buffer, nav detector, screenshot helper,
+ * and transport to implement the full journey lifecycle.
+ */
+
+// The SDK-owned constant, not the debug/protocol shim — the shim re-exports from the vendored
+// schema module, which would pull every desktop wire-message schema into production bundles.
+
+// ─── Journey Event Names ────────────────────────────────────────────────────
+
+const JOURNEY_EVENTS = {
+  DEBUG_READY: 'journey:debug_ready',
+  CURRENT_SCREEN: 'journey:current_screen',
+  RECORDING_STATE: 'journey:recording_state',
+  STEP_RECORDED: 'journey:step_recorded',
+  JOURNEY_SAVED: 'journey:saved',
+  RUN_STARTED: 'journey:run_started',
+  RUN_STEP_STATUS: 'journey:run_step_status',
+  RUN_FINISHED: 'journey:run_finished',
+  IMAGE_CHUNK: 'journey:image_chunk'
+};
+
+// ─── Journey Manager ────────────────────────────────────────────────────────
+
+class JourneyManager {
+  // Recording state
+  _isRecording = false;
+  _journeyTempId = '';
+  _steps = [];
+  _stepIndex = 0;
+
+  // Running state
+  _isRunning = false;
+  _runId = '';
+  _stopRunFlag = false;
+
+  // Singleton guard
+  static _instance = null;
+  constructor(transport, config) {
+    this.transport = transport;
+    this.config = {
+      enabled: config?.enabled ?? _journeyTypes.DEFAULT_JOURNEY_CONFIG.enabled,
+      autoStart: config?.autoStart ?? _journeyTypes.DEFAULT_JOURNEY_CONFIG.autoStart,
+      screenshots: {
+        ..._journeyTypes.DEFAULT_JOURNEY_CONFIG.screenshots,
+        ...config?.screenshots
+      },
+      gestures: {
+        ..._journeyTypes.DEFAULT_JOURNEY_CONFIG.gestures,
+        ...config?.gestures
+      },
+      nav: {
+        ..._journeyTypes.DEFAULT_JOURNEY_CONFIG.nav,
+        ...config?.nav
+      }
+    };
+    this.gestureBuffer = new _gestureBuffer.GestureBuffer(this.config.gestures.bufferSize);
+    this.gestureDetector = new _gestureDetector.GestureDetector(this.gestureBuffer);
+    this.navDetector = new _navDetector.NavDetector();
+    this.screenshotHelper = new _screenshotHelper.ScreenshotHelper(this.config.screenshots);
+  }
+
+  /** Singleton factory — idempotent */
+  static getInstance(transport, config) {
+    if (!JourneyManager._instance) {
+      JourneyManager._instance = new JourneyManager(transport, config);
+    }
+    return JourneyManager._instance;
+  }
+
+  /** Reset singleton (for teardown) */
+  static resetInstance() {
+    if (JourneyManager._instance) {
+      JourneyManager._instance.teardown();
+      JourneyManager._instance = null;
+    }
+  }
+
+  // ─── Accessors ──────────────────────────────────────────────────────
+
+  get isRecording() {
+    return this._isRecording;
+  }
+  get isRunning() {
+    return this._isRunning;
+  }
+  get steps() {
+    return this._steps;
+  }
+  get currentScreen() {
+    return this.navDetector.currentScreen;
+  }
+  get detector() {
+    return this.gestureDetector;
+  }
+  get nav() {
+    return this.navDetector;
+  }
+  get screenshot() {
+    return this.screenshotHelper;
+  }
+
+  // ─── Initialization ─────────────────────────────────────────────────
+
+  /** Initialize the journey system. Called by ScaleBunDebugRoot on mount. */
+  initialize(rootRef) {
+    // Install gesture detection
+    this.gestureDetector.install();
+
+    // Install nav detection
+    this.navDetector.install(this.config.nav);
+
+    // Set screenshot root ref
+    if (rootRef) {
+      this.screenshotHelper.setRootRef(rootRef);
+    }
+
+    // Subscribe to nav changes to emit to desktop
+    this.navDetector.onScreenChange((screenName, stack) => {
+      this._emitEvent(JOURNEY_EVENTS.CURRENT_SCREEN, {
+        screenName,
+        stack
+      });
+      // Also push NAV gesture into buffer
+      this.gestureDetector.handleNavigation(screenName);
+    });
+
+    // Emit DEBUG_READY
+    this._emitDebugReady();
+
+    // Auto-start if configured
+    if (this.config.autoStart) {
+      this.startRecording();
+    }
+  }
+
+  // ─── Recording ──────────────────────────────────────────────────────
+
+  startRecording() {
+    if (this._isRecording) return;
+    this._isRecording = true;
+    this._journeyTempId = this._generateId();
+    this._steps = [];
+    this._stepIndex = 0;
+    console.warn('[ScaleBun Journey] Recording started:', this._journeyTempId);
+    this._emitEvent(JOURNEY_EVENTS.RECORDING_STATE, {
+      on: true,
+      journeyTempId: this._journeyTempId
+    });
+  }
+  stopRecording() {
+    if (!this._isRecording) return;
+    this._isRecording = false;
+    console.warn('[ScaleBun Journey] Recording stopped:', this._journeyTempId, `(${this._steps.length} steps)`);
+    this._emitEvent(JOURNEY_EVENTS.RECORDING_STATE, {
+      on: false,
+      journeyTempId: this._journeyTempId
+    });
+  }
+
+  /** Capture a step — matches gesture from buffer + takes screenshot */
+  async captureStep(gestureMode, label, note) {
+    if (!this._isRecording) {
+      return {
+        success: false,
+        error: 'Not recording'
+      };
+    }
+    const mode = gestureMode;
+
+    // 1. Match gesture from buffer
+    const matchedGesture = this.gestureBuffer.matchRecent(mode, this.config.gestures.matchWindowMs);
+
+    // 2. Take screenshot
+    const {
+      result: screenshotResult,
+      error: screenshotError
+    } = await this.screenshotHelper.capture();
+
+    // 3. Build step
+    const step = {
+      stepIndex: this._stepIndex++,
+      gestureType: mode,
+      target: matchedGesture?.target,
+      screenName: this.navDetector.currentScreen,
+      timestamp: Date.now(),
+      label,
+      note
+    };
+    if (!matchedGesture) {
+      step.captureOnly = true;
+      step.captureOnlyReason = `No ${mode} gesture found in last ${this.config.gestures.matchWindowMs}ms`;
+    }
+
+    // 4. Attach screenshot metadata + send image
+    let screenshotId;
+    if (screenshotResult) {
+      screenshotId = this._generateId();
+      step.screenshotId = screenshotId;
+      step.screenshotMeta = {
+        width: screenshotResult.width,
+        height: screenshotResult.height,
+        mime: screenshotResult.mime,
+        byteSize: screenshotResult.byteSize
+      };
+
+      // Send image as separate event (chunked for large images)
+      this._emitEvent(JOURNEY_EVENTS.IMAGE_CHUNK, {
+        imageId: screenshotId,
+        stepIndex: step.stepIndex,
+        base64: screenshotResult.base64,
+        mime: screenshotResult.mime,
+        width: screenshotResult.width,
+        height: screenshotResult.height,
+        byteSize: screenshotResult.byteSize
+      });
+    } else if (screenshotError) {
+      step.note = (step.note ? step.note + ' | ' : '') + `Screenshot: ${screenshotError}`;
+    }
+
+    // 5. Store and emit
+    this._steps.push(step);
+    this._emitEvent(JOURNEY_EVENTS.STEP_RECORDED, {
+      journeyTempId: this._journeyTempId,
+      step
+    });
+    return {
+      success: true,
+      data: {
+        stepIndex: step.stepIndex,
+        gestureType: step.gestureType,
+        screenName: step.screenName,
+        hasScreenshot: !!screenshotResult,
+        captureOnly: step.captureOnly ?? false,
+        captureOnlyReason: step.captureOnlyReason
+      }
+    };
+  }
+
+  // ─── Save Journey ───────────────────────────────────────────────────
+
+  async saveJourney(name, journeyId) {
+    const id = journeyId || this._generateId();
+    let screenWidth = 0,
+      screenHeight = 0,
+      platformOS = 'unknown';
+    try {
+      const RN = require('react-native');
+      const dims = RN.Dimensions.get('window');
+      screenWidth = dims.width;
+      screenHeight = dims.height;
+      platformOS = RN.Platform.OS;
+    } catch {/* no-throw */}
+    const journey = {
+      journeyId: id,
+      name,
+      createdAt: Date.now(),
+      updatedAt: Date.now(),
+      steps: [...this._steps],
+      metadata: {
+        platform: platformOS,
+        screenWidth,
+        screenHeight,
+        navMode: this.navDetector.navMode
+      }
+    };
+    this._emitEvent(JOURNEY_EVENTS.JOURNEY_SAVED, {
+      journeyId: id,
+      name,
+      journey
+    });
+    return {
+      success: true,
+      data: {
+        journeyId: id,
+        name,
+        stepCount: this._steps.length
+      }
+    };
+  }
+
+  // ─── Run Journey ────────────────────────────────────────────────────
+
+  async runJourney(journeyData, options) {
+    if (this._isRunning) return;
+    const journey = journeyData;
+    if (!journey?.steps?.length) return;
+    this._isRunning = true;
+    this._stopRunFlag = false;
+    this._runId = this._generateId();
+    const speed = options?.speed ?? 1;
+    const stepByStep = options?.stepByStep ?? false;
+    const startTime = Date.now();
+    this._emitEvent(JOURNEY_EVENTS.RUN_STARTED, {
+      journeyId: journey.journeyId,
+      runId: this._runId
+    });
+    let passed = 0,
+      failed = 0,
+      skipped = 0;
+    for (let i = 0; i < journey.steps.length; i++) {
+      if (this._stopRunFlag) break;
+      const step = journey.steps[i];
+      let status = 'PENDING';
+      let reason = '';
+      try {
+        if (step.gestureType === 'NAV') {
+          // Try navigation
+          status = 'PASS';
+          reason = 'NAV step acknowledged';
+        } else if (step.target?.testId && (0, _targetRegistry.findTarget)(step.target.testId)) {
+          // Deterministic execution via registered target
+          const target = (0, _targetRegistry.findTarget)(step.target.testId);
+          if (step.gestureType === 'TAP' && target.press) {
+            target.press();
+            status = 'PASS';
+          } else if (step.gestureType === 'TYPE' && target.setValue) {
+            target.setValue('replay-text');
+            status = 'PASS';
+          } else if (step.gestureType === 'SCROLL' && target.scrollTo) {
+            target.scrollTo({
+              y: 100,
+              animated: true
+            });
+            status = 'PASS';
+          } else {
+            status = 'SKIP';
+            reason = `SKIPPED_UNRESOLVED: No handler for ${step.gestureType} on target ${step.target.testId}`;
+          }
+        } else {
+          // No deterministic target — best-effort
+          status = 'SKIP';
+          reason = `SKIPPED_UNRESOLVED: No registered target for step ${i}`;
+        }
+      } catch (e) {
+        status = 'FAIL';
+        reason = e?.message || 'Step execution error';
+      }
+
+      // Capture screenshot after step
+      let screenshotId;
+      const {
+        result: ss
+      } = await this.screenshotHelper.capture();
+      if (ss) {
+        screenshotId = this._generateId();
+        this._emitEvent(JOURNEY_EVENTS.IMAGE_CHUNK, {
+          imageId: screenshotId,
+          stepIndex: i,
+          base64: ss.base64,
+          mime: ss.mime,
+          width: ss.width,
+          height: ss.height,
+          byteSize: ss.byteSize
+        });
+      }
+
+      // Verify screen name match
+      if (status === 'PASS' && step.screenName !== 'UnknownScreen') {
+        if (this.navDetector.currentScreen !== step.screenName) {
+          reason = `Screen mismatch: expected ${step.screenName}, got ${this.navDetector.currentScreen}`;
+          // Don't fail — just note it
+        }
+      }
+      if (status === 'PASS') passed++;else if (status === 'FAIL') failed++;else skipped++;
+      this._emitEvent(JOURNEY_EVENTS.RUN_STEP_STATUS, {
+        runId: this._runId,
+        stepIndex: i,
+        status,
+        reason: reason || undefined,
+        screenshotId,
+        screenshotMeta: ss ? {
+          width: ss.width,
+          height: ss.height,
+          mime: ss.mime,
+          byteSize: ss.byteSize
+        } : undefined
+      });
+
+      // Delay between steps (respecting speed)
+      if (i < journey.steps.length - 1 && !stepByStep) {
+        await new Promise(resolve => setTimeout(resolve, 1000 / speed));
+      }
+    }
+    const durationMs = Date.now() - startTime;
+    this._emitEvent(JOURNEY_EVENTS.RUN_FINISHED, {
+      runId: this._runId,
+      summary: {
+        total: journey.steps.length,
+        passed,
+        failed,
+        skipped,
+        durationMs
+      }
+    });
+    this._isRunning = false;
+  }
+  stopRun() {
+    this._stopRunFlag = true;
+  }
+
+  // ─── Teardown ───────────────────────────────────────────────────────
+
+  teardown() {
+    this.stopRecording();
+    this.stopRun();
+    this.gestureDetector.teardown();
+    this.navDetector.teardown();
+    this.gestureBuffer.clear();
+  }
+
+  // ─── Internal ───────────────────────────────────────────────────────
+
+  _emitDebugReady() {
+    const payload = {
+      journeyEnabled: this.config.enabled,
+      canScreenshot: this.screenshotHelper.canCapture,
+      navMode: this.navDetector.navMode,
+      sdkVersion: _version.SDK_VERSION
+    };
+    this._emitEvent(JOURNEY_EVENTS.DEBUG_READY, payload);
+  }
+  _emitEvent(name, data) {
+    try {
+      const msg = {
+        type: 'event',
+        protocolVersion: _protocol.PROTOCOL_VERSION,
+        deviceId: this.transport.deviceId,
+        sessionId: this.transport.sessionId,
+        timestamp: Date.now(),
+        sequence: this.transport.nextSequence(),
+        payload: {
+          id: this._generateId(),
+          category: 'journey',
+          name,
+          data
+        }
+      };
+      this.transport.send(msg);
+    } catch {
+      // No-throw
+    }
+  }
+  _generateId() {
+    return `${Date.now().toString(36)}-${Math.random().toString(36).substring(2, 8)}`;
+  }
+}
+exports.JourneyManager = JourneyManager;
+//# sourceMappingURL=journeyManager.js.map

package/lib/commonjs/features/journey/journeyTypes.js

@@ -0,0 +1,55 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.DEFAULT_JOURNEY_CONFIG = void 0;
+/**
+ * ScaleBun SDK — Journey Types & Config
+ *
+ * Shared type definitions for the Journey Recorder + Runner feature.
+ * Config is supplied via enableDebug({ journey: { ... } }).
+ */
+
+// ─── Gesture Modes ──────────────────────────────────────────────────────────
+
+// ─── Step Status (used during run) ──────────────────────────────────────────
+
+// ─── Navigation Mode ────────────────────────────────────────────────────────
+
+// ─── Journey Config ─────────────────────────────────────────────────────────
+
+const DEFAULT_JOURNEY_CONFIG = exports.DEFAULT_JOURNEY_CONFIG = {
+  enabled: false,
+  autoStart: false,
+  screenshots: {
+    mode: 'onDemand',
+    periodicMs: 1000,
+    maxWidth: 720,
+    maxImageKB: 250,
+    format: 'jpeg'
+  },
+  gestures: {
+    bufferSize: 50,
+    matchWindowMs: 3000
+  },
+  nav: {
+    autoDetect: true,
+    allowBeaconFallback: true
+  }
+};
+
+// ─── Gesture Event (stored in buffer) ───────────────────────────────────────
+
+// ─── Target Descriptor ──────────────────────────────────────────────────────
+
+// ─── Journey Step (recorded) ────────────────────────────────────────────────
+
+// ─── Saved Journey ──────────────────────────────────────────────────────────
+
+// ─── Run Step Status ────────────────────────────────────────────────────────
+
+// ─── Protocol Events (SDK → Desktop) ────────────────────────────────────────
+
+// ─── Registered Target (for deterministic replay) ───────────────────────────
+//# sourceMappingURL=journeyTypes.js.map

package/lib/commonjs/features/journey/nativeScroll.js

@@ -0,0 +1,85 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.HEATMAP_SCHEMA_VERSION = void 0;
+exports.sanitizeScrollContext = sanitizeScrollContext;
+exports.scrollFields = scrollFields;
+/**
+ * SCROLL FIELDS FOR ONE TAP — the JS wrapper's offset when present, else the native probe's.
+ *
+ * Production had 0 of ~55,000 mobile taps with a scroll offset: offsets were only recorded by the
+ * SDK's own ScrollView/FlatList wrappers, and apps use the stock components. The native trackers
+ * now read every scroll container under the finger at ACTION_DOWN (Android ScrollContextProbe),
+ * with no wrapper, in the capture view's pixel space — the same space as the tap's x/y.
+ *
+ * Precedence: the innermost NATIVE entry (`'native'`, capture-view pixels, the same space as x/y)
+ * first; the JS wrapper's offset (`'wrapper'`, layout points) only when native had none. `'none'`
+ * still means no scroll container was under the finger — which, unlike
+ * before, is now a statement about the layout rather than about the integration.
+ */
+
+/** Current version of the mobile heatmap tap contract. Bump when a field's meaning changes. */
+const HEATMAP_SCHEMA_VERSION = exports.HEATMAP_SCHEMA_VERSION = 2;
+const finite = v => typeof v === 'number' && Number.isFinite(v);
+
+/** Keep only well-formed entries: a malformed native payload must never become a fabricated offset. */
+function sanitizeScrollContext(raw) {
+  if (!Array.isArray(raw)) return [];
+  const out = [];
+  for (const e of raw) {
+    if (!e || typeof e !== 'object') continue;
+    const r = e;
+    if (!finite(r.offsetX) || !finite(r.offsetY)) continue;
+    out.push({
+      containerTag: finite(r.containerTag) ? r.containerTag : undefined,
+      kind: typeof r.kind === 'string' ? r.kind : undefined,
+      horizontal: r.horizontal === true,
+      offsetX: r.offsetX,
+      offsetY: r.offsetY,
+      contentWidth: finite(r.contentWidth) ? r.contentWidth : undefined,
+      contentHeight: finite(r.contentHeight) ? r.contentHeight : undefined,
+      viewportWidth: finite(r.viewportWidth) ? r.viewportWidth : undefined,
+      viewportHeight: finite(r.viewportHeight) ? r.viewportHeight : undefined
+    });
+    if (out.length >= 4) break;
+  }
+  return out;
+}
+function scrollFields(start, event) {
+  const chain = sanitizeScrollContext(event?.scrollContext);
+  const density = finite(event?.pixelDensity) && event.pixelDensity > 0 ? event.pixelDensity : undefined;
+  const base = {
+    ...(chain.length ? {
+      scrollContext: chain
+    } : {}),
+    ...(density ? {
+      pixelDensity: density
+    } : {}),
+    heatmapSchemaVersion: HEATMAP_SCHEMA_VERSION
+  };
+  /* NATIVE FIRST: it is in the capture view's pixel space, the same space as the tap's x/y. The JS
+     wrapper records contentOffset in layout points, so on Android (x/y in physical pixels) mixing
+     the two is off by the pixel density. The wrapper remains the fallback where native has none. */
+  const inner = chain[0];
+  if (inner) return {
+    scrollX: inner.offsetX,
+    scrollY: inner.offsetY,
+    scrollSource: 'native',
+    ...base
+  };
+  if (start?.scrollSource === 'wrapper' && finite(start.scrollX) && finite(start.scrollY)) {
+    return {
+      scrollX: start.scrollX,
+      scrollY: start.scrollY,
+      scrollSource: 'wrapper',
+      ...base
+    };
+  }
+  return {
+    scrollSource: 'none',
+    ...base
+  };
+}
+//# sourceMappingURL=nativeScroll.js.map