@scalebun-release/react-native 2.5.0

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

@@ -0,0 +1,39 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.ScaleBunFlatList = void 0;
+var _react = _interopRequireDefault(require("react"));
+var _reactNative = require("react-native");
+var _ScaleBunScrollView = require("./ScaleBunScrollView");
+var _jsxRuntime = require("react/jsx-runtime");
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+/**
+ * ScaleBun SDK — ScaleBunFlatList
+ *
+ * Instrumented FlatList wrapper for scroll tracking.
+ * Uses `renderScrollComponent` to inject ScaleBunScrollView so that all
+ * scroll events from the FlatList flow through the SessionManager's
+ * ScrollTracker for settle detection and post-scroll frame capture.
+ *
+ * Usage:
+ *   import { ScaleBunFlatList } from 'scalebun-react-native';
+ *
+ *   <ScaleBunFlatList data={data} renderItem={renderItem} />
+ *
+ * This component is transparent — it passes all props through to the
+ * underlying FlatList and does NOT consume or interfere with any scroll events.
+ */
+
+function ScaleBunFlatListInner(props, ref) {
+  return /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.FlatList, {
+    ref: ref,
+    ...props,
+    renderScrollComponent: scrollProps => /*#__PURE__*/(0, _jsxRuntime.jsx)(_ScaleBunScrollView.ScaleBunScrollView, {
+      ...scrollProps
+    })
+  });
+}
+const ScaleBunFlatList = exports.ScaleBunFlatList = /*#__PURE__*/_react.default.forwardRef(ScaleBunFlatListInner);
+//# sourceMappingURL=ScaleBunFlatList.js.map

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

@@ -0,0 +1,113 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.ScaleBunImpression = ScaleBunImpression;
+var _react = _interopRequireWildcard(require("react"));
+var _reactNative = require("react-native");
+var _automaticEvents = require("../../analytics/automaticEvents");
+var _impression = require("./impression");
+var _jsxRuntime = require("react/jsx-runtime");
+function _interopRequireWildcard(e, t) { if ("function" == typeof WeakMap) var r = new WeakMap(), n = new WeakMap(); return (_interopRequireWildcard = function (e, t) { if (!t && e && e.__esModule) return e; var o, i, f = { __proto__: null, default: e }; if (null === e || "object" != typeof e && "function" != typeof e) return f; if (o = t ? n : r) { if (o.has(e)) return o.get(e); o.set(e, f); } for (const t in e) "default" !== t && {}.hasOwnProperty.call(e, t) && ((i = (o = Object.defineProperty) && Object.getOwnPropertyDescriptor(e, t)) && (i.get || i.set) ? o(f, t, i) : f[t] = e[t]); return f; })(e, t); }
+/**
+ * `<ScaleBunImpression>` — the mobile counterpart to web's `[data-scalebun-track-impression]`.
+ *
+ * Wrap anything whose "was it actually seen" matters (a promo card, a feed item, an upsell) and it
+ * emits `element_viewed` once, after it has been at least half on screen for a moment. Opt-in for the
+ * same reason the web marker is: the SDK cannot know which of a thousand views deserve an event, and
+ * guessing would bury the ones that do.
+ *
+ * ```tsx
+ * <ScaleBunImpression name="summer_promo" properties={{ slot: 'home_hero' }}>
+ *   <PromoCard />
+ * </ScaleBunImpression>
+ * ```
+ *
+ * All the geometry lives in `impression.ts` — this file is the shell that measures and schedules.
+ */
+
+function ScaleBunImpression({
+  name,
+  properties,
+  resetKey,
+  children,
+  onLayout,
+  ...rest
+}) {
+  const ref = (0, _react.useRef)(null);
+  const trackerRef = (0, _react.useRef)(null);
+  const timerRef = (0, _react.useRef)(null);
+  if (trackerRef.current == null) {
+    trackerRef.current = new _impression.ImpressionTracker(dwellMs => {
+      (0, _automaticEvents.emitAutomaticEvent)('element_viewed', {
+        ...properties,
+        name,
+        dwell_ms: Math.round(dwellMs)
+      });
+    });
+  }
+
+  // A recycled row is a NEW impression even though React kept the instance — without this a FlatList
+  // would report the first item it ever rendered and nothing else.
+  (0, _react.useEffect)(() => {
+    trackerRef.current?.reset();
+  }, [resetKey]);
+
+  /**
+   * Measure against the window and feed the tracker.
+   *
+   * `measureInWindow` is the only way to know where a view sits after an arbitrary ancestor scrolls,
+   * and it is async — so the dwell rule is satisfied by measuring twice, once now and once after the
+   * dwell window, rather than by polling. That costs two measurements per element instead of a timer
+   * running for every tracked view on screen.
+   */
+  const sample = (0, _react.useCallback)(() => {
+    const node = ref.current;
+    const tracker = trackerRef.current;
+    if (!node || !tracker || tracker.hasFired) return;
+    try {
+      node.measureInWindow((x, y, width, height) => {
+        const t = trackerRef.current;
+        if (!t || t.hasFired) return;
+        const win = _reactNative.Dimensions.get('window');
+        const viewport = {
+          x: 0,
+          y: 0,
+          width: win.width,
+          height: win.height
+        };
+        const el = {
+          x,
+          y,
+          width,
+          height
+        };
+        t.update(el, viewport, Date.now());
+        if (t.hasFired || timerRef.current) return;
+        // Visible but not yet held long enough — re-measure once when the dwell would be satisfied.
+        timerRef.current = setTimeout(() => {
+          timerRef.current = null;
+          sample();
+        }, _impression.IMPRESSION_DWELL_MS);
+      });
+    } catch {
+      /* measure unavailable (unmounted mid-flight) — an impression is never worth a crash */
+    }
+  }, []);
+  (0, _react.useEffect)(() => () => {
+    if (timerRef.current) clearTimeout(timerRef.current);
+  }, []);
+  const handleLayout = (0, _react.useCallback)(e => {
+    onLayout?.(e);
+    sample();
+  }, [onLayout, sample]);
+  return /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.View, {
+    ref: ref,
+    onLayout: handleLayout,
+    collapsable: false,
+    ...rest,
+    children: children
+  });
+}
+//# sourceMappingURL=ScaleBunImpression.js.map

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

@@ -0,0 +1,102 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.ScaleBunScrollView = void 0;
+var _react = _interopRequireWildcard(require("react"));
+var _reactNative = require("react-native");
+var _jsxRuntime = require("react/jsx-runtime");
+function _interopRequireWildcard(e, t) { if ("function" == typeof WeakMap) var r = new WeakMap(), n = new WeakMap(); return (_interopRequireWildcard = function (e, t) { if (!t && e && e.__esModule) return e; var o, i, f = { __proto__: null, default: e }; if (null === e || "object" != typeof e && "function" != typeof e) return f; if (o = t ? n : r) { if (o.has(e)) return o.get(e); o.set(e, f); } for (const t in e) "default" !== t && {}.hasOwnProperty.call(e, t) && ((i = (o = Object.defineProperty) && Object.getOwnPropertyDescriptor(e, t)) && (i.get || i.set) ? o(f, t, i) : f[t] = e[t]); return f; })(e, t); }
+/**
+ * ScaleBun SDK — ScaleBunScrollView
+ *
+ * Instrumented ScrollView wrapper for scroll tracking.
+ * Feeds scroll events from actual scrollable surfaces into the SessionManager's
+ * ScrollTracker for proper settle detection, metadata accumulation, and
+ * post-scroll frame capture.
+ *
+ * Usage:
+ *   import { ScaleBunScrollView } from 'scalebun-react-native';
+ *
+ *   <ScaleBunScrollView style={{flex: 1}}>
+ *     {children}
+ *   </ScaleBunScrollView>
+ *
+ * Also works with FlatList / SectionList via renderScrollComponent:
+ *   <FlatList renderScrollComponent={props => <ScaleBunScrollView {...props} />} />
+ *
+ * This component is transparent — it passes all props through to the underlying
+ * ScrollView and does NOT consume or interfere with any scroll events.
+ */
+
+let _getSessionManager = null;
+function getSessionManager() {
+  if (!_getSessionManager) {
+    try {
+      const bs = require('../../debug/bootstrap');
+      _getSessionManager = () => bs._getSessionManager();
+    } catch {
+      _getSessionManager = () => null;
+    }
+  }
+  return _getSessionManager();
+}
+const ScaleBunScrollView = exports.ScaleBunScrollView = /*#__PURE__*/_react.default.forwardRef(function ScaleBunScrollView(props, ref) {
+  const {
+    onScroll: userOnScroll,
+    ...restProps
+  } = props;
+  const handleScroll = (0, _react.useCallback)(event => {
+    // Feed scroll data to SessionManager
+    try {
+      const sm = getSessionManager();
+      if (sm && sm.isActive && typeof sm.onScrollEvent === 'function') {
+        const {
+          contentOffset
+        } = event.nativeEvent;
+        sm.onScrollEvent(contentOffset.x, contentOffset.y);
+      }
+    } catch {/* no-throw */}
+
+    /**
+     * RN-3 — record WHERE THIS scroller sits, keyed by its own native tag, so a later
+     * tap can say which content was under the finger.
+     *
+     * OUTSIDE the `isActive` guard above, deliberately. That guard is correct for the
+     * gesture tracker, which produces scroll EVENTS and should only do so while
+     * recording. This is a different thing: it is the position a tap needs in order to
+     * be placed in content rather than on glass, and a tap is captured on the always-on
+     * analytics lane even when no recording is active. Gating this the same way would
+     * make content depth absent in exactly the sessions the heatmap is built from.
+     *
+     * The tag is taken from the EVENT's target rather than from this component's ref,
+     * so it identifies the scroller that actually moved. With nested scrollers the
+     * event may come from an inner one, and keying by the wrapper would file the
+     * carousel's offset under the list.
+     */
+    try {
+      const {
+        recordScrollOffset,
+        nativeTagOf
+      } = require('./scrollContext');
+      const {
+        contentOffset,
+        target
+      } = event.nativeEvent;
+      recordScrollOffset(typeof target === 'number' ? target : nativeTagOf(target), contentOffset.x, contentOffset.y);
+    } catch {/* no-throw */}
+
+    // Forward to user's onScroll handler
+    if (userOnScroll) {
+      userOnScroll(event);
+    }
+  }, [userOnScroll]);
+  return /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.ScrollView, {
+    ref: ref,
+    scrollEventThrottle: 16,
+    ...restProps,
+    onScroll: handleScroll
+  });
+});
+//# sourceMappingURL=ScaleBunScrollView.js.map

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

@@ -0,0 +1,39 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.ScaleBunSectionList = void 0;
+var _react = _interopRequireDefault(require("react"));
+var _reactNative = require("react-native");
+var _ScaleBunScrollView = require("./ScaleBunScrollView");
+var _jsxRuntime = require("react/jsx-runtime");
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+/**
+ * ScaleBun SDK — ScaleBunSectionList
+ *
+ * Instrumented SectionList wrapper for scroll tracking.
+ * Uses `renderScrollComponent` to inject ScaleBunScrollView so that all
+ * scroll events from the SectionList flow through the SessionManager's
+ * ScrollTracker for settle detection and post-scroll frame capture.
+ *
+ * Usage:
+ *   import { ScaleBunSectionList } from 'scalebun-react-native';
+ *
+ *   <ScaleBunSectionList sections={sections} renderItem={renderItem} />
+ *
+ * This component is transparent — it passes all props through to the
+ * underlying SectionList and does NOT consume or interfere with any scroll events.
+ */
+
+function ScaleBunSectionListInner(props, ref) {
+  return /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.SectionList, {
+    ref: ref,
+    ...props,
+    renderScrollComponent: scrollProps => /*#__PURE__*/(0, _jsxRuntime.jsx)(_ScaleBunScrollView.ScaleBunScrollView, {
+      ...scrollProps
+    })
+  });
+}
+const ScaleBunSectionList = exports.ScaleBunSectionList = /*#__PURE__*/_react.default.forwardRef(ScaleBunSectionListInner);
+//# sourceMappingURL=ScaleBunSectionList.js.map

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

@@ -0,0 +1,161 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.autoInstrumentScrollViews = autoInstrumentScrollViews;
+exports.resetAutoInstrumentForTests = resetAutoInstrumentForTests;
+var _scrollContext = require("./scrollContext");
+/**
+ * RN-3, ZERO-CONFIG — make every ScrollView report its offset, not just the wrapped ones.
+ *
+ * THE PROBLEM THIS SOLVES. Scroll offsets reach the SDK from `ScaleBunScrollView` and nowhere
+ * else, so an app using React Native's own `<ScrollView>` — which is most apps — produces taps
+ * with no content depth at all. Two taps at the same screen coordinate one viewport apart then
+ * merge into one hotspot, and the heatmap shows heavy engagement at a position where, in content
+ * terms, nothing in particular is. Asking every integration to swap its scroll views is a real
+ * migration cost and will never reach the long tail.
+ *
+ * WHY IT IS OFF BY DEFAULT, and why that is not timidity. This patches React Native's own module
+ * exports. Every scroll view in the host app — including ones inside third-party libraries the
+ * app did not write — starts routing through an SDK component. The failure mode of getting that
+ * wrong is not a wrong number in a dashboard, it is the host's UI behaving differently because an
+ * analytics SDK replaced a primitive. That is a decision an integrator makes with their eyes open,
+ * not a default they discover afterwards.
+ *
+ * THE PRECEDENT, AND ITS LESSON. The SDK already patches `@react-navigation/native` this way
+ * (`AutoScreenDetector._autoHookReactNavigation`). That hook shipped BROKEN: it assigned to module
+ * exports that are getters, which throws in strict mode, inside a `catch` that discarded the
+ * error. It reported success, captured no ref, and the whole screen-name pipeline stayed empty
+ * with nothing to indicate it. So this uses the same defence that fixed it — define the property
+ * rather than assign to it, then READ IT BACK — and refuses to claim success it has not verified.
+ *
+ * WHAT IT DELIBERATELY DOES NOT PATCH. `FlatList` and `SectionList` render a `ScrollView`
+ * internally, so patching that one export covers them without touching three. Fewer patch points
+ * is fewer ways to be wrong, and RN-4's row identity comes off the fiber regardless of which
+ * component rendered it.
+ */
+
+let alreadyPatched = false;
+
+/**
+ * Replace an export on a module whose exports are GETTERS.
+ *
+ * React Native's index is compiled re-exports, which bundlers emit as accessors with a getter and
+ * no setter. Plain assignment throws in strict mode and silently does nothing in sloppy mode.
+ * Defining the property works where assigning does not, and the read-back is what turns a future
+ * failure into a visible one instead of a silent no-op.
+ */
+function redefine(target, key, value) {
+  try {
+    Object.defineProperty(target, key, {
+      configurable: true,
+      enumerable: true,
+      writable: true,
+      value
+    });
+    return target[key] === value;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Wrap a scroll component so its offsets are recorded, forwarding everything else untouched.
+ *
+ * The host's own `onScroll` is called AFTER the offset is recorded and is never replaced: an SDK
+ * that swallows a host's handler breaks the app, which is a far worse outcome than missing
+ * analytics. Recording first also means a throwing host handler cannot cost us the measurement.
+ */
+function instrument(Original, React) {
+  const Wrapped = React.forwardRef((props, ref) => {
+    const onScroll = event => {
+      try {
+        const target = event?.nativeEvent?.target;
+        const offset = event?.nativeEvent?.contentOffset;
+        if (offset) {
+          (0, _scrollContext.recordScrollOffset)(typeof target === 'number' ? target : (0, _scrollContext.nativeTagOf)(target), offset.x, offset.y);
+        }
+      } catch {
+        /* no-throw: a scroll offset is never worth breaking a gesture over */
+      }
+      try {
+        props?.onScroll?.(event);
+      } catch (e) {
+        /* The host's handler is the host's problem, but it must still run and still throw where
+           they can see it — rethrow on a later tick so this wrapper is not in the stack. */
+        setTimeout(() => {
+          throw e;
+        }, 0);
+      }
+    };
+    /**
+     * `scrollEventThrottle` defaults to 16 only when the host has not chosen one. Overriding a
+     * host's explicit value would change how often their own handler runs — a behaviour change
+     * for a measurement, which is exactly the trade this module is not allowed to make.
+     */
+    const throttle = props?.scrollEventThrottle ?? 16;
+    return React.createElement(Original, {
+      ...props,
+      scrollEventThrottle: throttle,
+      onScroll,
+      ref
+    });
+  });
+  Wrapped.displayName = 'ScaleBunAutoScrollView';
+  return Wrapped;
+}
+
+/**
+ * Patch React Native's `ScrollView` export so every scroll view reports its offset.
+ *
+ * Idempotent, no-throw, and honest about failure: returns `installed: false` with a reason rather
+ * than claiming a success it did not verify.
+ */
+function autoInstrumentScrollViews() {
+  if (alreadyPatched) return {
+    installed: true
+  };
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    const RN = require('react-native');
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    const React = require('react');
+    const Original = RN.ScrollView;
+    if (typeof Original !== 'function' && typeof Original !== 'object') {
+      return {
+        installed: false,
+        reason: 'react-native has no ScrollView export to wrap'
+      };
+    }
+    if (Original.__scalebunInstrumented) {
+      alreadyPatched = true;
+      return {
+        installed: true
+      };
+    }
+    const Wrapped = instrument(Original, React);
+    Wrapped.__scalebunInstrumented = true;
+    if (!redefine(RN, 'ScrollView', Wrapped)) {
+      return {
+        installed: false,
+        reason: "react-native's ScrollView export could not be replaced — it is a getter with no " + 'configurable descriptor on this bundler. Use ScaleBunScrollView explicitly instead.'
+      };
+    }
+    alreadyPatched = true;
+    return {
+      installed: true
+    };
+  } catch (e) {
+    return {
+      installed: false,
+      reason: e?.message ?? 'unknown failure'
+    };
+  }
+}
+
+/** Test seam: forget that the patch ran, so a suite can exercise it more than once. */
+function resetAutoInstrumentForTests() {
+  alreadyPatched = false;
+}
+//# sourceMappingURL=autoInstrumentScroll.js.map

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

@@ -0,0 +1,42 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.consumeCalibrationTarget = consumeCalibrationTarget;
+exports.setCalibrationTarget = setCalibrationTarget;
+/**
+ * ScaleBun SDK — Calibration Context (diagnostic-only)
+ *
+ * Lets a calibration screen stamp the *expected* target for the next gesture
+ * event so the SDK and dashboard can compare expected vs. captured coordinates.
+ *
+ * Pure observability: SessionManager merges these fields into the gesture
+ * payload but does NOT use them to adjust normalization, offsets, or marker
+ * placement. They flow through unchanged for the dashboard to display.
+ *
+ * TTL guards against a stale calibration target leaking onto a non-calibration
+ * gesture (e.g., the user taps a real button shortly after a calibration tap).
+ */
+
+const TTL_MS = 500;
+let pending = null;
+function setCalibrationTarget(target) {
+  pending = {
+    targetId: target.targetId,
+    expectedNX: target.expectedNX,
+    expectedNY: target.expectedNY,
+    setAt: Date.now()
+  };
+}
+function consumeCalibrationTarget() {
+  if (!pending) return null;
+  if (Date.now() - pending.setAt > TTL_MS) {
+    pending = null;
+    return null;
+  }
+  const out = pending;
+  pending = null;
+  return out;
+}
+//# sourceMappingURL=calibrationContext.js.map

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

@@ -0,0 +1,63 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.GestureBuffer = void 0;
+/**
+ * ScaleBun SDK — Gesture Buffer
+ *
+ * Ring buffer of recent gesture events with time-windowed matching.
+ * Used by JourneyManager to match desktop-requested gesture mode
+ * with the most recent matching gesture on the device.
+ */
+
+class GestureBuffer {
+  buffer = [];
+  constructor(maxSize = 50) {
+    this.maxSize = maxSize;
+  }
+
+  /** Push a gesture event into the buffer */
+  push(gesture) {
+    this.buffer.push(gesture);
+    if (this.buffer.length > this.maxSize) {
+      this.buffer.shift(); // Drop oldest
+    }
+  }
+
+  /**
+   * Find the most recent gesture matching the given type within the time window.
+   * Returns null if no match found.
+   */
+  matchRecent(type, windowMs = 3000) {
+    const now = Date.now();
+    const cutoff = now - windowMs;
+
+    // Search backwards (most recent first)
+    for (let i = this.buffer.length - 1; i >= 0; i--) {
+      const gesture = this.buffer[i];
+      if (gesture.timestamp < cutoff) break; // Past the window
+      if (gesture.type === type) return gesture;
+    }
+    return null;
+  }
+
+  /** Get all gestures within a time window */
+  getRecent(windowMs = 3000) {
+    const cutoff = Date.now() - windowMs;
+    return this.buffer.filter(g => g.timestamp >= cutoff);
+  }
+
+  /** Clear the buffer */
+  clear() {
+    this.buffer = [];
+  }
+
+  /** Get current buffer size */
+  get size() {
+    return this.buffer.length;
+  }
+}
+exports.GestureBuffer = GestureBuffer;
+//# sourceMappingURL=gestureBuffer.js.map