refactor: simplify Harness architecture for safer evolution (#114)

## Summary
Introduce a set of architectural refactorings that make Harness easier
to understand, extend, and change safely without regressing existing
behavior.

## Context
This branch restructures the Jest, bridge, and runtime boundaries,
replaces global-state and ad hoc coupling with explicit session/domain
APIs, and adds coverage around the new abstractions. The goal is to make
future changes easier to reason about and to reduce the risk of breaking
previous behavior.

## Proposed Testing Scenario
Review the refactor across the Harness session, bridge, and runtime
layers, then run the Jest harness test suite and a representative
end-to-end path to confirm behavior is unchanged.

Author: V3RON

packages/babel-preset/src/resolve-weak-plugin.ts

@@ -6,6 +6,11 @@ const FUNCTIONS_REQUIRING_RESOLVE_WEAK = [
   'unmock',
   'requireActual',
 ] as const;
+type ResolveWeakFunctionName = (typeof FUNCTIONS_REQUIRING_RESOLVE_WEAK)[number];
+const isResolveWeakFunctionName = (
+  value: string
+): value is ResolveWeakFunctionName =>
+  FUNCTIONS_REQUIRING_RESOLVE_WEAK.includes(value as ResolveWeakFunctionName);
 
 const resolveWeakPlugin = ({
   types: t,
@@ -41,7 +46,7 @@ const resolveWeakPlugin = ({
           // Only transform if the function was imported from react-native-harness
           if (
             importedNames.has(functionName) &&
-            FUNCTIONS_REQUIRING_RESOLVE_WEAK.includes(functionName as any)
+            isResolveWeakFunctionName(functionName)
           ) {
             const firstArg = node.arguments[0];
 

packages/bridge/src/binary-transfer.ts

@@ -32,7 +32,7 @@ export function parseBinaryFrame(frame: Uint8Array): {
 
 export class BinaryStore {
   private store = new Map<number, Uint8Array>();
-  private timeouts = new Map<number, any>();
+  private timeouts = new Map<number, ReturnType<typeof setTimeout>>();
   // 5 minutes timeout for binary data
   private readonly TIMEOUT_MS = 5 * 60 * 1000;
 

packages/bridge/src/client.ts

@@ -1,19 +1,63 @@
-import { BirpcReturn, createBirpc } from 'birpc';
-import type { BridgeClientFunctions, BridgeServerFunctions } from './shared.js';
+import { createBirpc } from 'birpc';
 import { deserialize, serialize } from './serializer.js';
-import { createBinaryFrame } from './binary-transfer.js';
+import { createBinaryFrame, generateTransferId } from './binary-transfer.js';
+import type {
+  BridgeClientFunctions,
+  BridgeServerFunctions,
+  DeviceDescriptor,
+  BridgeEvents,
+  FileReference,
+  ImageSnapshotOptions,
+  TestExecutionOptions,
+  TestSuiteResult,
+} from './shared.js';
 
-export type BridgeClient = {
-  rpc: BirpcReturn<BridgeServerFunctions, BridgeClientFunctions>;
+// ---------------------------------------------------------------------------
+// Public types
+// ---------------------------------------------------------------------------
+
+/** 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;
-  sendBinary: (transferId: number, data: Uint8Array) => void;
 };
 
-const getBridgeClient = async (
+// ---------------------------------------------------------------------------
+// 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: string,
-  handlers: BridgeClientFunctions,
-): Promise<BridgeClient> => {
-  return new Promise((resolve, reject) => {
+  callbacks: HarnessCallbacks,
+): Promise<HarnessHandle> =>
+  new Promise((resolve, reject) => {
     const ws = new WebSocket(url);
     ws.binaryType = 'arraybuffer';
     let settled = false;
@@ -24,11 +68,8 @@ const getBridgeClient = async (
       ws.removeEventListener('close', handleClose);
     };
 
-    const rejectConnection = (message: string) => {
-      if (settled) {
-        return;
-      }
-
+    const fail = (message: string) => {
+      if (settled) return;
       settled = true;
       cleanup();
       reject(new Error(message));
@@ -39,56 +80,53 @@ const getBridgeClient = async (
       cleanup();
 
       const rpc = createBirpc<BridgeServerFunctions, BridgeClientFunctions>(
-        handlers,
+        callbacks,
         {
           post: (data) => ws.send(data),
           on: (handler) => {
-            ws.addEventListener('message', (event: any) => {
-              if (typeof event.data === 'string') {
-                handler(event.data);
-              }
+            ws.addEventListener('message', (event: MessageEvent<string | ArrayBuffer>) => {
+              if (typeof event.data === 'string') handler(event.data);
             });
           },
           serialize,
           deserialize,
         },
       );
 
-      const client: BridgeClient = {
-        rpc,
-        disconnect: () => {
-          ws.close();
-        },
-        sendBinary: (transferId: number, data: Uint8Array) => {
-          const frame = createBinaryFrame(transferId, data);
-          ws.send(frame);
+      resolve({
+        reportReady: (device) => void rpc.reportReady(device),
+        emitEvent: (event) => void rpc.emitEvent(event.type, 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,
+          );
         },
-      };
-
-      resolve(client);
+        matchImageSnapshot: (screenshot, testPath, options, runner) =>
+          rpc['test.matchImageSnapshot'](screenshot, testPath, options, runner),
+        disconnect: () => ws.close(),
+      });
     };
 
     const handleError = (event: Event & { message?: string }) => {
-      const reason =
-        typeof event.message === 'string' && event.message.length > 0
+      const detail =
+        typeof event.message === 'string' && event.message
           ? `: ${event.message}`
           : '';
-
-      rejectConnection(
-        `Failed to connect to the Harness bridge at ${url}${reason}`,
-      );
+      fail(`Failed to connect to Harness at ${url}${detail}`);
     };
 
     const handleClose = (event: CloseEvent) => {
-      rejectConnection(
-        `Harness bridge connection to ${url} closed before it became ready (code ${event.code}${event.reason ? `, reason: ${event.reason}` : ''})`,
+      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);
   });
-};
-
-export { getBridgeClient };