@vanira/sdk-react-native 0.0.2

package/src/__tests__/preset.test.ts

@@ -0,0 +1,239 @@
+/**
+ * Preset event bridge tests (Task 0.4)
+ */
+
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+
+const PRESET_TOOL_CALL = {
+    event: 'client_tool_call',
+    tool_call: {
+        tool_call_id: 'tc_preset_1',
+        name: 'show_preset',
+        arguments: { preset_id: 'product_card' },
+        execution_mode: 'blocking',
+    },
+};
+
+const NON_PRESET_TOOL_CALL = {
+    event: 'client_tool_call',
+    tool_call: {
+        tool_call_id: 'tc_custom_1',
+        name: 'custom_action',
+        arguments: { foo: 'bar' },
+        execution_mode: 'fire_and_forget',
+    },
+};
+
+function dispatchPreset(client: import('../core/WebRTCClient').WebRTCClient, msg: unknown) {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    (client as any).handleControlEvent(msg);
+}
+
+/** Minimal browser globals for DOM preset tests (vitest node env) */
+function stubBrowserEventGlobals() {
+    class MockCustomEvent {
+        readonly type: string;
+        readonly detail: unknown;
+        constructor(type: string, init?: { detail?: unknown }) {
+            this.type = type;
+            this.detail = init?.detail;
+        }
+    }
+
+    const listeners = new Map<string, Set<(event: MockCustomEvent) => void>>();
+
+    vi.stubGlobal('CustomEvent', MockCustomEvent);
+    vi.stubGlobal('addEventListener', (type: string, listener: (event: MockCustomEvent) => void) => {
+        if (!listeners.has(type)) listeners.set(type, new Set());
+        listeners.get(type)!.add(listener);
+    });
+    vi.stubGlobal('removeEventListener', (type: string, listener: (event: MockCustomEvent) => void) => {
+        listeners.get(type)?.delete(listener);
+    });
+    vi.stubGlobal('dispatchEvent', (event: MockCustomEvent) => {
+        listeners.get(event.type)?.forEach((listener) => listener(event));
+        return true;
+    });
+
+    return { listeners };
+}
+
+describe('WebRTCClient preset dispatch', () => {
+    afterEach(() => {
+        vi.unstubAllGlobals();
+        vi.restoreAllMocks();
+    });
+
+    it('ordering: ack → onPreset → onClientToolCall', async () => {
+        const order: string[] = [];
+        const { WebRTCClient } = await import('../core/WebRTCClient');
+
+        const client = new WebRTCClient({
+            agentId: 'agent_1',
+            serverUrl: 'https://worker.example.com',
+            onPreset: () => order.push('onPreset'),
+            onClientToolCall: () => order.push('onClientToolCall'),
+        });
+
+        vi.spyOn(client, 'sendToolAck').mockImplementation(() => {
+            order.push('ack');
+        });
+
+        dispatchPreset(client, PRESET_TOOL_CALL);
+
+        expect(order).toEqual(['ack', 'onPreset', 'onClientToolCall']);
+    });
+
+    it('dispatches vanira:preset DOM event on browser when CustomEvent is available', async () => {
+        stubBrowserEventGlobals();
+        const domListener = vi.fn();
+        globalThis.addEventListener('vanira:preset', domListener);
+
+        const { WebRTCClient } = await import('../core/WebRTCClient');
+
+        const client = new WebRTCClient({
+            agentId: 'agent_1',
+            serverUrl: 'https://worker.example.com',
+        });
+
+        dispatchPreset(client, PRESET_TOOL_CALL);
+
+        expect(domListener).toHaveBeenCalledTimes(1);
+        const event = domListener.mock.calls[0][0] as CustomEvent;
+        expect(event.detail.toolCall).toEqual({
+            tool_call_id: 'tc_preset_1',
+            name: 'show_preset',
+            arguments: { preset_id: 'product_card' },
+            execution_mode: 'blocking',
+            client_fields: {},
+        });
+        expect(event.detail.client).toBe(client);
+    });
+
+    it('does not dispatch DOM event when canDispatchBrowserEvent is false', async () => {
+        stubBrowserEventGlobals();
+        const platform = await import('../runtime/platform');
+        vi.spyOn(platform, 'canDispatchBrowserEvent').mockReturnValue(false);
+
+        const domListener = vi.fn();
+        globalThis.addEventListener('vanira:preset', domListener);
+
+        const { WebRTCClient } = await import('../core/WebRTCClient');
+        const onPreset = vi.fn();
+
+        const client = new WebRTCClient({
+            agentId: 'agent_1',
+            serverUrl: 'https://worker.example.com',
+            onPreset,
+        });
+
+        dispatchPreset(client, PRESET_TOOL_CALL);
+
+        expect(onPreset).toHaveBeenCalledTimes(1);
+        expect(domListener).not.toHaveBeenCalled();
+    });
+
+    it('does not call onPreset or DOM for non-preset tools', async () => {
+        stubBrowserEventGlobals();
+        const platform = await import('../runtime/platform');
+        const canDispatchSpy = vi.spyOn(platform, 'canDispatchBrowserEvent');
+
+        const domListener = vi.fn();
+        globalThis.addEventListener('vanira:preset', domListener);
+
+        const { WebRTCClient } = await import('../core/WebRTCClient');
+        const onPreset = vi.fn();
+        const onClientToolCall = vi.fn();
+
+        const client = new WebRTCClient({
+            agentId: 'agent_1',
+            serverUrl: 'https://worker.example.com',
+            onPreset,
+            onClientToolCall,
+        });
+
+        dispatchPreset(client, NON_PRESET_TOOL_CALL);
+
+        expect(onPreset).not.toHaveBeenCalled();
+        expect(onClientToolCall).toHaveBeenCalledTimes(1);
+        expect(domListener).not.toHaveBeenCalled();
+        expect(canDispatchSpy).not.toHaveBeenCalled();
+    });
+
+    it('onPreset receives raw toolCall and client reference', async () => {
+        const { WebRTCClient } = await import('../core/WebRTCClient');
+        const onPreset = vi.fn();
+
+        const client = new WebRTCClient({
+            agentId: 'agent_1',
+            serverUrl: 'https://worker.example.com',
+            onPreset,
+        });
+
+        dispatchPreset(client, PRESET_TOOL_CALL);
+
+        expect(onPreset).toHaveBeenCalledWith({
+            toolCall: {
+                tool_call_id: 'tc_preset_1',
+                name: 'show_preset',
+                arguments: { preset_id: 'product_card' },
+                execution_mode: 'blocking',
+                client_fields: {},
+            },
+            client,
+        });
+    });
+});
+
+describe('VaniraAI preset events', () => {
+    beforeEach(() => {
+        Object.defineProperty(globalThis, 'navigator', {
+            value: { product: 'Gecko' },
+            configurable: true,
+        });
+    });
+
+    afterEach(() => {
+        vi.restoreAllMocks();
+    });
+
+    it('emits preset before tool_call for preset tools', async () => {
+        const { VaniraAI } = await import('../core/VaniraAI');
+        const { WebRTCClient } = await import('../core/WebRTCClient');
+
+        vi.spyOn(WebRTCClient.prototype, 'connect').mockResolvedValue(undefined);
+
+        const order: string[] = [];
+        const ai = new VaniraAI({ agentId: 'agent_1', apiKey: 'sk_test' });
+        ai.on('preset', () => order.push('preset'));
+        ai.on('tool_call', () => order.push('tool_call'));
+
+        await ai.start();
+
+        const client = (ai as unknown as { client: import('../core/WebRTCClient').WebRTCClient }).client;
+        dispatchPreset(client, PRESET_TOOL_CALL);
+
+        expect(order).toEqual(['preset', 'tool_call']);
+    });
+
+    it('does not emit preset for non-preset tools', async () => {
+        const { VaniraAI } = await import('../core/VaniraAI');
+        const { WebRTCClient } = await import('../core/WebRTCClient');
+
+        vi.spyOn(WebRTCClient.prototype, 'connect').mockResolvedValue(undefined);
+
+        const presetSpy = vi.fn();
+        const toolSpy = vi.fn();
+        const ai = new VaniraAI({ agentId: 'agent_1', apiKey: 'sk_test' });
+        ai.on('preset', presetSpy);
+        ai.on('tool_call', toolSpy);
+
+        await ai.start();
+
+        const client = (ai as unknown as { client: import('../core/WebRTCClient').WebRTCClient }).client;
+        dispatchPreset(client, NON_PRESET_TOOL_CALL);
+
+        expect(presetSpy).not.toHaveBeenCalled();
+        expect(toolSpy).toHaveBeenCalledTimes(1);
+    });
+});

package/src/__tests__/resolveRuntimeConfig.test.ts

@@ -0,0 +1,90 @@
+/**
+ * resolveRuntimeConfig unit tests (Task 0.2)
+ */
+
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+
+describe('resolveRuntimeConfig', () => {
+    beforeEach(() => {
+        Object.defineProperty(globalThis, 'navigator', {
+            value: { product: 'Gecko' },
+            configurable: true,
+        });
+    });
+
+    afterEach(() => {
+        vi.restoreAllMocks();
+    });
+
+    it('returns browserDefaultBundle when no runtime on web', async () => {
+        const { resolveRuntimeConfig } = await import('../runtime/resolveRuntimeConfig');
+        const { browserDefaultBundle } = await import('../runtime/runtimeBundles');
+
+        const resolved = resolveRuntimeConfig({ agentId: 'a1', serverUrl: 'https://w.example.com' });
+
+        expect(resolved.runtimeName).toBe('browser');
+        expect(resolved.callIdPrefix).toBe('web_');
+        expect(resolved.audio).toBe(browserDefaultBundle.audio);
+        expect(resolved.storage).toBe(browserDefaultBundle.storage);
+    });
+
+    it('returns reactNativeDefaultBundle when config.runtime is RN', async () => {
+        const { resolveRuntimeConfig } = await import('../runtime/resolveRuntimeConfig');
+        const { reactNativeDefaultBundle } = await import('../runtime/runtimeBundles');
+
+        const resolved = resolveRuntimeConfig({
+            agentId: 'a1',
+            serverUrl: 'https://w.example.com',
+            runtime: reactNativeDefaultBundle,
+        });
+
+        expect(resolved.runtimeName).toBe('react-native');
+        expect(resolved.callIdPrefix).toBe('rn_');
+        expect(resolved.storage).toBe(reactNativeDefaultBundle.storage);
+    });
+
+    it('throws on React Native without config.runtime', async () => {
+        Object.defineProperty(globalThis, 'navigator', {
+            value: { product: 'ReactNative' },
+            configurable: true,
+        });
+
+        const { resolveRuntimeConfig } = await import('../runtime/resolveRuntimeConfig');
+
+        expect(() => {
+            resolveRuntimeConfig({ agentId: 'a1', apiKey: 'sk_test' });
+        }).toThrow('[VaniraSDK] runtime is required');
+    });
+
+    it('config.storageAdapter overrides bundle storage', async () => {
+        const { resolveRuntimeConfig } = await import('../runtime/resolveRuntimeConfig');
+        const { browserDefaultBundle } = await import('../runtime/runtimeBundles');
+        const { MemoryStorageAdapter } = await import('../adapters/storage/MemoryStorageAdapter');
+
+        const customStorage = new MemoryStorageAdapter();
+        const resolved = resolveRuntimeConfig({
+            agentId: 'a1',
+            serverUrl: 'https://w.example.com',
+            runtime: browserDefaultBundle,
+            storageAdapter: customStorage,
+        });
+
+        expect(resolved.storage).toBe(customStorage);
+        expect(resolved.storage).not.toBe(browserDefaultBundle.storage);
+    });
+
+    it('config.peerAdapter overrides bundle peer adapter', async () => {
+        const { resolveRuntimeConfig } = await import('../runtime/resolveRuntimeConfig');
+        const { browserDefaultBundle } = await import('../runtime/runtimeBundles');
+
+        const customPeer = { create: vi.fn() };
+        const resolved = resolveRuntimeConfig({
+            agentId: 'a1',
+            serverUrl: 'https://w.example.com',
+            runtime: browserDefaultBundle,
+            peerAdapter: customPeer,
+        });
+
+        expect(resolved.peer).toBe(customPeer);
+    });
+});

package/src/__tests__/storage.test.ts

@@ -0,0 +1,211 @@
+/**
+ * Storage adapter unit tests (Task 0.3)
+ */
+
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+
+// ─── BrowserDualStorageAdapter ────────────────────────────────────────────────
+
+describe('BrowserDualStorageAdapter', () => {
+    let sessionStore: Record<string, string>;
+    let localStore: Record<string, string>;
+
+    beforeEach(() => {
+        sessionStore = {};
+        localStore = {};
+
+        vi.stubGlobal('sessionStorage', {
+            getItem: vi.fn((key: string) => (key in sessionStore ? sessionStore[key] : null)),
+            setItem: vi.fn((key: string, value: string) => { sessionStore[key] = value; }),
+            removeItem: vi.fn((key: string) => { delete sessionStore[key]; }),
+        });
+
+        vi.stubGlobal('localStorage', {
+            getItem: vi.fn((key: string) => (key in localStore ? localStore[key] : null)),
+            setItem: vi.fn((key: string, value: string) => { localStore[key] = value; }),
+            removeItem: vi.fn((key: string) => { delete localStore[key]; }),
+        });
+    });
+
+    afterEach(() => {
+        vi.unstubAllGlobals();
+    });
+
+    it('setItem writes to both sessionStorage and localStorage', async () => {
+        const { BrowserDualStorageAdapter } = await import('../adapters/storage/BrowserDualStorageAdapter');
+        const adapter = new BrowserDualStorageAdapter();
+
+        adapter.setItem('vanira_prospect_id', 'prospect_abc');
+
+        expect(sessionStorage.setItem).toHaveBeenCalledWith('vanira_prospect_id', 'prospect_abc');
+        expect(localStorage.setItem).toHaveBeenCalledWith('vanira_prospect_id', 'prospect_abc');
+        expect(sessionStore['vanira_prospect_id']).toBe('prospect_abc');
+        expect(localStore['vanira_prospect_id']).toBe('prospect_abc');
+    });
+
+    it('getItem prefers sessionStorage over localStorage', async () => {
+        const { BrowserDualStorageAdapter } = await import('../adapters/storage/BrowserDualStorageAdapter');
+        const adapter = new BrowserDualStorageAdapter();
+
+        sessionStore['vanira_latest_call_id'] = 'call_from_session';
+        localStore['vanira_latest_call_id'] = 'call_from_local';
+
+        expect(adapter.getItem('vanira_latest_call_id')).toBe('call_from_session');
+    });
+
+    it('getItem falls back to localStorage when sessionStorage has no value', async () => {
+        const { BrowserDualStorageAdapter } = await import('../adapters/storage/BrowserDualStorageAdapter');
+        const adapter = new BrowserDualStorageAdapter();
+
+        localStore['vanira_prospect_id'] = 'prospect_from_local';
+
+        expect(adapter.getItem('vanira_prospect_id')).toBe('prospect_from_local');
+        expect(sessionStorage.getItem).toHaveBeenCalledWith('vanira_prospect_id');
+        expect(localStorage.getItem).toHaveBeenCalledWith('vanira_prospect_id');
+    });
+
+    it('removeItem removes from both sessionStorage and localStorage', async () => {
+        const { BrowserDualStorageAdapter } = await import('../adapters/storage/BrowserDualStorageAdapter');
+        const adapter = new BrowserDualStorageAdapter();
+
+        sessionStore['vanira_prospect_id'] = 'p1';
+        localStore['vanira_prospect_id'] = 'p1';
+
+        adapter.removeItem('vanira_prospect_id');
+
+        expect(sessionStorage.removeItem).toHaveBeenCalledWith('vanira_prospect_id');
+        expect(localStorage.removeItem).toHaveBeenCalledWith('vanira_prospect_id');
+        expect(sessionStore['vanira_prospect_id']).toBeUndefined();
+        expect(localStore['vanira_prospect_id']).toBeUndefined();
+    });
+
+    it('returns null when key is absent from both stores', async () => {
+        const { BrowserDualStorageAdapter } = await import('../adapters/storage/BrowserDualStorageAdapter');
+        const adapter = new BrowserDualStorageAdapter();
+
+        expect(adapter.getItem('missing_key')).toBeNull();
+    });
+});
+
+// ─── MemoryStorageAdapter ─────────────────────────────────────────────────────
+
+describe('MemoryStorageAdapter', () => {
+    it('round-trips getItem / setItem / removeItem', async () => {
+        const { MemoryStorageAdapter } = await import('../adapters/storage/MemoryStorageAdapter');
+        const adapter = new MemoryStorageAdapter();
+
+        expect(adapter.getItem('vanira_prospect_id')).toBeNull();
+
+        adapter.setItem('vanira_prospect_id', 'prospect_123');
+        expect(adapter.getItem('vanira_prospect_id')).toBe('prospect_123');
+
+        adapter.removeItem('vanira_prospect_id');
+        expect(adapter.getItem('vanira_prospect_id')).toBeNull();
+    });
+
+    it('getItem does not throw on missing keys', async () => {
+        const { MemoryStorageAdapter } = await import('../adapters/storage/MemoryStorageAdapter');
+        const adapter = new MemoryStorageAdapter();
+
+        expect(() => adapter.getItem('vanira_latest_call_id')).not.toThrow();
+        expect(adapter.getItem('vanira_latest_call_id')).toBeNull();
+    });
+
+    it('logs a one-time production warning on setItem', async () => {
+        const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+        const originalEnv = process.env.NODE_ENV;
+        process.env.NODE_ENV = 'production';
+
+        try {
+            const { MemoryStorageAdapter } = await import('../adapters/storage/MemoryStorageAdapter');
+            const adapter = new MemoryStorageAdapter();
+
+            adapter.setItem('k1', 'v1');
+            adapter.setItem('k2', 'v2');
+
+            expect(warnSpy).toHaveBeenCalledTimes(1);
+            expect(warnSpy.mock.calls[0][0]).toContain('MemoryStorageAdapter');
+        } finally {
+            process.env.NODE_ENV = originalEnv;
+            warnSpy.mockRestore();
+        }
+    });
+});
+
+// ─── createSyncStorageAdapter ─────────────────────────────────────────────────
+
+describe('createSyncStorageAdapter', () => {
+    it('delegates getItem, setItem, and removeItem to the backend', async () => {
+        const { createSyncStorageAdapter } = await import('../adapters/storage/createSyncStorageAdapter');
+
+        const store = new Map<string, string>();
+        const getString = vi.fn((key: string) => store.get(key));
+        const setString = vi.fn((key: string, value: string) => { store.set(key, value); });
+        const del = vi.fn((key: string) => { store.delete(key); });
+
+        const adapter = createSyncStorageAdapter({ getString, setString, delete: del });
+
+        expect(adapter.getItem('missing')).toBeNull();
+        expect(getString).toHaveBeenCalledWith('missing');
+
+        adapter.setItem('vanira_prospect_id', 'p_sync');
+        expect(setString).toHaveBeenCalledWith('vanira_prospect_id', 'p_sync');
+        expect(adapter.getItem('vanira_prospect_id')).toBe('p_sync');
+
+        adapter.removeItem('vanira_prospect_id');
+        expect(del).toHaveBeenCalledWith('vanira_prospect_id');
+        expect(adapter.getItem('vanira_prospect_id')).toBeNull();
+    });
+
+    it('maps undefined getString to null', async () => {
+        const { createSyncStorageAdapter } = await import('../adapters/storage/createSyncStorageAdapter');
+
+        const adapter = createSyncStorageAdapter({
+            getString: () => undefined,
+            setString: vi.fn(),
+        });
+
+        expect(adapter.getItem('any')).toBeNull();
+    });
+
+    it('removeItem is a no-op when backend has no delete', async () => {
+        const { createSyncStorageAdapter } = await import('../adapters/storage/createSyncStorageAdapter');
+
+        const store = new Map<string, string>([['k', 'v']]);
+        const adapter = createSyncStorageAdapter({
+            getString: (key) => store.get(key),
+            setString: (key, value) => { store.set(key, value); },
+        });
+
+        adapter.removeItem('k');
+        expect(adapter.getItem('k')).toBe('v');
+    });
+});
+
+// ─── Runtime bundle wiring ────────────────────────────────────────────────────
+
+describe('runtime bundle storage defaults', () => {
+    it('browserDefaultBundle uses BrowserDualStorageAdapter', async () => {
+        const { browserDefaultBundle } = await import('../runtime/runtimeBundles');
+        const { BrowserDualStorageAdapter } = await import('../adapters/storage/BrowserDualStorageAdapter');
+
+        expect(browserDefaultBundle.storage).toBeInstanceOf(BrowserDualStorageAdapter);
+    });
+
+    it('reactNativeDefaultBundle uses MemoryStorageAdapter', async () => {
+        const { reactNativeDefaultBundle } = await import('../runtime/runtimeBundles');
+        const { MemoryStorageAdapter } = await import('../adapters/storage/MemoryStorageAdapter');
+
+        expect(reactNativeDefaultBundle.storage).toBeInstanceOf(MemoryStorageAdapter);
+    });
+
+    it('browserRuntime and reactNativeRuntime re-export bundle storage', async () => {
+        const { browserRuntime } = await import('../runtime/browserRuntime');
+        const { reactNativeRuntime } = await import('../runtime/reactNativeRuntime');
+        const { BrowserDualStorageAdapter } = await import('../adapters/storage/BrowserDualStorageAdapter');
+        const { MemoryStorageAdapter } = await import('../adapters/storage/MemoryStorageAdapter');
+
+        expect(browserRuntime.storage).toBeInstanceOf(BrowserDualStorageAdapter);
+        expect(reactNativeRuntime.storage).toBeInstanceOf(MemoryStorageAdapter);
+    });
+});

package/src/__tests__/webrtcSignaling.test.ts

@@ -0,0 +1,42 @@
+import { describe, expect, it } from 'vitest';
+import { getIceTrickleUrl, isWorkerSdpUrl, mapIceServersFromCreate } from '../core/webrtcSignaling';
+
+describe('webrtcSignaling', () => {
+    it('derives /webrtc/ice URL from worker_url', () => {
+        const worker =
+            'https://in-godspeed.travelr.club/webrtc?agent_id=a&call_id=c&token=t';
+        expect(getIceTrickleUrl(worker)).toBe(
+            'https://in-godspeed.travelr.club/webrtc/ice?agent_id=a&call_id=c&token=t',
+        );
+        expect(isWorkerSdpUrl(worker)).toBe(true);
+        expect(isWorkerSdpUrl(getIceTrickleUrl(worker))).toBe(false);
+    });
+
+    it('falls back when worker_url is not parseable', () => {
+        expect(getIceTrickleUrl('bad-url', 'agent-1', 'call-1')).toBe(
+            'bad-url/webrtc/ice?agent_id=agent-1&call_id=call-1',
+        );
+    });
+
+    it('maps ice_servers from create response', () => {
+        const servers = mapIceServersFromCreate([
+            { urls: ['stun:stun.example.com:3478'], username: null, credential: null },
+            {
+                urls: ['turn:turn.example.com:3478'],
+                username: 'user',
+                credential: 'pass',
+            },
+        ]);
+        expect(servers).toHaveLength(2);
+        expect(servers[1]).toEqual({
+            urls: ['turn:turn.example.com:3478'],
+            username: 'user',
+            credential: 'pass',
+        });
+    });
+
+    it('throws when ice_servers missing', () => {
+        expect(() => mapIceServersFromCreate(undefined)).toThrow(/missing ice_servers/);
+        expect(() => mapIceServersFromCreate([])).toThrow(/missing ice_servers/);
+    });
+});

package/src/adapters/PeerConnectionAdapter.ts

@@ -0,0 +1,101 @@
+/**
+ * PeerConnectionAdapter + DataChannelAdapter
+ *
+ * These interfaces abstract the two remaining WebRTC browser globals that the
+ * core session directly instantiated:
+ *
+ *   new RTCPeerConnection(config)   →  PeerConnectionAdapter.create(config)
+ *   RTCDataChannel event binding    →  DataChannelAdapter.bind(channel, handlers)
+ *
+ * The core (WebRTCClient) no longer calls these constructors directly.
+ * Each platform provides its own implementation.
+ *
+ * Platform notes:
+ *   Browser        — wraps native RTCPeerConnection and RTCDataChannel globals
+ *   React Native   — wraps react-native-webrtc polyfilled RTCPeerConnection (same API)
+ *   Flutter        — Dart flutter_webrtc package (createPeerConnection(), RTCDataChannel)
+ */
+
+// ─── PeerConnectionAdapter ────────────────────────────────────────────────────
+
+export interface PeerConnectionIceServer {
+    urls: string | string[];
+    username?: string;
+    credential?: string;
+}
+
+export interface PeerConnectionConfig {
+    iceServers: PeerConnectionIceServer[];
+    iceTransportPolicy?: 'all' | 'relay';
+}
+
+/**
+ * Abstracts RTCPeerConnection construction.
+ * Core session code calls adapter.create() instead of `new RTCPeerConnection()`.
+ *
+ * This is the minimal factory interface — once created, the returned
+ * RTCPeerConnection is used directly (its method surface is already standardised
+ * by W3C and polyfilled identically by react-native-webrtc).
+ */
+export interface PeerConnectionAdapter {
+    /**
+     * Create and return a new peer connection.
+     * The returned object conforms to the standard RTCPeerConnection interface —
+     * callers may use it directly for addTrack, createDataChannel, createOffer, etc.
+     */
+    create(config: PeerConnectionConfig): RTCPeerConnection;
+}
+
+// ─── DataChannelAdapter ───────────────────────────────────────────────────────
+
+/**
+ * Normalised message payload delivered to onMessage.
+ * The adapter handles the browser's string / ArrayBuffer / Blob variants
+ * and always delivers decoded UTF-8 text.
+ */
+export interface DataChannelMessage {
+    /** Decoded text content — always a string regardless of wire format */
+    text: string;
+}
+
+export interface DataChannelHandlers {
+    onOpen(): void;
+    /** Always receives decoded text; binary frames are decoded by the adapter */
+    onMessage(msg: DataChannelMessage): void;
+    onError(error: unknown): void;
+}
+
+/**
+ * Returned by DataChannelAdapter.bind().
+ * Core code uses this controller to send messages and check state.
+ */
+export interface DataChannelController {
+    /** Send a JSON-serialised text message */
+    send(text: string): void;
+    /** Whether the channel is in the 'open' state */
+    isOpen(): boolean;
+    /** Close the data channel */
+    close(): void;
+}
+
+/**
+ * Abstracts DataChannel event binding and message normalisation.
+ *
+ * Browser has three message wire formats: string, ArrayBuffer, and Blob.
+ * React Native (react-native-webrtc) delivers messages as strings only.
+ * The adapter normalises all formats to decoded UTF-8 text before calling
+ * onMessage, so the core never needs to handle binary framing.
+ *
+ * Binary frame handling policy (preserving existing behaviour):
+ *   - Frames that decode to JSON with event === 'client_tool_call' are forwarded.
+ *   - All other binary frames are logged but NOT forwarded to prevent false
+ *     clearAudio events from being triggered by audio packet payloads.
+ */
+export interface DataChannelAdapter {
+    /**
+     * Bind event handlers to a DataChannel and return a controller.
+     * @param channel  The RTCDataChannel returned by pc.createDataChannel()
+     * @param handlers Event handlers — onMessage always receives decoded text
+     */
+    bind(channel: RTCDataChannel, handlers: DataChannelHandlers): DataChannelController;
+}