@thermal-label/brother-ql-web 0.4.0 → 0.6.0

package/dist/__tests__/request-printers.test.js

@@ -0,0 +1,250 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { DeviceIdentificationRequiredError } from '@thermal-label/contracts';
+import { DEVICES } from '@thermal-label/brother-ql-core';
+import { devicesForTransport, requestPrinters } from '../request-printers.js';
+import { createMockUSBDevice } from './webusb-mock.js';
+/**
+ * Minimal Web Serial `SerialPort` double for the Web Serial picker
+ * path. Typed structurally (not as the DOM `SerialPort`) because the
+ * web package only pulls in `w3c-web-usb`, not `w3c-web-serial`.
+ *
+ * `WebSerialTransport.fromPort` opens the port and locks a
+ * reader/writer; its pump loop awaits `reader.read()` indefinitely.
+ * This double's reader hangs until `cancel()` fires (mirroring a real
+ * idle SPP link) so `close()` can unwind the pump cleanly.
+ */
+function createMockSerialPort() {
+    let cancelReader;
+    const reader = {
+        read: () => new Promise(resolve => {
+            cancelReader = () => {
+                resolve({ value: new Uint8Array(0), done: true });
+            };
+        }),
+        cancel: () => {
+            cancelReader?.();
+            return Promise.resolve();
+        },
+        releaseLock: () => {
+            /* no-op */
+        },
+    };
+    const writer = {
+        write: () => Promise.resolve(),
+        close: () => Promise.resolve(),
+        releaseLock: () => {
+            /* no-op */
+        },
+    };
+    return {
+        open: vi.fn(() => Promise.resolve()),
+        close: vi.fn(() => Promise.resolve()),
+        readable: { getReader: () => reader },
+        writable: { getWriter: () => writer },
+    };
+}
+describe('requestPrinters(opts) — brother-ql generic factory', () => {
+    afterEach(() => {
+        vi.restoreAllMocks();
+    });
+    describe('transport: bluetooth-spp', () => {
+        it('throws DeviceIdentificationRequiredError when deviceKey omitted (no picker open)', async () => {
+            // No navigator.serial stubbed — a picker call would TypeError.
+            await expect(requestPrinters({ transport: 'bluetooth-spp' })).rejects.toBeInstanceOf(DeviceIdentificationRequiredError);
+        });
+        it('candidates are filtered to bluetooth-spp-capable entries (QL_820NWBc, PT_P910BT)', async () => {
+            try {
+                await requestPrinters({ transport: 'bluetooth-spp' });
+                throw new Error('expected DeviceIdentificationRequiredError');
+            }
+            catch (err) {
+                if (!(err instanceof DeviceIdentificationRequiredError))
+                    throw err;
+                const keys = err.candidates.map(c => c.key);
+                // Bench-confirmed SPP-capable models in the brother-ql registry.
+                expect(keys).toContain(DEVICES.QL_820NWBc.key);
+                expect(keys).toContain(DEVICES.PT_P910BT.key);
+                for (const candidate of err.candidates) {
+                    expect(candidate.transports['bluetooth-spp']).toBeDefined();
+                }
+            }
+        });
+        it('rejects an unknown deviceKey on bluetooth-spp', async () => {
+            await expect(requestPrinters({ transport: 'bluetooth-spp', deviceKey: 'NOT_A_KEY' })).rejects.toThrow(/unknown deviceKey/);
+        });
+        it('rejects a deviceKey for a model that does not declare bluetooth-spp', async () => {
+            // PT_P750W is a registered USB-only model — no bluetooth-spp entry.
+            expect(DEVICES.PT_P750W.transports['bluetooth-spp']).toBeUndefined();
+            await expect(requestPrinters({ transport: 'bluetooth-spp', deviceKey: DEVICES.PT_P750W.key })).rejects.toThrow(/does not declare bluetooth-spp/);
+        });
+        it('opens the Web Serial picker and returns a 1-key adapter map for a known SPP model', async () => {
+            const port = createMockSerialPort();
+            const requestPort = vi.fn().mockResolvedValue(port);
+            vi.stubGlobal('navigator', { serial: { requestPort } });
+            const printers = await requestPrinters({
+                transport: 'bluetooth-spp',
+                deviceKey: DEVICES.QL_820NWBc.key,
+            });
+            const roles = Object.keys(printers);
+            expect(roles).toHaveLength(1);
+            expect(roles[0]).toBe(DEVICES.QL_820NWBc.engines[0].role);
+            expect(printers[roles[0]].family).toBe('brother-ql');
+            expect(requestPort).toHaveBeenCalledOnce();
+            await printers[roles[0]].close();
+        });
+        it('continueWith opens the Web Serial picker with the operator-chosen SPP model', async () => {
+            const port = createMockSerialPort();
+            const requestPort = vi.fn().mockResolvedValue(port);
+            vi.stubGlobal('navigator', { serial: { requestPort } });
+            try {
+                await requestPrinters({ transport: 'bluetooth-spp' });
+                throw new Error('expected DeviceIdentificationRequiredError');
+            }
+            catch (err) {
+                if (!(err instanceof DeviceIdentificationRequiredError))
+                    throw err;
+                // No picker is opened until the operator resolves the choice.
+                expect(requestPort).not.toHaveBeenCalled();
+                const printers = await err.continueWith(DEVICES.PT_P910BT.key);
+                const roles = Object.keys(printers);
+                expect(roles).toHaveLength(1);
+                expect(requestPort).toHaveBeenCalledOnce();
+                await printers[roles[0]].close();
+            }
+        });
+        it('continueWith rejects an unknown deviceKey', async () => {
+            try {
+                await requestPrinters({ transport: 'bluetooth-spp' });
+                throw new Error('expected DeviceIdentificationRequiredError');
+            }
+            catch (err) {
+                if (!(err instanceof DeviceIdentificationRequiredError))
+                    throw err;
+                await expect(err.continueWith('NOT_A_KEY')).rejects.toThrow(/unknown deviceKey/);
+            }
+        });
+    });
+    describe('transport: serial', () => {
+        it('throws because brother-ql does not declare serial', async () => {
+            await expect(requestPrinters({ transport: 'serial' })).rejects.toThrow(/not declared/);
+        });
+    });
+    describe('transport: bluetooth-gatt', () => {
+        it('throws because brother-ql does not declare bluetooth-gatt', async () => {
+            await expect(requestPrinters({ transport: 'bluetooth-gatt' })).rejects.toThrow(/not declared/);
+        });
+    });
+    describe('transport: usb — auto-identify', () => {
+        it('returns a 1-key adapter map when the picked USBDevice matches a registry entry', async () => {
+            // QL_820NWBc canonical VID/PID — registered.
+            const known = DEVICES.QL_820NWBc.transports.usb;
+            if (!known)
+                throw new Error('QL_820NWBc missing usb transport in registry');
+            const device = createMockUSBDevice({
+                vendorId: Number.parseInt(known.vid, 16),
+                productId: Number.parseInt(known.pid, 16),
+            });
+            const usbStub = {
+                requestDevice: vi.fn().mockResolvedValue(device),
+                getDevices: vi.fn().mockResolvedValue([device]),
+            };
+            vi.stubGlobal('navigator', { usb: usbStub });
+            const printers = await requestPrinters({ transport: 'usb' });
+            const roles = Object.keys(printers);
+            expect(roles).toHaveLength(1);
+            const printer = printers[roles[0]];
+            expect(printer.family).toBe('brother-ql');
+            await printer.close();
+        });
+        it('uses an explicit deviceKey to wrap the picked USBDevice without registry auto-match', async () => {
+            // Pass a deviceKey alongside a device whose VID/PID would NOT
+            // auto-match — the explicit key takes the priority branch.
+            const device = createMockUSBDevice({ vendorId: 0x04f9, productId: 0xabcd });
+            const usbStub = {
+                requestDevice: vi.fn().mockResolvedValue(device),
+                getDevices: vi.fn().mockResolvedValue([device]),
+            };
+            vi.stubGlobal('navigator', { usb: usbStub });
+            const printers = await requestPrinters({
+                transport: 'usb',
+                deviceKey: DEVICES.QL_820NWBc.key,
+            });
+            const roles = Object.keys(printers);
+            expect(roles).toHaveLength(1);
+            expect(roles[0]).toBe(DEVICES.QL_820NWBc.engines[0].role);
+            await printers[roles[0]].close();
+        });
+        it('rejects an explicit unknown deviceKey on usb', async () => {
+            const device = createMockUSBDevice({ vendorId: 0x04f9, productId: 0x209d });
+            const usbStub = {
+                requestDevice: vi.fn().mockResolvedValue(device),
+                getDevices: vi.fn().mockResolvedValue([device]),
+            };
+            vi.stubGlobal('navigator', { usb: usbStub });
+            await expect(requestPrinters({ transport: 'usb', deviceKey: 'NOT_A_KEY' })).rejects.toThrow(/unknown deviceKey/);
+        });
+        it('continueWith rejects an unknown deviceKey on the usb path', async () => {
+            const device = createMockUSBDevice({ vendorId: 0x04f9, productId: 0xabcd });
+            const usbStub = {
+                requestDevice: vi.fn().mockResolvedValue(device),
+                getDevices: vi.fn().mockResolvedValue([device]),
+            };
+            vi.stubGlobal('navigator', { usb: usbStub });
+            try {
+                await requestPrinters({ transport: 'usb' });
+                throw new Error('expected DeviceIdentificationRequiredError');
+            }
+            catch (err) {
+                if (!(err instanceof DeviceIdentificationRequiredError))
+                    throw err;
+                await expect(err.continueWith('NOT_A_KEY')).rejects.toThrow(/unknown deviceKey/);
+            }
+        });
+        it('throws DeviceIdentificationRequiredError when the picked device has unknown VID/PID', async () => {
+            const device = createMockUSBDevice({ vendorId: 0xdead, productId: 0xbeef });
+            const usbStub = {
+                requestDevice: vi.fn().mockResolvedValue(device),
+                getDevices: vi.fn().mockResolvedValue([device]),
+            };
+            vi.stubGlobal('navigator', { usb: usbStub });
+            await expect(requestPrinters({ transport: 'usb' })).rejects.toBeInstanceOf(DeviceIdentificationRequiredError);
+        });
+        it('continueWith resumes with the chosen deviceKey reusing the picked USBDevice', async () => {
+            // Use a real Brother VID with an unknown PID — the registry
+            // won't match, the picker fires once, and continueWith wraps
+            // the same device with the operator's choice.
+            const device = createMockUSBDevice({ vendorId: 0x04f9, productId: 0xabcd });
+            const requestDevice = vi.fn().mockResolvedValue(device);
+            const usbStub = {
+                requestDevice,
+                getDevices: vi.fn().mockResolvedValue([device]),
+            };
+            vi.stubGlobal('navigator', { usb: usbStub });
+            try {
+                await requestPrinters({ transport: 'usb' });
+                throw new Error('expected DeviceIdentificationRequiredError');
+            }
+            catch (err) {
+                if (!(err instanceof DeviceIdentificationRequiredError))
+                    throw err;
+                const printers = await err.continueWith(DEVICES.QL_820NWBc.key);
+                const roles = Object.keys(printers);
+                expect(roles).toHaveLength(1);
+                // continueWith must not open the picker a second time.
+                expect(requestDevice).toHaveBeenCalledTimes(1);
+                await printers[roles[0]].close();
+            }
+        });
+    });
+});
+describe('devicesForTransport — brother-ql', () => {
+    it('returns only entries declaring the given transport', () => {
+        for (const entry of devicesForTransport('usb')) {
+            expect(entry.transports.usb).toBeDefined();
+        }
+        for (const entry of devicesForTransport('bluetooth-spp')) {
+            expect(entry.transports['bluetooth-spp']).toBeDefined();
+        }
+    });
+});
+//# sourceMappingURL=request-printers.test.js.map

package/dist/__tests__/request-printers.test.js.map

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

package/dist/__tests__/webusb-mock.d.ts

@@ -4,10 +4,21 @@ export interface MockUSBDevice extends USBDevice {
         data: Uint8Array;
     }[];
     __statusBytes: Uint8Array;
+    /**
+     * Inject an unsolicited status frame into the bulk-IN pipe. Used by
+     * tests to simulate spontaneous events the printer pushes outside of
+     * a getStatus request (lid open/close, media insert, etc.).
+     */
+    __pushUnsolicited: (frame: Uint8Array) => void;
 }
 export declare function createMockUSBDevice(overrides?: {
     vendorId?: number;
     productId?: number;
+    /**
+     * Response template for ESC iS (`1B 69 53`). Each status request
+     * enqueues a copy of this frame — modelling the real printer's
+     * "request → one response" cycle. Defaults to a 32-byte zero frame.
+     */
     statusBytes?: Uint8Array;
 }): MockUSBDevice;
 //# sourceMappingURL=webusb-mock.d.ts.map

package/dist/__tests__/webusb-mock.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"webusb-mock.d.ts","sourceRoot":"","sources":["../../src/__tests__/webusb-mock.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,aAAc,SAAQ,SAAS;IAC9C,WAAW,EAAE;QAAE,cAAc,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,UAAU,CAAA;KAAE,EAAE,CAAC;IAC5D,aAAa,EAAE,UAAU,CAAC;CAC3B;AAED,wBAAgB,mBAAmB,CAAC,SAAS,CAAC,EAAE;IAC9C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,UAAU,CAAC;CAC1B,GAAG,aAAa,CAoEhB"}
+{"version":3,"file":"webusb-mock.d.ts","sourceRoot":"","sources":["../../src/__tests__/webusb-mock.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,aAAc,SAAQ,SAAS;IAC9C,WAAW,EAAE;QAAE,cAAc,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,UAAU,CAAA;KAAE,EAAE,CAAC;IAC5D,aAAa,EAAE,UAAU,CAAC;IAC1B;;;;OAIG;IACH,iBAAiB,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,CAAC;CAChD;AAED,wBAAgB,mBAAmB,CAAC,SAAS,CAAC,EAAE;IAC9C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,WAAW,CAAC,EAAE,UAAU,CAAC;CAC1B,GAAG,aAAa,CAoHhB"}

package/dist/__tests__/webusb-mock.js

@@ -2,6 +2,19 @@ import { vi } from 'vitest';
 export function createMockUSBDevice(overrides) {
     const transfers = [];
     let opened = false;
+    // Single in-flight pipe queue. Each ESC iS write appends a response
+    // copy. Pending readers (calls to `transferIn` made while the queue
+    // is empty) park in `waiters` and are resolved as soon as a frame is
+    // appended — matching real WebUSB bulk-IN behaviour.
+    const frameQueue = [];
+    const waiters = [];
+    function enqueue(frame) {
+        const waiter = waiters.shift();
+        if (waiter)
+            waiter(frame);
+        else
+            frameQueue.push(frame);
+    }
     const endpoints = [
         { endpointNumber: 2, direction: 'out' },
         { endpointNumber: 1, direction: 'in' },
@@ -40,6 +53,20 @@ export function createMockUSBDevice(overrides) {
         }),
         close: vi.fn(() => {
             opened = false;
+            // Reject any pending readers with a TransportClosed-shaped error
+            // so the read loop can exit cleanly.
+            while (waiters.length > 0) {
+                const waiter = waiters.shift();
+                if (waiter) {
+                    const err = new Error('Transport closed');
+                    err.name = 'TransportClosedError';
+                    // The mock's transferIn signals via the resolved Promise — to
+                    // surface a rejection, route via the waiter as a thrown call.
+                    // Using a sentinel "empty" frame works because the read loop
+                    // checks `transport.connected` which flips to false on close.
+                    waiter(new Uint8Array(0));
+                }
+            }
             return Promise.resolve();
         }),
         selectConfiguration: vi.fn(() => Promise.resolve()),
@@ -48,18 +75,40 @@ export function createMockUSBDevice(overrides) {
         transferOut: vi.fn((endpointNumber, data) => {
             const array = data instanceof Uint8Array ? data : new Uint8Array(data);
             transfers.push({ endpointNumber, data: Uint8Array.from(array) });
+            // Brother ESC iS = `1B 69 53`. Enqueue a response copy.
+            if (array.length >= 3 && array[0] === 0x1b && array[1] === 0x69 && array[2] === 0x53) {
+                enqueue(Uint8Array.from(statusBytes));
+            }
             return Promise.resolve({ bytesWritten: array.byteLength, status: 'ok' });
         }),
         transferIn: vi.fn((_endpointNumber, length) => {
-            const out = new Uint8Array(length);
-            out.set(statusBytes.subarray(0, length));
-            return Promise.resolve({
-                data: new DataView(out.buffer),
-                status: 'ok',
+            // Drain any pre-queued frames first.
+            const next = frameQueue.shift();
+            if (next) {
+                const out = new Uint8Array(length);
+                out.set(next.subarray(0, length));
+                return Promise.resolve({
+                    data: new DataView(out.buffer),
+                    status: 'ok',
+                });
+            }
+            // Park as a waiter; resolve when a future frame is enqueued.
+            return new Promise(resolve => {
+                waiters.push(frame => {
+                    const out = new Uint8Array(length);
+                    out.set(frame.subarray(0, Math.min(length, frame.length)));
+                    resolve({
+                        data: new DataView(out.buffer, 0, frame.length),
+                        status: 'ok',
+                    });
+                });
             });
         }),
         __transfers: transfers,
         __statusBytes: statusBytes,
+        __pushUnsolicited: (frame) => {
+            enqueue(Uint8Array.from(frame));
+        },
     };
     return device;
 }

package/dist/__tests__/webusb-mock.js.map

@@ -1 +1 @@
-{"version":3,"file":"webusb-mock.js","sourceRoot":"","sources":["../../src/__tests__/webusb-mock.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,EAAE,EAAE,MAAM,QAAQ,CAAC;AAO5B,MAAM,UAAU,mBAAmB,CAAC,SAInC;IACC,MAAM,SAAS,GAAmD,EAAE,CAAC;IACrE,IAAI,MAAM,GAAG,KAAK,CAAC;IAEnB,MAAM,SAAS,GAAG;QAChB,EAAE,cAAc,EAAE,CAAC,EAAE,SAAS,EAAE,KAAK,EAAE;QACvC,EAAE,cAAc,EAAE,CAAC,EAAE,SAAS,EAAE,IAAI,EAAE;KACX,CAAC;IAE9B,MAAM,aAAa,GAAqB;QACtC,kBAAkB,EAAE,CAAC;QACrB,iBAAiB,EAAE,IAAI;QACvB,UAAU,EAAE;YACV;gBACE,eAAe,EAAE,CAAC;gBAClB,SAAS,EAAE;oBACT,gBAAgB,EAAE,CAAC;oBACnB,cAAc,EAAE,CAAC;oBACjB,iBAAiB,EAAE,CAAC;oBACpB,iBAAiB,EAAE,CAAC;oBACpB,aAAa,EAAE,IAAI;oBACnB,SAAS;iBACV;gBACD,UAAU,EAAE,EAAE;gBACd,OAAO,EAAE,KAAK;aACf;SACF;KACF,CAAC;IAEF,MAAM,WAAW,GAAG,SAAS,EAAE,WAAW,IAAI,IAAI,UAAU,CAAC,EAAE,CAAC,CAAC;IAEjE,MAAM,MAAM,GAAG;QACb,QAAQ,EAAE,SAAS,EAAE,QAAQ,IAAI,MAAM;QACvC,SAAS,EAAE,SAAS,EAAE,SAAS,IAAI,MAAM;QACzC,YAAY,EAAE,SAAS;QACvB,IAAI,MAAM;YACR,OAAO,MAAM,CAAC;QAChB,CAAC;QACD,aAAa;QACb,IAAI,EAAE,EAAE,CAAC,EAAE,CAAC,GAAG,EAAE;YACf,MAAM,GAAG,IAAI,CAAC;YACd,OAAO,OAAO,CAAC,OAAO,EAAE,CAAC;QAC3B,CAAC,CAAC;QACF,KAAK,EAAE,EAAE,CAAC,EAAE,CAAC,GAAG,EAAE;YAChB,MAAM,GAAG,KAAK,CAAC;YACf,OAAO,OAAO,CAAC,OAAO,EAAE,CAAC;QAC3B,CAAC,CAAC;QACF,mBAAmB,EAAE,EAAE,CAAC,EAAE,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC;QACnD,cAAc,EAAE,EAAE,CAAC,EAAE,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC;QAC9C,gBAAgB,EAAE,EAAE,CAAC,EAAE,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC;QAChD,WAAW,EAAE,EAAE,CAAC,EAAE,CAAC,CAAC,cAAsB,EAAE,IAAkB,EAAE,EAAE;YAChE,MAAM,KAAK,GAAG,IAAI,YAAY,UAAU,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,UAAU,CAAC,IAAmB,CAAC,CAAC;YACtF,SAAS,CAAC,IAAI,CAAC,EAAE,cAAc,EAAE,IAAI,EAAE,UAAU,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;YACjE,OAAO,OAAO,CAAC,OAAO,CAAC,EAAE,YAAY,EAAE,KAAK,CAAC,UAAU,EAAE,MAAM,EAAE,IAAa,EAAE,CAAC,CAAC;QACpF,CAAC,CAAC;QACF,UAAU,EAAE,EAAE,CAAC,EAAE,CAAC,CAAC,eAAuB,EAAE,MAAc,EAAE,EAAE;YAC5D,MAAM,GAAG,GAAG,IAAI,UAAU,CAAC,MAAM,CAAC,CAAC;YACnC,GAAG,CAAC,GAAG,CAAC,WAAW,CAAC,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC;YACzC,OAAO,OAAO,CAAC,OAAO,CAAC;gBACrB,IAAI,EAAE,IAAI,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC;gBAC9B,MAAM,EAAE,IAAa;aACtB,CAAC,CAAC;QACL,CAAC,CAAC;QACF,WAAW,EAAE,SAAS;QACtB,aAAa,EAAE,WAAW;KACC,CAAC;IAE9B,OAAO,MAAM,CAAC;AAChB,CAAC"}
+{"version":3,"file":"webusb-mock.js","sourceRoot":"","sources":["../../src/__tests__/webusb-mock.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -1,2 +1,6 @@
-export { DEFAULT_FILTERS, WebBrotherQLPrinter, fromUSBDevice, requestPrinter, type RequestOptions, } from './printer.js';
+export { DEFAULT_FILTERS, WebBrotherQLPrinter, type RequestOptions } from './printer.js';
+export { fromUSBDevice, fromUSBDeviceAll, requestPrinter, requestPrintersUsbLegacy, } from './printer.js';
+export { devicesForTransport, requestPrinters } from './request-printers.js';
+export type { ConnectOptions, PrinterAdapterMap } from '@thermal-label/contracts';
+export { DeviceIdentificationRequiredError } from '@thermal-label/contracts';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,eAAe,EACf,mBAAmB,EACnB,aAAa,EACb,cAAc,EACd,KAAK,cAAc,GACpB,MAAM,cAAc,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,mBAAmB,EAAE,KAAK,cAAc,EAAE,MAAM,cAAc,CAAC;AAGzF,OAAO,EACL,aAAa,EACb,gBAAgB,EAChB,cAAc,EACd,wBAAwB,GACzB,MAAM,cAAc,CAAC;AAGtB,OAAO,EAAE,mBAAmB,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAE7E,YAAY,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAClF,OAAO,EAAE,iCAAiC,EAAE,MAAM,0BAA0B,CAAC"}

package/dist/index.js

@@ -1,2 +1,7 @@
-export { DEFAULT_FILTERS, WebBrotherQLPrinter, fromUSBDevice, requestPrinter, } from './printer.js';
+export { DEFAULT_FILTERS, WebBrotherQLPrinter } from './printer.js';
+/* eslint-disable @typescript-eslint/no-deprecated -- legacy factories re-exported during plan-10 transition */
+export { fromUSBDevice, fromUSBDeviceAll, requestPrinter, requestPrintersUsbLegacy, } from './printer.js';
+/* eslint-enable @typescript-eslint/no-deprecated */
+export { devicesForTransport, requestPrinters } from './request-printers.js';
+export { DeviceIdentificationRequiredError } from '@thermal-label/contracts';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,eAAe,EACf,mBAAmB,EACnB,aAAa,EACb,cAAc,GAEf,MAAM,cAAc,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,mBAAmB,EAAuB,MAAM,cAAc,CAAC;AAEzF,+GAA+G;AAC/G,OAAO,EACL,aAAa,EACb,gBAAgB,EAChB,cAAc,EACd,wBAAwB,GACzB,MAAM,cAAc,CAAC;AACtB,oDAAoD;AAEpD,OAAO,EAAE,mBAAmB,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAG7E,OAAO,EAAE,iCAAiC,EAAE,MAAM,0BAA0B,CAAC"}

package/dist/printer.d.ts

@@ -15,13 +15,69 @@ export declare class WebBrotherQLPrinter implements PrinterAdapter {
     readonly device: BrotherQLDevice;
     private readonly transport;
     private lastStatus;
+    private readonly statusListeners;
+    private readLoopStarted;
+    private readLoopStopped;
+    /**
+     * Serialises every bulk-OUT operation (print + getStatus). Required
+     * because `getStatus()` may write the QL preamble (`buildInvalidate` —
+     * 200×0x00 + `ESC @`) to put the parser in a known state, and the
+     * preamble's "invalidate" cancels any in-flight print job. Polling
+     * concurrently with a print would shred the raster stream.
+     *
+     * Plan 15 A4: this was a hand-rolled `writeLock`/`runLocked` pair;
+     * it is now the shared `WriteSerializer` from `@thermal-label/contracts`
+     * so all four drivers serialise identically. Behaviour is unchanged —
+     * `WriteSerializer.run()` is exactly the old `runLocked` semantics.
+     */
+    private readonly serializer;
+    /**
+     * Whether the printer's command parser is in a known-clean state.
+     * Set to `true` after a successful `getStatus()`; flipped back to
+     * `false` on timeout so the next attempt re-sends the preamble. The
+     * preamble (200-byte invalidate + `ESC @`) is only needed once per
+     * session unless the parser falls back into a confused state.
+     */
+    private parserReady;
     constructor(device: BrotherQLDevice, transport: Transport);
     get model(): string;
     get connected(): boolean;
     print(image: RawImageData, media?: MediaDescriptor, options?: BrotherQLPrintOptions): Promise<void>;
     private writeChunked;
     createPreview(image: RawImageData, options?: PreviewOptions): Promise<PreviewResult>;
+    /**
+     * Send ESC iS and resolve with the next status frame the printer
+     * emits. The read loop is the sole reader of the bulk-IN pipe —
+     * `getStatus()` subscribes transiently, writes the request, and the
+     * subscription receives the response (alongside any spontaneous
+     * frames; see `onStatus()`).
+     *
+     * The QL preamble (200×0x00 invalidate + `ESC @` initialize) is
+     * sent only when the parser hasn't been confirmed clean — first
+     * call of the session, or after a previous timeout. Steady-state
+     * polls send bare `ESC iS`. Bench observation: a freshly-opened QL
+     * doesn't reply to bare `ESC iS` until the invalidate flushes any
+     * stale parser state from a prior session.
+     */
     getStatus(): Promise<BrotherQLStatus>;
+    /**
+     * Subscribe to status updates. A polling shim built on
+     * `pollingOnStatus` from contracts — it calls `getStatus()` on first
+     * subscribe and then every `DEFAULT_POLLING_INTERVAL_MS`, matching the
+     * labelwriter and labelmanager web drivers (plan 11 §`onStatus`
+     * parity).
+     *
+     * An earlier revision skipped polling and relied solely on the
+     * printer's unsolicited frames. That was a workaround for the Chromium
+     * WebUSB sub-packet stall — `getStatus()`'s `read()` would hang, so
+     * polling looked unreliable and was dropped. `WebUsbTransport.read()`
+     * now rounds reads up to the endpoint packet size, so `getStatus()` is
+     * dependable and polling is restored.
+     */
+    onStatus(cb: (status: BrotherQLStatus) => void): () => void;
+    private nextStatusFrame;
+    private startReadLoop;
+    private readLoop;
     close(): Promise<void>;
 }
 export declare const DEFAULT_FILTERS: USBDeviceFilter[];
@@ -30,12 +86,49 @@ export declare const DEFAULT_FILTERS: USBDeviceFilter[];
  *
  * Requires a user gesture. Opens the device and claims interface 0 via
  * `WebUsbTransport.fromDevice()`.
+ *
+ * Single-instance entry point — preserved for back-compat with existing
+ * consumers (CLIs, ad-hoc scripts). For the symmetric driver-web shape
+ * (1-key map keyed by engine role) call `requestPrinters()` instead;
+ * the harness shell uses that path.
+ *
+ * @deprecated Use `requestPrinters({ transport: 'usb' })` from
+ *   `./request-printers.ts`. Removed once consumers migrate (plan 11).
  */
 export declare function requestPrinter(options?: RequestOptions): Promise<WebBrotherQLPrinter>;
+/**
+ * Show the browser's USB picker and return one `PrinterAdapter` per
+ * drivable engine on the selected device, keyed by engine role.
+ *
+ * Brother QL devices are always single-engine — this returns a 1-key
+ * record keyed by the device's `engines[0].role` (typically `'primary'`).
+ *
+ * @deprecated Use the generic `requestPrinters({ transport: 'usb' })`
+ *   from `./request-printers.ts` — the legacy USB-only name is preserved
+ *   as `requestPrintersUsbLegacy` for back-compat. Removed once
+ *   consumers migrate (plan 11).
+ */
+export declare function requestPrintersUsbLegacy(options?: RequestOptions): Promise<Record<string, WebBrotherQLPrinter>>;
 /**
  * Wrap an already-selected `USBDevice`.
  *
  * @throws when the VID/PID is not in the Brother QL registry.
+ *
+ * @deprecated Use `requestPrinters({ transport: 'usb' })` from
+ *   `./request-printers.ts`. Removed once consumers migrate (plan 11).
  */
 export declare function fromUSBDevice(usbDevice: USBDevice): Promise<WebBrotherQLPrinter>;
+/**
+ * Wrap an already-selected `USBDevice` and return a 1-key adapter map
+ * keyed by the device's `engines[0].role`. Public surface for
+ * `requestPrinters()`; exported so harnesses that already hold a
+ * `USBDevice` (e.g. picked-up via `navigator.usb.getDevices()` on a
+ * returning visit) can skip the picker.
+ *
+ * Brother QL is single-engine and single-interface (IF 0).
+ *
+ * @deprecated Use `requestPrinters({ transport: 'usb' })` from
+ *   `./request-printers.ts`. Removed once consumers migrate (plan 11).
+ */
+export declare function fromUSBDeviceAll(usbDevice: USBDevice): Promise<Record<string, WebBrotherQLPrinter>>;
 //# sourceMappingURL=printer.d.ts.map

package/dist/printer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"printer.d.ts","sourceRoot":"","sources":["../src/printer.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EACV,eAAe,EAEf,qBAAqB,EACrB,eAAe,EAEf,eAAe,EAEf,cAAc,EACd,aAAa,EACb,cAAc,EACd,YAAY,EACZ,SAAS,EACV,MAAM,gCAAgC,CAAC;AAYxC,MAAM,WAAW,cAAc;IAC7B,OAAO,CAAC,EAAE,eAAe,EAAE,CAAC;CAC7B;AAED;;;;;;;GAOG;AACH,qBAAa,mBAAoB,YAAW,cAAc;IACxD,QAAQ,CAAC,MAAM,eAAyB;IACxC,QAAQ,CAAC,MAAM,EAAE,eAAe,CAAC;IAEjC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAY;IACtC,OAAO,CAAC,UAAU,CAA8B;gBAEpC,MAAM,EAAE,eAAe,EAAE,SAAS,EAAE,SAAS;IAKzD,IAAI,KAAK,IAAI,MAAM,CAElB;IAED,IAAI,SAAS,IAAI,OAAO,CAEvB;IAEK,KAAK,CACT,KAAK,EAAE,YAAY,EACnB,KAAK,CAAC,EAAE,eAAe,EACvB,OAAO,CAAC,EAAE,qBAAqB,GAC9B,OAAO,CAAC,IAAI,CAAC;YAuCF,YAAY;IAU1B,aAAa,CAAC,KAAK,EAAE,YAAY,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC;IAW9E,SAAS,IAAI,OAAO,CAAC,eAAe,CAAC;IAQrC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAG7B;AAED,eAAO,MAAM,eAAe,EAAE,eAAe,EAGmC,CAAC;AAEjF;;;;;GAKG;AACH,wBAAsB,cAAc,CAAC,OAAO,GAAE,cAAmB,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAI/F;AAED;;;;GAIG;AACH,wBAAsB,aAAa,CAAC,SAAS,EAAE,SAAS,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAStF"}
+{"version":3,"file":"printer.d.ts","sourceRoot":"","sources":["../src/printer.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EACV,eAAe,EAEf,qBAAqB,EACrB,eAAe,EAEf,eAAe,EAEf,cAAc,EACd,aAAa,EACb,cAAc,EACd,YAAY,EACZ,SAAS,EACV,MAAM,gCAAgC,CAAC;AA4BxC,MAAM,WAAW,cAAc;IAC7B,OAAO,CAAC,EAAE,eAAe,EAAE,CAAC;CAC7B;AAED;;;;;;;GAOG;AACH,qBAAa,mBAAoB,YAAW,cAAc;IACxD,QAAQ,CAAC,MAAM,eAAyB;IACxC,QAAQ,CAAC,MAAM,EAAE,eAAe,CAAC;IAEjC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAY;IACtC,OAAO,CAAC,UAAU,CAA8B;IAChD,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAgD;IAChF,OAAO,CAAC,eAAe,CAAS;IAChC,OAAO,CAAC,eAAe,CAAS;IAChC;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAyB;IACpD;;;;;;OAMG;IACH,OAAO,CAAC,WAAW,CAAS;gBAEhB,MAAM,EAAE,eAAe,EAAE,SAAS,EAAE,SAAS;IAMzD,IAAI,KAAK,IAAI,MAAM,CAElB;IAED,IAAI,SAAS,IAAI,OAAO,CAEvB;IAEK,KAAK,CACT,KAAK,EAAE,YAAY,EACnB,KAAK,CAAC,EAAE,eAAe,EACvB,OAAO,CAAC,EAAE,qBAAqB,GAC9B,OAAO,CAAC,IAAI,CAAC;YAgDF,YAAY;IAU1B,aAAa,CAAC,KAAK,EAAE,YAAY,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC;IAWpF;;;;;;;;;;;;;OAaG;IACG,SAAS,IAAI,OAAO,CAAC,eAAe,CAAC;IAqB3C;;;;;;;;;;;;;OAaG;IACH,QAAQ,CAAC,EAAE,EAAE,CAAC,MAAM,EAAE,eAAe,KAAK,IAAI,GAAG,MAAM,IAAI;IAI3D,OAAO,CAAC,eAAe;IAiBvB,OAAO,CAAC,aAAa;YAOP,QAAQ;IAuChB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAK7B;AAED,eAAO,MAAM,eAAe,EAAE,eAAe,EAGmC,CAAC;AAEjF;;;;;;;;;;;;;GAaG;AACH,wBAAsB,cAAc,CAAC,OAAO,GAAE,cAAmB,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAK/F;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,wBAAwB,CAC5C,OAAO,GAAE,cAAmB,GAC3B,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAAC,CAK9C;AAED;;;;;;;GAOG;AACH,wBAAsB,aAAa,CAAC,SAAS,EAAE,SAAS,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAStF;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,gBAAgB,CACpC,SAAS,EAAE,SAAS,GACnB,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAAC,CAc9C"}