@flighthq/ipc 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * from './ipc';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,OAAO,CAAC"}

package/dist/index.js

@@ -0,0 +1,2 @@
+export * from './ipc';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,OAAO,CAAC"}

package/dist/ipc.d.ts

@@ -0,0 +1,19 @@
+import type { IpcBackend, IpcChannel, IpcMessageEvent, IpcSignals, IpcTarget } from '@flighthq/types';
+export declare function createIpcChannel(name: string): IpcChannel;
+export declare function createWebIpcBackend(): IpcBackend;
+export declare function enableIpcSignals(): IpcSignals;
+export declare function getIpcBackend(): IpcBackend;
+export declare function getIpcListenerCount(channel: string | Readonly<IpcChannel>): number;
+export declare function getIpcSignals(): Readonly<IpcSignals> | null;
+export declare function hasIpcBackend(): boolean;
+export declare function invokeIpc(channel: string | Readonly<IpcChannel>, ...args: readonly unknown[]): Promise<unknown>;
+export declare function invokeIpcWithTimeout(channel: string | Readonly<IpcChannel>, timeoutMs: number, ...args: readonly unknown[]): Promise<unknown>;
+export declare function onceIpcMessage(channel: string | Readonly<IpcChannel>, listener: (...args: readonly unknown[]) => void): () => void;
+export declare function onIpcInvoke(channel: string | Readonly<IpcChannel>, handler: (...args: readonly unknown[]) => unknown | Promise<unknown>): () => void;
+export declare function onIpcMessage(channel: string | Readonly<IpcChannel>, listener: (...args: readonly unknown[]) => void): () => void;
+export declare function onIpcMessageEvent(channel: string | Readonly<IpcChannel>, listener: (event: Readonly<IpcMessageEvent>) => void): () => void;
+export declare function removeAllIpcListeners(channel?: string | Readonly<IpcChannel>): void;
+export declare function sendIpcMessage(channel: string | Readonly<IpcChannel>, ...args: readonly unknown[]): void;
+export declare function sendIpcMessageTo(target: Readonly<IpcTarget>, channel: string | Readonly<IpcChannel>, ...args: readonly unknown[]): void;
+export declare function setIpcBackend(backend: IpcBackend | null): void;
+//# sourceMappingURL=ipc.d.ts.map

package/dist/ipc.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ipc.d.ts","sourceRoot":"","sources":["../src/ipc.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,UAAU,EAEV,UAAU,EACV,eAAe,EACf,UAAU,EACV,SAAS,EACV,MAAM,iBAAiB,CAAC;AAwCzB,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,CAEzD;AAID,wBAAgB,mBAAmB,IAAI,UAAU,CAahD;AAKD,wBAAgB,gBAAgB,IAAI,UAAU,CAQ7C;AAGD,wBAAgB,aAAa,IAAI,UAAU,CAG1C;AAGD,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,QAAQ,CAAC,UAAU,CAAC,GAAG,MAAM,CAGlF;AAGD,wBAAgB,aAAa,IAAI,QAAQ,CAAC,UAAU,CAAC,GAAG,IAAI,CAE3D;AAID,wBAAgB,aAAa,IAAI,OAAO,CAEvC;AAID,wBAAgB,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,QAAQ,CAAC,UAAU,CAAC,EAAE,GAAG,IAAI,EAAE,SAAS,OAAO,EAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAE/G;AAID,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,MAAM,GAAG,QAAQ,CAAC,UAAU,CAAC,EACtC,SAAS,EAAE,MAAM,EACjB,GAAG,IAAI,EAAE,SAAS,OAAO,EAAE,GAC1B,OAAO,CAAC,OAAO,CAAC,CAYlB;AAID,wBAAgB,cAAc,CAC5B,OAAO,EAAE,MAAM,GAAG,QAAQ,CAAC,UAAU,CAAC,EACtC,QAAQ,EAAE,CAAC,GAAG,IAAI,EAAE,SAAS,OAAO,EAAE,KAAK,IAAI,GAC9C,MAAM,IAAI,CAOZ;AAKD,wBAAgB,WAAW,CACzB,OAAO,EAAE,MAAM,GAAG,QAAQ,CAAC,UAAU,CAAC,EACtC,OAAO,EAAE,CAAC,GAAG,IAAI,EAAE,SAAS,OAAO,EAAE,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,GACnE,MAAM,IAAI,CAIZ;AAID,wBAAgB,YAAY,CAC1B,OAAO,EAAE,MAAM,GAAG,QAAQ,CAAC,UAAU,CAAC,EACtC,QAAQ,EAAE,CAAC,GAAG,IAAI,EAAE,SAAS,OAAO,EAAE,KAAK,IAAI,GAC9C,MAAM,IAAI,CAgBZ;AAID,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,MAAM,GAAG,QAAQ,CAAC,UAAU,CAAC,EACtC,QAAQ,EAAE,CAAC,KAAK,EAAE,QAAQ,CAAC,eAAe,CAAC,KAAK,IAAI,GACnD,MAAM,IAAI,CAyBZ;AAGD,wBAAgB,qBAAqB,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,QAAQ,CAAC,UAAU,CAAC,GAAG,IAAI,CAYnF;AAGD,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,QAAQ,CAAC,UAAU,CAAC,EAAE,GAAG,IAAI,EAAE,SAAS,OAAO,EAAE,GAAG,IAAI,CAExG;AAID,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,QAAQ,CAAC,SAAS,CAAC,EAC3B,OAAO,EAAE,MAAM,GAAG,QAAQ,CAAC,UAAU,CAAC,EACtC,GAAG,IAAI,EAAE,SAAS,OAAO,EAAE,GAC1B,IAAI,CAEN;AAGD,wBAAgB,aAAa,CAAC,OAAO,EAAE,UAAU,GAAG,IAAI,GAAG,IAAI,CAG9D"}

package/dist/ipc.js

@@ -0,0 +1,199 @@
+import { createSignal, emitSignal } from '@flighthq/signals';
+import { IpcTimeoutError } from '@flighthq/types';
+// Resolves a channel argument that may be either a string or an IpcChannel descriptor.
+function resolveChannel(channel) {
+    return typeof channel === 'string' ? channel : channel.name;
+}
+// ---- Bronze: listener registry for once/removeAll/count ----
+// Package-local listener tracking, keyed by channel name. Used by onceIpcMessage,
+// removeAllIpcListeners, and getIpcListenerCount. Each entry is the unsubscribe thunk
+// returned by the backend, associated with a channel string.
+const _listeners = new Map();
+function _trackListener(channel, unsubscribe) {
+    let set = _listeners.get(channel);
+    if (set === undefined) {
+        set = new Set();
+        _listeners.set(channel, set);
+    }
+    set.add(unsubscribe);
+}
+function _untrackListener(channel, unsubscribe) {
+    const set = _listeners.get(channel);
+    if (set !== undefined) {
+        set.delete(unsubscribe);
+        if (set.size === 0)
+            _listeners.delete(channel);
+    }
+}
+// ---- IpcSignals (Silver opt-in) ----
+let _ipcSignals = null;
+// ---- Core backend ----
+// Creates a typed channel descriptor. Functions that accept a channel string also accept an
+// IpcChannel, so a feature can publish its channel constants once and get a single grep target.
+export function createIpcChannel(name) {
+    return { name };
+}
+// Builds the default web backend. There is no main process on web, so send no-ops, invoke resolves
+// to undefined, and subscribe returns an inert unsubscribe — a native host is required for real IPC.
+export function createWebIpcBackend() {
+    return {
+        send() { },
+        invoke() {
+            return Promise.resolve(undefined);
+        },
+        subscribe() {
+            return () => { };
+        },
+        getCapabilities() {
+            return { canHandle: false, canInvoke: false, canSend: false, canTarget: false };
+        },
+    };
+}
+// Activates the optional IpcSignals group and returns it. Calling this is when the cost is assumed.
+// The returned object is shared for the lifetime of the package; calling enableIpcSignals multiple
+// times returns the same instance.
+export function enableIpcSignals() {
+    if (_ipcSignals === null) {
+        _ipcSignals = {
+            onBackendChanged: createSignal(),
+            onChannelMessage: createSignal(),
+        };
+    }
+    return _ipcSignals;
+}
+// Returns the active IpcBackend, or a lazily-created web default. There is always a backend.
+export function getIpcBackend() {
+    if (_backend === null)
+        _backend = createWebIpcBackend();
+    return _backend;
+}
+// Returns the count of active in-package listeners on a channel. Returns 0 for an unknown channel.
+export function getIpcListenerCount(channel) {
+    const name = resolveChannel(channel);
+    return _listeners.get(name)?.size ?? 0;
+}
+// Returns the active IpcSignals group, or null if enableIpcSignals has not been called.
+export function getIpcSignals() {
+    return _ipcSignals;
+}
+// Returns true when a real native backend is installed, false when the lazy web default is active.
+// Use this to distinguish "no main process" (web) from a connected host without performing an invoke.
+export function hasIpcBackend() {
+    return _backend !== null;
+}
+// Sends a request on `channel` and resolves with the host's response, or undefined on web.
+// Rejects with a plain Error if the host handler throws.
+export function invokeIpc(channel, ...args) {
+    return getIpcBackend().invoke(resolveChannel(channel), args);
+}
+// Sends a request on `channel` and resolves with the host's response, or rejects with
+// IpcTimeoutError if the invoke does not complete within timeoutMs milliseconds.
+export function invokeIpcWithTimeout(channel, timeoutMs, ...args) {
+    const name = resolveChannel(channel);
+    const invoke = getIpcBackend().invoke(name, args);
+    const timeout = new Promise((_, reject) => {
+        const id = setTimeout(() => reject(new IpcTimeoutError(name, timeoutMs)), timeoutMs);
+        // Attach a no-op catch so the invoke rejection does not surface if timeout fires first.
+        invoke.then(() => clearTimeout(id), () => clearTimeout(id));
+    });
+    return Promise.race([invoke, timeout]);
+}
+// Subscribes `listener` to a single message on `channel`, then auto-unsubscribes.
+// Returns an unsubscribe thunk for the not-yet-fired case.
+export function onceIpcMessage(channel, listener) {
+    let unsubscribe = null;
+    unsubscribe = onIpcMessage(channel, (...args) => {
+        unsubscribe?.();
+        listener(...args);
+    });
+    return unsubscribe;
+}
+// Registers a responder for invokeIpc calls on `channel`. The handler may return a value or a
+// Promise. Returns an unregister thunk. Requires a backend that supports `handle`; if the backend
+// does not support it, returns an inert no-op unsubscribe.
+export function onIpcInvoke(channel, handler) {
+    const backend = getIpcBackend();
+    if (typeof backend.handle !== 'function')
+        return () => { };
+    return backend.handle(resolveChannel(channel), handler);
+}
+// Subscribes `listener` to messages on `channel`; returns an unsubscribe function.
+// Incoming args are spread to the listener, mirroring sendIpcMessage's variadic shape.
+export function onIpcMessage(channel, listener) {
+    const name = resolveChannel(channel);
+    const backend = getIpcBackend();
+    const signals = _ipcSignals;
+    const unsubscribe = backend.subscribe(name, (args) => {
+        if (signals !== null)
+            emitSignal(signals.onChannelMessage, name);
+        listener(...args);
+    });
+    const tracked = () => {
+        unsubscribe();
+        _untrackListener(name, tracked);
+    };
+    _trackListener(name, tracked);
+    return tracked;
+}
+// Subscribes `listener` to messages on `channel`, delivering an IpcMessageEvent with channel,
+// senderId, args, and a reply thunk. The existing args-spread onIpcMessage path stays untouched.
+export function onIpcMessageEvent(channel, listener) {
+    const name = resolveChannel(channel);
+    const backend = getIpcBackend();
+    const signals = _ipcSignals;
+    const unsubscribe = backend.subscribe(name, (args) => {
+        if (signals !== null)
+            emitSignal(signals.onChannelMessage, name);
+        const event = {
+            channel: name,
+            senderId: -1,
+            args,
+            reply(...replyArgs) {
+                if (this.senderId === -1)
+                    return;
+                backend.sendTo?.({ windowId: this.senderId }, name, replyArgs);
+            },
+        };
+        listener(event);
+    });
+    const tracked = () => {
+        unsubscribe();
+        _untrackListener(name, tracked);
+    };
+    _trackListener(name, tracked);
+    return tracked;
+}
+// Drops every in-package listener for `channel`, or all channels when omitted.
+export function removeAllIpcListeners(channel) {
+    if (channel !== undefined) {
+        const name = resolveChannel(channel);
+        const set = _listeners.get(name);
+        if (set !== undefined) {
+            for (const unsubscribe of [...set])
+                unsubscribe();
+        }
+    }
+    else {
+        for (const [, set] of [..._listeners]) {
+            for (const unsubscribe of [...set])
+                unsubscribe();
+        }
+    }
+}
+// Sends a fire-and-forget message on `channel`. No-ops on web (no main process).
+export function sendIpcMessage(channel, ...args) {
+    getIpcBackend().send(resolveChannel(channel), args);
+}
+// Sends a fire-and-forget message to a specific target window/process. No-ops when the backend
+// does not support targeted send (i.e. `getCapabilities().canTarget` is false or `sendTo` is absent).
+export function sendIpcMessageTo(target, channel, ...args) {
+    getIpcBackend().sendTo?.(target, resolveChannel(channel), args);
+}
+// Installs a native host IPC backend; pass null to fall back to the web default.
+export function setIpcBackend(backend) {
+    _backend = backend;
+    if (_ipcSignals !== null)
+        emitSignal(_ipcSignals.onBackendChanged);
+}
+let _backend = null;
+//# sourceMappingURL=ipc.js.map

package/dist/ipc.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ipc.js","sourceRoot":"","sources":["../src/ipc.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@flighthq/ipc",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src/**/*.test.ts",
+    "!dist/**/*.test.js",
+    "!dist/**/*.test.d.ts",
+    "!dist/**/*.test.js.map",
+    "!dist/**/*.test.d.ts.map"
+  ],
+  "scripts": {
+    "build": "tsc -b",
+    "clean": "tsc -b --clean",
+    "test": "vitest run --config vitest.config.ts",
+    "test:watch": "vitest --watch --config vitest.config.ts",
+    "prepack": "npm run clean && npm run clean:dist && npm run build",
+    "clean:dist": "tsx ../../scripts/clean-package-dist.ts"
+  },
+  "dependencies": {
+    "@flighthq/signals": "0.1.0",
+    "@flighthq/types": "0.1.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.3.0"
+  },
+  "description": "Inter-process messaging (send, invoke, per-channel subscribe) over a swappable web/native backend",
+  "sideEffects": false
+}

package/src/ipc.test.ts

@@ -0,0 +1,495 @@
+import type { IpcBackend, IpcBackendCapabilities, IpcChannel, IpcSignals } from '@flighthq/types';
+import { IpcTimeoutError } from '@flighthq/types';
+
+import {
+  createIpcChannel,
+  createWebIpcBackend,
+  enableIpcSignals,
+  getIpcBackend,
+  getIpcListenerCount,
+  getIpcSignals,
+  hasIpcBackend,
+  invokeIpc,
+  invokeIpcWithTimeout,
+  onceIpcMessage,
+  onIpcInvoke,
+  onIpcMessage,
+  onIpcMessageEvent,
+  removeAllIpcListeners,
+  sendIpcMessage,
+  sendIpcMessageTo,
+  setIpcBackend,
+} from './ipc';
+
+interface FakeIpcBackend extends IpcBackend {
+  sent: { channel: string; args: readonly unknown[] }[];
+  sentTo: { target: { windowId: number }; channel: string; args: readonly unknown[] }[];
+  result: unknown;
+  handlers: Map<string, (...args: readonly unknown[]) => unknown | Promise<unknown>>;
+  fire: (channel: string, args: readonly unknown[]) => void;
+}
+
+function fakeBackend(
+  opts: { canSend?: boolean; canInvoke?: boolean; canHandle?: boolean; canTarget?: boolean } = {},
+): FakeIpcBackend {
+  const { canSend = true, canInvoke = true, canHandle = true, canTarget = true } = opts;
+
+  const listeners = new Map<string, (args: readonly unknown[]) => void>();
+  const backend: FakeIpcBackend = {
+    sent: [],
+    sentTo: [],
+    result: undefined,
+    handlers: new Map(),
+    send(channel, args) {
+      this.sent.push({ channel, args });
+    },
+    invoke(channel, _args) {
+      return Promise.resolve(this.result);
+    },
+    subscribe(channel, listener) {
+      listeners.set(channel, listener);
+      return () => {
+        listeners.delete(channel);
+      };
+    },
+    handle(channel, handler) {
+      this.handlers.set(channel, handler);
+      return () => {
+        this.handlers.delete(channel);
+      };
+    },
+    sendTo(target, channel, args) {
+      this.sentTo.push({ target, channel, args });
+    },
+    getCapabilities(): Readonly<IpcBackendCapabilities> {
+      return { canHandle, canInvoke, canSend, canTarget };
+    },
+    fire(channel, args) {
+      listeners.get(channel)?.(args);
+    },
+  };
+  return backend;
+}
+
+afterEach(() => {
+  setIpcBackend(null);
+  removeAllIpcListeners();
+});
+
+describe('createIpcChannel', () => {
+  it('returns a descriptor with the given name', () => {
+    const ch: IpcChannel = createIpcChannel('events.ready');
+    expect(ch.name).toBe('events.ready');
+  });
+
+  it('accepts IpcChannel descriptors in sendIpcMessage', () => {
+    const backend = fakeBackend();
+    setIpcBackend(backend);
+    const ch = createIpcChannel('log');
+    sendIpcMessage(ch, 'hello');
+    expect(backend.sent).toEqual([{ channel: 'log', args: ['hello'] }]);
+  });
+
+  it('accepts IpcChannel descriptors in onIpcMessage', () => {
+    const backend = fakeBackend();
+    setIpcBackend(backend);
+    const ch = createIpcChannel('event');
+    const received: unknown[] = [];
+    onIpcMessage(ch, (...args) => received.push(...args));
+    backend.fire('event', ['x']);
+    expect(received).toEqual(['x']);
+  });
+});
+
+describe('createWebIpcBackend', () => {
+  it('no-ops send, resolves invoke to undefined, returns an inert unsubscribe', async () => {
+    const backend = createWebIpcBackend();
+    expect(() => backend.send('channel', [1])).not.toThrow();
+    expect(await backend.invoke('channel', [])).toBeUndefined();
+    expect(typeof backend.subscribe('channel', () => {})).toBe('function');
+  });
+
+  it('reports canSend/canInvoke/canHandle/canTarget as false', () => {
+    const backend = createWebIpcBackend();
+    const caps = backend.getCapabilities!();
+    expect(caps.canSend).toBe(false);
+    expect(caps.canInvoke).toBe(false);
+    expect(caps.canHandle).toBe(false);
+    expect(caps.canTarget).toBe(false);
+  });
+});
+
+describe('enableIpcSignals', () => {
+  it('returns an IpcSignals group', () => {
+    const signals: IpcSignals = enableIpcSignals();
+    expect(signals.onBackendChanged).toBeDefined();
+    expect(signals.onChannelMessage).toBeDefined();
+  });
+
+  it('returns the same instance on repeated calls', () => {
+    const a = enableIpcSignals();
+    const b = enableIpcSignals();
+    expect(a).toBe(b);
+  });
+
+  it('fires onBackendChanged when setIpcBackend is called', () => {
+    const signals = enableIpcSignals();
+    let fired = 0;
+    signals.onBackendChanged.emit = () => {
+      fired++;
+    };
+    setIpcBackend(fakeBackend());
+    expect(fired).toBe(1);
+    setIpcBackend(null);
+    expect(fired).toBe(2);
+  });
+
+  it('fires onChannelMessage when a message is received', () => {
+    const signals = enableIpcSignals();
+    const backend = fakeBackend();
+    setIpcBackend(backend);
+    const channels: string[] = [];
+    signals.onChannelMessage.emit = (ch) => {
+      channels.push(ch);
+    };
+    onIpcMessage('events', () => {});
+    backend.fire('events', []);
+    expect(channels).toEqual(['events']);
+  });
+
+  it('does not emit onChannelMessage at subscribe time, only on delivery', () => {
+    const signals = enableIpcSignals();
+    const backend = fakeBackend();
+    setIpcBackend(backend);
+    const channels: string[] = [];
+    signals.onChannelMessage.emit = (ch) => {
+      channels.push(ch);
+    };
+    onIpcMessage('events', () => {});
+    onIpcMessageEvent('events2', () => {});
+    // Registering listeners must not emit; the signal is a per-delivery notification.
+    expect(channels).toEqual([]);
+    backend.fire('events', []);
+    backend.fire('events2', []);
+    expect(channels).toEqual(['events', 'events2']);
+  });
+});
+
+describe('getIpcBackend', () => {
+  it('falls back to a web backend', () => {
+    expect(getIpcBackend()).not.toBeNull();
+  });
+
+  it('returns the registered backend', () => {
+    const backend = fakeBackend();
+    setIpcBackend(backend);
+    expect(getIpcBackend()).toBe(backend);
+  });
+});
+
+describe('getIpcListenerCount', () => {
+  it('returns 0 for an unknown channel', () => {
+    expect(getIpcListenerCount('never')).toBe(0);
+  });
+
+  it('increments when listeners are added', () => {
+    const backend = fakeBackend();
+    setIpcBackend(backend);
+    onIpcMessage('ch', () => {});
+    onIpcMessage('ch', () => {});
+    expect(getIpcListenerCount('ch')).toBe(2);
+  });
+
+  it('decrements when a listener unsubscribes', () => {
+    const backend = fakeBackend();
+    setIpcBackend(backend);
+    const off = onIpcMessage('ch', () => {});
+    expect(getIpcListenerCount('ch')).toBe(1);
+    off();
+    expect(getIpcListenerCount('ch')).toBe(0);
+  });
+
+  it('accepts an IpcChannel descriptor', () => {
+    const backend = fakeBackend();
+    setIpcBackend(backend);
+    const ch = createIpcChannel('typed');
+    onIpcMessage(ch, () => {});
+    expect(getIpcListenerCount(ch)).toBe(1);
+  });
+});
+
+describe('getIpcSignals', () => {
+  it('returns null before enableIpcSignals is called', async () => {
+    // The IpcSignals group is a module-level singleton, so once any test in this suite calls
+    // enableIpcSignals the value persists. Re-import the module in isolation to assert the
+    // lazy-null contract deterministically: a fresh module has no group until enable is called.
+    vi.resetModules();
+    const fresh = await import('./ipc');
+    expect(fresh.getIpcSignals()).toBeNull();
+    // Delivery still works with the group disabled — the emit is guarded, never required.
+    const backend = fakeBackend();
+    fresh.setIpcBackend(backend);
+    const received: unknown[] = [];
+    fresh.onIpcMessage('disabled', (...args) => received.push(...args));
+    backend.fire('disabled', ['x']);
+    expect(received).toEqual(['x']);
+    expect(fresh.getIpcSignals()).toBeNull();
+    fresh.setIpcBackend(null);
+  });
+
+  it('returns the signals object after enableIpcSignals', () => {
+    const signals = enableIpcSignals();
+    expect(getIpcSignals()).toBe(signals);
+  });
+});
+
+describe('hasIpcBackend', () => {
+  it('returns false before any backend is set', () => {
+    expect(hasIpcBackend()).toBe(false);
+  });
+
+  it('returns true after setting a native backend', () => {
+    setIpcBackend(fakeBackend());
+    expect(hasIpcBackend()).toBe(true);
+  });
+
+  it('returns false after resetting to null', () => {
+    setIpcBackend(fakeBackend());
+    setIpcBackend(null);
+    expect(hasIpcBackend()).toBe(false);
+  });
+});
+
+describe('invokeIpc', () => {
+  it('passes variadic args as an array and resolves the backend result', async () => {
+    const backend = fakeBackend();
+    backend.result = 42;
+    setIpcBackend(backend);
+    expect(await invokeIpc('compute', 1, 2)).toBe(42);
+  });
+
+  it('accepts an IpcChannel descriptor', async () => {
+    const backend = fakeBackend();
+    backend.result = 'ok';
+    setIpcBackend(backend);
+    expect(await invokeIpc(createIpcChannel('compute'), 1)).toBe('ok');
+  });
+});
+
+describe('invokeIpcWithTimeout', () => {
+  it('resolves when the backend responds before timeout', async () => {
+    const backend = fakeBackend();
+    backend.result = 99;
+    setIpcBackend(backend);
+    expect(await invokeIpcWithTimeout('cmd', 1000)).toBe(99);
+  });
+
+  it('rejects with IpcTimeoutError when the backend does not respond in time', async () => {
+    // Replace invoke with one that never resolves.
+    const backend = fakeBackend();
+    backend.invoke = (_channel, _args) => new Promise(() => {});
+    setIpcBackend(backend);
+    await expect(invokeIpcWithTimeout('cmd', 10)).rejects.toBeInstanceOf(IpcTimeoutError);
+  });
+
+  it('IpcTimeoutError carries channel and timeoutMs', async () => {
+    const backend = fakeBackend();
+    backend.invoke = () => new Promise(() => {});
+    setIpcBackend(backend);
+    let err: IpcTimeoutError | undefined;
+    try {
+      await invokeIpcWithTimeout('slow-channel', 5);
+    } catch (e) {
+      err = e as IpcTimeoutError;
+    }
+    expect(err?.channel).toBe('slow-channel');
+    expect(err?.timeoutMs).toBe(5);
+  });
+});
+
+describe('onceIpcMessage', () => {
+  it('auto-unsubscribes after the first message', () => {
+    const backend = fakeBackend();
+    setIpcBackend(backend);
+    const received: unknown[] = [];
+    onceIpcMessage('ping', (...args) => received.push(...args));
+    backend.fire('ping', ['first']);
+    backend.fire('ping', ['second']);
+    expect(received).toEqual(['first']);
+  });
+
+  it('can be manually unsubscribed before the message fires', () => {
+    const backend = fakeBackend();
+    setIpcBackend(backend);
+    const received: unknown[] = [];
+    const off = onceIpcMessage('ping', () => received.push('fired'));
+    off();
+    backend.fire('ping', []);
+    expect(received).toHaveLength(0);
+  });
+});
+
+describe('onIpcInvoke', () => {
+  it('registers a handler via backend.handle', async () => {
+    const backend = fakeBackend();
+    setIpcBackend(backend);
+    onIpcInvoke('compute', (...args) => (args[0] as number) * 2);
+    expect(backend.handlers.has('compute')).toBe(true);
+  });
+
+  it('returns an inert unsubscribe when backend has no handle method', () => {
+    const backend = fakeBackend();
+    // Remove optional handle method.
+    delete (backend as Partial<FakeIpcBackend>).handle;
+    setIpcBackend(backend);
+    const off = onIpcInvoke('compute', () => {});
+    expect(typeof off).toBe('function');
+    expect(() => off()).not.toThrow();
+  });
+
+  it('unregisters the handler when unsubscribe is called', () => {
+    const backend = fakeBackend();
+    setIpcBackend(backend);
+    const off = onIpcInvoke('compute', () => {});
+    off();
+    expect(backend.handlers.has('compute')).toBe(false);
+  });
+});
+
+describe('onIpcMessage', () => {
+  it('spreads incoming args to the listener and unsubscribes', () => {
+    const backend = fakeBackend();
+    setIpcBackend(backend);
+    const received: unknown[] = [];
+    const unsubscribe = onIpcMessage('event', (...args) => received.push(args));
+    backend.fire('event', ['a', 'b']);
+    expect(received).toEqual([['a', 'b']]);
+    unsubscribe();
+    backend.fire('event', ['c']);
+    expect(received).toEqual([['a', 'b']]);
+  });
+
+  it('tracks listener count correctly', () => {
+    const backend = fakeBackend();
+    setIpcBackend(backend);
+    expect(getIpcListenerCount('evt')).toBe(0);
+    const off = onIpcMessage('evt', () => {});
+    expect(getIpcListenerCount('evt')).toBe(1);
+    off();
+    expect(getIpcListenerCount('evt')).toBe(0);
+  });
+});
+
+describe('onIpcMessageEvent', () => {
+  it('delivers an IpcMessageEvent with channel, senderId -1, and args', () => {
+    const backend = fakeBackend();
+    setIpcBackend(backend);
+    const events: Array<{ channel: string; senderId: number; args: readonly unknown[] }> = [];
+    const off = onIpcMessageEvent('ch', (ev) =>
+      events.push({ channel: ev.channel, senderId: ev.senderId, args: ev.args }),
+    );
+    backend.fire('ch', ['hello', 42]);
+    expect(events).toEqual([{ channel: 'ch', senderId: -1, args: ['hello', 42] }]);
+    off();
+  });
+
+  it('reply is a no-op when senderId is -1, even with a sendTo-capable backend', () => {
+    // No backend surfaces sender identity yet, so senderId is permanently -1 and reply must
+    // early-return before touching backend.sendTo. Use a sendTo-capable fake to prove the gate
+    // is on senderId, not method presence: a reply still produces zero outbound sends. This pins
+    // the forward-compatible contract until a backend supplies a real senderId.
+    const backend = fakeBackend();
+    setIpcBackend(backend);
+    let observedSenderId: number | undefined;
+    const off = onIpcMessageEvent('ch', (ev) => {
+      observedSenderId = ev.senderId;
+      ev.reply('pong');
+    });
+    backend.fire('ch', []);
+    expect(observedSenderId).toBe(-1);
+    expect(typeof backend.sendTo).toBe('function');
+    expect(backend.sentTo).toHaveLength(0);
+    off();
+  });
+
+  it('tracks listener count and unsubscribes correctly', () => {
+    const backend = fakeBackend();
+    setIpcBackend(backend);
+    const off = onIpcMessageEvent('ch2', () => {});
+    expect(getIpcListenerCount('ch2')).toBe(1);
+    off();
+    expect(getIpcListenerCount('ch2')).toBe(0);
+  });
+});
+
+describe('removeAllIpcListeners', () => {
+  it('removes all listeners for a specific channel', () => {
+    const backend = fakeBackend();
+    setIpcBackend(backend);
+    const received: string[] = [];
+    onIpcMessage('a', () => received.push('a1'));
+    onIpcMessage('a', () => received.push('a2'));
+    onIpcMessage('b', () => received.push('b1'));
+    removeAllIpcListeners('a');
+    backend.fire('a', []);
+    backend.fire('b', []);
+    // 'a' listeners removed, 'b' still active.
+    expect(received).toEqual(['b1']);
+  });
+
+  it('removes all listeners for all channels when omitted', () => {
+    const backend = fakeBackend();
+    setIpcBackend(backend);
+    const received: string[] = [];
+    onIpcMessage('a', () => received.push('a'));
+    onIpcMessage('b', () => received.push('b'));
+    removeAllIpcListeners();
+    backend.fire('a', []);
+    backend.fire('b', []);
+    expect(received).toHaveLength(0);
+  });
+
+  it('accepts an IpcChannel descriptor', () => {
+    const backend = fakeBackend();
+    setIpcBackend(backend);
+    const ch = createIpcChannel('typed');
+    const received: number[] = [];
+    onIpcMessage(ch, () => received.push(1));
+    removeAllIpcListeners(ch);
+    backend.fire('typed', []);
+    expect(received).toHaveLength(0);
+  });
+});
+
+describe('sendIpcMessage', () => {
+  it('forwards channel and args array to the backend', () => {
+    const backend = fakeBackend();
+    setIpcBackend(backend);
+    sendIpcMessage('log', 'hi', 7);
+    expect(backend.sent).toEqual([{ channel: 'log', args: ['hi', 7] }]);
+  });
+});
+
+describe('sendIpcMessageTo', () => {
+  it('forwards target, channel, and args to backend.sendTo', () => {
+    const backend = fakeBackend();
+    setIpcBackend(backend);
+    sendIpcMessageTo({ windowId: 3 }, 'log', 'hello');
+    expect(backend.sentTo).toEqual([{ target: { windowId: 3 }, channel: 'log', args: ['hello'] }]);
+  });
+
+  it('no-ops when backend has no sendTo method', () => {
+    const backend = fakeBackend();
+    delete (backend as Partial<FakeIpcBackend>).sendTo;
+    setIpcBackend(backend);
+    expect(() => sendIpcMessageTo({ windowId: 1 }, 'log', 'hi')).not.toThrow();
+  });
+});
+
+describe('setIpcBackend', () => {
+  it('clears back to the web fallback when passed null', () => {
+    setIpcBackend(fakeBackend());
+    setIpcBackend(null);
+    expect(getIpcBackend()).not.toBeNull();
+  });
+});