@scalebun/react-native 1.0.0 → 1.0.2

package/src/debug/transport.ts

@@ -1,439 +1,439 @@
-/**
- * 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';
-
-// ─── 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: '0.1.0',
-                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
-            }
-        }
-    }
-}
+/**
+ * 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';
+
+// ─── 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: '0.1.0',
+                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
+            }
+        }
+    }
+}