@thermal-label/brother-ql-core 0.6.1 → 0.6.3

package/src/__tests__/network-status.test.ts

@@ -0,0 +1,165 @@
+import { describe, it, expect } from 'vitest';
+import { parseMediaName, statusFromPrinterMib, type PrinterMibStatus } from '../network-status.js';
+
+/** Bench values, QL-820NWBc 2026-09-15 (plan 17 Context). */
+const DK_11201_NAME = '29mm x 90mm / 1.1" x 3.5"';
+const DK_22205_NAME = '62mm / 2.4"';
+
+function mib(overrides: Partial<PrinterMibStatus> = {}): PrinterMibStatus {
+  return {
+    printerStatus: 3,
+    errorState: new Uint8Array([0x00]),
+    mediaName: DK_22205_NAME,
+    feedDir: -1,
+    xFeedDir: -1,
+    ...overrides,
+  };
+}
+
+/** Octets with the given RFC 2790 bit numbers set (bit 0 = MSB of octet 0). */
+function errorBits(...bits: number[]): Uint8Array {
+  const octets = new Uint8Array(2);
+  for (const bit of bits) octets[bit >> 3] = (octets[bit >> 3] ?? 0) | (0x80 >> (bit & 7));
+  return octets;
+}
+
+describe('parseMediaName', () => {
+  it.each([
+    [DK_11201_NAME, { widthMm: 29, heightMm: 90 }],
+    [DK_22205_NAME, { widthMm: 62 }],
+    ['17mm x 54mm / 0.66" x 2.1"', { widthMm: 17, heightMm: 54 }],
+    ['62mm', { widthMm: 62 }],
+    ['24mm Dia / 0.9" Dia', { widthMm: 24, heightMm: 24 }],
+    ['29 mm × 90 mm', { widthMm: 29, heightMm: 90 }],
+  ])('%s', (name, expected) => {
+    expect(parseMediaName(name)).toEqual(expected);
+  });
+
+  it.each(['', 'garbage', '2.4"', 'mm', '62 / 2.4"', 'Roll 62'])('rejects %j', name => {
+    expect(parseMediaName(name)).toBeUndefined();
+  });
+});
+
+describe('statusFromPrinterMib', () => {
+  it('idle, no errors, 62 mm continuous → ready with DK-22205 and the two-colour warning', () => {
+    const status = statusFromPrinterMib(mib());
+    expect(status.ready).toBe(true);
+    expect(status.errors).toEqual([]);
+    expect(status.mediaLoaded).toBe(true);
+    expect(status.detectedMedia?.id).toBe(259);
+    expect(status.rawBytes).toHaveLength(0);
+    expect(status.details).toContainEqual({
+      label: 'Two-colour',
+      value: 'not detectable over network',
+      severity: 'warn',
+    });
+    expect(status.details?.find(d => d.label === 'Printer state')?.value).toBe('idle');
+  });
+
+  it('29×90 die-cut → DK-11201, no two-colour row', () => {
+    const status = statusFromPrinterMib(mib({ mediaName: DK_11201_NAME }));
+    expect(status.detectedMedia?.id).toBe(271);
+    expect(status.details?.some(d => d.label === 'Two-colour')).toBe(false);
+  });
+
+  it('printing counts as ready; warmup, other and unknown do not', () => {
+    expect(statusFromPrinterMib(mib({ printerStatus: 4 })).ready).toBe(true);
+    expect(statusFromPrinterMib(mib({ printerStatus: 5 })).ready).toBe(false);
+    expect(statusFromPrinterMib(mib({ printerStatus: 1 })).ready).toBe(false);
+    expect(statusFromPrinterMib(mib({ printerStatus: 99 })).ready).toBe(false);
+    expect(
+      statusFromPrinterMib(mib({ printerStatus: 99 })).details?.find(
+        d => d.label === 'Printer state',
+      )?.value,
+    ).toBe('unknown');
+  });
+
+  it.each([
+    [1, 'no_media', 'No media'],
+    [4, 'cover_open', 'Cover open'],
+    [5, 'cutter_jam', 'Jammed'],
+    [6, 'not_ready', 'Offline'],
+    [7, 'system_error', 'Service requested'],
+    [13, 'no_media', 'Input tray empty'],
+    [8, 'system_error', 'inputTrayMissing'],
+    [14, 'system_error', 'overduePreventMaint'],
+  ])('error-state bit %i → %s', (bit, code, message) => {
+    const status = statusFromPrinterMib(mib({ errorState: errorBits(bit) }));
+    expect(status.errors).toEqual([{ code, message }]);
+    expect(status.ready).toBe(false);
+  });
+
+  it('lowPaper is a warning row, not an error', () => {
+    const status = statusFromPrinterMib(mib({ errorState: errorBits(0) }));
+    expect(status.errors).toEqual([]);
+    expect(status.ready).toBe(true);
+    expect(status.details).toContainEqual({ label: 'Media', value: 'Media low', severity: 'warn' });
+  });
+
+  it('reads error state from 0, 1 and 2 octets', () => {
+    expect(statusFromPrinterMib(mib({ errorState: new Uint8Array(0) })).errors).toEqual([]);
+    expect(statusFromPrinterMib(mib({ errorState: new Uint8Array([0x08]) })).errors).toEqual([
+      { code: 'cover_open', message: 'Cover open' },
+    ]);
+    expect(statusFromPrinterMib(mib({ errorState: new Uint8Array([0x00, 0x04]) })).errors).toEqual([
+      { code: 'no_media', message: 'Input tray empty' },
+    ]);
+  });
+
+  it('the name wins over Dim OIDs (bench: unit 4 claimed, 1/100 mm sent)', () => {
+    const status = statusFromPrinterMib(
+      mib({ mediaName: DK_11201_NAME, xFeedDir: 2900, feedDir: 9000, dimUnit: 4 }),
+    );
+    expect(status.detectedMedia?.id).toBe(271);
+  });
+
+  it('falls back to Dim OIDs in ten-thousandths of an inch (unit 3)', () => {
+    // 29 mm = 11417, 90 mm = 35433 ten-thousandths of an inch.
+    const status = statusFromPrinterMib(
+      mib({ mediaName: 'nonsense', xFeedDir: 11417, feedDir: 35433, dimUnit: 3 }),
+    );
+    expect(status.detectedMedia?.id).toBe(271);
+  });
+
+  it('falls back to Dim OIDs in micrometres (unit 4)', () => {
+    const status = statusFromPrinterMib(
+      mib({ mediaName: 'nonsense', xFeedDir: 62000, feedDir: -1, dimUnit: 4 }),
+    );
+    expect(status.detectedMedia?.id).toBe(259);
+  });
+
+  it('no media when the name is unparseable and the Dim OIDs are negative or unitless', () => {
+    expect(
+      statusFromPrinterMib(mib({ mediaName: 'nonsense', xFeedDir: -1, feedDir: -1, dimUnit: 3 }))
+        .detectedMedia,
+    ).toBeUndefined();
+    expect(
+      statusFromPrinterMib(mib({ mediaName: 'nonsense', xFeedDir: 11417, feedDir: 35433 }))
+        .detectedMedia,
+    ).toBeUndefined();
+    // RFC 3805 only defines 3 and 4; anything else is not converted.
+    expect(
+      statusFromPrinterMib(
+        mib({ mediaName: 'nonsense', xFeedDir: 11417, feedDir: 35433, dimUnit: 1 }),
+      ).detectedMedia,
+    ).toBeUndefined();
+  });
+
+  it('unrecognised media name → no media, warn row with the raw string', () => {
+    const status = statusFromPrinterMib(mib({ mediaName: 'Roll 62' }));
+    expect(status.mediaLoaded).toBe(false);
+    expect(status.detectedMedia).toBeUndefined();
+    expect(status.details).toContainEqual({
+      label: 'Media',
+      value: 'not recognised: "Roll 62"',
+      severity: 'warn',
+    });
+    expect(status.ready).toBe(true);
+  });
+
+  it('a recognised size with no registry entry → warn row, no media', () => {
+    const status = statusFromPrinterMib(mib({ mediaName: '99mm x 99mm / x' }));
+    expect(status.detectedMedia).toBeUndefined();
+    expect(status.details?.some(d => d.value.startsWith('not recognised'))).toBe(true);
+  });
+});

package/src/__tests__/protocol.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect } from 'vitest';
-import { createBitmap } from '@mbtech-nl/bitmap';
+import { createBitmap, type LabelBitmap } from '@mbtech-nl/bitmap';
 import {
   buildInvalidate,
   buildInitialize,
@@ -16,7 +16,7 @@ import {
   encodeJobForEngine,
   type EncoderEngine,
 } from '../protocol.js';
-import type { PageData } from '../types.js';
+import type { BrotherQLMedia, PageData } from '../types.js';
 import { MEDIA } from '../media.js';
 
 describe('buildInvalidate', () => {
@@ -494,3 +494,130 @@ describe('encodeJob legacy entry point — back compat', () => {
     expect(out[204]).toBe(0x1b);
   });
 });
+
+describe('die-cut page length (reference §2.3.2(b), §2.3.3, §2.3.4)', () => {
+  const DK_29X90 = MEDIA[271]!; // print area length 991 dots
+  const DK_62MM = MEDIA[259]!;
+  const QL_ENGINE: EncoderEngine = {
+    protocol: 'ql-raster',
+    headDots: 720,
+    capabilities: { autocut: true, mediaDetection: true },
+  };
+
+  /** Bitmap with every pixel of one row set, so the row is recognisable on the wire. */
+  function bitmapWithBlackRow(widthPx: number, heightPx: number, row: number): LabelBitmap {
+    const bitmap = createBitmap(widthPx, heightPx);
+    const bytesPerRow = Math.ceil(widthPx / 8);
+    bitmap.data.fill(0xff, row * bytesPerRow, (row + 1) * bytesPerRow);
+    return bitmap;
+  }
+
+  function findCmd(buf: Uint8Array, third: number): number {
+    for (let i = 0; i < buf.length - 4; i++) {
+      if (buf[i] === 0x1b && buf[i + 1] === 0x69 && buf[i + 2] === third) return i;
+    }
+    return -1;
+  }
+  const rasterNumber = (buf: Uint8Array): number => {
+    const i = findCmd(buf, 0x7a);
+    return (buf[i + 7] ?? 0) | ((buf[i + 8] ?? 0) << 8);
+  };
+  const marginDots = (buf: Uint8Array): number => {
+    const i = findCmd(buf, 0x64);
+    return (buf[i + 3] ?? 0) | ((buf[i + 4] ?? 0) << 8);
+  };
+  /** Raster rows as [opcode, colour, payload] triples, in wire order. */
+  function rasterRows(buf: Uint8Array): { op: number; color: number; payload: Uint8Array }[] {
+    const rows = [];
+    // Rows start after ESC i d (5 bytes) and run until the print command.
+    let i = findCmd(buf, 0x64) + 5;
+    while (i < buf.length && (buf[i] === 0x67 || buf[i] === 0x77)) {
+      const len = buf[i + 2] ?? 0;
+      rows.push({ op: buf[i]!, color: buf[i + 1]!, payload: buf.subarray(i + 3, i + 3 + len) });
+      i += 3 + len;
+    }
+    return rows;
+  }
+
+  it('sends the print-area length as the raster number and margin 0 on DK-11201', () => {
+    const bitmap = createBitmap(306, 608);
+    const out = encodeJobForEngine([{ bitmap, media: DK_29X90 }], {}, QL_ENGINE);
+    expect(rasterNumber(out)).toBe(991);
+    expect(marginDots(out)).toBe(0);
+    expect(rasterRows(out)).toHaveLength(991);
+  });
+
+  it('ignores marginDots on die-cut media', () => {
+    const bitmap = createBitmap(306, 10);
+    const out = encodeJobForEngine(
+      [{ bitmap, media: DK_29X90, options: { marginDots: 100 } }],
+      {},
+      QL_ENGINE,
+    );
+    expect(marginDots(out)).toBe(0);
+  });
+
+  it('centres the bitmap in the page', () => {
+    const bitmap = bitmapWithBlackRow(306, 3, 1);
+    const out = encodeJobForEngine([{ bitmap, media: DK_29X90 }], {}, QL_ENGINE);
+    const rows = rasterRows(out);
+    const black = rows.map((r, i) => (r.payload.some(b => b !== 0) ? i : -1)).filter(i => i >= 0);
+    // padTop = floor((991 - 3) / 2) = 494; the black row is bitmap row 1.
+    expect(black).toEqual([495]);
+  });
+
+  it('doubles the page length when QL high-res rows are supplied', () => {
+    const bitmap = createBitmap(306, 100);
+    const out = encodeJob([{ bitmap, media: DK_29X90, options: { highResolution: true } }]);
+    expect(rasterNumber(out)).toBe(1982);
+    expect(rasterRows(out)).toHaveLength(1982);
+    expect(marginDots(out)).toBe(0);
+  });
+
+  it('rejects a bitmap taller than the page, naming both numbers', () => {
+    const bitmap = createBitmap(306, 1200);
+    expect(() => encodeJobForEngine([{ bitmap, media: DK_29X90 }], {}, QL_ENGINE)).toThrow(
+      /1200 rows.*exactly 991/,
+    );
+  });
+
+  it('pads both planes alike on two-colour die-cut', () => {
+    const bitmap = bitmapWithBlackRow(306, 3, 1);
+    const redBitmap = bitmapWithBlackRow(306, 3, 1);
+    const out = encodeJobForEngine([{ bitmap, redBitmap, media: DK_29X90 }], {}, QL_ENGINE);
+    const rows = rasterRows(out);
+    expect(rows).toHaveLength(991 * 2);
+    const inked = rows
+      .map((r, i) => (r.payload.some(b => b !== 0) ? { i, color: r.color } : undefined))
+      .filter(r => r !== undefined);
+    expect(inked).toEqual([
+      { i: 495 * 2, color: 0x01 },
+      { i: 495 * 2 + 1, color: 0x02 },
+    ]);
+  });
+
+  it('throws when a die-cut entry lacks dieCutMaskedAreaDots', () => {
+    const media: BrotherQLMedia = { ...DK_29X90 };
+    delete media.dieCutMaskedAreaDots;
+    const bitmap = createBitmap(306, 10);
+    expect(() => encodeJobForEngine([{ bitmap, media }], {}, QL_ENGINE)).toThrow(
+      /dieCutMaskedAreaDots/,
+    );
+  });
+
+  it('leaves the continuous path byte-identical', async () => {
+    const { createHash } = await import('node:crypto');
+    const bitmap = bitmapWithBlackRow(696, 40, 7);
+    const out = encodeJobForEngine(
+      [{ bitmap, media: DK_62MM, options: { marginDots: 50 } }],
+      { copies: 2 },
+      QL_ENGINE,
+    );
+    expect(rasterNumber(out)).toBe(40);
+    expect(marginDots(out)).toBe(50);
+    // Digest recorded from the encoder before die-cut padding existed.
+    expect(createHash('sha256').update(out).digest('hex')).toBe(
+      'ebc2b5f467faca133f0f72c6f3123671d4e4dc130f2dd8cad8d9a69fa50e95fc',
+    );
+  });
+});

package/src/__tests__/status.test.ts

@@ -18,7 +18,8 @@ function makeStatusBytes(
   bytes[0] = 0x80;
   bytes[1] = 0x20;
   bytes[2] = 0x42;
-  bytes[3] = 0x30;
+  bytes[3] = 0x34;
+  bytes[4] = 0x41;
   bytes[8] = overrides?.errInfo1 ?? 0;
   bytes[9] = overrides?.errInfo2 ?? 0;
   bytes[10] = overrides?.mediaWidthMm ?? 62;
@@ -150,6 +151,18 @@ describe('parseStatus', () => {
 });
 
 describe('parseStatus — details[]', () => {
+  it('model-code row renders bytes 3/4 as ASCII (4A = QL-820NWB capture)', () => {
+    const status = parseStatus(CAPTURE_DK_22205);
+    expect(status.details?.[0]).toEqual({ label: 'Model code', value: '4A' });
+  });
+
+  it('model-code row falls back to hex for unprintable bytes', () => {
+    const bytes = makeStatusBytes();
+    bytes[3] = 0x00;
+    bytes[4] = 0x41;
+    expect(parseStatus(bytes).details?.[0]?.value).toBe('0x00 0x41');
+  });
+
   it('always emits a Print phase row', () => {
     const status = parseStatus(makeStatusBytes());
     expect(status.details).toBeDefined();
@@ -196,6 +209,7 @@ describe('parseStatus — details[]', () => {
   it('details carries both phase and cooling rows while printing + cooling', () => {
     const status = parseStatus(makeStatusBytes({ phaseType: 0x01, notification: 0x03 }));
     expect(status.details).toEqual([
+      { label: 'Model code', value: '4A' },
       { label: 'Print phase', value: 'printing' },
       { label: 'Head cooling', value: 'cooling started', severity: 'warn' },
     ]);

package/src/devices.generated.ts

@@ -251,7 +251,7 @@ export const REGISTRY = {
       "transports": {
         "usb": {
           "vid": "0x04f9",
-          "pid": "0x2027"
+          "pid": "0x2020"
         }
       },
       "engines": [
@@ -282,7 +282,7 @@ export const REGISTRY = {
       "transports": {
         "usb": {
           "vid": "0x04f9",
-          "pid": "0x2028"
+          "pid": "0x202a"
         },
         "tcp": {
           "port": 9100
@@ -427,7 +427,7 @@ export const REGISTRY = {
       "transports": {
         "usb": {
           "vid": "0x04f9",
-          "pid": "0x2013"
+          "pid": "0x2015"
         }
       },
       "engines": [
@@ -485,7 +485,7 @@ export const REGISTRY = {
       "transports": {
         "usb": {
           "vid": "0x04f9",
-          "pid": "0x2018"
+          "pid": "0x2027"
         }
       },
       "engines": [
@@ -515,7 +515,7 @@ export const REGISTRY = {
       "transports": {
         "usb": {
           "vid": "0x04f9",
-          "pid": "0x2019"
+          "pid": "0x2028"
         }
       },
       "engines": [
@@ -545,7 +545,7 @@ export const REGISTRY = {
       "transports": {
         "usb": {
           "vid": "0x04f9",
-          "pid": "0x201b"
+          "pid": "0x2029"
         },
         "tcp": {
           "port": 9100
@@ -578,7 +578,7 @@ export const REGISTRY = {
       "transports": {
         "usb": {
           "vid": "0x04f9",
-          "pid": "0x2100"
+          "pid": "0x20c0"
         }
       },
       "engines": [
@@ -608,7 +608,7 @@ export const REGISTRY = {
       "transports": {
         "usb": {
           "vid": "0x04f9",
-          "pid": "0x201c"
+          "pid": "0x201b"
         }
       },
       "engines": [
@@ -674,7 +674,7 @@ export const REGISTRY = {
             "date": "2026-05-21",
             "result": "verified",
             "os": "Windows",
-            "notes": "WebUSB on Edge 148 / Windows 11, 62mm continuous (DK-22205). Pre- and post-print status clean: no errors, phase advanced to printing."
+            "notes": "WebUSB on Edge 148 / Windows 11 with DK-22205, clean status and phase advancing to printing."
           }
         ]
       },
@@ -687,7 +687,7 @@ export const REGISTRY = {
       "transports": {
         "usb": {
           "vid": "0x04f9",
-          "pid": "0x2044"
+          "pid": "0x2043"
         },
         "tcp": {
           "port": 9100
@@ -723,7 +723,7 @@ export const REGISTRY = {
       "transports": {
         "usb": {
           "vid": "0x04f9",
-          "pid": "0x2045"
+          "pid": "0x2044"
         },
         "tcp": {
           "port": 9100
@@ -745,9 +745,24 @@ export const REGISTRY = {
         }
       ],
       "support": {
-        "status": "untested"
+        "status": "verified",
+        "transports": {
+          "usb": "verified"
+        },
+        "lastVerified": "2026-09-19",
+        "packageVersion": "0.6.1",
+        "reports": [
+          {
+            "issue": 10,
+            "reporter": "@viktis",
+            "date": "2026-09-19",
+            "result": "verified",
+            "os": "macOS",
+            "notes": "WebUSB on Chromium 152 / macOS with DK-22205, clean status and phase advancing to printing; filed as QL-710W because of the PID mix-up fixed in #11."
+          }
+        ]
       },
-      "supportStatus": "expected"
+      "supportStatus": "verified"
     },
     {
       "key": "QL_800",
@@ -792,7 +807,7 @@ export const REGISTRY = {
             "date": "2026-05-22",
             "result": "verified",
             "os": "Windows",
-            "notes": "QL-800 USB print confirmed (reporter produced output). The report revealed the DK continuous margins were stored right-registered, parking the printable area off the left-seated paper; the left-registration fix (leftMarginPins=6 for 29mm) merged in PR #3 and shipped in 0.6.1."
+            "notes": "USB print confirmed on Windows; the report exposed right-registered DK continuous margins, fixed in PR #3 and shipped in 0.6.1."
           }
         ]
       },
@@ -838,6 +853,10 @@ export const REGISTRY = {
     {
       "key": "QL_820NWBc",
       "name": "QL-820NWBc",
+      "modelNames": [
+        "QL-820NWB",
+        "QL-820NWBc"
+      ],
       "family": "brother-ql",
       "transports": {
         "usb": {
@@ -878,18 +897,17 @@ export const REGISTRY = {
           "tcp": "verified",
           "bluetooth-spp": "untested"
         },
-        "lastVerified": "2026-04-27",
-        "packageVersion": "0.2.1",
-        "quirks": "Reference test device. Two-colour printing on DK-22251 confirmed, auto-cut works on USB and TCP, WebUSB demo prints correctly. The QL-820NWB and QL-820NWBc share PID 0x209d; this entry covers both marketing names.",
+        "lastVerified": "2026-08-25",
+        "packageVersion": "0.6.1",
+        "quirks": "Maintainer bench reference device (Linux): two-colour printing on DK-22251 confirmed, auto-cut works on USB and TCP. The QL-820NWB and QL-820NWBc share PID 0x209d; this entry covers both marketing names.",
         "reports": [
           {
-            "issue": 0,
-            "reporter": "@mannes",
-            "date": "2026-04-27",
+            "issue": 6,
+            "reporter": "@BrettJackson1987",
+            "date": "2026-08-25",
             "result": "verified",
-            "os": "Linux",
-            "selfVerified": true,
-            "notes": "Bench verification by the maintainer at the time of seeding this entry. Issue #0 is a placeholder — replace with the real issue number when a public verification report is filed."
+            "os": "macOS",
+            "notes": "WebUSB on Chromium 150 / macOS with DK-22251 two-colour, clean status with the two-colour flag set and phase advancing to printing."
           }
         ]
       },

package/src/devices.ts

@@ -6,18 +6,6 @@ import { DEVICES, REGISTRY } from './devices.generated.js';
 // labelwriter-aligned `REGISTRY` symbol.
 export const DEVICE_REGISTRY = REGISTRY;
 
-// Mass-storage PIDs aligned to Linux usb-ids (gowdy.us / linux-usb.org).
-// Each large-format printer with Editor Lite enumerates as USB Mass
-// Storage Class on this alternate PID until the user holds the Editor
-// Lite button to switch back to printer-class. Aggregated from each
-// device entry's `capabilities.massStoragePid`.
-const MASS_STORAGE_PIDS = new Set<number>(
-  Object.values(DEVICES).flatMap(d => {
-    const pid = d.capabilities?.massStoragePid;
-    return typeof pid === 'string' ? [parseInt(pid, 16)] : [];
-  }),
-);
-
 export { DEVICES };
 
 /**
@@ -39,7 +27,3 @@ export function findDevice(vid: number, pid: number): BrotherQLDevice | undefine
     return ids?.vid === vid && ids.pid === pid;
   });
 }
-
-export function isMassStorageMode(pid: number): boolean {
-  return MASS_STORAGE_PIDS.has(pid);
-}

package/src/index.ts

@@ -33,7 +33,7 @@ export {
   UnsupportedOperationError,
 } from '@thermal-label/contracts';
 
-export { DEVICE_REGISTRY, DEVICES, findDevice, getUsbIds, isMassStorageMode } from './devices.js';
+export { DEVICE_REGISTRY, DEVICES, findDevice, getUsbIds } from './devices.js';
 
 /**
  * Protocols this core's encoder produces correct wire bytes for.
@@ -63,6 +63,8 @@ export {
 } from './protocol.js';
 export type { EncoderEngine, RasterProtocolConfig } from './protocol.js';
 export { parseStatus, STATUS_REQUEST } from './status.js';
+export { hasTwoColourSibling, parseMediaName, statusFromPrinterMib } from './network-status.js';
+export type { PrinterMibStatus } from './network-status.js';
 export { createPreviewOffline } from './preview.js';
 
 export type {