@scalebun-release/react-native 2.5.0

package/src/features/session/sessionTypes.ts

@@ -0,0 +1,528 @@
+import type { PlatformOS } from '../../core/context/device';
+import type { FrameScrollEntry } from './frameScrollState';
+/**
+ * ScaleBun SDK — Unified Session Domain Model
+ *
+ * Single source of truth for event types, frame types, session lifecycle,
+ * transport contracts, sync contracts, capture configuration, and artifact indexing.
+ *
+ * Architecture rules:
+ * - imageRef in ReplayFrame is an artifact reference (ID/path), NOT base64.
+ *   Base64 is transport-layer detail only.
+ * - SyncDecisionEngine in the SDK owns sync policy; native only gathers metadata.
+ * - Frame capture is native-only (PixelCopy on Android, UIWindow on iOS).
+ *   No JS screenshot fallback for session replay.
+ * - Frame retention prefers crash-adjacent/error-context frames over generic old frames.
+ */
+
+// ─── Session ────────────────────────────────────────────────────────────────
+
+export type SessionStatus = 'active' | 'ended' | 'timeout';
+
+export interface SessionMetadata {
+    appName?: string;
+    appVersion?: string;
+    bundleId?: string;
+    // Widened to the real Platform.OS — see core/context/device. The wire's platform field is an
+    // open enum, so a value this union did not anticipate travels rather than being coerced.
+    platform?: PlatformOS;
+    osVersion?: string;
+    deviceModel?: string;
+    deviceName?: string;
+    screenWidth?: number;
+    screenHeight?: number;
+    buildType?: 'debug' | 'release';
+}
+
+export interface Session {
+    sessionId: string;
+    deviceId: string;
+    startedAt: number;
+    endedAt?: number;
+    status: SessionStatus;
+    metadata: SessionMetadata;
+    transportState: TransportState;
+    syncState: SyncState;
+    artifactIndex: SessionArtifactIndex;
+}
+
+// ─── Journey Event ──────────────────────────────────────────────────────────
+
+export type JourneyEventType =
+    | 'SESSION_STARTED'
+    | 'SESSION_ENDED'
+    | 'APP_FOREGROUND'
+    | 'APP_BACKGROUND'
+    | 'SCREEN_VIEW'
+    /** Leaving a screen, carrying the MEASURED dwell time — see SessionManager.onScreenChange. */
+    | 'SCREEN_EXIT'
+    | 'USER_ACTION'
+    | 'NETWORK_REQUEST_STARTED'
+    | 'NETWORK_REQUEST_COMPLETED'
+    | 'NETWORK_REQUEST_FAILED'
+    | 'LOG_EMITTED'
+    | 'ERROR_CAPTURED'
+    | 'CRASH_CAPTURED'
+    | 'REPLAY_FRAME_CAPTURED'
+    | 'LOADING_STARTED'
+    | 'LOADING_COMPLETED';
+
+export type JourneyEventSeverity = 'info' | 'warning' | 'error' | 'fatal';
+export type JourneyEventSource = 'sdk' | 'native' | 'user' | 'system';
+
+export interface JourneyEvent {
+    eventId: string;
+    sessionId: string;
+    /** If this event belongs to a recorded journey */
+    journeyId?: string;
+    ts: number;
+    type: JourneyEventType;
+    /** Subtype for further classification (e.g. 'TAP', 'SWIPE', 'console.error') */
+    subtype?: string;
+    severity?: JourneyEventSeverity;
+    /** Screen name at time of event */
+    screen?: string;
+    /**
+     * frameId of the screenshot that was ON SCREEN when this event happened.
+     *
+     * The picture the user was looking at, not the one that follows. Mobile has no DOM to
+     * reconstruct, so a captured frame is the only record of what a screen looked like at a
+     * moment — which makes this the join key between a tap and the state it was made in.
+     *
+     * Set only when a keyframe from the SAME screen was captured recently enough to still be
+     * showing (see SessionManager.currentFrameForEvent). Absent means "not captured", which is a
+     * DIFFERENT answer from "nothing was open" and must never be folded into it:
+     *   · the analytics lane never has one — it runs only when no recording is active, so no
+     *     screenshots exist at all
+     *   · a tap right after navigation has none — the capture is debounced and evicted on
+     *     screen change
+     */
+    frameId?: string;
+    payload?: Record<string, unknown>;
+    /** Links related events (e.g. network request start → complete) */
+    correlationId?: string;
+    /** Distributed trace ID */
+    traceId?: string;
+    source?: JourneyEventSource;
+}
+
+// ─── Replay Frame ───────────────────────────────────────────────────────────
+
+/**
+ * imageRef is an ARTIFACT REFERENCE (opaque ID/path), not raw base64.
+ * Base64 content is a transport/storage detail resolved separately.
+ * This keeps the domain model transport-agnostic.
+ */
+export interface ReplayFrame {
+    frameId: string;
+    sessionId: string;
+    ts: number;
+    /** Monotonic per-session sequence (P2-0). Assigned in JS, starts at 1, +1 per emitted frame. */
+    sequenceNumber: number;
+    /** Keyframe (full image) or delta (changed regions vs baseFrameId). P2-5. */
+    frameType: 'keyframe' | 'delta';
+    /** frameId of the keyframe a delta is encoded against; undefined for keyframes. P2-5. */
+    baseFrameId?: string;
+    /** Artifact reference — resolved to actual data by transport/storage layer */
+    imageRef: string;
+    width: number;
+    height: number;
+    /** Encoded image byte size (real value from native), 0 if unknown. */
+    byteSize?: number;
+    /** Image encoding from native ('avif' | 'webp' | 'jpeg' | 'png'). P2-2 fallback chain. */
+    format?: string;
+    quality: ReplayQuality;
+    captureReason: CaptureReason;
+    /** Native-only capture — JS never captures frames */
+    // Widened: a frame reports the REAL Platform.OS. The old union forced every non-iOS capture to
+    // be relabelled 'android', which is how RN-macOS and RN-Windows sessions became Android ones.
+    sourcePlatform: PlatformOS;
+    redactionState?: 'none' | 'text-masked' | 'full';
+    /** Screen name at capture time — for frame-to-screen correlation */
+    screen?: string;
+    /**
+     * Visible scroll containers read natively at the moment of capture, largest first, at most 4
+     * (Android capture-view px, iOS points). Undefined = not measured; [] = none on screen.
+     * See frameScrollState.ts.
+     */
+    scrollState?: FrameScrollEntry[];
+    /** Interaction point metadata — populated when captureReason is 'interaction' */
+    interactionPoint?: {
+        /** Tap/gesture X coordinate in device pixels */
+        x: number;
+        /** Tap/gesture Y coordinate in device pixels */
+        y: number;
+        /** Normalized X (0 to 1) for safe heatmap overlay across different viewport sizes */
+        normalizedX?: number;
+        /** Normalized Y (0 to 1) for safe heatmap overlay across different viewport sizes */
+        normalizedY?: number;
+        /** Device screen width at capture time */
+        screenWidth: number;
+        /** Device screen height at capture time */
+        screenHeight: number;
+        /** Actual viewport width at capture time, equivalent to screenWidth in most cases */
+        viewportWidth?: number;
+        /** Actual viewport height at capture time, equivalent to screenHeight in most cases */
+        viewportHeight?: number;
+        /** Gesture type: tap, long_press, swipe, scroll */
+        gestureType: string;
+        /** For swipes/scrolls: End X coordinate */
+        endX?: number;
+        /** For swipes/scrolls: End Y coordinate */
+        endY?: number;
+        /** For swipes/scrolls: Normalized End X */
+        normalizedEndX?: number;
+        /** For swipes/scrolls: Normalized End Y */
+        normalizedEndY?: number;
+        /** Duration of gesture if tracked */
+        durationMs?: number;
+        /** Gesture direction: up, down, left, right */
+        direction?: string;
+    };
+}
+
+export type CaptureReason =
+    | 'navigation'
+    | 'interaction'
+    | 'frequency'
+    | 'manual'
+    | 'error-context'
+    | 'scroll'
+    | 'screen_loaded';
+
+// ─── Session Artifact Index ─────────────────────────────────────────────────
+
+export interface CrashAnchor {
+    crashEventId: string;
+    /** Event IDs within ±N of the crash */
+    nearbyEventIds: string[];
+    /** Frame IDs within ±N of the crash */
+    nearbyFrameIds: string[];
+    timestamp: number;
+}
+
+export interface SessionArtifactIndex {
+    /** Frame IDs in chronological order */
+    frameRefs: string[];
+    /** Event IDs in chronological order */
+    eventRefs: string[];
+    /** Event IDs where type is NETWORK_REQUEST_* */
+    networkRefs: string[];
+    /** Event IDs where type is LOG_EMITTED */
+    logRefs: string[];
+    /** Crash/error anchors with nearby context */
+    crashAnchors: CrashAnchor[];
+    /** Future: artifact upload references for remote dashboard */
+    uploadRefs?: string[];
+}
+
+// ─── Capture Configuration ──────────────────────────────────────────────────
+
+/** When to capture frames */
+export type CaptureMode = 'navigation' | 'interactions' | 'frequency';
+
+/** Frame quality presets — maps to native JPEG compression */
+export type ReplayQuality = 'high' | 'normal' | 'low' | 'grayscale';
+
+/** Quality preset → concrete capture parameters (used by native engines) */
+export const QUALITY_PRESETS: Record<ReplayQuality, { maxWidth: number; jpegQuality: number }> = {
+    high: { maxWidth: 0, jpegQuality: 90 }, // 0 = full width
+    normal: { maxWidth: 720, jpegQuality: 70 },
+    low: { maxWidth: 480, jpegQuality: 40 },
+    grayscale: { maxWidth: 720, jpegQuality: 60 }, // native applies grayscale conversion
+};
+
+export interface PrivacyPolicy {
+    redactTextInputs: boolean;
+    redactImages: boolean;
+    /** TestIDs to completely exclude from capture */
+    blockTestIds: string[];
+    /** Screen names to exclude from replay capture */
+    captureExclusions: string[];
+}
+
+export interface SessionReplayConfig {
+    captureMode: CaptureMode;
+    quality: ReplayQuality;
+    /** Used with 'frequency' mode. Minimum 500ms. */
+    intervalMs: number;
+    includeNetworkLogs: boolean;
+    includeSdkLogs: boolean;
+    includeUserSteps: boolean;
+    /** Max frames before dropping old (prefers keeping crash-adjacent) */
+    maxFrames: number;
+    /** Max events before dropping old (prefers keeping crash-adjacent) */
+    maxEventCount: number;
+    /** Auto-end session after this duration */
+    maxDurationMs: number;
+    privacyPolicy: PrivacyPolicy;
+
+    // ── P2 capture knobs (all tunable; see P2_CONTRACT.md §5) ──
+    /** P2-1: suppress visually-unchanged consecutive frames. Default true. */
+    changeDetection?: boolean;
+    /** P2-1: 0 = exact-hash match; >0 = perceptual distance threshold (native). Default 0. */
+    changeSensitivity?: number;
+    /** P2-1 heartbeat: force a keyframe even if unchanged after this many ms, so static
+     *  periods still have a frame AND deltas always have a fresh base. Default 5000. */
+    maxKeyframeIntervalMs?: number;
+    /** P2-2: native encode preference order; first that succeeds on-device wins. */
+    frameFormatPreference?: Array<'avif' | 'webp' | 'jpeg'>;
+    /** P2-2: lossy encoder quality 0..100. Default 55. */
+    frameQuality?: number;
+    /** P2-5: emit deltas between keyframes. Default false (keyframe-only when off). */
+    deltaEncoding?: boolean;
+    /** P2-5: force a keyframe every N frames so a dropped base strands < N-1 deltas. Default 10. */
+    deltaKeyframeInterval?: number;
+    /** `interactions` mode: sample the screen briefly after each semantic frame, uploading only
+     *  samples whose pixels changed, so motion between taps is not lost. Needs changeDetection.
+     *  See ACTIVITY_SAMPLE_INTERVAL_MS in ReplayCaptureManager. Default true. */
+    activitySampling?: boolean;
+}
+
+export const DEFAULT_SESSION_REPLAY_CONFIG: SessionReplayConfig = {
+    captureMode: 'navigation',
+    quality: 'normal',
+    intervalMs: 2000,
+    includeNetworkLogs: true,
+    includeSdkLogs: false,
+    includeUserSteps: true,
+    maxFrames: 200,
+    maxEventCount: 1000,
+    maxDurationMs: 10 * 60 * 1000, // 10 minutes
+    privacyPolicy: {
+        redactTextInputs: true,
+        redactImages: false,
+        blockTestIds: [],
+        captureExclusions: [],
+    },
+    // P2 capture knobs
+    changeDetection: true,
+    changeSensitivity: 0,
+    maxKeyframeIntervalMs: 5000,
+    frameFormatPreference: ['avif', 'webp', 'jpeg'],
+    frameQuality: 55,
+    deltaEncoding: false,
+    deltaKeyframeInterval: 10,
+    activitySampling: true,
+};
+
+// ─── Transport Contracts ────────────────────────────────────────────────────
+
+export type TransportState =
+    | 'local'
+    | 'pending-sync'
+    | 'syncing'
+    | 'synced'
+    | 'failed';
+
+/**
+ * SessionTransport abstraction.
+ * DesktopSessionTransport implements this now.
+ * RemoteDashboardSessionTransport will implement this later.
+ * Core session logic never knows transport details.
+ */
+export interface SessionTransport {
+    sendSessionStart(session: Session): void;
+    sendSessionEnd(session: Session): void;
+    sendEvent(event: JourneyEvent): void;
+    /**
+     * Send a replay frame. The transport is responsible for resolving
+     * imageRef → actual content (base64, URL, etc.) at the transport boundary.
+     * @param frame - frame metadata (imageRef is artifact reference)
+     * @param imageData - raw image data (base64) for transport serialization
+     */
+    sendFrame(frame: ReplayFrame, imageData: string): void;
+}
+
+// ─── Sync Decision Contracts ────────────────────────────────────────────────
+
+export type SyncState =
+    | 'eligible'
+    | 'ineligible'
+    | 'pending-evaluation'
+    | 'opted-out';
+
+/**
+ * Metadata gathered by NATIVE layer, passed to SDK for sync decision.
+ * Native only gathers; SDK's SyncDecisionEngine owns the eligibility policy.
+ */
+export interface NativeSyncMetadata {
+    deviceModel: string;
+    osVersion: string;
+    batteryLevel?: number;
+    batteryCharging?: boolean;
+    networkType?: 'wifi' | 'cellular' | 'ethernet' | 'none' | 'unknown';
+    isMeteredNetwork?: boolean;
+    availableMemoryMb?: number;
+    thermalState?: 'nominal' | 'fair' | 'serious' | 'critical';
+}
+
+/**
+ * Candidate presented to SyncDecisionEngine for eligibility evaluation.
+ */
+export interface SyncCandidate {
+    sessionId: string;
+    metadata: SessionMetadata;
+    nativeMetadata?: NativeSyncMetadata;
+    eventCount: number;
+    frameCount: number;
+    durationMs: number;
+    hasCrash: boolean;
+    hasError: boolean;
+}
+
+export interface SyncDecision {
+    shouldSync: boolean;
+    reason: string;
+    priority: 'high' | 'normal' | 'low';
+}
+
+/**
+ * Callback type for custom sync eligibility evaluation.
+ * The SDK provides a default implementation; host apps can override.
+ */
+export type SyncDecisionCallback = (candidate: SyncCandidate) => SyncDecision;
+
+// ─── Native Capture Result ──────────────────────────────────────────────────
+
+/**
+ * Result returned by native capture engine.
+ * base64 is transient — used at the transport boundary, NOT stored in domain as imageRef.
+ */
+export interface NativeFrameResult {
+    base64: string;
+    width: number;
+    height: number;
+    /** Byte size of the compressed image */
+    byteSize: number;
+    /** Platform that performed the capture */
+    // Widened from 'android'|'ios': a frame is labelled with the REAL Platform.OS now, and the
+    // old union forced every non-iOS capture to be relabelled 'android'.
+    platform: PlatformOS;
+    /** Actual on-device encoding after the AVIF->WebP->JPEG fallback (P2-2). */
+    format?: string;
+    /** Optional native frame hash for change detection (P2-1). JS falls back to hashing base64. */
+    frameHash?: string;
+    /** Sanitized visible scroll containers at capture time; undefined = not measured. */
+    scrollState?: FrameScrollEntry[];
+}
+
+/**
+ * Native device/session metadata result.
+ */
+export interface NativeDeviceMetadata {
+    deviceModel: string;
+    osVersion: string;
+    screenWidth: number;
+    screenHeight: number;
+    platform: 'android' | 'ios';
+    appName?: string;
+    appVersion?: string;
+    bundleId?: string;
+    buildType?: 'debug' | 'release';
+}
+
+// ─── Frame Retention Policy ─────────────────────────────────────────────────
+
+/**
+ * Priority levels for frame retention when buffer is full.
+ * Higher priority frames are kept longer.
+ *
+ * CRASH_ADJACENT and ERROR_CONTEXT frames are NEVER dropped before
+ * generic NAVIGATION/INTERACTION/FREQUENCY frames.
+ */
+export enum FrameRetentionPriority {
+    /** Lowest: regular periodic captures */
+    FREQUENCY = 0,
+    /** Low: regular navigation frames */
+    NAVIGATION = 1,
+    /** Medium: interaction-triggered frames */
+    INTERACTION = 2,
+    /** Medium-high: manually triggered captures */
+    MANUAL = 3,
+    /** High: captured in response to an error event */
+    ERROR_CONTEXT = 4,
+    /** Highest: adjacent to a crash event — never drop before others */
+    CRASH_ADJACENT = 5,
+}
+
+/** Map CaptureReason → retention priority */
+export function getFrameRetentionPriority(reason: CaptureReason): FrameRetentionPriority {
+    switch (reason) {
+        case 'error-context': return FrameRetentionPriority.ERROR_CONTEXT;
+        case 'manual': return FrameRetentionPriority.MANUAL;
+        case 'interaction': return FrameRetentionPriority.INTERACTION;
+        case 'screen_loaded': return FrameRetentionPriority.INTERACTION; // Same priority as interaction
+        case 'scroll': return FrameRetentionPriority.INTERACTION;
+        case 'navigation': return FrameRetentionPriority.NAVIGATION;
+        case 'frequency': return FrameRetentionPriority.FREQUENCY;
+    }
+}
+
+// ─── Session Protocol Event Names ───────────────────────────────────────────
+
+export const SESSION_EVENTS = {
+    SESSION_START: 'session:start',
+    SESSION_END: 'session:end',
+    EVENT: 'session:event',
+    FRAME: 'session:frame',
+} as const;
+
+// ─── Event Retention Policy ─────────────────────────────────────────────────
+
+/**
+ * Priority levels for event retention when buffer is full.
+ * Crash/error events are NEVER dropped before generic events.
+ */
+export enum EventRetentionPriority {
+    LOG = 0,
+    NETWORK = 1,
+    LIFECYCLE = 2,
+    SCREEN_VIEW = 3,
+    USER_ACTION = 4,
+    ERROR = 5,
+    CRASH = 6,
+}
+
+/** Map JourneyEventType → retention priority */
+export function getEventRetentionPriority(type: JourneyEventType): EventRetentionPriority {
+    switch (type) {
+        case 'LOG_EMITTED': return EventRetentionPriority.LOG;
+        case 'NETWORK_REQUEST_STARTED':
+        case 'NETWORK_REQUEST_COMPLETED':
+        case 'NETWORK_REQUEST_FAILED': return EventRetentionPriority.NETWORK;
+        case 'APP_FOREGROUND':
+        case 'APP_BACKGROUND':
+        case 'SESSION_STARTED':
+        case 'SESSION_ENDED':
+        case 'LOADING_STARTED':
+        case 'LOADING_COMPLETED': return EventRetentionPriority.LIFECYCLE;
+        // An exit is the other half of a view and carries the dwell time, so it retains together with
+        // it — dropping exits first would leave entries whose duration can never be recovered.
+        case 'SCREEN_VIEW':
+        case 'SCREEN_EXIT': return EventRetentionPriority.SCREEN_VIEW;
+        case 'USER_ACTION':
+        case 'REPLAY_FRAME_CAPTURED': return EventRetentionPriority.USER_ACTION;
+        case 'ERROR_CAPTURED': return EventRetentionPriority.ERROR;
+        case 'CRASH_CAPTURED': return EventRetentionPriority.CRASH;
+    }
+}
+
+// ─── Re-exports from contracts ──────────────────────────────────────────────
+// Pure types are now canonical in @scalebun/sdk-contracts.
+// Runtime values (enums, constants, functions) remain here.
+export type {
+    Session as ContractSession,
+    SessionMetadata as ContractSessionMetadata,
+    SessionStatus as ContractSessionStatus,
+    JourneyEvent as ContractJourneyEvent,
+    JourneyEventType as ContractJourneyEventType,
+    ReplayFrame as ContractReplayFrame,
+    CaptureReason as ContractCaptureReason,
+    SessionReplayConfig as ContractSessionReplayConfig,
+    SessionTransport as ContractSessionTransport,
+    SyncCandidate as ContractSyncCandidate,
+    SyncDecision as ContractSyncDecision,
+    NativeFrameResult as ContractNativeFrameResult,
+    NativeDeviceMetadata as ContractNativeDeviceMetadata,
+} from '../../vendor/sdk-contracts';

package/src/features/session/viewportPlausibility.ts

@@ -0,0 +1,134 @@
+/**
+ * Is the viewport the platform just reported actually believable?
+ *
+ * WHY THIS EXISTS
+ * ───────────────
+ * The native layer reports the content view's size and the SDK trusts it unconditionally: in
+ * `SessionManager._normalizeInteractionPayload`, a payload tagged `confidence: 'high'` short-circuits
+ * every other source and is cached as the normalization base for the rest of the session. One device
+ * in production reports a size that cannot be true, and nothing noticed.
+ *
+ * Measured on production 2026-09-20, across 56 device models:
+ *
+ *   device                    viewportWidth(px)   windowWidth(dp)   implied density
+ *   OPPO CPH2821                      720               360.0             2.000  ok
+ *   Xiaomi 23129RAA4G                1080               392.7             2.750  ok
+ *   samsung SM-M526BR                1080               411.4             2.625  ok
+ *   HUAWEI INE-LX1                   1080               360.0             3.000  ok
+ *   HONOR DNY-NX9                    1264               361.1             3.500  ok
+ *   every iPhone                  390..440          390..440             1.000  ok  (pt space)
+ *   OnePlus OnePlus8Pro               288               434.7             0.663  IMPLAUSIBLE
+ *
+ * 55 of 56 pass, one fails, and the failure is the device whose replays render as an impossibly
+ * tall, narrow phone. Its `windowWidth` of 434.7dp is *correct* for a 1440px screen (1440/434.7 =
+ * 3.3125) — it is `viewportWidth` that is wrong, by a factor of five.
+ *
+ * WHY THIS TEST AND NOT A DEVICE LIST
+ * ───────────────────────────────────
+ * The SDK already sends two INDEPENDENTLY SOURCED measurements of the same screen: the native
+ * content view (physical px on Android, points on iOS) and the JS layout width from
+ * `Dimensions.get('window')` (density-independent). Converted into a common unit they must agree.
+ * That is a self-consistency check, so it holds on hardware nobody here has ever seen — which is the
+ * whole point. A model allowlist would have to be updated for the next OnePlus, and would not exist
+ * until after that device had already shipped bad data for a week.
+ *
+ * WHY NOT ASPECT RATIO, the obvious alternative: it does not separate. The OnePlus sits at 0.643 and
+ * a legitimate Android emulator in the same fleet sits at 0.629. Aspect is kept below only as a
+ * SECONDARY guard against a corrupted height, never as the primary signal.
+ *
+ * Pure and dependency-free on purpose: the backend holds a byte-identical copy so ingest can reach
+ * the same verdict as capture, and `geometry:parity` asserts the two have not drifted.
+ */
+
+/** Android densities run 0.75 (ldpi) to 4.0 (xxxhdpi); the bound is loose so only nonsense fails. */
+const DENSITY_MIN = 0.9;
+const DENSITY_MAX = 5.0;
+
+/**
+ * How far the two measurements may disagree when the real density IS known.
+ *
+ * Generous at 10% because `windowWidth` is itself derived by the platform as px/density and can
+ * carry rounding, and because insets are excluded inconsistently across OEMs. The failure this
+ * catches is off by 5x, so precision is not what makes it work.
+ */
+const DENSITY_TOLERANCE = 0.1;
+
+/** A screen cannot be 10x taller than it is wide, or wider than it is tall by that much. */
+const ASPECT_MIN = 0.2;
+const ASPECT_MAX = 5.0;
+
+export interface ViewportSample {
+  /** Native content view width — physical px on Android, points on iOS. */
+  viewportWidth?: number | null;
+  viewportHeight?: number | null;
+  /** JS layout width from `Dimensions.get('window')`, in density-independent units. */
+  windowWidth?: number | null;
+  /** Which unit `viewportWidth` is in; the SDK tags every payload with it. */
+  coordinateSpace?: string | null;
+  /** `PixelRatio.get()` when the caller knows it. Absent → the looser range test is used. */
+  density?: number | null;
+}
+
+export type ViewportVerdict = 'ok' | 'implausible' | 'unverified';
+
+export interface ViewportCheck {
+  verdict: ViewportVerdict;
+  /** viewportWidth / windowWidth — what the device implies its density is. Null when uncheckable. */
+  impliedDensity: number | null;
+  /** What it should have been: `PixelRatio.get()`, or 1 in point-space. Null when unknown. */
+  expectedDensity: number | null;
+  /** Short machine-readable cause, for logs and for the ingest flag. Null when ok. */
+  reason: string | null;
+}
+
+function positive(v: unknown): number | null {
+  return typeof v === 'number' && isFinite(v) && v > 0 ? v : null;
+}
+
+/**
+ * Judge a reported viewport.
+ *
+ * `unverified` is a THIRD state on purpose and never collapses into `ok`. A payload from an older
+ * SDK build carries no `windowWidth`, so the invariant cannot be evaluated at all — recording that
+ * as "checked and fine" would be the same defect as rendering a missing measurement as zero. The
+ * caller decides what to do with an unverifiable sample; it must not be told a lie about it.
+ */
+export function checkViewport(sample: ViewportSample): ViewportCheck {
+  const vw = positive(sample.viewportWidth);
+  const vh = positive(sample.viewportHeight);
+  const dpW = positive(sample.windowWidth);
+
+  if (vw == null || vh == null) {
+    return { verdict: 'unverified', impliedDensity: null, expectedDensity: null, reason: 'no-viewport' };
+  }
+
+  // Secondary guard: a plausible density cannot rescue a height that is obviously corrupt.
+  const aspect = vw / vh;
+  if (aspect < ASPECT_MIN || aspect > ASPECT_MAX) {
+    return { verdict: 'implausible', impliedDensity: null, expectedDensity: null, reason: 'aspect-out-of-range' };
+  }
+
+  if (dpW == null) {
+    return { verdict: 'unverified', impliedDensity: null, expectedDensity: null, reason: 'no-window-width' };
+  }
+
+  const impliedDensity = vw / dpW;
+
+  // Point-space (iOS): the native size is ALREADY in the unit `Dimensions.get('window')` uses, so
+  // the two must be the same number, not related by a density.
+  const space = typeof sample.coordinateSpace === 'string' ? sample.coordinateSpace : '';
+  const expectedDensity = space.endsWith('-pt') ? 1 : positive(sample.density);
+
+  if (expectedDensity != null) {
+    const off = Math.abs(impliedDensity - expectedDensity) / expectedDensity;
+    return off <= DENSITY_TOLERANCE
+      ? { verdict: 'ok', impliedDensity, expectedDensity, reason: null }
+      : { verdict: 'implausible', impliedDensity, expectedDensity, reason: 'density-mismatch' };
+  }
+
+  // Density unknown (an older payload, or a platform that does not report it): fall back to the
+  // range test. Weaker, but it still rejects the 0.663 that started this.
+  return impliedDensity >= DENSITY_MIN && impliedDensity <= DENSITY_MAX
+    ? { verdict: 'ok', impliedDensity, expectedDensity: null, reason: null }
+    : { verdict: 'implausible', impliedDensity, expectedDensity: null, reason: 'density-out-of-range' };
+}