@react-native-harness/bridge 1.2.0 → 1.4.0-rc.1

package/dist/__tests__/client.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=client.test.d.ts.map

package/dist/__tests__/client.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/client.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/client.test.js

@@ -0,0 +1,81 @@
+import { describe, expect, it, vi } from 'vitest';
+import { connectToHarness } from '../client.js';
+const createMockTransport = (initialState = 'connecting') => {
+    let state = initialState;
+    const openListeners = new Set();
+    const messageListeners = new Set();
+    const closeListeners = new Set();
+    const errorListeners = new Set();
+    const sent = [];
+    const transport = {
+        get state() {
+            return state;
+        },
+        send: (message) => {
+            sent.push(message);
+        },
+        close: (code = 1000, reason = '') => {
+            state = 'closed';
+            for (const listener of closeListeners) {
+                listener({ code, reason });
+            }
+        },
+        onOpen: (listener) => {
+            openListeners.add(listener);
+            return () => openListeners.delete(listener);
+        },
+        onMessage: (listener) => {
+            messageListeners.add(listener);
+            return () => messageListeners.delete(listener);
+        },
+        onClose: (listener) => {
+            closeListeners.add(listener);
+            return () => closeListeners.delete(listener);
+        },
+        onError: (listener) => {
+            errorListeners.add(listener);
+            return () => errorListeners.delete(listener);
+        },
+    };
+    return {
+        transport,
+        sent,
+        open: () => {
+            state = 'open';
+            for (const listener of openListeners) {
+                listener();
+            }
+        },
+        receive: (message) => {
+            for (const listener of messageListeners) {
+                listener(message);
+            }
+        },
+        fail: (error) => {
+            for (const listener of errorListeners) {
+                listener(error);
+            }
+        },
+    };
+};
+describe('connectToHarness transport injection', () => {
+    it('uses the injected transport instead of constructing a WebSocket', async () => {
+        const mockTransport = createMockTransport();
+        const handlePromise = connectToHarness('ws://unused', { runTests: vi.fn() }, { transport: mockTransport.transport });
+        mockTransport.open();
+        const handle = await handlePromise;
+        handle.reportReady({
+            platform: 'ios',
+            manufacturer: 'Apple',
+            model: 'Injected',
+            osVersion: '18.0',
+        });
+        expect(mockTransport.sent).toHaveLength(1);
+        expect(mockTransport.sent[0]).toBeTypeOf('string');
+        expect(JSON.parse(mockTransport.sent[0])).toMatchObject({
+            type: 'ready',
+            device: { model: 'Injected' },
+        });
+        handle.disconnect();
+    });
+});

package/dist/__tests__/heartbeat.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=heartbeat.test.d.ts.map

package/dist/__tests__/heartbeat.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"heartbeat.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/heartbeat.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/heartbeat.test.js

@@ -0,0 +1,37 @@
+import { describe, expect, it, vi } from 'vitest';
+import { createHeartbeat } from '../heartbeat.js';
+describe('bridge heartbeat', () => {
+    it('sends pings and times out stale sessions', () => {
+        vi.useFakeTimers();
+        const sendPing = vi.fn();
+        const onTimeout = vi.fn();
+        createHeartbeat({
+            sendPing,
+            onTimeout,
+            intervalMs: 5,
+            timeoutMs: 10,
+        });
+        vi.advanceTimersByTime(5);
+        expect(sendPing).toHaveBeenCalledWith(1);
+        vi.advanceTimersByTime(10);
+        expect(onTimeout).toHaveBeenCalledTimes(1);
+        vi.useRealTimers();
+    });
+    it('clears the timeout when the matching pong arrives', () => {
+        vi.useFakeTimers();
+        const sendPing = vi.fn();
+        const onTimeout = vi.fn();
+        const heartbeat = createHeartbeat({
+            sendPing,
+            onTimeout,
+            intervalMs: 5,
+            timeoutMs: 10,
+        });
+        vi.advanceTimersByTime(5);
+        heartbeat.notifyPong(1);
+        vi.advanceTimersByTime(10);
+        expect(onTimeout).not.toHaveBeenCalled();
+        heartbeat.dispose();
+        vi.useRealTimers();
+    });
+});

package/dist/__tests__/protocol.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=protocol.test.d.ts.map

package/dist/__tests__/protocol.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/protocol.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/protocol.test.js

@@ -0,0 +1,37 @@
+import { describe, expect, it } from 'vitest';
+import { deserializeBridgeError, parseBridgeMessage, serializeBridgeError, serializeBridgeMessage, } from '../protocol.js';
+describe('bridge protocol', () => {
+    it('round-trips invoke messages', () => {
+        const raw = serializeBridgeMessage({
+            type: 'invoke',
+            id: 1,
+            method: 'runTests',
+            args: ['example.ts', { runner: '/runner.js' }],
+        });
+        expect(parseBridgeMessage(raw)).toEqual({
+            type: 'invoke',
+            id: 1,
+            method: 'runTests',
+            args: ['example.ts', { runner: '/runner.js' }],
+        });
+    });
+    it('serializes and restores errors with metadata', () => {
+        const cause = new Error('inner');
+        const error = new TypeError('boom', { cause });
+        error.stack = 'stack trace';
+        const restored = deserializeBridgeError(serializeBridgeError(error));
+        expect(restored.name).toBe('TypeError');
+        expect(restored.message).toBe('boom');
+        expect(restored.stack).toBe('stack trace');
+        expect(restored.cause).toBe(cause);
+    });
+    it('serializes non-Error thrown values explicitly', () => {
+        expect(serializeBridgeError('boom')).toEqual({
+            name: 'NonErrorThrown',
+            message: 'boom',
+        });
+    });
+    it('rejects malformed messages', () => {
+        expect(() => parseBridgeMessage('{"type":"invoke","id":"1"}')).toThrow('Invalid bridge message: id must be a number');
+    });
+});

package/dist/__tests__/rpc-peer.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=rpc-peer.test.d.ts.map

package/dist/__tests__/rpc-peer.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rpc-peer.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/rpc-peer.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/rpc-peer.test.js

@@ -0,0 +1,127 @@
+import { describe, expect, it, vi } from 'vitest';
+import { createRpcPeer } from '../rpc-peer.js';
+const createMockTransport = () => {
+    const messages = [];
+    return {
+        state: 'open',
+        messages,
+        send: (message) => {
+            messages.push(message);
+        },
+    };
+};
+describe('rpc-peer', () => {
+    it('resolves successful RPC calls', async () => {
+        let serverHandleMessage = null;
+        const client = createRpcPeer({
+            localMethods: {},
+            transport: {
+                state: 'open',
+                send: (message) => {
+                    if (!serverHandleMessage) {
+                        throw new Error('Server peer not initialized');
+                    }
+                    void serverHandleMessage(message);
+                },
+            },
+        });
+        const server = createRpcPeer({
+            localMethods: {
+                add: async (left, right) => left + right,
+                fail: async () => {
+                    throw new Error('unused');
+                },
+            },
+            transport: {
+                state: 'open',
+                send: (message) => {
+                    void client.handleMessage(message);
+                },
+            },
+        });
+        serverHandleMessage = server.handleMessage;
+        const result = await client.invoke('add', 2, 3);
+        expect(result).toBe(5);
+    });
+    it('rejects failed RPC calls with restored errors', async () => {
+        const client = createRpcPeer({
+            localMethods: {},
+            transport: createMockTransport(),
+        });
+        const server = createRpcPeer({
+            localMethods: {
+                fail: async () => {
+                    throw new TypeError('boom');
+                },
+            },
+            transport: {
+                state: 'open',
+                send: (message) => {
+                    void client.handleMessage(message);
+                },
+            },
+        });
+        await server.handleMessage(JSON.stringify({ type: 'invoke', id: 1, method: 'fail', args: [] }));
+        await expect(client.handleMessage('{"type":"return","id":1,"ok":false,"error":{"name":"TypeError","message":"boom"}}')).resolves.toBeNull();
+    });
+    it('rejects unknown methods', async () => {
+        let response = '';
+        const peer = createRpcPeer({
+            localMethods: {},
+            transport: {
+                state: 'open',
+                send: (message) => {
+                    response = message;
+                },
+            },
+        });
+        await peer.handleMessage(JSON.stringify({ type: 'invoke', id: 1, method: 'missing', args: [] }));
+        expect(JSON.parse(response)).toMatchObject({
+            type: 'return',
+            id: 1,
+            ok: false,
+        });
+    });
+    it('dispatches incoming events', async () => {
+        const onEvent = vi.fn();
+        const peer = createRpcPeer({
+            localMethods: {},
+            transport: createMockTransport(),
+            onEvent,
+        });
+        await peer.handleMessage(JSON.stringify({
+            type: 'event',
+            event: { type: 'collection-started', file: 'example.ts' },
+        }));
+        expect(onEvent).toHaveBeenCalledWith({
+            type: 'collection-started',
+            file: 'example.ts',
+        });
+    });
+    it('rejects pending calls when closed', async () => {
+        const peer = createRpcPeer({
+            localMethods: {},
+            transport: createMockTransport(),
+        });
+        const pending = peer.invoke('runTests', 'example.ts', { runner: '/runner.js' });
+        peer.close(new Error('closed'));
+        await expect(pending).rejects.toThrow('closed');
+    });
+    it('rejects pending calls on timeout', async () => {
+        const peer = createRpcPeer({
+            localMethods: {},
+            transport: createMockTransport(),
+            callTimeoutMs: 10,
+            createTimeoutError: () => new Error('timed out'),
+        });
+        const pending = peer.invoke('runTests', 'example.ts', { runner: '/runner.js' });
+        await expect(pending).rejects.toThrow('timed out');
+    });
+    it('throws on malformed messages', async () => {
+        const peer = createRpcPeer({
+            localMethods: {},
+            transport: createMockTransport(),
+        });
+        await expect(peer.handleMessage('{"type":"invoke"}')).rejects.toThrow('Invalid bridge message: id must be a number');
+    });
+});

package/dist/client.d.ts

@@ -1,32 +1,25 @@
+import { type BridgeTransport } from './transport.js';
+import { createWebSocketClientTransport } from './websocket-client-transport.js';
 import type { DeviceDescriptor, BridgeEvents, FileReference, ImageSnapshotOptions, TestExecutionOptions, TestSuiteResult } from './shared.js';
-/** Handlers the app must implement for the CLI to call into. */
 export type HarnessCallbacks = {
     runTests: (path: string, options: TestExecutionOptions) => Promise<TestSuiteResult>;
 };
-/** The app-side handle returned by connectToHarness. */
 export type HarnessHandle = {
-    /** Call once when the app is initialised and ready to run tests. */
     reportReady: (device: DeviceDescriptor) => void;
-    /** Forward a test or bundler event to the CLI. */
     emitEvent: (event: BridgeEvents) => void;
-    /** Send a screenshot to the CLI and receive a file reference for snapshot comparison. */
     transferScreenshot: (data: Uint8Array, metadata: {
         width: number;
         height: number;
     }) => Promise<FileReference>;
-    /** Request an image snapshot comparison on the CLI. */
     matchImageSnapshot: (screenshot: FileReference, testPath: string, options: ImageSnapshotOptions, runner: string) => Promise<{
         pass: boolean;
         message: string;
     }>;
     disconnect: () => void;
 };
-/**
- * Connect the app to the CLI harness bridge.
- *
- * Pass the handlers the CLI can call (runTests). Returns a HarnessHandle
- * exposing the operations the app needs to drive a test run. The binary
- * transfer protocol and RPC wiring are fully encapsulated.
- */
-export declare const connectToHarness: (url: string, callbacks: HarnessCallbacks) => Promise<HarnessHandle>;
+export type ConnectToHarnessOptions = {
+    transport?: BridgeTransport;
+};
+export { createWebSocketClientTransport };
+export declare const connectToHarness: (url: string, callbacks: HarnessCallbacks, options?: ConnectToHarnessOptions) => Promise<HarnessHandle>;
 //# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAGV,gBAAgB,EAChB,YAAY,EACZ,aAAa,EACb,oBAAoB,EACpB,oBAAoB,EACpB,eAAe,EAChB,MAAM,aAAa,CAAC;AAMrB,gEAAgE;AAChE,MAAM,MAAM,gBAAgB,GAAG;IAC7B,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,oBAAoB,KAAK,OAAO,CAAC,eAAe,CAAC,CAAC;CACrF,CAAC;AAEF,wDAAwD;AACxD,MAAM,MAAM,aAAa,GAAG;IAC1B,oEAAoE;IACpE,WAAW,EAAE,CAAC,MAAM,EAAE,gBAAgB,KAAK,IAAI,CAAC;IAChD,kDAAkD;IAClD,SAAS,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,CAAC;IACzC,yFAAyF;IACzF,kBAAkB,EAAE,CAClB,IAAI,EAAE,UAAU,EAChB,QAAQ,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,KACxC,OAAO,CAAC,aAAa,CAAC,CAAC;IAC5B,uDAAuD;IACvD,kBAAkB,EAAE,CAClB,UAAU,EAAE,aAAa,EACzB,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,oBAAoB,EAC7B,MAAM,EAAE,MAAM,KACX,OAAO,CAAC;QAAE,IAAI,EAAE,OAAO,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACjD,UAAU,EAAE,MAAM,IAAI,CAAC;CACxB,CAAC;AAMF;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB,GAC3B,KAAK,MAAM,EACX,WAAW,gBAAgB,KAC1B,OAAO,CAAC,aAAa,CAyEpB,CAAC"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAGA,OAAO,EAEL,KAAK,eAAe,EACrB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,8BAA8B,EAAE,MAAM,iCAAiC,CAAC;AACjF,OAAO,KAAK,EAGV,gBAAgB,EAChB,YAAY,EACZ,aAAa,EACb,oBAAoB,EACpB,oBAAoB,EACpB,eAAe,EAChB,MAAM,aAAa,CAAC;AAErB,MAAM,MAAM,gBAAgB,GAAG;IAC7B,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,oBAAoB,KAAK,OAAO,CAAC,eAAe,CAAC,CAAC;CACrF,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG;IAC1B,WAAW,EAAE,CAAC,MAAM,EAAE,gBAAgB,KAAK,IAAI,CAAC;IAChD,SAAS,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,CAAC;IACzC,kBAAkB,EAAE,CAClB,IAAI,EAAE,UAAU,EAChB,QAAQ,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,KACxC,OAAO,CAAC,aAAa,CAAC,CAAC;IAC5B,kBAAkB,EAAE,CAClB,UAAU,EAAE,aAAa,EACzB,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,oBAAoB,EAC7B,MAAM,EAAE,MAAM,KACX,OAAO,CAAC;QAAE,IAAI,EAAE,OAAO,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACjD,UAAU,EAAE,MAAM,IAAI,CAAC;CACxB,CAAC;AAEF,MAAM,MAAM,uBAAuB,GAAG;IACpC,SAAS,CAAC,EAAE,eAAe,CAAC;CAC7B,CAAC;AAEF,OAAO,EAAE,8BAA8B,EAAE,CAAC;AAI1C,eAAO,MAAM,gBAAgB,GAC3B,KAAK,MAAM,EACX,WAAW,gBAAgB,EAC3B,UAAS,uBAA4B,KACpC,OAAO,CAAC,aAAa,CAyKpB,CAAC"}

package/dist/client.js

@@ -1,68 +1,122 @@
-import { createBirpc } from 'birpc';
-import { deserialize, serialize } from './serializer.js';
 import { createBinaryFrame, generateTransferId } from './binary-transfer.js';
-// ---------------------------------------------------------------------------
-// Factory
-// ---------------------------------------------------------------------------
-/**
- * Connect the app to the CLI harness bridge.
- *
- * Pass the handlers the CLI can call (runTests). Returns a HarnessHandle
- * exposing the operations the app needs to drive a test run. The binary
- * transfer protocol and RPC wiring are fully encapsulated.
- */
-export const connectToHarness = (url, callbacks) => new Promise((resolve, reject) => {
-    const ws = new WebSocket(url);
-    ws.binaryType = 'arraybuffer';
+import { serializeBridgeMessage } from './protocol.js';
+import { createRpcPeer } from './rpc-peer.js';
+import { createRpcTransport, } from './transport.js';
+import { createWebSocketClientTransport } from './websocket-client-transport.js';
+export { createWebSocketClientTransport };
+const noop = () => undefined;
+export const connectToHarness = (url, callbacks, options = {}) => new Promise((resolve, reject) => {
+    const transport = options.transport ?? createWebSocketClientTransport(url);
     let settled = false;
+    let peerClosed = false;
+    let offOpen = noop;
+    let offError = noop;
+    let offClose = noop;
     const cleanup = () => {
-        ws.removeEventListener('open', handleOpen);
-        ws.removeEventListener('error', handleError);
-        ws.removeEventListener('close', handleClose);
+        offOpen();
+        offError();
+        offClose();
     };
     const fail = (message) => {
-        if (settled)
+        if (settled) {
             return;
+        }
         settled = true;
         cleanup();
         reject(new Error(message));
     };
     const handleOpen = () => {
+        if (settled) {
+            return;
+        }
         settled = true;
         cleanup();
-        const rpc = createBirpc(callbacks, {
-            post: (data) => ws.send(data),
-            on: (handler) => {
-                ws.addEventListener('message', (event) => {
-                    if (typeof event.data === 'string')
-                        handler(event.data);
-                });
-            },
-            serialize,
-            deserialize,
+        const getTransportNotOpenError = () => {
+            return new Error('Harness bridge transport is not open');
+        };
+        const rpc = createRpcPeer({
+            localMethods: callbacks,
+            transport: createRpcTransport(transport),
+        });
+        let offMessage = noop;
+        let offRuntimeClose = noop;
+        let offRuntimeError = noop;
+        const closePeer = (reason) => {
+            if (peerClosed) {
+                return;
+            }
+            peerClosed = true;
+            offMessage();
+            offRuntimeClose();
+            offRuntimeError();
+            rpc.close(reason);
+        };
+        const handleMessage = async (data) => {
+            const controlMessage = await rpc.handleMessage(data);
+            if (!controlMessage) {
+                return;
+            }
+            if (controlMessage.type === 'ping') {
+                transport.send(serializeBridgeMessage({ type: 'pong', id: controlMessage.id }));
+            }
+        };
+        offMessage = transport.onMessage((message) => {
+            if (typeof message !== 'string') {
+                return;
+            }
+            void handleMessage(message).catch((error) => {
+                closePeer(error instanceof Error
+                    ? error
+                    : new Error('Received invalid Harness bridge message'));
+                if (transport.state === 'open') {
+                    transport.close(1002, 'Invalid message');
+                }
+            });
+        });
+        offRuntimeClose = transport.onClose((event) => {
+            closePeer(new Error(`Harness connection closed (code ${event.code}${event.reason ? `, reason: ${event.reason}` : ''})`));
+        });
+        offRuntimeError = transport.onError((error) => {
+            closePeer(error);
         });
         resolve({
-            reportReady: (device) => void rpc.reportReady(device),
-            emitEvent: (event) => void rpc.emitEvent(event.type, event),
+            reportReady: (device) => {
+                try {
+                    if (transport.state !== 'open') {
+                        throw getTransportNotOpenError();
+                    }
+                    transport.send(serializeBridgeMessage({ type: 'ready', device }));
+                }
+                catch (error) {
+                    closePeer(error instanceof Error ? error : getTransportNotOpenError());
+                }
+            },
+            emitEvent: (event) => {
+                rpc.sendEvent(event);
+            },
             transferScreenshot: async (data, metadata) => {
                 const transferId = generateTransferId();
-                ws.send(createBinaryFrame(transferId, data));
-                return rpc['device.screenshot.receive']({ type: 'binary', transferId, size: data.length, mimeType: 'image/png' }, metadata);
+                transport.send(createBinaryFrame(transferId, data));
+                return rpc.invoke('device.screenshot.receive', { type: 'binary', transferId, size: data.length, mimeType: 'image/png' }, metadata);
+            },
+            matchImageSnapshot: (screenshot, testPath, options, runner) => rpc.invoke('test.matchImageSnapshot', screenshot, testPath, options, runner),
+            disconnect: () => {
+                closePeer(new Error('Harness connection closed by client'));
+                transport.close();
             },
-            matchImageSnapshot: (screenshot, testPath, options, runner) => rpc['test.matchImageSnapshot'](screenshot, testPath, options, runner),
-            disconnect: () => ws.close(),
         });
     };
-    const handleError = (event) => {
-        const detail = typeof event.message === 'string' && event.message
-            ? `: ${event.message}`
-            : '';
+    const handleError = (error) => {
+        const detail = error.message ? `: ${error.message}` : '';
         fail(`Failed to connect to Harness at ${url}${detail}`);
     };
     const handleClose = (event) => {
         fail(`Harness connection at ${url} closed before becoming ready (code ${event.code}${event.reason ? `, reason: ${event.reason}` : ''})`);
     };
-    ws.addEventListener('open', handleOpen);
-    ws.addEventListener('error', handleError);
-    ws.addEventListener('close', handleClose);
+    offOpen = transport.onOpen(handleOpen);
+    offError = transport.onError(handleError);
+    offClose = transport.onClose(handleClose);
+    if (transport.state === 'open') {
+        handleOpen();
+    }
 });

package/dist/errors.d.ts

@@ -4,4 +4,9 @@ export declare class DeviceNotRespondingError extends HarnessError {
     readonly args: unknown[];
     constructor(functionName: string, args: unknown[]);
 }
+export type AppBridgeDisconnectedReason = 'app-disconnected' | 'app-replaced' | 'heartbeat-timeout' | 'socket-error' | 'bridge-disposed';
+export declare class AppBridgeDisconnectedError extends HarnessError {
+    readonly reason: AppBridgeDisconnectedReason;
+    constructor(reason: AppBridgeDisconnectedReason);
+}
 //# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAE3D,qBAAa,wBAAyB,SAAQ,YAAY;aAEtC,YAAY,EAAE,MAAM;aACpB,IAAI,EAAE,OAAO,EAAE;gBADf,YAAY,EAAE,MAAM,EACpB,IAAI,EAAE,OAAO,EAAE;CAKlC"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAE3D,qBAAa,wBAAyB,SAAQ,YAAY;aAEtC,YAAY,EAAE,MAAM;aACpB,IAAI,EAAE,OAAO,EAAE;gBADf,YAAY,EAAE,MAAM,EACpB,IAAI,EAAE,OAAO,EAAE;CAKlC;AAED,MAAM,MAAM,2BAA2B,GACnC,kBAAkB,GAClB,cAAc,GACd,mBAAmB,GACnB,cAAc,GACd,iBAAiB,CAAC;AAmBtB,qBAAa,0BAA2B,SAAQ,YAAY;aAC9B,MAAM,EAAE,2BAA2B;gBAAnC,MAAM,EAAE,2BAA2B;CAKhE"}

package/dist/errors.js

@@ -9,3 +9,26 @@ export class DeviceNotRespondingError extends HarnessError {
         this.name = 'DeviceNotRespondingError';
     }
 }
+const appBridgeDisconnectedMessage = (reason) => {
+    switch (reason) {
+        case 'app-replaced':
+            return 'The app bridge was replaced by a newer app connection. This can happen when the app reloads, restarts, or reconnects while a test file is still running.';
+        case 'heartbeat-timeout':
+            return 'The app bridge stopped responding during test execution. This can happen if the app was killed, crashed, became unresponsive, or lost its WebSocket connection.';
+        case 'socket-error':
+            return 'The app bridge connection failed during test execution. This can happen if the app was killed, crashed, or the underlying WebSocket connection closed unexpectedly.';
+        case 'bridge-disposed':
+            return 'The app bridge was disposed before the test file finished running.';
+        case 'app-disconnected':
+            return 'The app bridge disconnected during test execution. This can happen if the app was killed, crashed, reloaded, or restarted while the test file was running.';
+    }
+};
+export class AppBridgeDisconnectedError extends HarnessError {
+    reason;
+    constructor(reason) {
+        super(appBridgeDisconnectedMessage(reason));
+        this.reason = reason;
+        this.name = 'AppBridgeDisconnectedError';
+        this.stack = `${this.name}: ${this.message}`;
+    }
+}

package/dist/heartbeat.d.ts

@@ -0,0 +1,13 @@
+export declare const DEFAULT_HEARTBEAT_INTERVAL_MS = 5000;
+export declare const DEFAULT_HEARTBEAT_TIMEOUT_MS = 20000;
+export type BridgeHeartbeat = {
+    notifyPong: (id: number) => void;
+    dispose: () => void;
+};
+export declare const createHeartbeat: (options: {
+    sendPing: (id: number) => void;
+    onTimeout: () => void;
+    intervalMs?: number;
+    timeoutMs?: number;
+}) => BridgeHeartbeat;
+//# sourceMappingURL=heartbeat.d.ts.map

package/dist/heartbeat.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"heartbeat.d.ts","sourceRoot":"","sources":["../src/heartbeat.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,6BAA6B,OAAQ,CAAC;AACnD,eAAO,MAAM,4BAA4B,QAAS,CAAC;AAEnD,MAAM,MAAM,eAAe,GAAG;IAC5B,UAAU,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,CAAC;IACjC,OAAO,EAAE,MAAM,IAAI,CAAC;CACrB,CAAC;AAEF,eAAO,MAAM,eAAe,GAAI,SAAS;IACvC,QAAQ,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,CAAC;IAC/B,SAAS,EAAE,MAAM,IAAI,CAAC;IACtB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,KAAG,eAqDH,CAAC"}

package/dist/heartbeat.js

@@ -0,0 +1,49 @@
+export const DEFAULT_HEARTBEAT_INTERVAL_MS = 5_000;
+export const DEFAULT_HEARTBEAT_TIMEOUT_MS = 20_000;
+export const createHeartbeat = (options) => {
+    const intervalMs = options.intervalMs ?? DEFAULT_HEARTBEAT_INTERVAL_MS;
+    const timeoutMs = options.timeoutMs ?? DEFAULT_HEARTBEAT_TIMEOUT_MS;
+    let nextPingId = 1;
+    let pendingPingId = null;
+    let disposed = false;
+    let timeoutHandle = null;
+    const clearPendingTimeout = () => {
+        if (timeoutHandle) {
+            clearTimeout(timeoutHandle);
+            timeoutHandle = null;
+        }
+    };
+    const intervalHandle = setInterval(() => {
+        if (disposed || pendingPingId !== null) {
+            return;
+        }
+        const pingId = nextPingId++;
+        pendingPingId = pingId;
+        options.sendPing(pingId);
+        timeoutHandle = setTimeout(() => {
+            if (disposed || pendingPingId !== pingId) {
+                return;
+            }
+            pendingPingId = null;
+            timeoutHandle = null;
+            options.onTimeout();
+        }, timeoutMs);
+    }, intervalMs);
+    return {
+        notifyPong: (id) => {
+            if (id !== pendingPingId) {
+                return;
+            }
+            pendingPingId = null;
+            clearPendingTimeout();
+        },
+        dispose: () => {
+            if (disposed) {
+                return;
+            }
+            disposed = true;
+            clearInterval(intervalHandle);
+            clearPendingTimeout();
+        },
+    };
+};

package/dist/index.d.ts

@@ -1,3 +1,4 @@
 export * from './shared.js';
 export * from './binary-transfer.js';
+export * from './transport.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,sBAAsB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,sBAAsB,CAAC;AACrC,cAAc,gBAAgB,CAAC"}

package/dist/index.js

@@ -1,2 +1,3 @@
 export * from './shared.js';
 export * from './binary-transfer.js';
+export * from './transport.js';