@onekeyfe/hd-transport-web-device 1.2.0-alpha.17 → 1.2.0-alpha.170

package/__tests__/webusb-protocol-cache.test.ts

@@ -0,0 +1,261 @@
+import transport from '@onekeyfe/hd-transport';
+import { HardwareErrorCode } from '@onekeyfe/hd-shared';
+
+import WebUsbTransport from '../src/webusb';
+
+const schema = {
+  nested: {
+    Ping: { fields: { message: { type: 'string', id: 1 } } },
+    Success: { fields: { message: { type: 'string', id: 1 } } },
+    MessageType: {
+      values: {
+        MessageType_Ping: 60206,
+        MessageType_Success: 60207,
+      },
+    },
+  },
+};
+
+function buildAcquirableTransport(path = 'pro-webusb') {
+  const webusb = new WebUsbTransport() as any;
+  webusb.Log = { debug: jest.fn() };
+  webusb.rotateProtocolV2UsbGeneration = jest.fn().mockResolvedValue(undefined);
+  webusb.closeOpenDevice = jest.fn().mockResolvedValue(undefined);
+  webusb.connect = jest.fn().mockResolvedValue(undefined);
+  // Simulate a device that stayed connected since the probe: same USBDevice
+  // object present in the device list and recorded as the probed object.
+  const deviceObject = { serialNumber: path } as unknown as USBDevice;
+  webusb.deviceList = [{ path, device: deviceObject, commType: 'webusb' }];
+  webusb.probedDeviceObjects.set(path, deviceObject);
+  return webusb;
+}
+
+describe('WebUsbTransport protocol probe cache', () => {
+  test('acquire skips the wire probe when the protocol is already cached', async () => {
+    const webusb = buildAcquirableTransport();
+    const path = 'pro-webusb';
+    webusb.deviceProtocol.set(path, 'V1');
+    webusb.detectProtocol = jest.fn();
+
+    await expect(webusb.acquire({ path, expectedProtocol: 'V1' })).resolves.toBe(path);
+
+    expect(webusb.detectProtocol).not.toHaveBeenCalled();
+    expect(webusb.deviceProtocol.get(path)).toBe('V1');
+    expect(webusb.acquiredPaths.has(path)).toBe(true);
+  });
+
+  test('acquire re-probes when the caller expects a different protocol than cached', async () => {
+    const webusb = buildAcquirableTransport();
+    const path = 'pro-webusb';
+    webusb.deviceProtocol.set(path, 'V1');
+    webusb.detectProtocol = jest.fn().mockImplementation((p: string) => {
+      webusb.deviceProtocol.set(p, 'V2');
+      return Promise.resolve('V2');
+    });
+
+    await expect(webusb.acquire({ path, expectedProtocol: 'V2' })).resolves.toBe(path);
+
+    expect(webusb.detectProtocol).toHaveBeenCalledWith(path, 'V2', undefined);
+    expect(webusb.deviceProtocol.get(path)).toBe('V2');
+  });
+
+  test('acquire probes when nothing is cached for the path', async () => {
+    const webusb = buildAcquirableTransport();
+    const path = 'pro-webusb';
+    webusb.detectProtocol = jest.fn().mockResolvedValue('V1');
+
+    await expect(webusb.acquire({ path, expectedProtocol: 'V1' })).resolves.toBe(path);
+
+    expect(webusb.detectProtocol).toHaveBeenCalledWith(path, 'V1', undefined);
+  });
+
+  test('acquire trusts the expected protocol during an explicit no-probe recovery', async () => {
+    const webusb = buildAcquirableTransport();
+    const path = 'pro-webusb';
+    webusb.deviceProtocol.set(path, 'V1');
+    webusb.markProtocolStale(path);
+    webusb.detectProtocol = jest.fn();
+
+    await expect(
+      webusb.acquire({ path, expectedProtocol: 'V2', skipProtocolProbe: true })
+    ).resolves.toBe(path);
+
+    expect(webusb.detectProtocol).not.toHaveBeenCalled();
+    expect(webusb.deviceProtocol.get(path)).toBe('V2');
+    expect(webusb.staleProtocolPaths.has(path)).toBe(false);
+    expect(webusb.acquiredPaths.has(path)).toBe(true);
+  });
+
+  test('forced protocol detection bypasses a valid cache and probes on the wire', async () => {
+    const webusb = buildAcquirableTransport();
+    const path = 'pro-webusb';
+    // Valid cache AND unchanged USBDevice object — the strongest cache hit.
+    webusb.deviceProtocol.set(path, 'V1');
+    webusb.detectProtocol = jest.fn().mockImplementation((p: string) => {
+      webusb.deviceProtocol.set(p, 'V1');
+      return Promise.resolve('V1');
+    });
+
+    await expect(webusb.acquire({ path, forceProtocolDetection: true })).resolves.toBe(path);
+
+    // Explicit recovery must always reach the wire probe.
+    expect(webusb.detectProtocol).toHaveBeenCalledTimes(1);
+  });
+
+  test('acquire re-probes when the USBDevice object identity changed since the probe', async () => {
+    const webusb = buildAcquirableTransport();
+    const path = 'pro-webusb';
+    webusb.deviceProtocol.set(path, 'V1');
+    // Simulate a replug the transport never saw a disconnect event for: the OS
+    // re-enumerated the device, so the list now holds a NEW USBDevice object.
+    webusb.deviceList = [
+      { path, device: { serialNumber: path } as unknown as USBDevice, commType: 'webusb' },
+    ];
+    webusb.detectProtocol = jest.fn().mockImplementation((p: string) => {
+      webusb.deviceProtocol.set(p, 'V1');
+      return Promise.resolve('V1');
+    });
+
+    await expect(webusb.acquire({ path, expectedProtocol: 'V1' })).resolves.toBe(path);
+
+    expect(webusb.detectProtocol).toHaveBeenCalledTimes(1);
+  });
+
+  test('acquire re-probes a stale-marked path even when a protocol is cached', async () => {
+    const webusb = buildAcquirableTransport();
+    const path = 'pro-webusb';
+    webusb.deviceProtocol.set(path, 'V1');
+    webusb.markProtocolStale(path);
+    webusb.detectProtocol = jest.fn().mockImplementation((p: string) => {
+      webusb.deviceProtocol.set(p, 'V1');
+      return Promise.resolve('V1');
+    });
+
+    await expect(webusb.acquire({ path, expectedProtocol: 'V1' })).resolves.toBe(path);
+
+    expect(webusb.detectProtocol).toHaveBeenCalledTimes(1);
+    expect(webusb.staleProtocolPaths.has(path)).toBe(false);
+  });
+
+  test('release keeps the cached V1 protocol so the next acquire can reuse it', async () => {
+    const webusb = new WebUsbTransport() as any;
+    const path = 'pro-webusb';
+    webusb.deviceProtocol.set(path, 'V1');
+    webusb.deviceProtocolHints.set(path, 'V2');
+    webusb.deviceEndpoints.set(path, { interfaceNumber: 0, endpointIn: 1, endpointOut: 1 });
+    webusb.acquiredPaths.add(path);
+    webusb.closeOpenDevice = jest.fn().mockResolvedValue(undefined);
+
+    await webusb.release(path);
+
+    expect(webusb.deviceProtocol.get(path)).toBe('V1');
+    expect(webusb.deviceProtocolHints.get(path)).toBe('V2');
+    expect(webusb.deviceEndpoints.has(path)).toBe(false);
+    expect(webusb.acquiredPaths.has(path)).toBe(false);
+  });
+
+  test('release still drops a cached V2 protocol through link invalidation', async () => {
+    const webusb = new WebUsbTransport() as any;
+    const path = 'pro2-webusb';
+    webusb.Log = { debug: jest.fn() };
+    webusb.messages = transport.parseConfigure(schema);
+    webusb.messagesV2 = transport.parseConfigure(schema);
+    webusb.writeProtocolV2UsbPacket = jest.fn().mockResolvedValue(undefined);
+    let markReadStarted: () => void = () => undefined;
+    const readStarted = new Promise<void>(resolve => {
+      markReadStarted = resolve;
+    });
+    webusb.readProtocolV2UsbPacket = jest.fn().mockImplementation(() => {
+      markReadStarted();
+      return new Promise<void>(() => {});
+    });
+    webusb.closeOpenDevice = jest.fn().mockResolvedValue(undefined);
+    webusb.deviceProtocol.set(path, 'V2');
+    await webusb.rotateProtocolV2UsbGeneration(path, 'test connection');
+
+    const call = webusb.callProtocolV2(path, 'Ping', { message: 'release' });
+    await readStarted;
+    await webusb.release(path);
+
+    await expect(call).rejects.toThrow('WebUSB transport released');
+    expect(webusb.deviceProtocol.has(path)).toBe(false);
+  });
+
+  test('call and post fail fast for a path that is not acquired', async () => {
+    const webusb = new WebUsbTransport() as any;
+    const path = 'pro-webusb';
+    webusb.Log = { debug: jest.fn() };
+    webusb.messages = transport.parseConfigure(schema);
+    webusb.messagesV2 = transport.parseConfigure(schema);
+    // A surviving protocol cache entry must NOT act as a session token.
+    webusb.deviceProtocol.set(path, 'V1');
+
+    await expect(webusb.call(path, 'Ping', {})).rejects.toMatchObject({
+      errorCode: HardwareErrorCode.RuntimeError,
+      message: expect.stringContaining('not acquired'),
+    });
+    await expect(webusb.post(path, 'Ping', {})).rejects.toMatchObject({
+      errorCode: HardwareErrorCode.RuntimeError,
+      message: expect.stringContaining('not acquired'),
+    });
+  });
+
+  test('a transfer-level reconnect marks the protocol stale for the next acquire', async () => {
+    const webusb = new WebUsbTransport() as any;
+    const path = 'pro-webusb';
+    webusb.Log = { debug: jest.fn() };
+    webusb.deviceProtocol.set(path, 'V1');
+    webusb.findDevice = jest.fn().mockResolvedValue({ opened: false });
+    webusb.getConnectedDevices = jest.fn().mockResolvedValue([]);
+    webusb.connect = jest.fn().mockResolvedValue(undefined);
+
+    await webusb.reconnectForPacketIoRetry(path, 'in', 0, new Error('transferIn failed'));
+
+    // The in-flight call keeps the cached protocol; only the next acquire re-probes.
+    expect(webusb.deviceProtocol.get(path)).toBe('V1');
+    expect(webusb.staleProtocolPaths.has(path)).toBe(true);
+  });
+
+  test('USB disconnect marks the serial stale and the listener attaches only once', () => {
+    const addEventListener = jest.fn();
+    const usb = { addEventListener } as unknown as USB;
+    const originalNavigator = (globalThis as any).navigator;
+    Object.defineProperty(globalThis, 'navigator', {
+      value: { usb },
+      configurable: true,
+    });
+    try {
+      const first = new WebUsbTransport() as any;
+      first.init({ debug: jest.fn() });
+      const second = new WebUsbTransport() as any;
+      second.init({ debug: jest.fn() });
+
+      // Module-level listener: one registration across instances.
+      expect(addEventListener).toHaveBeenCalledTimes(1);
+      const handler = addEventListener.mock.calls[0][1] as (event: {
+        device?: { serialNumber?: string | null };
+      }) => void;
+
+      const path = 'pro-webusb';
+      first.deviceProtocol.set(path, 'V1');
+      second.deviceProtocol.set(path, 'V1');
+      handler({ device: { serialNumber: path } });
+
+      // Routed to the most recently initialized instance; the cached value is
+      // retained (in-flight sessions keep working) but marked stale.
+      expect(second.staleProtocolPaths.has(path)).toBe(true);
+      expect(second.deviceProtocol.get(path)).toBe('V1');
+      expect(first.staleProtocolPaths.has(path)).toBe(false);
+
+      // Events without a device identity are ignored.
+      handler({ device: { serialNumber: null } });
+      handler({});
+      expect(second.staleProtocolPaths.size).toBe(1);
+    } finally {
+      Object.defineProperty(globalThis, 'navigator', {
+        value: originalNavigator,
+        configurable: true,
+      });
+    }
+  });
+});

package/__tests__/webusb-protocol-v2-timeout.test.ts

@@ -1,4 +1,9 @@
-import transport, { ProtocolV2FrameAssembler } from '@onekeyfe/hd-transport';
+import transport, {
+  PROTOCOL_V2_CHANNEL_USB,
+  ProtocolV2,
+  ProtocolV2LinkError,
+} from '@onekeyfe/hd-transport';
+import { HardwareErrorCode, ONEKEY_WEBUSB_FILTER } from '@onekeyfe/hd-shared';
 
 import WebUsbTransport from '../src/webusb';
 
@@ -16,25 +21,372 @@ const schema = {
 };
 
 describe('WebUsbTransport Protocol V2 timeout recovery', () => {
+  test('enumerates OneKey USB devices even when the serial string is omitted', async () => {
+    const filter =
+      ONEKEY_WEBUSB_FILTER.find(item => item.productId === 0x4f4c) ?? ONEKEY_WEBUSB_FILTER[0];
+    const deviceWithSerial = {
+      ...filter,
+      manufacturerName: 'OneKey',
+      productName: 'OneKey Pro 2',
+      serialNumber: 'PRO2-SERIAL',
+    } as USBDevice;
+    const deviceWithoutSerial = {
+      ...filter,
+      manufacturerName: 'OneKey',
+      productName: 'OneKey Neo',
+      serialNumber: null,
+    } as USBDevice;
+    const webusb = new WebUsbTransport();
+    webusb.usb = {
+      getDevices: jest.fn().mockResolvedValue([deviceWithSerial, deviceWithoutSerial]),
+    } as unknown as USB;
+
+    await expect(webusb.getConnectedDevices()).resolves.toEqual([
+      {
+        path: 'PRO2-SERIAL',
+        device: deviceWithSerial,
+        commType: 'webusb',
+      },
+      {
+        path: 'usb-1209-4f4c-onekey-neo',
+        device: deviceWithoutSerial,
+        commType: 'webusb',
+      },
+    ]);
+  });
+
+  test('keeps active links when the Protocol V2 schema is configured repeatedly', () => {
+    const webusb = new WebUsbTransport() as any;
+    webusb.invalidateAllProtocolV2UsbLinks = jest.fn().mockResolvedValue(undefined);
+    const schemaSource = JSON.stringify(schema);
+
+    webusb.configureProtocolV2(schemaSource);
+    webusb.configureProtocolV2(schemaSource);
+
+    expect(webusb.invalidateAllProtocolV2UsbLinks).not.toHaveBeenCalled();
+
+    webusb.configureProtocolV2(
+      JSON.stringify({
+        ...schema,
+        nested: {
+          ...schema.nested,
+          Failure: { fields: { message: { type: 'string', id: 1 } } },
+        },
+      })
+    );
+    expect(webusb.invalidateAllProtocolV2UsbLinks).toHaveBeenCalledWith(
+      'Protocol V2 schema reconfigured'
+    );
+  });
+
+  test('resets the connection between a failed V1 probe and the V2 probe', async () => {
+    const webusb = new WebUsbTransport() as any;
+    const path = 'pro2-webusb';
+    const events: string[] = [];
+    webusb.probeProtocolV1 = jest.fn().mockImplementation(() => {
+      events.push('probe-v1');
+      return Promise.resolve(false);
+    });
+    webusb.resetConnectionAfterProbe = jest.fn().mockImplementation(() => {
+      events.push('reset');
+      return Promise.resolve();
+    });
+    webusb.probeProtocolV2 = jest.fn().mockImplementation(() => {
+      events.push('probe-v2');
+      return Promise.resolve(true);
+    });
+
+    await expect(webusb.detectProtocol(path)).resolves.toBe('V2');
+
+    expect(events).toEqual(['probe-v1', 'reset', 'probe-v2']);
+    expect(webusb.deviceProtocol.get(path)).toBe('V2');
+  });
+
+  test('reports DeviceNotFound when automatic protocol detection exhausts both probes', async () => {
+    const webusb = new WebUsbTransport() as any;
+    const path = 'unresponsive-webusb';
+    webusb.probeProtocolV1 = jest.fn().mockResolvedValue(false);
+    webusb.probeProtocolV2 = jest.fn().mockResolvedValue(false);
+    webusb.resetConnectionAfterProbe = jest.fn().mockResolvedValue(undefined);
+    webusb.closeConnectionAfterProbe = jest.fn().mockResolvedValue(undefined);
+
+    await expect(webusb.detectProtocol(path)).rejects.toMatchObject({
+      errorCode: HardwareErrorCode.DeviceNotFound,
+    });
+
+    expect(webusb.probeProtocolV1).toHaveBeenCalledTimes(1);
+    expect(webusb.probeProtocolV2).toHaveBeenCalledTimes(1);
+    expect(webusb.resetConnectionAfterProbe).toHaveBeenCalledTimes(1);
+    expect(webusb.closeConnectionAfterProbe).toHaveBeenCalledTimes(1);
+    expect(webusb.deviceProtocol.has(path)).toBe(false);
+  });
+
+  test('allows legacy WebUSB Initialize up to the Node USB probe timeout', async () => {
+    const webusb = new WebUsbTransport() as any;
+    const path = 'pro-webusb';
+    webusb.messages = {};
+    webusb.callProtocolV1 = jest.fn().mockResolvedValue({});
+
+    await expect(webusb.probeProtocolV1(path)).resolves.toBe(true);
+
+    expect(webusb.callProtocolV1).toHaveBeenCalledWith(
+      path,
+      'Initialize',
+      {},
+      {
+        timeoutMs: 5000,
+      }
+    );
+  });
+
+  test('retries an expected Protocol V2 probe once after resetting the connection', async () => {
+    const webusb = new WebUsbTransport() as any;
+    const path = 'pro2-webusb';
+    webusb.probeProtocolV1 = jest.fn();
+    webusb.probeProtocolV2 = jest.fn().mockResolvedValueOnce(false).mockResolvedValueOnce(true);
+    webusb.resetConnectionAfterProbe = jest.fn().mockResolvedValue(undefined);
+
+    await expect(webusb.detectProtocol(path, 'V2')).resolves.toBe('V2');
+
+    expect(webusb.probeProtocolV2).toHaveBeenCalledTimes(2);
+    expect(webusb.probeProtocolV1).not.toHaveBeenCalled();
+    expect(webusb.resetConnectionAfterProbe).toHaveBeenCalledTimes(1);
+    expect(webusb.deviceProtocol.get(path)).toBe('V2');
+  });
+
+  test('reports a device initialization failure only after the bounded retry is exhausted', async () => {
+    const webusb = new WebUsbTransport() as any;
+    const path = 'pro2-webusb';
+    webusb.probeProtocolV1 = jest.fn();
+    webusb.probeProtocolV2 = jest.fn().mockResolvedValue(false);
+    webusb.resetConnectionAfterProbe = jest.fn().mockResolvedValue(undefined);
+    webusb.closeConnectionAfterProbe = jest.fn().mockResolvedValue(undefined);
+
+    await expect(webusb.detectProtocol(path, 'V2')).rejects.toMatchObject({
+      errorCode: HardwareErrorCode.DeviceInitializeFailed,
+      message: 'Protocol V2 probe timeout after 2 attempts',
+    });
+
+    expect(webusb.probeProtocolV2).toHaveBeenCalledTimes(2);
+    expect(webusb.probeProtocolV1).not.toHaveBeenCalled();
+    expect(webusb.resetConnectionAfterProbe).toHaveBeenCalledTimes(1);
+    expect(webusb.closeConnectionAfterProbe).toHaveBeenCalledTimes(1);
+    expect(webusb.deviceProtocol.has(path)).toBe(false);
+  });
+
+  test('closes the reopened device when acquire exhausts the expected Protocol V2 probe', async () => {
+    const webusb = new WebUsbTransport() as any;
+    const path = 'pro2-webusb';
+    const device = {
+      opened: false,
+      releaseInterface: jest.fn().mockResolvedValue(undefined),
+      close: jest.fn().mockImplementation(() => {
+        device.opened = false;
+        return Promise.resolve();
+      }),
+    };
+    webusb.deviceList = [{ path, device }];
+    webusb.Log = { debug: jest.fn() };
+    webusb.rotateProtocolV2UsbGeneration = jest.fn().mockResolvedValue(undefined);
+    webusb.connect = jest.fn().mockImplementation(() => {
+      device.opened = true;
+      return Promise.resolve();
+    });
+    webusb.detectProtocol = jest.fn().mockRejectedValue(new Error('terminal probe failure'));
+
+    await expect(webusb.acquire({ path, expectedProtocol: 'V2' })).rejects.toThrow(
+      'terminal probe failure'
+    );
+
+    expect(device.releaseInterface).toHaveBeenCalledTimes(1);
+    expect(device.close).toHaveBeenCalledTimes(1);
+    expect(device.opened).toBe(false);
+  });
+
   test('invalidates and resets the cached connection before another call can start', async () => {
     const webusb = new WebUsbTransport() as any;
     const path = 'pro2-webusb';
     webusb.messages = transport.parseConfigure(schema);
     webusb.messagesV2 = transport.parseConfigure(schema);
-    webusb.protocolV2Assemblers.set(path, new ProtocolV2FrameAssembler());
-    webusb.transferOutOnce = jest.fn().mockResolvedValue(undefined);
-    webusb.receiveProtocolV2Frame = jest.fn(() => new Promise(() => undefined));
-    webusb.resetConnectionAfterProbe = jest.fn().mockImplementation(async () => {
-      webusb.protocolV2Sessions.delete(path);
-      webusb.protocolV2ReadTimeouts.delete(path);
-      webusb.protocolV2Assemblers.get(path)?.reset();
-    });
+    webusb.writeProtocolV2UsbPacket = jest.fn().mockResolvedValue(undefined);
+    webusb.readProtocolV2UsbPacket = jest.fn(() => new Promise<void>(() => {}));
+    webusb.resetProtocolV2UsbNativeLink = jest.fn().mockResolvedValue(undefined);
+    webusb.resetConnectionAfterProbe = jest.fn();
+    await webusb.rotateProtocolV2UsbGeneration(path, 'test connection');
 
     await expect(
       webusb.callProtocolV2(path, 'Ping', { message: 'timeout' }, { timeoutMs: 10 })
     ).rejects.toThrow('timeout');
 
-    expect(webusb.resetConnectionAfterProbe).toHaveBeenCalledWith(path);
-    expect(webusb.protocolV2Sessions.has(path)).toBe(false);
+    expect(webusb.resetProtocolV2UsbNativeLink).toHaveBeenCalledWith(
+      path,
+      expect.stringContaining('timeout')
+    );
+    expect(webusb.resetConnectionAfterProbe).not.toHaveBeenCalled();
+  });
+
+  test('does not reconnect inside a Protocol V2 frame read after a USB I/O failure', async () => {
+    const webusb = new WebUsbTransport() as any;
+    const path = 'pro2-webusb';
+    webusb.messages = transport.parseConfigure(schema);
+    webusb.messagesV2 = transport.parseConfigure(schema);
+    webusb.writeProtocolV2UsbPacket = jest.fn().mockResolvedValue(undefined);
+    webusb.readProtocolV2UsbPacket = jest
+      .fn()
+      .mockRejectedValue(new Error('NetworkError: transferIn device disconnected'));
+    webusb.resetProtocolV2UsbNativeLink = jest.fn().mockResolvedValue(undefined);
+    webusb.resetConnectionAfterProbe = jest.fn();
+    await webusb.rotateProtocolV2UsbGeneration(path, 'test connection');
+
+    await expect(webusb.callProtocolV2(path, 'Ping', { message: 'read-error' })).rejects.toThrow(
+      'NetworkError'
+    );
+
+    expect(webusb.readProtocolV2UsbPacket).toHaveBeenCalledTimes(1);
+    expect(webusb.resetProtocolV2UsbNativeLink).toHaveBeenCalledWith(
+      path,
+      expect.stringContaining('NetworkError')
+    );
+    expect(webusb.resetConnectionAfterProbe).not.toHaveBeenCalled();
+  });
+
+  test('rejects an active Protocol V2 read without reconnecting after release', async () => {
+    const webusb = new WebUsbTransport() as any;
+    const path = 'pro2-webusb';
+    let markReadStarted: () => void = () => undefined;
+    const readStarted = new Promise<void>(resolve => {
+      markReadStarted = resolve;
+    });
+    webusb.messages = transport.parseConfigure(schema);
+    webusb.messagesV2 = transport.parseConfigure(schema);
+    webusb.writeProtocolV2UsbPacket = jest.fn().mockResolvedValue(undefined);
+    webusb.readProtocolV2UsbPacket = jest.fn().mockImplementation(() => {
+      markReadStarted();
+      return new Promise<void>(() => {});
+    });
+    webusb.closeOpenDevice = jest.fn().mockResolvedValue(undefined);
+    webusb.connect = jest.fn();
+    await webusb.rotateProtocolV2UsbGeneration(path, 'test connection');
+
+    const call = webusb.callProtocolV2(path, 'Ping', { message: 'release' });
+    await readStarted;
+    await webusb.release(path);
+
+    await expect(call).rejects.toThrow('WebUSB transport released');
+    expect(webusb.connect).not.toHaveBeenCalled();
+  });
+
+  test.each(['router', 'packet-source', 'ack-sequence', 'response-sequence', 'frame'] as const)(
+    'invalidates cached state for typed Protocol V2 %s errors',
+    async code => {
+      const webusb = new WebUsbTransport() as any;
+      const path = 'pro2-webusb';
+      webusb.messages = transport.parseConfigure(schema);
+      webusb.messagesV2 = transport.parseConfigure(schema);
+      webusb.writeProtocolV2UsbPacket = jest.fn().mockResolvedValue(undefined);
+      const recoveredResponse = ProtocolV2.encodeFrame(
+        { protocolV1: webusb.messages, protocolV2: webusb.messagesV2 },
+        'Success',
+        { message: 'recovered' },
+        { seq: 1 }
+      );
+      webusb.readProtocolV2UsbPacket = jest
+        .fn()
+        .mockRejectedValueOnce(
+          new ProtocolV2LinkError(code, `Protocol V2 ${code} validation failed`)
+        )
+        .mockResolvedValue(recoveredResponse);
+      webusb.resetProtocolV2UsbNativeLink = jest.fn().mockResolvedValue(undefined);
+      webusb.resetConnectionAfterProbe = jest.fn();
+      await webusb.rotateProtocolV2UsbGeneration(path, 'test connection');
+
+      await expect(webusb.callProtocolV2(path, 'Ping', { message: 'mismatch' })).rejects.toThrow(
+        `${code} validation failed`
+      );
+
+      expect(webusb.resetProtocolV2UsbNativeLink).toHaveBeenCalledWith(
+        path,
+        expect.stringContaining(`${code} validation failed`)
+      );
+      expect(webusb.resetConnectionAfterProbe).not.toHaveBeenCalled();
+
+      await webusb.rotateProtocolV2UsbGeneration(path, 'test reconnect');
+      await expect(
+        webusb.callProtocolV2(path, 'Ping', { message: 'after-reset' })
+      ).resolves.toMatchObject({
+        type: 'Success',
+        message: { message: 'recovered' },
+      });
+    }
+  );
+
+  test('does not discard buffered Protocol V2 frames before each call', async () => {
+    const webusb = new WebUsbTransport() as any;
+    const path = 'pro2-webusb';
+    webusb.messages = transport.parseConfigure(schema);
+    webusb.messagesV2 = transport.parseConfigure(schema);
+    webusb.writeProtocolV2UsbPacket = jest.fn().mockResolvedValue(undefined);
+    const firstResponse = ProtocolV2.encodeFrame(
+      { protocolV1: webusb.messages, protocolV2: webusb.messagesV2 },
+      'Success',
+      { message: 'first' },
+      { router: PROTOCOL_V2_CHANNEL_USB, seq: 1 }
+    );
+    const secondResponse = ProtocolV2.encodeFrame(
+      { protocolV1: webusb.messages, protocolV2: webusb.messagesV2 },
+      'Success',
+      { message: 'second' },
+      { router: PROTOCOL_V2_CHANNEL_USB, seq: 2 }
+    );
+    const coalescedResponses = new Uint8Array(firstResponse.length + secondResponse.length);
+    coalescedResponses.set(firstResponse);
+    coalescedResponses.set(secondResponse, firstResponse.length);
+    webusb.readProtocolV2UsbPacket = jest.fn().mockResolvedValue(coalescedResponses);
+    webusb.resetProtocolV2UsbNativeLink = jest.fn().mockResolvedValue(undefined);
+    await webusb.rotateProtocolV2UsbGeneration(path, 'test connection');
+
+    await expect(webusb.callProtocolV2(path, 'Ping', { message: 'first' })).resolves.toMatchObject({
+      type: 'Success',
+      message: { message: 'first' },
+    });
+    await expect(webusb.callProtocolV2(path, 'Ping', { message: 'second' })).resolves.toMatchObject(
+      {
+        type: 'Success',
+        message: { message: 'second' },
+      }
+    );
+
+    expect(webusb.readProtocolV2UsbPacket).toHaveBeenCalledTimes(1);
+  });
+
+  test('keeps queued Protocol V2 read timeouts scoped to each call', async () => {
+    const webusb = new WebUsbTransport() as any;
+    const path = 'pro2-webusb';
+    let responseSequence = 0;
+    const readTimeouts: number[] = [];
+    webusb.messages = transport.parseConfigure(schema);
+    webusb.messagesV2 = transport.parseConfigure(schema);
+    webusb.writeProtocolV2UsbPacket = jest.fn().mockResolvedValue(undefined);
+    webusb.readProtocolV2UsbPacket = jest.fn().mockImplementation((_path, context) => {
+      responseSequence += 1;
+      readTimeouts.push(context.timeoutMs);
+      return Promise.resolve(
+        ProtocolV2.encodeFrame(
+          { protocolV1: webusb.messages, protocolV2: webusb.messagesV2 },
+          'Success',
+          { message: 'ok' },
+          { seq: responseSequence }
+        )
+      );
+    });
+    webusb.resetProtocolV2UsbNativeLink = jest.fn().mockResolvedValue(undefined);
+    await webusb.rotateProtocolV2UsbGeneration(path, 'test connection');
+
+    await Promise.all([
+      webusb.callProtocolV2(path, 'Ping', { message: 'long' }, { timeoutMs: 1_000 }),
+      webusb.callProtocolV2(path, 'Ping', { message: 'short' }, { timeoutMs: 25 }),
+    ]);
+
+    expect(readTimeouts).toEqual([1_000, 25]);
   });
 });

package/dist/ble-packet-capacity.d.ts

@@ -0,0 +1,2 @@
+export declare function resolveBlePacketCapacity(mtu: number | null | undefined, maximumPacketCapacity: number, fallbackPacketCapacity: number): number;
+//# sourceMappingURL=ble-packet-capacity.d.ts.map

package/dist/ble-packet-capacity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ble-packet-capacity.d.ts","sourceRoot":"","sources":["../src/ble-packet-capacity.ts"],"names":[],"mappings":"AAEA,wBAAgB,wBAAwB,CACtC,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EAC9B,qBAAqB,EAAE,MAAM,EAC7B,sBAAsB,EAAE,MAAM,GAC7B,MAAM,CAMR"}