@scalebun/react-native 1.0.1 → 1.0.2

package/src/features/journey/ScaleBunFlatList.tsx

@@ -1,39 +1,39 @@
-/**
- * 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.
- */
-
-import React from 'react';
-import { FlatList, type FlatListProps } from 'react-native';
-import { ScaleBunScrollView } from './ScaleBunScrollView';
-
-function ScaleBunFlatListInner<T>(
-    props: FlatListProps<T>,
-    ref: React.Ref<FlatList<T>>,
-) {
-    return (
-        <FlatList
-            ref={ref}
-            {...props}
-            renderScrollComponent={(scrollProps) => (
-                <ScaleBunScrollView {...scrollProps} />
-            )}
-        />
-    );
-}
-
-export const ScaleBunFlatList = React.forwardRef(ScaleBunFlatListInner) as <T>(
-    props: FlatListProps<T> & React.RefAttributes<FlatList<T>>,
-) => React.ReactElement;
+/**
+ * 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.
+ */
+
+import React from 'react';
+import { FlatList, type FlatListProps } from 'react-native';
+import { ScaleBunScrollView } from './ScaleBunScrollView';
+
+function ScaleBunFlatListInner<T>(
+    props: FlatListProps<T>,
+    ref: React.Ref<FlatList<T>>,
+) {
+    return (
+        <FlatList
+            ref={ref}
+            {...props}
+            renderScrollComponent={(scrollProps) => (
+                <ScaleBunScrollView {...scrollProps} />
+            )}
+        />
+    );
+}
+
+export const ScaleBunFlatList = React.forwardRef(ScaleBunFlatListInner) as <T>(
+    props: FlatListProps<T> & React.RefAttributes<FlatList<T>>,
+) => React.ReactElement;

package/src/features/journey/ScaleBunImpression.tsx

@@ -1,109 +1,109 @@
-/**
- * `<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.
- */
-import React, { useCallback, useEffect, useRef } from 'react';
-import { View, Dimensions, type LayoutChangeEvent, type ViewProps } from 'react-native';
-import { emitAutomaticEvent } from '../../analytics/automaticEvents';
-import { ImpressionTracker, IMPRESSION_DWELL_MS, type Rect } from './impression';
-
-export interface ScaleBunImpressionProps extends ViewProps {
-  /** What was seen. This is the grouping key on the dashboard, so keep it stable. */
-  name: string;
-  /** Extra dimensions to slice by (slot, position, campaign…). No user content, please. */
-  properties?: Record<string, unknown>;
-  /** Re-arm when the underlying content changes — required for RECYCLED list rows, which keep the
-   *  same component instance while showing different items. */
-  resetKey?: string | number;
-  children?: React.ReactNode;
-}
-
-export function ScaleBunImpression({
-  name,
-  properties,
-  resetKey,
-  children,
-  onLayout,
-  ...rest
-}: ScaleBunImpressionProps) {
-  const ref = useRef<View | null>(null);
-  const trackerRef = useRef<ImpressionTracker | null>(null);
-  const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
-
-  if (trackerRef.current == null) {
-    trackerRef.current = new ImpressionTracker((dwellMs) => {
-      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.
-  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 = useCallback(() => {
-    const node = ref.current;
-    const tracker = trackerRef.current;
-    if (!node || !tracker || tracker.hasFired) return;
-    try {
-      node.measureInWindow((x: number, y: number, width: number, height: number) => {
-        const t = trackerRef.current;
-        if (!t || t.hasFired) return;
-        const win = Dimensions.get('window');
-        const viewport: Rect = { x: 0, y: 0, width: win.width, height: win.height };
-        const el: Rect = { 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_DWELL_MS);
-      });
-    } catch {
-      /* measure unavailable (unmounted mid-flight) — an impression is never worth a crash */
-    }
-  }, []);
-
-  useEffect(
-    () => () => {
-      if (timerRef.current) clearTimeout(timerRef.current);
-    },
-    [],
-  );
-
-  const handleLayout = useCallback(
-    (e: LayoutChangeEvent) => {
-      onLayout?.(e);
-      sample();
-    },
-    [onLayout, sample],
-  );
-
-  return (
-    <View ref={ref} onLayout={handleLayout} collapsable={false} {...rest}>
-      {children}
-    </View>
-  );
-}
+/**
+ * `<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.
+ */
+import React, { useCallback, useEffect, useRef } from 'react';
+import { View, Dimensions, type LayoutChangeEvent, type ViewProps } from 'react-native';
+import { emitAutomaticEvent } from '../../analytics/automaticEvents';
+import { ImpressionTracker, IMPRESSION_DWELL_MS, type Rect } from './impression';
+
+export interface ScaleBunImpressionProps extends ViewProps {
+  /** What was seen. This is the grouping key on the dashboard, so keep it stable. */
+  name: string;
+  /** Extra dimensions to slice by (slot, position, campaign…). No user content, please. */
+  properties?: Record<string, unknown>;
+  /** Re-arm when the underlying content changes — required for RECYCLED list rows, which keep the
+   *  same component instance while showing different items. */
+  resetKey?: string | number;
+  children?: React.ReactNode;
+}
+
+export function ScaleBunImpression({
+  name,
+  properties,
+  resetKey,
+  children,
+  onLayout,
+  ...rest
+}: ScaleBunImpressionProps) {
+  const ref = useRef<View | null>(null);
+  const trackerRef = useRef<ImpressionTracker | null>(null);
+  const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  if (trackerRef.current == null) {
+    trackerRef.current = new ImpressionTracker((dwellMs) => {
+      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.
+  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 = useCallback(() => {
+    const node = ref.current;
+    const tracker = trackerRef.current;
+    if (!node || !tracker || tracker.hasFired) return;
+    try {
+      node.measureInWindow((x: number, y: number, width: number, height: number) => {
+        const t = trackerRef.current;
+        if (!t || t.hasFired) return;
+        const win = Dimensions.get('window');
+        const viewport: Rect = { x: 0, y: 0, width: win.width, height: win.height };
+        const el: Rect = { 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_DWELL_MS);
+      });
+    } catch {
+      /* measure unavailable (unmounted mid-flight) — an impression is never worth a crash */
+    }
+  }, []);
+
+  useEffect(
+    () => () => {
+      if (timerRef.current) clearTimeout(timerRef.current);
+    },
+    [],
+  );
+
+  const handleLayout = useCallback(
+    (e: LayoutChangeEvent) => {
+      onLayout?.(e);
+      sample();
+    },
+    [onLayout, sample],
+  );
+
+  return (
+    <View ref={ref} onLayout={handleLayout} collapsable={false} {...rest}>
+      {children}
+    </View>
+  );
+}

package/src/features/journey/ScaleBunScrollView.tsx

@@ -1,72 +1,72 @@
-/**
- * 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.
- */
-
-import React, { useCallback, useRef } from 'react';
-import { ScrollView, type ScrollViewProps, type NativeScrollEvent, type NativeSyntheticEvent } from 'react-native';
-
-let _getSessionManager: (() => any) | null = null;
-
-function getSessionManager(): any {
-    if (!_getSessionManager) {
-        try {
-            const bs = require('../../debug/bootstrap');
-            _getSessionManager = () => bs._getSessionManager();
-        } catch {
-            _getSessionManager = () => null;
-        }
-    }
-    return _getSessionManager();
-}
-
-export const ScaleBunScrollView = React.forwardRef<ScrollView, ScrollViewProps>(
-    function ScaleBunScrollView(props, ref) {
-        const { onScroll: userOnScroll, ...restProps } = props;
-
-        const handleScroll = useCallback(
-            (event: NativeSyntheticEvent<NativeScrollEvent>) => {
-                // 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 */ }
-
-                // Forward to user's onScroll handler
-                if (userOnScroll) {
-                    userOnScroll(event);
-                }
-            },
-            [userOnScroll],
-        );
-
-        return (
-            <ScrollView
-                ref={ref}
-                scrollEventThrottle={16}
-                {...restProps}
-                onScroll={handleScroll}
-            />
-        );
-    },
-);
+/**
+ * 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.
+ */
+
+import React, { useCallback, useRef } from 'react';
+import { ScrollView, type ScrollViewProps, type NativeScrollEvent, type NativeSyntheticEvent } from 'react-native';
+
+let _getSessionManager: (() => any) | null = null;
+
+function getSessionManager(): any {
+    if (!_getSessionManager) {
+        try {
+            const bs = require('../../debug/bootstrap');
+            _getSessionManager = () => bs._getSessionManager();
+        } catch {
+            _getSessionManager = () => null;
+        }
+    }
+    return _getSessionManager();
+}
+
+export const ScaleBunScrollView = React.forwardRef<ScrollView, ScrollViewProps>(
+    function ScaleBunScrollView(props, ref) {
+        const { onScroll: userOnScroll, ...restProps } = props;
+
+        const handleScroll = useCallback(
+            (event: NativeSyntheticEvent<NativeScrollEvent>) => {
+                // 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 */ }
+
+                // Forward to user's onScroll handler
+                if (userOnScroll) {
+                    userOnScroll(event);
+                }
+            },
+            [userOnScroll],
+        );
+
+        return (
+            <ScrollView
+                ref={ref}
+                scrollEventThrottle={16}
+                {...restProps}
+                onScroll={handleScroll}
+            />
+        );
+    },
+);

package/src/features/journey/ScaleBunSectionList.tsx

@@ -1,39 +1,39 @@
-/**
- * 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.
- */
-
-import React from 'react';
-import { SectionList, type SectionListProps } from 'react-native';
-import { ScaleBunScrollView } from './ScaleBunScrollView';
-
-function ScaleBunSectionListInner<T, S>(
-    props: SectionListProps<T, S>,
-    ref: React.Ref<SectionList<T, S>>,
-) {
-    return (
-        <SectionList
-            ref={ref}
-            {...props}
-            renderScrollComponent={(scrollProps) => (
-                <ScaleBunScrollView {...scrollProps} />
-            )}
-        />
-    );
-}
-
-export const ScaleBunSectionList = React.forwardRef(ScaleBunSectionListInner) as <T, S = any>(
-    props: SectionListProps<T, S> & React.RefAttributes<SectionList<T, S>>,
-) => React.ReactElement;
+/**
+ * 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.
+ */
+
+import React from 'react';
+import { SectionList, type SectionListProps } from 'react-native';
+import { ScaleBunScrollView } from './ScaleBunScrollView';
+
+function ScaleBunSectionListInner<T, S>(
+    props: SectionListProps<T, S>,
+    ref: React.Ref<SectionList<T, S>>,
+) {
+    return (
+        <SectionList
+            ref={ref}
+            {...props}
+            renderScrollComponent={(scrollProps) => (
+                <ScaleBunScrollView {...scrollProps} />
+            )}
+        />
+    );
+}
+
+export const ScaleBunSectionList = React.forwardRef(ScaleBunSectionListInner) as <T, S = any>(
+    props: SectionListProps<T, S> & React.RefAttributes<SectionList<T, S>>,
+) => React.ReactElement;

package/src/features/journey/calibrationContext.ts

@@ -1,53 +1,53 @@
-/**
- * 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).
- */
-
-export interface CalibrationTarget {
-    targetId: string;
-    expectedNX: number;
-    expectedNY: number;
-    setAt: number;
-}
-
-const TTL_MS = 500;
-
-let pending: CalibrationTarget | null = null;
-
-export function setCalibrationTarget(target: { targetId: string; expectedNX: number; expectedNY: number }): void {
-    pending = {
-        targetId: target.targetId,
-        expectedNX: target.expectedNX,
-        expectedNY: target.expectedNY,
-        setAt: Date.now(),
-    };
-}
-
-export function consumeCalibrationTarget(): CalibrationTarget | null {
-    if (!pending) return null;
-    if (Date.now() - pending.setAt > TTL_MS) {
-        pending = null;
-        return null;
-    }
-    const out = pending;
-    pending = null;
-    return out;
-}
-
-export function peekCalibrationTarget(): CalibrationTarget | null {
-    if (!pending) return null;
-    if (Date.now() - pending.setAt > TTL_MS) {
-        pending = null;
-        return null;
-    }
-    return pending;
-}
+/**
+ * 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).
+ */
+
+export interface CalibrationTarget {
+    targetId: string;
+    expectedNX: number;
+    expectedNY: number;
+    setAt: number;
+}
+
+const TTL_MS = 500;
+
+let pending: CalibrationTarget | null = null;
+
+export function setCalibrationTarget(target: { targetId: string; expectedNX: number; expectedNY: number }): void {
+    pending = {
+        targetId: target.targetId,
+        expectedNX: target.expectedNX,
+        expectedNY: target.expectedNY,
+        setAt: Date.now(),
+    };
+}
+
+export function consumeCalibrationTarget(): CalibrationTarget | null {
+    if (!pending) return null;
+    if (Date.now() - pending.setAt > TTL_MS) {
+        pending = null;
+        return null;
+    }
+    const out = pending;
+    pending = null;
+    return out;
+}
+
+export function peekCalibrationTarget(): CalibrationTarget | null {
+    if (!pending) return null;
+    if (Date.now() - pending.setAt > TTL_MS) {
+        pending = null;
+        return null;
+    }
+    return pending;
+}