@scalebun-release/react-native 2.5.0

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

@@ -0,0 +1,176 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.GestureDetector = void 0;
+/**
+ * ScaleBun SDK — Gesture Detector
+ *
+ * Lightweight gesture detection using RN touch/scroll events.
+ * Feeds detected gestures into the GestureBuffer.
+ *
+ * Detection strategy:
+ * - Uses global touch responder events (non-brittle, no monkey-patching)
+ * - Back button via BackHandler
+ * - Text input via global event listener
+ */
+
+class GestureDetector {
+  teardownFns = [];
+  installed = false;
+
+  // Touch tracking state
+  touchStartTime = 0;
+  touchStartX = 0;
+  touchStartY = 0;
+  lastTapTime = 0;
+  constructor(buffer) {
+    this.buffer = buffer;
+  }
+
+  /** Install gesture detection listeners. Idempotent. */
+  install() {
+    if (this.installed) return;
+    this.installed = true;
+    this._installBackHandler();
+    // Note: Touch and scroll detection happen via the ScaleBunDebugRoot component
+    // which provides gesture capture layer via onStartShouldSetResponder
+  }
+
+  /** Record a touch event from the ScaleBunDebugRoot gesture layer */
+  handleTouchStart(x, y, target) {
+    this.touchStartTime = Date.now();
+    this.touchStartX = x;
+    this.touchStartY = y;
+  }
+
+  /** Record touch end from the ScaleBunDebugRoot gesture layer */
+  handleTouchEnd(x, y, target) {
+    const duration = Date.now() - this.touchStartTime;
+    const dx = x - this.touchStartX;
+    const dy = y - this.touchStartY;
+    const distance = Math.sqrt(dx * dx + dy * dy);
+    if (distance > 30) {
+      // Swipe
+      const direction = this._getSwipeDirection(dx, dy);
+      this.buffer.push({
+        type: 'SWIPE',
+        timestamp: Date.now(),
+        target,
+        direction,
+        startCoords: {
+          x: this.touchStartX,
+          y: this.touchStartY
+        },
+        endCoords: {
+          x,
+          y
+        },
+        durationMs: duration
+      });
+    } else if (duration > 500) {
+      // Long press
+      this.buffer.push({
+        type: 'LONG_PRESS',
+        timestamp: Date.now(),
+        target,
+        durationMs: duration
+      });
+    } else {
+      // Check for double tap
+      const now = Date.now();
+      if (now - this.lastTapTime < 300) {
+        this.buffer.push({
+          type: 'DOUBLE_TAP',
+          timestamp: now,
+          target
+        });
+        this.lastTapTime = 0; // Reset
+      } else {
+        this.buffer.push({
+          type: 'TAP',
+          timestamp: now,
+          target
+        });
+        this.lastTapTime = now;
+      }
+    }
+  }
+
+  /** Record a scroll event from ScrollView/FlatList */
+  handleScroll(direction, target) {
+    this.buffer.push({
+      type: 'SCROLL',
+      timestamp: Date.now(),
+      target,
+      direction
+    });
+  }
+
+  /** Record a text input event */
+  handleTextInput(textLength, fieldId) {
+    this.buffer.push({
+      type: 'TYPE',
+      timestamp: Date.now(),
+      textLength,
+      fieldId,
+      target: fieldId ? {
+        testId: fieldId
+      } : undefined
+    });
+  }
+
+  /** Record a navigation event */
+  handleNavigation(screenName) {
+    this.buffer.push({
+      type: 'NAV',
+      timestamp: Date.now(),
+      target: {
+        text: screenName
+      }
+    });
+  }
+
+  /** Teardown all listeners */
+  teardown() {
+    for (const fn of this.teardownFns) {
+      try {
+        fn();
+      } catch {/* no-throw */}
+    }
+    this.teardownFns = [];
+    this.installed = false;
+  }
+
+  // ─── Internal ───────────────────────────────────────────────────────
+
+  _installBackHandler() {
+    try {
+      const {
+        BackHandler
+      } = require('react-native');
+      const handler = () => {
+        this.buffer.push({
+          type: 'BACK',
+          timestamp: Date.now()
+        });
+        return false; // Don't consume the event
+      };
+      BackHandler.addEventListener('hardwareBackPress', handler);
+      this.teardownFns.push(() => {
+        BackHandler.removeEventListener('hardwareBackPress', handler);
+      });
+    } catch {
+      // BackHandler not available — no-throw
+    }
+  }
+  _getSwipeDirection(dx, dy) {
+    if (Math.abs(dx) > Math.abs(dy)) {
+      return dx > 0 ? 'right' : 'left';
+    }
+    return dy > 0 ? 'down' : 'up';
+  }
+}
+exports.GestureDetector = GestureDetector;
+//# sourceMappingURL=gestureDetector.js.map

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

@@ -0,0 +1,93 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.ImpressionTracker = exports.IMPRESSION_THRESHOLD = exports.IMPRESSION_DWELL_MS = void 0;
+exports.isViewable = isViewable;
+exports.visibleFraction = visibleFraction;
+/**
+ * Impressions — "this element was actually seen".
+ *
+ * THE GAP. Web has had `$impression` via an IntersectionObserver on `[data-scalebun-track-impression]`
+ * since A2; mobile had no equivalent, so feed, carousel and list analytics ("was the promo ever on
+ * screen before they bounced?") were impossible. React Native has no IntersectionObserver, and there is
+ * no way for the SDK to observe an arbitrary host view without being mounted inside it — so, exactly
+ * like web, this is OPT-IN: the host marks what it wants counted.
+ *
+ * WHY THE MATH IS HERE. The viewability rule is pure geometry, and geometry is the part that is easy to
+ * get subtly wrong (a view scrolled half off the top is not "seen"). Keeping it in a plain function
+ * means it is unit-testable without a renderer, and the component around it stays a thin shell.
+ */
+
+/** Fraction of `el` that lies inside `viewport`, 0–1. Zero for degenerate or off-screen rects. */
+function visibleFraction(el, viewport) {
+  const area = el.width * el.height;
+  // A zero-area view cannot be "50% visible" — any ratio would be a divide-by-zero dressed up.
+  if (!(area > 0)) return 0;
+  const left = Math.max(el.x, viewport.x);
+  const right = Math.min(el.x + el.width, viewport.x + viewport.width);
+  const top = Math.max(el.y, viewport.y);
+  const bottom = Math.min(el.y + el.height, viewport.y + viewport.height);
+  const w = right - left;
+  const h = bottom - top;
+  if (w <= 0 || h <= 0) return 0;
+  return w * h / area;
+}
+
+/** The share of an element that must be on screen before it counts as seen. Matches web's threshold. */
+const IMPRESSION_THRESHOLD = exports.IMPRESSION_THRESHOLD = 0.5;
+
+/** How long it must stay that visible. A view flicking past during a fling was never really seen. */
+const IMPRESSION_DWELL_MS = exports.IMPRESSION_DWELL_MS = 250;
+function isViewable(el, viewport, threshold = IMPRESSION_THRESHOLD) {
+  return visibleFraction(el, viewport) >= threshold;
+}
+
+/**
+ * Tracks one element's viewability over time and decides when to fire.
+ *
+ * Fires AT MOST ONCE per instance — an impression is "was this seen", not "how many times did it cross
+ * the line", and a list that scrolls back and forth would otherwise inflate the count several-fold.
+ * Time is injected so the dwell rule can be tested without waiting.
+ */
+class ImpressionTracker {
+  visibleSince = null;
+  fired = false;
+  constructor(onImpression, threshold = IMPRESSION_THRESHOLD, dwellMs = IMPRESSION_DWELL_MS) {
+    this.onImpression = onImpression;
+    this.threshold = threshold;
+    this.dwellMs = dwellMs;
+  }
+
+  /** Feed a measurement. Safe to call as often as layout/scroll produces one. */
+  update(el, viewport, now) {
+    if (this.fired) return;
+    if (!isViewable(el, viewport, this.threshold)) {
+      this.visibleSince = null; // Scrolled away before the dwell elapsed — start over, do not accumulate.
+      return;
+    }
+    if (this.visibleSince == null) {
+      this.visibleSince = now;
+      return;
+    }
+    const held = now - this.visibleSince;
+    if (held >= this.dwellMs) {
+      this.fired = true;
+      this.onImpression(held);
+    }
+  }
+
+  /** True once this element has been counted. */
+  get hasFired() {
+    return this.fired;
+  }
+
+  /** Forget the element entirely — used when a recycled list row is bound to new content. */
+  reset() {
+    this.visibleSince = null;
+    this.fired = false;
+  }
+}
+exports.ImpressionTracker = ImpressionTracker;
+//# sourceMappingURL=impression.js.map

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

@@ -0,0 +1,168 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.INTERACTION_PROTOCOL_VERSION = exports.CORRELATION_TOLERANCE_MS = exports.CORRELATION_MARGIN_MS = void 0;
+exports.automaticInteractionProperties = automaticInteractionProperties;
+exports.correlateInteraction = correlateInteraction;
+exports.generateInteractionId = generateInteractionId;
+exports.pruneInteractionStarts = pruneInteractionStarts;
+/** One physical interaction, shared by replay and analytics projections. */
+const INTERACTION_PROTOCOL_VERSION = exports.INTERACTION_PROTOCOL_VERSION = 1;
+function generateInteractionId() {
+  return `ixj-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
+}
+
+/**
+ * RN-6 — THE CORRELATION CONTRACT.
+ *
+ * WHAT IS BEING JOINED, AND WHY IT IS HARD. A physical tap is observed twice: natively, by
+ * a window callback that sees ACTION_DOWN/UP and produces the coordinates; and in JS, by a
+ * capture-phase touch handler that produces the IDENTITY — which control was hit, what UI
+ * state was declared, which screen. Both sides mint their own id and neither can derive
+ * the other's: native builds `ixn-a-<process nonce>-<MotionEvent ts>` from a clock JS
+ * cannot read, and JS builds `ixj-<Date.now()>-<random>`. So the two observations have to
+ * be JOINED, and the only shared quantity is time.
+ *
+ * WHY THE OLD JOIN WAS DANGEROUS RATHER THAN MERELY APPROXIMATE. It took whichever start
+ * was nearest in time within ±1500 ms and used it unconditionally. The fields it carries
+ * across are `target`, `targetId`, `ui`, `stateStatus` and `screenName`; the coordinates
+ * come from the native side and are always right. So a wrong pairing does not produce
+ * obviously broken data — it produces heat in the CORRECT position attributed to the
+ * WRONG control, in the wrong UI state, on the wrong screen. Nothing downstream can
+ * detect that, because every field is individually well-formed.
+ *
+ * 1500 ms is a very long time on a touch surface. A deliberate double-tap is 150–300 ms
+ * apart; an impatient tapper is faster. So "nearest within 1500 ms" routinely had more
+ * than one candidate, and picked one with no record that it had a choice.
+ *
+ * WHAT THIS REPLACES IT WITH — three outcomes instead of one, and a refusal:
+ *
+ *   'exact'      one candidate is clearly closest: the runner-up is at least
+ *                `marginMs` further away. The join is used.
+ *   'ambiguous'  two candidates are within `marginMs` of each other, so choosing
+ *                between them is a coin flip. The join is REFUSED and the caller must
+ *                emit the interaction WITHOUT js-derived identity. A tap with no target
+ *                is honest and visibly incomplete; a tap with the wrong target is
+ *                indistinguishable from a correct one and corrupts every aggregate it
+ *                enters.
+ *   'none'       nothing within tolerance. Same refusal, different reason — worth
+ *                separating because 'none' means the JS handler never fired (a real
+ *                capture gap) while 'ambiguous' means it fired too often to attribute.
+ *
+ * It also reports `deltaMs` and `runnerUpDeltaMs` so the outcome is auditable after the
+ * fact rather than being a claim this comment makes.
+ *
+ * WHAT IT DELIBERATELY DOES NOT DO: use position to disambiguate. The native event carries
+ * raw px in the capture view and normalized 0..1 coordinates; the JS start carries its own
+ * x/y in a different space (dp in the root view). Comparing them needs a proven scale
+ * factor between the two, and getting it wrong would REJECT valid pairings — strictly
+ * worse than today. That calibration needs a device run, so it is a follow-up, not a
+ * guess made here.
+ */
+
+/**
+ * How far apart a native event and a JS start may be and still be the same touch.
+ *
+ * Unchanged at 1500 ms from the previous implementation, deliberately: narrowing it is a
+ * separate, measurable decision about how late the JS handler can run on a slow device,
+ * and bundling it into this change would make any regression impossible to attribute.
+ */
+const CORRELATION_TOLERANCE_MS = exports.CORRELATION_TOLERANCE_MS = 1500;
+
+/**
+ * How much closer the winner must be than the runner-up to count as identified.
+ *
+ * 100 ms because that is comfortably below the fastest deliberate double-tap (~150 ms):
+ * when two candidate starts are within 100 ms of each other in distance, the native event
+ * sits effectively between them and the "nearest" one is a coin flip.
+ */
+const CORRELATION_MARGIN_MS = exports.CORRELATION_MARGIN_MS = 100;
+
+/** Match a native bridge event to the JS evidence sampled at the same finger-down. */
+function correlateInteraction(starts, occurredAt, toleranceMs = CORRELATION_TOLERANCE_MS, marginMs = CORRELATION_MARGIN_MS) {
+  const candidates = [];
+  for (let i = 0; i < starts.length; i++) {
+    const start = starts[i];
+    if (!start) continue;
+    const delta = Math.abs(start.occurredAt - occurredAt);
+    if (delta <= toleranceMs) candidates.push({
+      index: i,
+      delta
+    });
+  }
+  if (candidates.length === 0) {
+    return {
+      index: -1,
+      outcome: 'none',
+      deltaMs: null,
+      runnerUpDeltaMs: null
+    };
+  }
+
+  /* Stable ordering: equal deltas resolve by index so a repeated run cannot produce a
+     different answer from the same inputs. A non-deterministic correlation would make
+     every downstream measurement unreproducible. */
+  candidates.sort((a, b) => a.delta - b.delta || a.index - b.index);
+  const best = candidates[0];
+  const runnerUp = candidates[1];
+  if (runnerUp && runnerUp.delta - best.delta < marginMs) {
+    return {
+      index: -1,
+      outcome: 'ambiguous',
+      deltaMs: best.delta,
+      runnerUpDeltaMs: runnerUp.delta
+    };
+  }
+  return {
+    start: starts[best.index],
+    index: best.index,
+    outcome: 'exact',
+    deltaMs: best.delta,
+    runnerUpDeltaMs: runnerUp ? runnerUp.delta : null
+  };
+}
+
+/**
+ * Drop starts that can no longer match anything, in place.
+ *
+ * WHY IT MATTERS BEYOND MEMORY. A start older than the tolerance is unreachable, but while
+ * it sits in the list it is still a CANDIDATE for the ambiguity test — so a stale entry can
+ * turn a perfectly clear pairing into a refusal, and an accumulating list makes that more
+ * likely the longer a session runs. Pruning is therefore part of the correctness of the
+ * join, not housekeeping.
+ *
+ * Mutates rather than returning a copy because the caller holds it in a ref that the native
+ * listener and the touch handler both read.
+ */
+function pruneInteractionStarts(starts, now, toleranceMs = CORRELATION_TOLERANCE_MS) {
+  let removed = 0;
+  for (let i = starts.length - 1; i >= 0; i--) {
+    const start = starts[i];
+    if (!start || now - start.occurredAt > toleranceMs) {
+      starts.splice(i, 1);
+      removed++;
+    }
+  }
+  return removed;
+}
+
+/** Analytics is a projection of the same evidence; no second click is invented. */
+function automaticInteractionProperties(payload, screenName, canonicalMirror) {
+  return {
+    gesture_type: payload.gestureType,
+    screen_name: screenName,
+    interaction_id: payload.interaction_id,
+    interaction_protocol: payload.interaction_protocol,
+    state_status: payload.state_status,
+    ui: payload.ui,
+    target_id: payload.target_id,
+    normalized_x: payload.normalizedX,
+    normalized_y: payload.normalizedY,
+    direction: payload.direction,
+    duration_ms: payload.durationMs,
+    canonical_mirror: canonicalMirror || undefined
+  };
+}
+//# sourceMappingURL=interactionProtocol.js.map