@scalebun-release/react-native 2.5.0

package/src/debug/transport.ts

@@ -0,0 +1,440 @@
+/**
+ * ScaleBun Debug — WebSocket Client Transport
+ *
+ * Connects the SDK to the Desktop app over LAN WebSocket.
+ * Features:
+ *   - Auto-reconnect with exponential backoff
+ *   - Message buffering when disconnected
+ *   - Heartbeat ping/pong for connection health
+ *   - Server ACK confirmation after handshake
+ *   - No-throw safety on all public methods
+ */
+
+import {
+    type DebugMessage,
+    type CommandMessage,
+    type HelloMessage,
+    type AckMessage,
+    type PingMessage,
+    serializeMessage,
+    deserializeMessage,
+    parseDebugMessage,
+    parseAnyMessage,
+    PROTOCOL_VERSION,
+} from './protocol';
+import {
+    DEFAULT_HEARTBEAT_INTERVAL_MS,
+    TRANSPORT_MAX_BUFFER_SIZE,
+    TRANSPORT_MAX_RECONNECT_ATTEMPTS,
+    TRANSPORT_RECONNECT_BASE_MS,
+    TRANSPORT_RECONNECT_MAX_MS,
+    TRANSPORT_HIGH_LATENCY_WARN_MS,
+} from '../core/constants/timings';
+import { SDK_VERSION } from '../core/constants/version';
+
+// ─── Types ──────────────────────────────────────────────────────────────────
+
+export interface DebugTransportConfig {
+    host: string;
+    port: number;
+    /** Max messages to buffer when disconnected. Default: 500 */
+    maxBufferSize?: number;
+    /** Max reconnect attempts before giving up. Default: 20 */
+    maxReconnectAttempts?: number;
+    /** Base reconnect delay in ms. Default: 250 */
+    reconnectBaseMs?: number;
+    /** Max reconnect delay in ms. Default: 5000 */
+    reconnectMaxMs?: number;
+
+    // ─── Device identity (populated by bootstrap) ───────────────────
+    appName?: string;
+    appVersion?: string;
+    bundleId?: string;
+    platform?: 'ios' | 'android' | 'web';
+    osVersion?: string;
+    deviceModel?: string;
+    deviceName?: string;
+    buildType?: 'debug' | 'release';
+    capabilities?: string[];
+
+    /**
+     * Shared secret for desktop authentication.
+     * If provided (non-null), included in the HelloMessage payload.
+     * The desktop will validate this against its configured secret.
+     * Default: null (not sent — backward compatible with old desktops).
+     */
+    secret?: string | null;
+}
+
+export type ConnectionState = 'disconnected' | 'connecting' | 'connected' | 'closed';
+export type CommandHandler = (cmd: CommandMessage) => void;
+export type StateChangeHandler = (state: ConnectionState) => void;
+
+// ─── Transport Class ────────────────────────────────────────────────────────
+
+export class DebugTransport {
+    private ws: WebSocket | null = null;
+    private config: Required<Pick<DebugTransportConfig, 'host' | 'port' | 'maxBufferSize' | 'maxReconnectAttempts' | 'reconnectBaseMs' | 'reconnectMaxMs'>> & DebugTransportConfig;
+    private state: ConnectionState = 'disconnected';
+    private buffer: string[] = [];
+    private reconnectAttempt = 0;
+    private reconnectTimer: ReturnType<typeof setTimeout> | null = null;
+    private heartbeatTimer: ReturnType<typeof setInterval> | null = null;
+    private heartbeatIntervalMs = DEFAULT_HEARTBEAT_INTERVAL_MS;
+    private commandHandlers: CommandHandler[] = [];
+    private stateHandlers: StateChangeHandler[] = [];
+    private sequence = 0;
+    private _deviceId = '';
+    private _sessionId = '';
+    private _closed = false;
+    private _handshakeAcked = false;
+    /** Cumulative count of messages dropped due to buffer overflow */
+    private _droppedMessages = 0;
+
+    constructor(config: DebugTransportConfig) {
+        this.config = {
+            maxBufferSize: TRANSPORT_MAX_BUFFER_SIZE,
+            maxReconnectAttempts: TRANSPORT_MAX_RECONNECT_ATTEMPTS,
+            reconnectBaseMs: TRANSPORT_RECONNECT_BASE_MS,
+            reconnectMaxMs: TRANSPORT_RECONNECT_MAX_MS,
+            ...config,
+        };
+    }
+
+    // ─── Public API ─────────────────────────────────────────────────────────
+
+    /** Set device/session identity (called before connect) */
+    setIdentity(deviceId: string, sessionId: string): void {
+        this._deviceId = deviceId;
+        this._sessionId = sessionId;
+    }
+
+    /** Connect to the desktop app */
+    connect(): void {
+        if (this._closed) return;
+        if (this.state === 'connecting' || this.state === 'connected') return;
+
+        this._setState('connecting');
+        this._doConnect();
+    }
+
+    /**
+     * Send a debug message. Buffers if not connected. Never throws.
+     *
+     * MESSAGE ORDERING POLICY (v1 — best-effort):
+     * Within a single WebSocket connection TCP guarantees in-order delivery,
+     * so messages sent here arrive at the desktop in the same order they are
+     * passed to send(). Across a reconnect, buffered messages are flushed FIFO
+     * via _flushBuffer(), preserving their relative send order. However, any
+     * messages that were already delivered before the disconnect and any that
+     * are delivered after the flush may interleave with in-flight state in the
+     * desktop store. No sequence number is stamped on application messages, and
+     * the desktop performs no gap-detection or reordering. This is intentional
+     * for v1: the overhead of a per-device reorder buffer is not justified until
+     * a concrete UI correctness issue is observed. Revisit if needed.
+     */
+    send(msg: DebugMessage): void {
+        try {
+            const serialized = serializeMessage(msg);
+            if (!serialized) return;
+
+            if (this.state === 'connected' && this.ws?.readyState === WebSocket.OPEN) {
+                this.ws.send(serialized);
+            } else {
+                // Buffer for later
+                if (this.buffer.length < this.config.maxBufferSize) {
+                    this.buffer.push(serialized);
+                }
+                // If buffer full, drop oldest
+                else if (this.buffer.length > 0) {
+                    this.buffer.shift();
+                    this.buffer.push(serialized);
+                    this._droppedMessages++;
+                }
+            }
+        } catch {
+            // No-throw: silently drop if serialization fails
+        }
+    }
+
+    /** Register a handler for incoming commands from desktop */
+    onCommand(handler: CommandHandler): () => void {
+        this.commandHandlers.push(handler);
+        return () => {
+            this.commandHandlers = this.commandHandlers.filter(h => h !== handler);
+        };
+    }
+
+    /** Register a state change listener */
+    onStateChange(handler: StateChangeHandler): () => void {
+        this.stateHandlers.push(handler);
+        return () => {
+            this.stateHandlers = this.stateHandlers.filter(h => h !== handler);
+        };
+    }
+
+    /** Get current connection state */
+    getState(): ConnectionState {
+        return this.state;
+    }
+
+    /** Get next sequence number */
+    nextSequence(): number {
+        return this.sequence++;
+    }
+
+    /** Get device ID */
+    get deviceId(): string {
+        return this._deviceId;
+    }
+
+    /** Get session ID */
+    get sessionId(): string {
+        return this._sessionId;
+    }
+
+    /** Get cumulative count of messages dropped due to buffer overflow */
+    get droppedMessages(): number {
+        return this._droppedMessages;
+    }
+
+    /** Disconnect and stop reconnecting */
+    disconnect(): void {
+        this._closed = true;
+        this._clearReconnect();
+        this._stopHeartbeat();
+
+        if (this.ws) {
+            try {
+                this.ws.close(1000, 'Client disconnect');
+            } catch {
+                // Ignore close errors
+            }
+            this.ws = null;
+        }
+
+        this.buffer = [];
+        this._setState('closed');
+    }
+
+    // ─── Private ────────────────────────────────────────────────────────────
+
+    private _doConnect(): void {
+        try {
+            const url = `ws://${this.config.host}:${this.config.port}`;
+            console.log(`[ScaleBun Transport] Connecting to ${url} (attempt ${this.reconnectAttempt + 1})...`);
+            this.ws = new WebSocket(url);
+
+            this.ws.onopen = () => {
+                console.log(`[ScaleBun Transport] ✅ WebSocket open to ${url}`);
+                this.reconnectAttempt = 0;
+                this._handshakeAcked = false;
+                this._sendHandshake();
+            };
+
+            this.ws.onmessage = (event: any) => {
+                this._handleMessage(event.data);
+            };
+
+            this.ws.onerror = (err: any) => {
+                const reason = err?.message || err?.type || 'unknown';
+                console.log(`[ScaleBun Transport] ❌ WS Error: ${reason}`);
+            };
+
+            this.ws.onclose = (event: any) => {
+                console.log(`[ScaleBun Transport] WS Closed: code=${event?.code} reason=${event?.reason || 'none'}`);
+                this.ws = null;
+                this._stopHeartbeat();
+                this._handshakeAcked = false;
+                if (!this._closed) {
+                    this._setState('disconnected');
+                    this._scheduleReconnect();
+                }
+            };
+        } catch (e: any) {
+            console.log(`[ScaleBun Transport] ❌ Connect exception: ${e?.message}`);
+            this._setState('disconnected');
+            if (!this._closed) {
+                this._scheduleReconnect();
+            }
+        }
+    }
+
+    private _sendHandshake(): void {
+        if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
+            console.log(`[ScaleBun Transport] ⚠ Cannot send handshake: ws not open`);
+            return;
+        }
+        const hello: HelloMessage = {
+            type: 'hello',
+            protocolVersion: PROTOCOL_VERSION,
+            deviceId: this._deviceId,
+            sessionId: this._sessionId,
+            timestamp: Date.now(),
+            sequence: this.nextSequence(),
+            payload: {
+                sdkVersion: SDK_VERSION,
+                appName: this.config.appName,
+                appVersion: this.config.appVersion,
+                bundleId: this.config.bundleId,
+                platform: this.config.platform,
+                osVersion: this.config.osVersion,
+                deviceModel: this.config.deviceModel,
+                buildType: this.config.buildType,
+                capabilities: this.config.capabilities ?? ['logs', 'events', 'network', 'crashes', 'metrics'],
+                // Include shared secret if configured (for desktop authentication)
+                ...(this.config.secret ? { secret: this.config.secret } : {}),
+                // Include transport stats so the desktop can warn about data loss
+                ...(this._droppedMessages > 0 ? {
+                    transportStats: { droppedMessages: this._droppedMessages },
+                } : {}),
+            },
+        };
+        console.log(`[ScaleBun Transport] Sending hello handshake (deviceId=${this._deviceId})`);
+        try {
+            // Send directly via ws.send() — NOT this.send() which requires state === 'connected'
+            const serialized = serializeMessage(hello);
+            if (serialized) {
+                this.ws.send(serialized);
+                console.log(`[ScaleBun Transport] ✅ Hello sent (${serialized.length} bytes)`);
+            } else {
+                console.log(`[ScaleBun Transport] ❌ Hello serialization failed`);
+            }
+        } catch (e: any) {
+            console.log(`[ScaleBun Transport] ❌ Hello send error: ${e?.message}`);
+        }
+    }
+
+    private _handleAck(ack: AckMessage): void {
+        this._handshakeAcked = true;
+        this.heartbeatIntervalMs = ack.heartbeatIntervalMs;
+        console.log(`[ScaleBun Transport] ✅ Handshake ACKed by server v${ack.serverVersion} (heartbeat every ${ack.heartbeatIntervalMs}ms)`);
+        this._setState('connected');
+        this._flushBuffer();
+        this._startHeartbeat();
+    }
+
+    private _startHeartbeat(): void {
+        this._stopHeartbeat();
+        this.heartbeatTimer = setInterval(() => {
+            if (this.ws?.readyState === WebSocket.OPEN) {
+                const ping: PingMessage = {
+                    type: 'scalebun:ping',
+                    deviceId: this._deviceId,
+                    timestamp: Date.now(),
+                };
+                try {
+                    this.ws.send(JSON.stringify(ping));
+                } catch {
+                    // No-throw
+                }
+            }
+        }, this.heartbeatIntervalMs);
+    }
+
+    private _stopHeartbeat(): void {
+        if (this.heartbeatTimer) {
+            clearInterval(this.heartbeatTimer);
+            this.heartbeatTimer = null;
+        }
+    }
+
+    private _flushBuffer(): void {
+        if (!this.ws || this.ws.readyState !== WebSocket.OPEN) return;
+
+        const toSend = [...this.buffer];
+        this.buffer = [];
+
+        for (const msg of toSend) {
+            try {
+                this.ws.send(msg);
+            } catch {
+                // Drop messages that fail to send
+            }
+        }
+    }
+
+    private _handleMessage(data: unknown): void {
+        try {
+            const text = typeof data === 'string' ? data : String(data);
+            const raw = deserializeMessage(text);
+            if (!raw) return;
+
+            const parsed = parseAnyMessage(raw);
+            if (!parsed.success) return;
+
+            const msg = parsed.data;
+
+            // Handle ACK from server
+            if (msg.type === 'scalebun:ack') {
+                this._handleAck(msg);
+                return;
+            }
+
+            // Handle pong (heartbeat response) — just log latency
+            if (msg.type === 'scalebun:pong') {
+                const latency = Date.now() - msg.echoTimestamp;
+                if (latency > TRANSPORT_HIGH_LATENCY_WARN_MS) {
+                    console.log(`[ScaleBun Transport] ⚠ High ping latency: ${latency}ms`);
+                }
+                return;
+            }
+
+            // Handle commands
+            if (msg.type === 'command') {
+                for (const handler of this.commandHandlers) {
+                    try {
+                        handler(msg);
+                    } catch {
+                        // Never let a handler crash the transport
+                    }
+                }
+            }
+        } catch {
+            // No-throw
+        }
+    }
+
+    private _scheduleReconnect(): void {
+        if (this._closed) return;
+        if (this.reconnectAttempt >= this.config.maxReconnectAttempts) {
+            console.log(`[ScaleBun Transport] ❌ Max reconnect attempts (${this.config.maxReconnectAttempts}) reached. Giving up.`);
+            this._setState('closed');
+            return;
+        }
+
+        const delay = Math.min(
+            this.config.reconnectBaseMs * Math.pow(2, this.reconnectAttempt),
+            this.config.reconnectMaxMs,
+        );
+
+        console.log(`[ScaleBun Transport] Reconnecting in ${delay}ms (attempt ${this.reconnectAttempt + 1}/${this.config.maxReconnectAttempts})`);
+
+        this.reconnectAttempt++;
+        this.reconnectTimer = setTimeout(() => {
+            if (!this._closed) {
+                this._setState('connecting');
+                this._doConnect();
+            }
+        }, delay);
+    }
+
+    private _clearReconnect(): void {
+        if (this.reconnectTimer) {
+            clearTimeout(this.reconnectTimer);
+            this.reconnectTimer = null;
+        }
+    }
+
+    private _setState(newState: ConnectionState): void {
+        if (this.state === newState) return;
+        this.state = newState;
+        for (const handler of this.stateHandlers) {
+            try {
+                handler(newState);
+            } catch {
+                // Never let listeners break state management
+            }
+        }
+    }
+}

package/src/features/bugreport/BugReportFeature.ts

@@ -0,0 +1,128 @@
+/**
+ * F-BUG (React Native) — bug-report feature.
+ *
+ * Ported from the web SDK's `features/bugreport/BugReportFeature.ts`, deliberately keeping its
+ * split: this class is THIN. It raises the capture signal and holds a `submitFn` injected by the
+ * facade, which owns session + transport and therefore owns the HTTP. Duplicating the submit here
+ * would give the two SDKs two contracts to drift apart.
+ *
+ * WHAT DOES NOT PORT
+ * The web feature lazy-imports a DOM launcher widget (`widget.ts`, 185 lines of document/CSS). RN
+ * has no DOM: the form is rendered by `EngagePromptView`, which already exists, already handles the
+ * native modal/keyboard behaviour, and is already what `shake_device` puts on screen. Building a
+ * second prompt system for this would be the same mistake in a different repo.
+ *
+ * TRIGGERING
+ * `shake_device` is already wired end to end — native CoreMotion/SensorManager →
+ * `engageShakeBridge` → `gestureTriggerDetector.reportShake()` → the `$gesture` signal lane → the
+ * engage trigger engine. This feature is a submit target for that flow, not a second detector.
+ */
+import { logger } from '../../core/logger/internalLogger';
+import type { EngageAttachmentDraft } from '../engage/engageTypes';
+
+/** Why a submit did not produce a report id. Mirrors the web SDK's discriminated failure union. */
+export type BugFailure = 'init' | 'consent' | 'send' | 'empty';
+
+/** Resolves to the report id, or to `{ e }` naming WHICH branch failed. */
+export type BugSubmitResult = string | { e: BugFailure };
+
+export interface BugReportInput {
+  /** The issue text. Required — a report with no description is not a report. */
+  message: string;
+  title?: string;
+  /**
+   * Reporter's email. Optional on purpose: the session usually already resolves to an end user, so
+   * the form should PREFILL this rather than demand it from someone who just shook their phone in
+   * frustration. `BugReport.reporterEmail` is nullable server-side.
+   */
+  email?: string;
+  /**
+   * An approved voice note, produced by `features/engage/captureVoiceAttachment`.
+   *
+   * That module returns a transcript as a PREFILL and only marks `transcriptApproved` once the user
+   * has explicitly accepted the wording. This feature must never submit an unapproved draft — a
+   * machine transcription of someone's voice, sent without them confirming it, is a different
+   * product decision than the one that pipeline was built for.
+   */
+  voice?: EngageAttachmentDraft;
+}
+
+type SubmitFn = (input: BugReportInput) => Promise<BugSubmitResult>;
+
+export class BugReportFeature {
+  readonly name = 'bugReport';
+
+  private active = false;
+  private submitFn: SubmitFn | null = null;
+  /** Raises the 'report' capture signal so replay flushes its buffer into the current session. */
+  private signalFn: (() => void) | null = null;
+
+  get isActive(): boolean {
+    return this.active;
+  }
+
+  setup(hooks: { signal?: () => void } = {}): void {
+    this.signalFn = hooks.signal ?? null;
+    this.active = true;
+  }
+
+  /**
+   * Flush replay into the session so the report has its visual context.
+   *
+   * Fail-soft: replay may be disabled, paused, or unsupported on this build. A report without a
+   * replay anchor is still a useful report, so this must never block a submit.
+   */
+  signalReport(): void {
+    try {
+      this.signalFn?.();
+    } catch {
+      /* never let a capture-signal failure break a bug report */
+    }
+  }
+
+  /** Wired by the facade after init — the full submit path (transport + session + context). */
+  setSubmit(fn: SubmitFn): void {
+    this.submitFn = fn;
+  }
+
+  /**
+   * Submit a report.
+   *
+   * Returns rather than throws, always. This is called from a UI the host app renders, often from a
+   * user gesture; an exception escaping into a React Native render tree is a redbox for the
+   * customer's user, over a bug report they were trying to send us.
+   */
+  async submit(input: BugReportInput): Promise<BugSubmitResult> {
+    if (!input || !input.message || input.message.trim().length === 0) {
+      logger.warn('[scalebun] reportBug: a message is required');
+      return { e: 'empty' };
+    }
+    // No submitFn means the facade never finished wiring. That is 'init', not a send failure —
+    // the distinction is what tells an integrator to check their setup rather than their network.
+    if (!this.submitFn) return { e: 'init' };
+
+    if (input.voice && !input.voice.transcriptApproved) {
+      // Refused rather than silently stripped: dropping the attachment would send a report the user
+      // believes contains their voice note, and they would never learn it did not.
+      logger.warn('[scalebun] reportBug: voice note has no approved transcript — not sending');
+      return { e: 'empty' };
+    }
+
+    try {
+      // Order matters and mirrors the web path: signal BEFORE submit so the replay bytes are already
+      // in flight, and so the report's replay coordinate refers to a frame that exists. A flush
+      // cannot retroactively manufacture a frame, so a missing anchor must stay missing rather than
+      // become a misleading "start of session" link in the dashboard.
+      this.signalReport();
+      return await this.submitFn(input);
+    } catch {
+      return { e: 'send' };
+    }
+  }
+
+  teardown(): void {
+    this.submitFn = null;
+    this.signalFn = null;
+    this.active = false;
+  }
+}

package/src/features/bugreport/buildPayload.ts

@@ -0,0 +1,116 @@
+/**
+ * Builds the body for POST /ingestion/sessions/:sessionId/bug-reports.
+ *
+ * Kept as a PURE function with no transport, no bridge and no clock of its own, because the wire
+ * shape is a cross-repo contract and the only way to keep it honest is to be able to assert it
+ * directly. Every bound below is copied from the server DTO
+ * (wzb-dashboard-backend/src/features/bug-reports/dto/submit-bug-report.dto.ts) rather than guessed:
+ *
+ *   clientReportId?   string            idempotency key -> BugReport.clientReportId (@unique)
+ *   title?            string   <= 300
+ *   message           string   <= 20000  -> BugReport.description  (REQUIRED)
+ *   email?            string   <= 320
+ *   url?              string   <= 2000
+ *   console?          unknown[]          recent breadcrumbs
+ *   screenshotKey?    string   <= 512, [A-Za-z0-9._/-] and no ".."
+ *   timestamp?        number             2000-01-01 .. 2100-01-01 in epoch MILLIS
+ *   replaySeq?        int      0 .. 2147483647
+ *   replaySegmentId?  string   <= 256
+ *
+ * Truncating here rather than letting the server 400 is deliberate: a 20,001-character description
+ * is a real report from a real annoyed user, and losing it to a validation error helps nobody. The
+ * ceiling is theirs, so we respect it at the edge. Nothing is silently REWRITTEN — only cut, and
+ * only at bounds the server would otherwise reject outright.
+ */
+
+/** Mirrors SubmitBugReportDto. Optional keys are omitted entirely rather than sent as undefined. */
+export interface BugReportPayload {
+  clientReportId?: string;
+  title?: string;
+  message: string;
+  email?: string;
+  url?: string;
+  console?: unknown[];
+  screenshotKey?: string;
+  timestamp?: number;
+  replaySeq?: number;
+  replaySegmentId?: string;
+}
+
+export interface ReplayCoord {
+  seq?: number | null;
+  segmentId?: string | null;
+}
+
+const MAX_TITLE = 300;
+const MAX_MESSAGE = 20_000;
+const MAX_EMAIL = 320;
+const MAX_SEGMENT_ID = 256;
+/** The server rejects outside these; a drifted device clock must not cost us the whole report. */
+const TS_MIN = 946684800000; // 2000-01-01
+const TS_MAX = 4102444800000; // 2100-01-01
+const MAX_BREADCRUMBS = 50;
+
+function clip(v: string | undefined | null, max: number): string | undefined {
+  if (typeof v !== 'string') return undefined;
+  const t = v.trim();
+  return t.length === 0 ? undefined : t.slice(0, max);
+}
+
+export function buildBugReportPayload(
+  input: { message: string; title?: string; email?: string; clientReportId?: string },
+  breadcrumbs: readonly unknown[] = [],
+  ctx: { replayCoord?: ReplayCoord | null; timestamp?: number } = {},
+): BugReportPayload {
+  const message = (input.message ?? '').trim().slice(0, MAX_MESSAGE);
+
+  const payload: BugReportPayload = { message };
+
+  const title = clip(input.title, MAX_TITLE);
+  if (title) payload.title = title;
+
+  const email = clip(input.email, MAX_EMAIL);
+  if (email) payload.email = email;
+
+  const clientReportId = clip(input.clientReportId, 200);
+  if (clientReportId) payload.clientReportId = clientReportId;
+
+  if (breadcrumbs.length > 0) payload.console = breadcrumbs.slice(-MAX_BREADCRUMBS);
+
+  /**
+   * An out-of-range clock is DROPPED, not clamped.
+   *
+   * Clamping would invent a `reportedAt` the device never observed, and the server keeps that column
+   * separate from `createdAt` precisely so the two can be compared. A missing client time is honest;
+   * a fabricated one silently corrupts that comparison.
+   */
+  const ts = ctx.timestamp;
+  if (typeof ts === 'number' && Number.isFinite(ts) && ts >= TS_MIN && ts <= TS_MAX) {
+    payload.timestamp = ts;
+  }
+
+  /**
+   * The replay anchor is included ONLY when a frame actually existed at submit time.
+   *
+   * Defaulting `replaySeq` to 0 would point every anchor-less report at the start of the session,
+   * which reads in the dashboard exactly like a real anchor and is wrong. Replay may be disabled,
+   * paused, or yet to produce a frame; absent must stay absent.
+   */
+  const seq = ctx.replayCoord?.seq;
+  if (typeof seq === 'number' && Number.isInteger(seq) && seq >= 0 && seq <= 2147483647) {
+    payload.replaySeq = seq;
+    const segmentId = clip(ctx.replayCoord?.segmentId ?? undefined, MAX_SEGMENT_ID);
+    if (segmentId) payload.replaySegmentId = segmentId;
+  }
+
+  /**
+   * `url` is intentionally NEVER set on React Native.
+   *
+   * The field means a page URL. The nearest mobile concept is the current screen name, and putting
+   * a screen name in a column called `url` is exactly the field-misuse that makes a dashboard show
+   * one thing and mean another. Screen context already reaches the report through the session it is
+   * attached to. If mobile needs its own field, that is a schema change, not a reused column.
+   */
+
+  return payload;
+}