@scalebun-release/react-native 2.5.0

package/src/features/session/SyncDecisionEngine.ts

@@ -0,0 +1,117 @@
+/**
+ * ScaleBun SDK — Sync Decision Engine
+ *
+ * Evaluates session sync eligibility. This engine OWNS the policy —
+ * native layers only gather metadata and expose callback hooks.
+ *
+ * Default behavior in desktop mode: always eligible.
+ * Host apps can provide a custom SyncDecisionCallback for advanced logic.
+ */
+
+import { logger } from '../../core/logger/internalLogger';
+import type {
+    SyncCandidate,
+    SyncDecision,
+    SyncDecisionCallback,
+    NativeSyncMetadata,
+    SessionMetadata,
+} from './sessionTypes';
+
+// ─── Default Policy ─────────────────────────────────────────────────────────
+
+/**
+ * Default sync decision: always eligible in desktop mode.
+ * Sessions with crashes get high priority.
+ */
+function defaultSyncPolicy(candidate: SyncCandidate): SyncDecision {
+    // Always eligible locally
+    const priority = candidate.hasCrash
+        ? 'high' as const
+        : candidate.hasError
+            ? 'normal' as const
+            : 'low' as const;
+
+    return {
+        shouldSync: true,
+        reason: 'desktop-mode: always eligible',
+        priority,
+    };
+}
+
+// ─── Engine ─────────────────────────────────────────────────────────────────
+
+export class SyncDecisionEngine {
+    private _policy: SyncDecisionCallback;
+
+    constructor(customPolicy?: SyncDecisionCallback) {
+        this._policy = customPolicy ?? defaultSyncPolicy;
+    }
+
+    /**
+     * Replace the sync policy callback.
+     * Used by host apps to provide custom eligibility logic.
+     */
+    setPolicy(policy: SyncDecisionCallback): void {
+        this._policy = policy;
+    }
+
+    /**
+     * Evaluate whether a session should be synced.
+     * Native metadata is merged into the candidate before evaluation.
+     *
+     * @param candidate - Session metadata + stats
+     * @param nativeMetadata - Optional metadata gathered by native layer
+     */
+    evaluate(candidate: SyncCandidate, nativeMetadata?: NativeSyncMetadata): SyncDecision {
+        try {
+            // Merge native metadata if provided
+            const enrichedCandidate: SyncCandidate = nativeMetadata
+                ? { ...candidate, nativeMetadata }
+                : candidate;
+
+            const decision = this._policy(enrichedCandidate);
+
+            __DEV__ && logger.debug(
+                `[SyncDecisionEngine] Session ${candidate.sessionId}: ` +
+                `shouldSync=${decision.shouldSync}, priority=${decision.priority}, ` +
+                `reason="${decision.reason}"`,
+            );
+
+            return decision;
+        } catch (err) {
+            // Policy must never crash the session flow
+            logger.error('[SyncDecisionEngine] Policy evaluation failed:', err);
+            return {
+                shouldSync: false,
+                reason: 'policy-error: evaluation threw',
+                priority: 'low',
+            };
+        }
+    }
+
+    /**
+     * Build a SyncCandidate from session state.
+     * Convenience helper to avoid constructing the object manually.
+     */
+    static buildCandidate(
+        sessionId: string,
+        metadata: SessionMetadata,
+        eventCount: number,
+        frameCount: number,
+        durationMs: number,
+        hasCrash: boolean,
+        hasError: boolean,
+        nativeMetadata?: NativeSyncMetadata,
+    ): SyncCandidate {
+        return {
+            sessionId,
+            metadata,
+            nativeMetadata,
+            eventCount,
+            frameCount,
+            durationMs,
+            hasCrash,
+            hasError,
+        };
+    }
+}

package/src/features/session/frameLink.ts

@@ -0,0 +1,41 @@
+/**
+ * SHOULD THIS TAP BE LINKED TO THIS KEYFRAME?
+ *
+ * A tap is stamped with the last keyframe of its screen (≤10 s old). Once frames carry the scroll
+ * containers visible in them, that link can be CHECKED instead of assumed: a tap made after the list
+ * was scrolled is not a tap on the picture taken before the scroll, and linking the two presents a
+ * different row as the one that was tapped.
+ *
+ *   'linked'      the frame shows the tap's scroll container at the same offset (±4), or the tap was
+ *                 not in a scroll container
+ *   'unverified'  the tap was in a container but the frame carries no scroll record (older native
+ *                 build) — linked, and marked so a reader knows it was not checked
+ *   'scroll_moved' the frame shows the container at another offset, or does not show it: NOT linked
+ *   'none'        there was no fresh keyframe of this screen
+ */
+export type FrameLink = 'linked' | 'unverified' | 'scroll_moved' | 'none';
+
+export const FRAME_OFFSET_TOL = 4;
+
+interface ScrollEntryLike {
+  containerTag?: number | null;
+  offsetX?: number;
+  offsetY?: number;
+}
+
+export function frameLinkVerdict(
+  frame: { scrollState?: ScrollEntryLike[] } | null | undefined,
+  tapScroll: unknown,
+): FrameLink {
+  if (!frame) return 'none';
+  const chain = Array.isArray(tapScroll) ? (tapScroll as ScrollEntryLike[]) : [];
+  const inner = chain[0];
+  if (!inner || typeof inner.offsetX !== 'number' || typeof inner.offsetY !== 'number') return 'linked';
+  if (!frame.scrollState) return 'unverified';
+  if (inner.containerTag == null) return 'unverified';
+  const same = frame.scrollState.find((e) => e.containerTag === inner.containerTag);
+  if (!same || typeof same.offsetX !== 'number' || typeof same.offsetY !== 'number') return 'scroll_moved';
+  return Math.abs(same.offsetX - inner.offsetX) <= FRAME_OFFSET_TOL && Math.abs(same.offsetY - inner.offsetY) <= FRAME_OFFSET_TOL
+    ? 'linked'
+    : 'scroll_moved';
+}

package/src/features/session/frameScrollState.ts

@@ -0,0 +1,36 @@
+/**
+ * A FRAME'S SCROLL STATE — every visible scroll container at the moment the screenshot was taken.
+ *
+ * A frame that carries only width/height cannot say whether a tap belongs on it: a tap inside a
+ * list scrolled 900px lands on different content than the same point on a frame taken at offset 0.
+ * Native reads the visible scroll containers on the main thread immediately before the pixels
+ * (Android ScrollContextProbe.snapshot, iOS ScreenshotCaptureManager.visibleScrollState), with the
+ * same keys as a tap's `scrollContext`, so a tap is compatible with a frame when its container
+ * reports the same offset in both.
+ *
+ * Units follow the tap on each platform: Android capture-view pixels, iOS points.
+ *
+ * `undefined` = not measured (old native binary, or a snapshot that failed). `[]` = measured and
+ * no scroll container was on screen. The two are never collapsed: an absent measurement must not
+ * read as "nothing scrolls here".
+ */
+
+import { sanitizeScrollContext, type NativeScrollEntry } from '../journey/nativeScroll';
+
+export type FrameScrollEntry = NativeScrollEntry;
+
+/** Same cap as the native side and the backend DTO. */
+export const MAX_FRAME_SCROLL_ENTRIES = 4;
+
+/**
+ * Keep only well-formed entries (finite offsets; other numeric fields dropped unless finite),
+ * at most 4. A non-array is "not measured" and stays undefined; a malformed payload must never
+ * become a fabricated offset.
+ */
+export function sanitizeFrameScrollState(raw: unknown): FrameScrollEntry[] | undefined {
+    if (!Array.isArray(raw)) return undefined;
+    const clean = sanitizeScrollContext(raw).slice(0, MAX_FRAME_SCROLL_ENTRIES);
+    // Entries were present but none survived: that is an unreadable measurement, not "none on screen".
+    if (raw.length > 0 && clean.length === 0) return undefined;
+    return clean;
+}

package/src/features/session/index.ts

@@ -0,0 +1,88 @@
+/**
+ * ScaleBun SDK — Unified Session Feature
+ *
+ * Public API surface for the unified session system.
+ * Re-exports all domain types, contracts, configs, and constants.
+ */
+
+// ─── Domain Types ───────────────────────────────────────────────────────────
+
+export type {
+    Session,
+    SessionMetadata,
+    SessionStatus,
+    JourneyEvent,
+    JourneyEventType,
+    JourneyEventSeverity,
+    JourneyEventSource,
+    ReplayFrame,
+    CaptureReason,
+    SessionArtifactIndex,
+    CrashAnchor,
+} from './sessionTypes';
+
+// ─── Configuration ──────────────────────────────────────────────────────────
+
+export type {
+    CaptureMode,
+    ReplayQuality,
+    SessionReplayConfig,
+    PrivacyPolicy,
+} from './sessionTypes';
+
+export {
+    DEFAULT_SESSION_REPLAY_CONFIG,
+    QUALITY_PRESETS,
+} from './sessionTypes';
+
+// ─── Transport Contracts ────────────────────────────────────────────────────
+
+export type {
+    TransportState,
+    SessionTransport,
+} from './sessionTypes';
+
+// ─── Sync Contracts ─────────────────────────────────────────────────────────
+
+export type {
+    SyncState,
+    SyncCandidate,
+    SyncDecision,
+    SyncDecisionCallback,
+    NativeSyncMetadata,
+} from './sessionTypes';
+
+// ─── Native Capture Types ───────────────────────────────────────────────────
+
+export type {
+    NativeFrameResult,
+    NativeDeviceMetadata,
+} from './sessionTypes';
+
+// ─── Retention Policies ─────────────────────────────────────────────────────
+
+export {
+    FrameRetentionPriority,
+    getFrameRetentionPriority,
+    EventRetentionPriority,
+    getEventRetentionPriority,
+} from './sessionTypes';
+
+// ─── Protocol Constants ─────────────────────────────────────────────────────
+
+export { SESSION_EVENTS } from './sessionTypes';
+
+// ─── SDK Integration Layer ──────────────────────────────────────────────────
+
+export { SessionManager } from './SessionManager';
+export type { SessionManagerConfig } from './SessionManager';
+
+export { JourneyEventPipeline } from './JourneyEventPipeline';
+export type { EventEmitCallback } from './JourneyEventPipeline';
+
+export { ReplayCaptureManager } from './ReplayCaptureManager';
+export type { NativeCaptureFn, FrameEmitCallback } from './ReplayCaptureManager';
+
+export { DesktopSessionTransport } from './DesktopSessionTransport';
+
+export { SyncDecisionEngine } from './SyncDecisionEngine';

package/src/features/session/nativeCapture.ts

@@ -0,0 +1,43 @@
+/**
+ * ScaleBun SDK — Native Frame Capture
+ *
+ * Provides the callback for the SessionManager to request screenshots
+ * from the native layer (PixelCopy on Android, UIWindow on iOS).
+ */
+import { resolvePlatformOS, type PlatformOS } from '../../core/context/device';
+import { sanitizeFrameScrollState } from './frameScrollState';
+
+export const nativeCapture = async (sessionId: string, reason: string, _quality: any) => {
+    try {
+        // Resolve via the TurboModule-aware accessor (New Arch / bridgeless).
+        // Reading raw `NativeModules.ReplaySdk` returns null under bridgeless New
+        // Architecture, so frame capture silently no-ops → 0 frames.
+        const { getReplaySdkNative } = require('../replay/bridge/nativeModule');
+        const replaySdk: any = getReplaySdkNative();
+        if (!replaySdk?.captureScreenshot) return null;
+
+        const result = await replaySdk.captureScreenshot(reason);
+        if (!result?.base64) return null;
+
+        // Platform.OS verbatim. The ternary this replaces labelled every non-iOS frame 'android'.
+        const platform: PlatformOS = resolvePlatformOS();
+        // Visible scroll containers read beside the pixels; undefined when native did not measure.
+        const scrollState = sanitizeFrameScrollState(result.scrollState);
+
+        return {
+            base64: result.base64 as string,
+            width: (result.width ?? 0) as number,
+            height: (result.height ?? 0) as number,
+            byteSize: (result.sizeBytes ?? result.byteSize ?? 0) as number,
+            // P2-2: actual on-device encoding after the AVIF->WebP->JPEG fallback.
+            format: (result.format ?? 'jpeg') as string,
+            // P2-1: native-provided change-detection hash (perceptual or content);
+            // undefined when native doesn't supply one (JS falls back to base64 hash).
+            frameHash: result.frameHash as string | undefined,
+            platform,
+            ...(scrollState ? { scrollState } : {}),
+        };
+    } catch {
+        return null;
+    }
+};

package/src/features/session/outboxFrameCapture.ts

@@ -0,0 +1,79 @@
+/**
+ * ScaleBun SDK — Native File-Outbox Frame Capture Adapter
+ *
+ * Wraps the native staged-frame bridge for ReplayCaptureManager. The capture step
+ * captures + masks + encodes natively and STAGES the image (no upload marker), so
+ * the JS orchestrator keeps full ownership of sequencing / keyframe-delta /
+ * change-detection. The orchestrator then commits (writes JS-authoritative meta →
+ * uploadable) or discards (suppressed) the staged frame.
+ *
+ * No frame bytes/base64 ever cross the bridge on this path — capture returns
+ * metadata + a native content hash only.
+ *
+ * Every method is no-throw and gated by a readiness check so that with the flag
+ * off (or an old native binary) `capture` returns null and ReplayCaptureManager
+ * transparently falls back to the legacy `captureScreenshot` path.
+ */
+
+import { getReplaySdkNative } from '../replay/bridge/nativeModule';
+import { resolvePlatformOS, type PlatformOS } from '../../core/context/device';
+import { sanitizeFrameScrollState } from './frameScrollState';
+import type { OutboxFrameCapture, StagedFrameResult, OutboxFrameMeta } from './ReplayCaptureManager';
+
+/** Build the adapter. `ensureReady` resolves false when the native outbox is off. */
+export function makeOutboxFrameCapture(ensureReady: () => Promise<boolean>): OutboxFrameCapture {
+    // Platform.OS verbatim — see core/context/device.
+    const platform: PlatformOS = resolvePlatformOS();
+
+    return {
+        async capture(sessionId, screenName, trigger): Promise<StagedFrameResult | null> {
+            try {
+                if (!(await ensureReady())) return null;
+                const native = getReplaySdkNative();
+                if (!native?.captureScreenshotToFile) return null;
+                const res = await native.captureScreenshotToFile({
+                    sessionId,
+                    screenName: screenName ?? 'unknown',
+                    trigger,
+                });
+                if (!res) return null;
+                // Visible scroll containers read beside the pixels; undefined when not measured.
+                const scrollState = sanitizeFrameScrollState(res.scrollState);
+                return {
+                    frameId: res.frameId,
+                    width: res.width,
+                    height: res.height,
+                    byteSize: res.sizeBytes,
+                    format: res.format,
+                    contentType: res.contentType,
+                    frameHash: res.frameHash,
+                    masked: res.masked,
+                    timestamp: res.timestamp,
+                    platform,
+                    ...(scrollState ? { scrollState } : {}),
+                };
+            } catch {
+                return null;
+            }
+        },
+
+        async commit(meta: OutboxFrameMeta): Promise<boolean> {
+            try {
+                const native = getReplaySdkNative();
+                if (!native?.commitOutboxFrame) return false;
+                const path = await native.commitOutboxFrame(meta as unknown as Record<string, unknown>);
+                return path != null;
+            } catch {
+                return false;
+            }
+        },
+
+        async discard(sessionId: string, frameId: string): Promise<void> {
+            try {
+                await getReplaySdkNative()?.discardOutboxFrame?.(sessionId, frameId);
+            } catch {
+                /* no-throw */
+            }
+        },
+    };
+}