@react-native-harness/bridge 1.6.0 → 1.7.0

package/dist/app-liveness.d.ts

@@ -0,0 +1,33 @@
+import { type ConnectionCheckOptions, type PingableSocket } from './connection-check.js';
+import { AppBridgeDisconnectedError } from './errors.js';
+import { type JsBlockBudgetPolicyOptions } from './js-block-budget-policy.js';
+import type { BridgeEvents } from './shared.js';
+export type AppLivenessOptions = {
+    connectionCheck: ConnectionCheckOptions;
+    jsBlockBudget: JsBlockBudgetPolicyOptions;
+    jsProbeIntervalMs?: number;
+};
+export type AppLivenessOverrides = {
+    connectionCheck?: Partial<ConnectionCheckOptions>;
+    jsBlockBudget?: Partial<JsBlockBudgetPolicyOptions>;
+    jsProbeIntervalMs?: number;
+};
+export declare const DEFAULT_APP_LIVENESS_OPTIONS: AppLivenessOptions;
+export declare const resolveAppLivenessOptions: (overrides?: AppLivenessOverrides) => AppLivenessOptions;
+export type AppLiveness = {
+    handleEvent: (event: BridgeEvents) => void;
+    handleProbeAck: (id: number) => void;
+    dispose: () => void;
+};
+/**
+ * Watches one app connection with two independent checks: the connection
+ * check (is the process reachable?) and the JS watchdog (is the JS thread
+ * getting a turn?). See docs/adr/0001-app-liveness-detection.md.
+ */
+export declare const createAppLiveness: (options: {
+    socket: PingableSocket;
+    sendProbe: (id: number) => void;
+    onLost: (error: AppBridgeDisconnectedError) => void;
+    config: AppLivenessOptions;
+}) => AppLiveness;
+//# sourceMappingURL=app-liveness.d.ts.map

package/dist/app-liveness.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"app-liveness.d.ts","sourceRoot":"","sources":["../src/app-liveness.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,sBAAsB,EAC3B,KAAK,cAAc,EACpB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,0BAA0B,EAAE,MAAM,aAAa,CAAC;AACzD,OAAO,EAGL,KAAK,0BAA0B,EAChC,MAAM,6BAA6B,CAAC;AAErC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEhD,MAAM,MAAM,kBAAkB,GAAG;IAC/B,eAAe,EAAE,sBAAsB,CAAC;IACxC,aAAa,EAAE,0BAA0B,CAAC;IAC1C,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG;IACjC,eAAe,CAAC,EAAE,OAAO,CAAC,sBAAsB,CAAC,CAAC;IAClD,aAAa,CAAC,EAAE,OAAO,CAAC,0BAA0B,CAAC,CAAC;IACpD,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B,CAAC;AAEF,eAAO,MAAM,4BAA4B,EAAE,kBAG1C,CAAC;AASF,eAAO,MAAM,yBAAyB,GACpC,YAAW,oBAAyB,KACnC,kBAUD,CAAC;AAEH,MAAM,MAAM,WAAW,GAAG;IACxB,WAAW,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,CAAC;IAC3C,cAAc,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,CAAC;IACrC,OAAO,EAAE,MAAM,IAAI,CAAC;CACrB,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,GAAI,SAAS;IACzC,MAAM,EAAE,cAAc,CAAC;IACvB,SAAS,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,CAAC;IAChC,MAAM,EAAE,CAAC,KAAK,EAAE,0BAA0B,KAAK,IAAI,CAAC;IACpD,MAAM,EAAE,kBAAkB,CAAC;CAC5B,KAAG,WAkCH,CAAC"}

package/dist/app-liveness.js

@@ -0,0 +1,57 @@
+import { createConnectionCheck, } from './connection-check.js';
+import { AppBridgeDisconnectedError } from './errors.js';
+import { createJsBlockBudgetPolicy, getIdleBudget, } from './js-block-budget-policy.js';
+import { createJsWatchdog } from './js-watchdog.js';
+export const DEFAULT_APP_LIVENESS_OPTIONS = {
+    connectionCheck: { intervalMs: 5_000, timeoutMs: 20_000 },
+    jsBlockBudget: { idleMs: 20_000, fileLoadMs: 60_000, graceMs: 5_000 },
+};
+// An override left `undefined` keeps the default instead of replacing it,
+// which would turn a budget into `undefined` and disable it.
+const definedOnly = (values = {}) => Object.fromEntries(Object.entries(values).filter(([, value]) => value !== undefined));
+export const resolveAppLivenessOptions = (overrides = {}) => ({
+    connectionCheck: {
+        ...DEFAULT_APP_LIVENESS_OPTIONS.connectionCheck,
+        ...definedOnly(overrides.connectionCheck),
+    },
+    jsBlockBudget: {
+        ...DEFAULT_APP_LIVENESS_OPTIONS.jsBlockBudget,
+        ...definedOnly(overrides.jsBlockBudget),
+    },
+    jsProbeIntervalMs: overrides.jsProbeIntervalMs,
+});
+/**
+ * Watches one app connection with two independent checks: the connection
+ * check (is the process reachable?) and the JS watchdog (is the JS thread
+ * getting a turn?). See docs/adr/0001-app-liveness-detection.md.
+ */
+export const createAppLiveness = (options) => {
+    const connectionCheck = createConnectionCheck(options.socket, {
+        ...options.config.connectionCheck,
+        onLost: () => {
+            options.onLost(new AppBridgeDisconnectedError('connection-lost'));
+        },
+    });
+    const policy = createJsBlockBudgetPolicy(options.config.jsBlockBudget);
+    const watchdog = createJsWatchdog({
+        sendProbe: options.sendProbe,
+        initialBudget: getIdleBudget(options.config.jsBlockBudget),
+        probeIntervalMs: options.config.jsProbeIntervalMs,
+        onUnresponsive: (budget) => {
+            options.onLost(new AppBridgeDisconnectedError('js-thread-unresponsive', budget.label));
+        },
+    });
+    return {
+        handleEvent: (event) => {
+            const budget = policy.getBudgetForEvent(event);
+            if (budget) {
+                watchdog.setBlockBudget(budget);
+            }
+        },
+        handleProbeAck: watchdog.notifyProbeAck,
+        dispose: () => {
+            connectionCheck.dispose();
+            watchdog.dispose();
+        },
+    };
+};

package/dist/client.d.ts

@@ -1,5 +1,4 @@
-import { type BridgeTransport } from './transport.js';
-import { createWebSocketClientTransport } from './websocket-client-transport.js';
+import { type StandardWebSocket, type UplinkTransportConnection } from './link/index.js';
 import type { DeviceDescriptor, BridgeEvents, FileReference, ImageSnapshotOptions, TestExecutionOptions, TestSuiteResult } from './shared.js';
 export type HarnessCallbacks = {
     runTests: (path: string, options: TestExecutionOptions) => Promise<TestSuiteResult>;
@@ -19,8 +18,11 @@ export type HarnessHandle = {
     disconnect: () => void;
 };
 export type ConnectToHarnessOptions = {
-    transport?: BridgeTransport;
+    /** An already open link transport, used instead of dialing `url`. */
+    transport?: UplinkTransportConnection;
+    /** Creates the WebSocket to dial `url` with. Defaults to the global `WebSocket`. */
+    createSocket?: (url: string) => StandardWebSocket;
 };
-export { createWebSocketClientTransport };
+export type { UplinkTransportConnection };
 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,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;IACpF,gBAAgB,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CACvC,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"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AACA,OAAO,EAML,KAAK,iBAAiB,EACtB,KAAK,yBAAyB,EAC/B,MAAM,iBAAiB,CAAC;AAGzB,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;IACpF,gBAAgB,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CACvC,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,qEAAqE;IACrE,SAAS,CAAC,EAAE,yBAAyB,CAAC;IACtC,oFAAoF;IACpF,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,iBAAiB,CAAC;CACnD,CAAC;AAEF,YAAY,EAAE,yBAAyB,EAAE,CAAC;AA2C1C,eAAO,MAAM,gBAAgB,GAC3B,KAAK,MAAM,EACX,WAAW,gBAAgB,EAC3B,UAAS,uBAA4B,KACpC,OAAO,CAAC,aAAa,CA6HvB,CAAC"}

package/dist/client.js

@@ -1,122 +1,129 @@
-import { createBinaryFrame, generateTransferId } from './binary-transfer.js';
+import { sendBinary } from './binary.js';
+import { connectStandardWebSocket, createLink, globalClock, } from './link/index.js';
 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;
+const createConsoleLogger = () => {
+    const logger = {
+        debug: noop,
+        info: noop,
+        warn: (message) => console.warn(`[harness] ${message}`),
+        error: (message) => console.error(`[harness] ${message}`),
+        child: () => logger,
+    };
+    return logger;
+};
+// React Native has no `crypto.randomUUID`, so channel ids come from a counter. Ids only
+// need to be unique among this connection's channels.
+const createChannelIdGenerator = () => {
+    let nextId = 1;
+    return () => `app-${nextId++}`;
+};
+const dial = async (url, options) => {
+    if (options.transport) {
+        return options.transport;
+    }
+    try {
+        return await connectStandardWebSocket({
+            url,
+            createSocket: options.createSocket,
+        });
+    }
+    catch (error) {
+        const detail = error instanceof Error && error.message ? `: ${error.message}` : '';
+        throw new Error(`Failed to connect to Harness at ${url}${detail}`);
+    }
+};
+export const connectToHarness = async (url, callbacks, options = {}) => {
+    const transport = await dial(url, options);
+    const link = createLink(transport, {
+        end: 'worker',
+        clock: globalClock,
+        logger: createConsoleLogger(),
+        generateId: createChannelIdGenerator(),
+    });
+    const rpc = createRpcPeer({
+        localMethods: callbacks,
+        transport: {
+            send: (message) => {
+                void link.write(message);
+            },
+        },
+    });
     let peerClosed = false;
-    let offOpen = noop;
-    let offError = noop;
+    let offMessage = noop;
     let offClose = noop;
-    const cleanup = () => {
-        offOpen();
-        offError();
-        offClose();
+    let offError = noop;
+    const getLinkClosedError = () => {
+        return new Error('Harness bridge link is closed');
     };
-    const fail = (message) => {
-        if (settled) {
+    const closePeer = (reason) => {
+        if (peerClosed) {
             return;
         }
-        settled = true;
-        cleanup();
-        reject(new Error(message));
+        peerClosed = true;
+        offMessage();
+        offClose();
+        offError();
+        rpc.close(reason);
     };
-    const handleOpen = () => {
-        if (settled) {
+    const handleMessage = async (data) => {
+        const controlMessage = await rpc.handleMessage(data);
+        if (!controlMessage) {
             return;
         }
-        settled = true;
-        cleanup();
-        const getTransportNotOpenError = () => {
-            return new Error('Harness bridge transport is not open');
-        };
-        const rpc = createRpcPeer({
-            localMethods: callbacks,
-            transport: createRpcTransport(transport),
+        if (controlMessage.type === 'js-probe') {
+            void link.write(serializeBridgeMessage({ type: 'js-probe-ack', id: controlMessage.id }));
+        }
+    };
+    offMessage = link.onData((message) => {
+        void handleMessage(message).catch((error) => {
+            closePeer(error instanceof Error
+                ? error
+                : new Error('Received invalid Harness bridge message'));
+            void link.close();
         });
-        let offMessage = noop;
-        let offRuntimeClose = noop;
-        let offRuntimeError = noop;
-        const closePeer = (reason) => {
-            if (peerClosed) {
+    });
+    offError = link.onError((error) => {
+        closePeer(error);
+    });
+    offClose = link.onClose(() => {
+        closePeer(new Error('Harness connection closed'));
+    });
+    return {
+        reportReady: (device) => {
+            if (link.closed) {
+                closePeer(getLinkClosedError());
                 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 }));
+            void link.write(serializeBridgeMessage({ type: 'ready', device }));
+        },
+        emitEvent: (event) => {
+            rpc.sendEvent(event);
+        },
+        transferScreenshot: async (data, metadata) => {
+            const binary = await sendBinary(link, data);
+            try {
+                const [file] = await Promise.all([
+                    rpc.invoke('device.screenshot.receive', {
+                        type: 'binary',
+                        channelId: binary.channelId,
+                        size: data.length,
+                        mimeType: 'image/png',
+                    }, metadata),
+                    binary.written,
+                ]);
+                return file;
             }
-        };
-        offMessage = transport.onMessage((message) => {
-            if (typeof message !== 'string') {
-                return;
+            catch (error) {
+                binary.abort();
+                throw error;
             }
-            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) => {
-                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();
-                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.invoke('test.matchImageSnapshot', screenshot, testPath, options, runner),
+        disconnect: () => {
+            closePeer(new Error('Harness connection closed by client'));
+            void link.close();
+        },
     };
-    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}` : ''})`);
-    };
-    offOpen = transport.onOpen(handleOpen);
-    offError = transport.onError(handleError);
-    offClose = transport.onClose(handleClose);
-    if (transport.state === 'open') {
-        handleOpen();
-    }
-});
+};

package/dist/connection-check.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Checks that the app process is still reachable, using WebSocket protocol
+ * ping frames (RFC 6455). The app's native WebSocket answers them without
+ * involving JS (OkHttp on Android, SocketRocket on iOS, the network stack in
+ * browsers), so a blocked JS thread does not fail this check.
+ */
+export type PingableSocket = {
+    ping: () => void;
+    on: (event: 'pong', listener: () => void) => unknown;
+    off: (event: 'pong', listener: () => void) => unknown;
+};
+export type ConnectionCheckOptions = {
+    intervalMs: number;
+    timeoutMs: number;
+};
+export type ConnectionCheck = {
+    dispose: () => void;
+};
+export declare const createConnectionCheck: (socket: PingableSocket, options: ConnectionCheckOptions & {
+    onLost: () => void;
+}) => ConnectionCheck;
+//# sourceMappingURL=connection-check.d.ts.map

package/dist/connection-check.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"connection-check.d.ts","sourceRoot":"","sources":["../src/connection-check.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B,IAAI,EAAE,MAAM,IAAI,CAAC;IACjB,EAAE,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,IAAI,KAAK,OAAO,CAAC;IACrD,GAAG,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,IAAI,KAAK,OAAO,CAAC;CACvD,CAAC;AAEF,MAAM,MAAM,sBAAsB,GAAG;IACnC,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG;IAC5B,OAAO,EAAE,MAAM,IAAI,CAAC;CACrB,CAAC;AAEF,eAAO,MAAM,qBAAqB,GAChC,QAAQ,cAAc,EACtB,SAAS,sBAAsB,GAAG;IAAE,MAAM,EAAE,MAAM,IAAI,CAAA;CAAE,KACvD,eAmCF,CAAC"}

package/dist/connection-check.js

@@ -0,0 +1,30 @@
+export const createConnectionCheck = (socket, options) => {
+    let lastPongAt = Date.now();
+    let disposed = false;
+    const handlePong = () => {
+        lastPongAt = Date.now();
+    };
+    socket.on('pong', handlePong);
+    const dispose = () => {
+        if (disposed) {
+            return;
+        }
+        disposed = true;
+        clearInterval(interval);
+        socket.off('pong', handlePong);
+    };
+    const interval = setInterval(() => {
+        if (Date.now() - lastPongAt > options.timeoutMs) {
+            dispose();
+            options.onLost();
+            return;
+        }
+        try {
+            socket.ping();
+        }
+        catch {
+            // The socket is closing; its close event ends the session.
+        }
+    }, options.intervalMs);
+    return { dispose };
+};

package/dist/errors.d.ts

@@ -4,9 +4,13 @@ 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 type AppBridgeDisconnectedReason = 'app-disconnected' | 'app-replaced' | 'connection-lost' | 'js-thread-unresponsive' | 'socket-error' | 'bridge-disposed';
 export declare class AppBridgeDisconnectedError extends HarnessError {
     readonly reason: AppBridgeDisconnectedReason;
-    constructor(reason: AppBridgeDisconnectedReason);
+    /** What the app was busy with, when known. Appended to the message. */
+    readonly detail?: string | undefined;
+    constructor(reason: AppBridgeDisconnectedReason, 
+    /** What the app was busy with, when known. Appended to the message. */
+    detail?: string | undefined);
 }
 //# 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;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"}
+{"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,iBAAiB,GACjB,wBAAwB,GACxB,cAAc,GACd,iBAAiB,CAAC;AAqBtB,qBAAa,0BAA2B,SAAQ,YAAY;aAExC,MAAM,EAAE,2BAA2B;IACnD,uEAAuE;aACvD,MAAM,CAAC,EAAE,MAAM;gBAFf,MAAM,EAAE,2BAA2B;IACnD,uEAAuE;IACvD,MAAM,CAAC,EAAE,MAAM,YAAA;CAUlC"}

package/dist/errors.js

@@ -13,8 +13,10 @@ 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 'connection-lost':
+            return 'The app stopped answering WebSocket pings during test execution. The app process was likely killed, frozen, or lost its network connection. Check .harness/crash-reports for a crash report.';
+        case 'js-thread-unresponsive':
+            return "The app's JS thread was blocked for longer than allowed during test execution.";
         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':
@@ -25,9 +27,15 @@ const appBridgeDisconnectedMessage = (reason) => {
 };
 export class AppBridgeDisconnectedError extends HarnessError {
     reason;
-    constructor(reason) {
-        super(appBridgeDisconnectedMessage(reason));
+    detail;
+    constructor(reason, 
+    /** What the app was busy with, when known. Appended to the message. */
+    detail) {
+        super(detail
+            ? `${appBridgeDisconnectedMessage(reason)} It was busy with: ${detail}.`
+            : appBridgeDisconnectedMessage(reason));
         this.reason = reason;
+        this.detail = detail;
         this.name = 'AppBridgeDisconnectedError';
         this.stack = `${this.name}: ${this.message}`;
     }

package/dist/image-snapshot.d.ts

@@ -1,5 +1,5 @@
-import type { FileReference, ImageSnapshotOptions } from './shared.js';
-export declare const matchImageSnapshot: (screenshot: FileReference, testFilePath: string, options: ImageSnapshotOptions, platformName: string) => Promise<{
+import type { FileReference, ImageSnapshotOptions, SnapshotUpdateState } from './shared.js';
+export declare const matchImageSnapshot: (screenshot: FileReference, testFilePath: string, options: ImageSnapshotOptions, platformName: string, updateSnapshot: SnapshotUpdateState) => Promise<{
     pass: boolean;
     message: string;
 }>;

package/dist/image-snapshot.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"image-snapshot.d.ts","sourceRoot":"","sources":["../src/image-snapshot.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,aAAa,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AA0CvE,eAAO,MAAM,kBAAkB,GAC7B,YAAY,aAAa,EACzB,cAAc,MAAM,EACpB,SAAS,oBAAoB,EAC7B,cAAc,MAAM;;;EAsHrB,CAAC"}
+{"version":3,"file":"image-snapshot.d.ts","sourceRoot":"","sources":["../src/image-snapshot.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EACV,aAAa,EACb,oBAAoB,EACpB,mBAAmB,EACpB,MAAM,aAAa,CAAC;AA2CrB,eAAO,MAAM,kBAAkB,GAC7B,YAAY,aAAa,EACzB,cAAc,MAAM,EACpB,SAAS,oBAAoB,EAC7B,cAAc,MAAM,EACpB,gBAAgB,mBAAmB;;;EAsIpC,CAAC"}

package/dist/image-snapshot.js

@@ -4,6 +4,7 @@ import fs from 'node:fs/promises';
 import path from 'node:path';
 import { PNG } from 'pngjs';
 const SNAPSHOT_DIR_NAME = '__image_snapshots__';
+const DIFF_OUTPUT_DIR_NAME = '__diff_output__';
 const DEFAULT_OPTIONS_FOR_PIXELMATCH = {
     threshold: 0.1,
     includeAA: false,
@@ -31,7 +32,7 @@ function maskRegions(data, imageWidth, regions) {
         }
     }
 }
-export const matchImageSnapshot = async (screenshot, testFilePath, options, platformName) => {
+export const matchImageSnapshot = async (screenshot, testFilePath, options, platformName, updateSnapshot) => {
     const pixelmatchOptions = {
         ...DEFAULT_OPTIONS_FOR_PIXELMATCH,
         ...options,
@@ -47,13 +48,25 @@ export const matchImageSnapshot = async (screenshot, testFilePath, options, plat
     // Create __image_snapshots__ directory in same directory as test file
     const testDir = path.dirname(testFilePath);
     const snapshotsDir = path.join(testDir, SNAPSHOT_DIR_NAME, platformName);
-    const snapshotName = `${options.name}.png`;
-    const snapshotPath = path.join(snapshotsDir, snapshotName);
+    const snapshotPath = path.join(snapshotsDir, `${options.name}.png`);
+    // Failure artifacts live in their own folder so they can never overwrite
+    // a baseline of another snapshot (e.g. one named `<name>-diff`).
+    const diffOutputDir = path.join(snapshotsDir, DIFF_OUTPUT_DIR_NAME);
+    const failureImagePath = (image) => path.join(diffOutputDir, `${options.name}-${image}.png`);
+    const actualPath = failureImagePath('actual');
     await fs.mkdir(snapshotsDir, { recursive: true });
     try {
         await fs.access(snapshotPath);
     }
     catch {
+        if (updateSnapshot === 'none') {
+            await fs.mkdir(diffOutputDir, { recursive: true });
+            await fs.writeFile(actualPath, receivedBuffer);
+            return {
+                pass: false,
+                message: `New snapshot was not written: ${snapshotPath} does not exist, and missing snapshots are not written in CI mode. Received image saved at ${actualPath}; commit it as ${snapshotPath}, or run without CI mode (--ci=false) on a machine with this device and commit the snapshot it writes.`,
+            };
+        }
         // First time - create snapshot
         await fs.writeFile(snapshotPath, receivedBuffer);
         return {
@@ -70,9 +83,11 @@ export const matchImageSnapshot = async (screenshot, testFilePath, options, plat
     const { width, height } = img1;
     const diff = new PNG({ width, height });
     if (img1.width !== img2.width || img1.height !== img2.height) {
+        await fs.mkdir(diffOutputDir, { recursive: true });
+        await fs.writeFile(actualPath, receivedBuffer);
         return {
             pass: false,
-            message: `Images have different dimensions. Received image width: ${img1.width}, height: ${img1.height}. Snapshot image width: ${img2.width}, height: ${img2.height}.`,
+            message: `Images have different dimensions. Received image width: ${img1.width}, height: ${img1.height}. Snapshot image width: ${img2.width}, height: ${img2.height}. Actual image saved at ${actualPath}.`,
         };
     }
     if (options.ignoreRegions) {
@@ -116,11 +131,9 @@ export const matchImageSnapshot = async (screenshot, testFilePath, options, plat
     }
     // Save diff and actual images when test fails
     if (!pass) {
-        const diffFileName = `${snapshotName.replace('.png', '')}-diff.png`;
-        const diffPath = path.join(snapshotsDir, diffFileName);
+        await fs.mkdir(diffOutputDir, { recursive: true });
+        const diffPath = failureImagePath('diff');
         await fs.writeFile(diffPath, PNG.sync.write(diff));
-        const actualFileName = `${snapshotName.replace('.png', '')}-actual.png`;
-        const actualPath = path.join(snapshotsDir, actualFileName);
         await fs.writeFile(actualPath, receivedBuffer);
         message += ` Diff saved at ${diffPath}. Actual image saved at ${actualPath}.`;
     }

package/dist/index.d.ts

@@ -1,4 +1,2 @@
 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;AACrC,cAAc,gBAAgB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC"}

package/dist/index.js

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

package/dist/js-block-budget-policy.d.ts

@@ -0,0 +1,31 @@
+import type { JsBlockBudget } from './js-watchdog.js';
+import type { BridgeEvents } from './shared.js';
+export type JsBlockBudgetPolicyOptions = {
+    /** Budget outside any test, hook or file load. */
+    idleMs: number;
+    /** Budget while a setup file or test file loads (module code and `describe` bodies). */
+    fileLoadMs: number;
+    /** Added to a test's or hook's own timeout. */
+    graceMs: number;
+};
+export declare const IDLE_BUDGET_LABEL = "between test phases";
+export declare const getIdleBudget: (options: JsBlockBudgetPolicyOptions) => JsBlockBudget;
+export type JsBlockBudgetPolicy = {
+    /**
+     * Returns the block budget that applies from this event on, or `null` for
+     * events that do not change it.
+     */
+    getBudgetForEvent: (event: BridgeEvents) => JsBlockBudget | null;
+};
+/**
+ * Maps runner events to block budgets. Budgets come from timeouts the user
+ * already configures, so long work within them never fails a run:
+ *
+ * - loading a setup file or test file: `fileLoadMs`
+ * - a test, including its `beforeEach`/`afterEach` hooks: its timeout + grace
+ * - a suite's `beforeAll`/`afterAll` hooks: the hook timeout + grace, from
+ *   `suite-started` until `suite-finished`, outside the suite's tests
+ * - anything else: `idleMs`
+ */
+export declare const createJsBlockBudgetPolicy: (options: JsBlockBudgetPolicyOptions) => JsBlockBudgetPolicy;
+//# sourceMappingURL=js-block-budget-policy.d.ts.map

package/dist/js-block-budget-policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"js-block-budget-policy.d.ts","sourceRoot":"","sources":["../src/js-block-budget-policy.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACtD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEhD,MAAM,MAAM,0BAA0B,GAAG;IACvC,kDAAkD;IAClD,MAAM,EAAE,MAAM,CAAC;IACf,wFAAwF;IACxF,UAAU,EAAE,MAAM,CAAC;IACnB,+CAA+C;IAC/C,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,eAAO,MAAM,iBAAiB,wBAAwB,CAAC;AAEvD,eAAO,MAAM,aAAa,GACxB,SAAS,0BAA0B,KAClC,aAAmE,CAAC;AAEvE,MAAM,MAAM,mBAAmB,GAAG;IAChC;;;OAGG;IACH,iBAAiB,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,aAAa,GAAG,IAAI,CAAC;CAClE,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,yBAAyB,GACpC,SAAS,0BAA0B,KAClC,mBAmDF,CAAC"}