@thermal-label/brother-ql-core 0.0.1 → 0.2.1

package/dist/types.d.ts

@@ -1,39 +1,65 @@
 import { type LabelBitmap } from '@mbtech-nl/bitmap';
+import type { DeviceDescriptor, MediaDescriptor, PrinterStatus } from '@thermal-label/contracts';
 export type MediaType = 'continuous' | 'die-cut';
 export type HeadWidth = 720 | 1296;
 export type ColorMode = 'single' | 'two-color';
 export type NetworkSupport = 'none' | 'wifi' | 'wired' | 'wifi+wired';
-export interface DeviceDescriptor {
-    name: string;
+/**
+ * Brother QL device descriptor.
+ *
+ * Extends the contracts base with QL-specific fields: head geometry,
+ * protocol feature flags, and the optional mass-storage PID for Editor
+ * Lite mode.
+ *
+ * **Bluetooth on the QL-820NWB / 820NWBc**: not exposed over GATT.
+ * Classic Bluetooth (SPP) is paired at the OS level; the kernel/driver
+ * exposes an RFCOMM serial port, reachable via the `'serial'` transport
+ * in Node.js and the `'web-serial'` transport in Chrome/Edge. macOS has
+ * dropped classic Bluetooth SPP — no serial route there.
+ */
+export interface BrotherQLDevice extends DeviceDescriptor {
+    family: 'brother-ql';
     vid: number;
     pid: number;
     headPins: HeadWidth;
     bytesPerRow: number;
     twoColor: boolean;
     network: NetworkSupport;
-    bluetooth: boolean;
     autocut: boolean;
     compression: boolean;
     editorLite: boolean;
+    /** Alternate PID seen when the printer is in Editor Lite mass-storage mode. */
     massStoragePid?: number;
 }
-export interface MediaDescriptor {
+/**
+ * Brother QL media descriptor.
+ *
+ * Extends `MediaDescriptor` with the dots-based geometry the raster
+ * encoder needs. `colorCapable: true` flips the driver into
+ * two-colour mode — only DK-22251 has this set in the registry.
+ */
+export interface BrotherQLMedia extends MediaDescriptor {
     id: number;
-    name: string;
     type: MediaType;
-    widthMm: number;
-    lengthMm: number;
+    colorCapable: boolean;
     printAreaDots: number;
     leftMarginPins: number;
     rightMarginPins: number;
+    /** Die-cut masked area in dots (registration windows). */
     dieCutMaskedAreaDots?: number;
-    /** True for DK-22251 and similar two-color tapes — printer rejects single-color jobs */
-    twoColorTape?: boolean;
+}
+/**
+ * Brother QL status — contracts `PrinterStatus` plus the
+ * `editorLiteMode` flag (pre-paired QL-820NWB silently drops raster
+ * jobs when in Editor Lite mode; callers need to know).
+ */
+export interface BrotherQLStatus extends PrinterStatus {
+    editorLiteMode: boolean;
 }
 export interface PageData {
     bitmap: LabelBitmap;
     redBitmap?: LabelBitmap;
-    media: MediaDescriptor;
+    media: BrotherQLMedia;
     options?: PageOptions;
 }
 export interface PageOptions {
@@ -46,24 +72,4 @@ export interface PageOptions {
 export interface JobOptions {
     copies?: number;
 }
-export interface TextPrintOptions extends PageOptions {
-    invert?: boolean;
-    scaleX?: number;
-    scaleY?: number;
-}
-export interface ImagePrintOptions extends PageOptions {
-    threshold?: number;
-    dither?: boolean;
-    invert?: boolean;
-    rotate?: 0 | 90 | 180 | 270;
-}
-export interface PrinterStatus {
-    ready: boolean;
-    mediaWidthMm: number;
-    mediaLengthMm: number;
-    mediaType: MediaType | null;
-    errors: string[];
-    editorLiteMode: boolean;
-    rawBytes: Uint8Array;
-}
 //# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAErD,MAAM,MAAM,SAAS,GAAG,YAAY,GAAG,SAAS,CAAC;AACjD,MAAM,MAAM,SAAS,GAAG,GAAG,GAAG,IAAI,CAAC;AACnC,MAAM,MAAM,SAAS,GAAG,QAAQ,GAAG,WAAW,CAAC;AAC/C,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,YAAY,CAAC;AAEtE,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,SAAS,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,OAAO,CAAC;IAClB,OAAO,EAAE,cAAc,CAAC;IACxB,SAAS,EAAE,OAAO,CAAC;IACnB,OAAO,EAAE,OAAO,CAAC;IACjB,WAAW,EAAE,OAAO,CAAC;IACrB,UAAU,EAAE,OAAO,CAAC;IACpB,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,SAAS,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,EAAE,MAAM,CAAC;IACvB,eAAe,EAAE,MAAM,CAAC;IACxB,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,wFAAwF;IACxF,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,QAAQ;IACvB,MAAM,EAAE,WAAW,CAAC;IACpB,SAAS,CAAC,EAAE,WAAW,CAAC;IACxB,KAAK,EAAE,eAAe,CAAC;IACvB,OAAO,CAAC,EAAE,WAAW,CAAC;CACvB;AAED,MAAM,WAAW,WAAW;IAC1B,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,UAAU;IACzB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,gBAAiB,SAAQ,WAAW;IACnD,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,iBAAkB,SAAQ,WAAW;IACpD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,CAAC,GAAG,EAAE,GAAG,GAAG,GAAG,GAAG,CAAC;CAC7B;AAED,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,OAAO,CAAC;IACf,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,SAAS,EAAE,SAAS,GAAG,IAAI,CAAC;IAC5B,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,cAAc,EAAE,OAAO,CAAC;IACxB,QAAQ,EAAE,UAAU,CAAC;CACtB"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAEjG,MAAM,MAAM,SAAS,GAAG,YAAY,GAAG,SAAS,CAAC;AACjD,MAAM,MAAM,SAAS,GAAG,GAAG,GAAG,IAAI,CAAC;AACnC,MAAM,MAAM,SAAS,GAAG,QAAQ,GAAG,WAAW,CAAC;AAC/C,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,YAAY,CAAC;AAEtE;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,eAAgB,SAAQ,gBAAgB;IACvD,MAAM,EAAE,YAAY,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,SAAS,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,OAAO,CAAC;IAClB,OAAO,EAAE,cAAc,CAAC;IACxB,OAAO,EAAE,OAAO,CAAC;IACjB,WAAW,EAAE,OAAO,CAAC;IACrB,UAAU,EAAE,OAAO,CAAC;IACpB,+EAA+E;IAC/E,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,cAAe,SAAQ,eAAe;IACrD,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,SAAS,CAAC;IAChB,YAAY,EAAE,OAAO,CAAC;IACtB,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,EAAE,MAAM,CAAC;IACvB,eAAe,EAAE,MAAM,CAAC;IACxB,0DAA0D;IAC1D,oBAAoB,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED;;;;GAIG;AACH,MAAM,WAAW,eAAgB,SAAQ,aAAa;IACpD,cAAc,EAAE,OAAO,CAAC;CACzB;AAED,MAAM,WAAW,QAAQ;IACvB,MAAM,EAAE,WAAW,CAAC;IACpB,SAAS,CAAC,EAAE,WAAW,CAAC;IACxB,KAAK,EAAE,cAAc,CAAC;IACtB,OAAO,CAAC,EAAE,WAAW,CAAC;CACvB;AAED,MAAM,WAAW,WAAW;IAC1B,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,UAAU;IACzB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB"}

package/dist/types.js

@@ -1,2 +1,3 @@
+/* eslint-disable import-x/consistent-type-specifier-style */
 import {} from '@mbtech-nl/bitmap';
 //# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAoB,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,6DAA6D;AAC7D,OAAO,EAAoB,MAAM,mBAAmB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thermal-label/brother-ql-core",
-  "version": "0.0.1",
+  "version": "0.2.1",
   "description": "Protocol encoding, device registry, and media registry for Brother QL label printers",
   "keywords": [
     "brother",
@@ -53,7 +53,8 @@
     }
   },
   "dependencies": {
-    "@mbtech-nl/bitmap": "^0.1.0"
+    "@mbtech-nl/bitmap": "^0.1.0",
+    "@thermal-label/contracts": "^0.1.2"
   },
   "devDependencies": {
     "@mbtech-nl/tsconfig": "^1.0.0",

package/src/__tests__/colour.test.ts

@@ -0,0 +1,126 @@
+import { describe, expect, it } from 'vitest';
+import { getPixel } from '@mbtech-nl/bitmap';
+import { isRedish, splitTwoColor } from '../colour.js';
+
+function rgbaOf(
+  width: number,
+  height: number,
+  [r, g, b, a]: [number, number, number, number],
+): {
+  width: number;
+  height: number;
+  data: Uint8Array;
+} {
+  const data = new Uint8Array(width * height * 4);
+  for (let i = 0; i < data.length; i += 4) {
+    data[i] = r;
+    data[i + 1] = g;
+    data[i + 2] = b;
+    data[i + 3] = a;
+  }
+  return { width, height, data };
+}
+
+function countInkPixels(bitmap: { widthPx: number; heightPx: number; data: Uint8Array }): number {
+  let n = 0;
+  for (let y = 0; y < bitmap.heightPx; y++) {
+    for (let x = 0; x < bitmap.widthPx; x++) {
+      if (getPixel(bitmap, x, y)) n++;
+    }
+  }
+  return n;
+}
+
+describe('isRedish', () => {
+  it('treats a strong red as red', () => {
+    expect(isRedish(255, 0, 0, 255)).toBe(true);
+  });
+
+  it('rejects red when green is too high (threshold g < 100)', () => {
+    expect(isRedish(255, 100, 0, 255)).toBe(false);
+    expect(isRedish(255, 99, 0, 255)).toBe(true);
+  });
+
+  it('rejects red when blue is too high (threshold b < 100)', () => {
+    expect(isRedish(255, 0, 100, 255)).toBe(false);
+    expect(isRedish(255, 0, 99, 255)).toBe(true);
+  });
+
+  it('rejects red when the red channel is too low (threshold r > 180)', () => {
+    expect(isRedish(180, 0, 0, 255)).toBe(false);
+    expect(isRedish(181, 0, 0, 255)).toBe(true);
+  });
+
+  it('rejects transparent pixels (alpha < 128)', () => {
+    expect(isRedish(255, 0, 0, 127)).toBe(false);
+    expect(isRedish(255, 0, 0, 128)).toBe(true);
+  });
+
+  it('rejects black (no red dominance)', () => {
+    expect(isRedish(0, 0, 0, 255)).toBe(false);
+  });
+
+  it('rejects white', () => {
+    expect(isRedish(255, 255, 255, 255)).toBe(false);
+  });
+});
+
+describe('splitTwoColor', () => {
+  it('routes a solid red image to the red plane, nothing to black', () => {
+    const { black, red } = splitTwoColor(rgbaOf(8, 8, [255, 0, 0, 255]));
+    expect(countInkPixels(red)).toBeGreaterThan(0);
+    expect(countInkPixels(black)).toBe(0);
+  });
+
+  it('routes a solid black image to the black plane, nothing to red', () => {
+    const { black, red } = splitTwoColor(rgbaOf(8, 8, [0, 0, 0, 255]));
+    expect(countInkPixels(black)).toBeGreaterThan(0);
+    expect(countInkPixels(red)).toBe(0);
+  });
+
+  it('produces bitmaps matching the source dimensions', () => {
+    const { black, red } = splitTwoColor(rgbaOf(16, 12, [128, 128, 128, 255]));
+    expect(black.widthPx).toBe(16);
+    expect(black.heightPx).toBe(12);
+    expect(red.widthPx).toBe(16);
+    expect(red.heightPx).toBe(12);
+  });
+
+  it('resolves overlapping bits in favour of black (red bit cleared)', () => {
+    // Construct a mixed image: one row red, one row black.
+    const data = new Uint8Array(8 * 2 * 4);
+    // Row 0: red
+    for (let i = 0; i < 8; i++) {
+      data[i * 4] = 255;
+      data[i * 4 + 3] = 255;
+    }
+    // Row 1: black
+    for (let i = 0; i < 8; i++) {
+      const offset = (8 + i) * 4;
+      data[offset] = 0;
+      data[offset + 1] = 0;
+      data[offset + 2] = 0;
+      data[offset + 3] = 255;
+    }
+    const image = { width: 8, height: 2, data };
+    const { black, red } = splitTwoColor(image);
+    // Every non-transparent pixel should land on exactly one plane —
+    // resolveOverlap guarantees no bit is set in both.
+    for (let y = 0; y < 2; y++) {
+      for (let x = 0; x < 8; x++) {
+        const inBlack = getPixel(black, x, y);
+        const inRed = getPixel(red, x, y);
+        expect(inBlack && inRed).toBe(false);
+      }
+    }
+  });
+
+  it('accepts custom threshold + dither options', () => {
+    const { black, red } = splitTwoColor(rgbaOf(4, 4, [0, 0, 0, 255]), {
+      threshold: 64,
+      dither: false,
+    });
+    expect(black.widthPx).toBe(4);
+    expect(red.widthPx).toBe(4);
+  });
+});

package/src/__tests__/devices.test.ts

@@ -65,9 +65,25 @@ describe('Device registry invariants', () => {
     }
   });
 
-  it('every device has bluetooth: false (BT out of scope)', () => {
+  it('every device belongs to the brother-ql family', () => {
     for (const dev of Object.values(DEVICES)) {
-      expect(dev.bluetooth).toBe(false);
+      expect(dev.family).toBe('brother-ql');
+    }
+  });
+
+  it('QL-820NWB(c) advertise serial/web-serial for OS-paired Bluetooth', () => {
+    for (const key of ['QL_820NWB', 'QL_820NWBc'] as const) {
+      const dev = DEVICES[key];
+      expect(dev.transports).toContain('serial');
+      expect(dev.transports).toContain('web-serial');
+    }
+  });
+
+  it('no device descriptor declares web-bluetooth', () => {
+    // Bluetooth on the 820 series is classic SPP, not GATT — the
+    // serial transports cover it. See packages/core/src/types.ts.
+    for (const dev of Object.values(DEVICES)) {
+      expect(dev.transports).not.toContain('web-bluetooth');
     }
   });
 });

package/src/__tests__/media.test.ts

@@ -7,14 +7,14 @@ describe('findMedia', () => {
     expect(m).toBeDefined();
     expect(m!.widthMm).toBe(62);
     expect(m!.type).toBe('continuous');
-    expect(m!.lengthMm).toBe(0);
+    expect(m!.heightMm).toBeUndefined();
   });
 
   it('returns correct descriptor for 62x29mm die-cut (ID 274)', () => {
     const m = findMedia(274);
     expect(m).toBeDefined();
     expect(m!.type).toBe('die-cut');
-    expect(m!.lengthMm).toBeGreaterThan(0);
+    expect(m!.heightMm).toBe(29);
   });
 
   it('returns undefined for unknown ID', () => {
@@ -46,18 +46,29 @@ describe('findMediaByWidth', () => {
 });
 
 describe('Media registry invariants', () => {
-  it('die-cut media has non-zero lengthMm', () => {
+  it('die-cut media has a heightMm', () => {
     for (const m of Object.values(MEDIA)) {
       if (m.type === 'die-cut') {
-        expect(m.lengthMm).toBeGreaterThan(0);
+        expect(m.heightMm).toBeDefined();
+        expect(m.heightMm!).toBeGreaterThan(0);
       }
     }
   });
 
-  it('continuous media has lengthMm === 0', () => {
+  it('continuous media omits heightMm', () => {
     for (const m of Object.values(MEDIA)) {
       if (m.type === 'continuous') {
-        expect(m.lengthMm).toBe(0);
+        expect(m.heightMm).toBeUndefined();
+      }
+    }
+  });
+
+  it('only DK-22251 is colorCapable', () => {
+    for (const m of Object.values(MEDIA)) {
+      if (m.id === 251) {
+        expect(m.colorCapable).toBe(true);
+      } else {
+        expect(m.colorCapable).toBe(false);
       }
     }
   });

package/src/__tests__/preview.test.ts

@@ -0,0 +1,52 @@
+import { describe, expect, it } from 'vitest';
+import { MEDIA } from '../media.js';
+import { createPreviewOffline } from '../preview.js';
+
+function solidRgba(
+  width: number,
+  height: number,
+  rgba: [number, number, number, number],
+): {
+  width: number;
+  height: number;
+  data: Uint8Array;
+} {
+  const data = new Uint8Array(width * height * 4);
+  for (let i = 0; i < data.length; i += 4) {
+    data[i] = rgba[0];
+    data[i + 1] = rgba[1];
+    data[i + 2] = rgba[2];
+    data[i + 3] = rgba[3];
+  }
+  return { width, height, data };
+}
+
+describe('createPreviewOffline', () => {
+  it('returns a single black plane for single-colour media', () => {
+    const image = solidRgba(8, 8, [0, 0, 0, 255]);
+    const preview = createPreviewOffline(image, MEDIA[259]!);
+    expect(preview.planes).toHaveLength(1);
+    expect(preview.planes[0]!.name).toBe('black');
+    expect(preview.planes[0]!.displayColor).toBe('#000000');
+    expect(preview.media).toBe(MEDIA[259]);
+    expect(preview.assumed).toBe(false);
+  });
+
+  it('returns black + red planes for colorCapable media (DK-22251)', () => {
+    const image = solidRgba(8, 8, [255, 0, 0, 255]);
+    const preview = createPreviewOffline(image, MEDIA[251]!);
+    expect(preview.planes.map(p => p.name)).toEqual(['black', 'red']);
+    expect(preview.planes[1]!.displayColor).toBe('#ff0000');
+    expect(preview.media).toBe(MEDIA[251]);
+    expect(preview.assumed).toBe(false);
+  });
+
+  it('planes share the source image dimensions', () => {
+    const image = solidRgba(24, 12, [128, 128, 128, 255]);
+    const preview = createPreviewOffline(image, MEDIA[251]!);
+    for (const plane of preview.planes) {
+      expect(plane.bitmap.widthPx).toBe(24);
+      expect(plane.bitmap.heightPx).toBe(12);
+    }
+  });
+});

package/src/__tests__/status.test.ts

@@ -33,44 +33,53 @@ describe('parseStatus', () => {
   it('returns ready=true with no errors', () => {
     const status = parseStatus(makeStatusBytes());
     expect(status.ready).toBe(true);
-    expect(status.errors).toHaveLength(0);
+    expect(status.errors).toEqual([]);
   });
 
-  it('parses media width and type', () => {
+  it('resolves 62mm continuous to detectedMedia', () => {
     const status = parseStatus(makeStatusBytes({ mediaWidthMm: 62, mediaTypeByte: 0x0a }));
-    expect(status.mediaWidthMm).toBe(62);
-    expect(status.mediaType).toBe('continuous');
+    expect(status.mediaLoaded).toBe(true);
+    expect(status.detectedMedia?.id).toBe(259);
+    expect(status.detectedMedia?.widthMm).toBe(62);
+    expect(status.detectedMedia?.type).toBe('continuous');
   });
 
-  it('parses media length from byte 17 (0 for continuous, mm for die-cut)', () => {
-    const cont = parseStatus(makeStatusBytes({ mediaLengthMm: 0 }));
-    expect(cont.mediaLengthMm).toBe(0);
-    const diecut = parseStatus(makeStatusBytes({ mediaTypeByte: 0x0b, mediaLengthMm: 90 }));
-    expect(diecut.mediaLengthMm).toBe(90);
+  it('resolves 62x29mm die-cut to detectedMedia', () => {
+    const status = parseStatus(
+      makeStatusBytes({ mediaWidthMm: 62, mediaTypeByte: 0x0b, mediaLengthMm: 29 }),
+    );
+    expect(status.detectedMedia?.id).toBe(274);
+    expect(status.detectedMedia?.type).toBe('die-cut');
+    expect(status.detectedMedia?.heightMm).toBe(29);
   });
 
-  it('parses die-cut media type', () => {
-    const status = parseStatus(makeStatusBytes({ mediaTypeByte: 0x0b }));
-    expect(status.mediaType).toBe('die-cut');
+  it('leaves detectedMedia undefined for unknown media', () => {
+    const status = parseStatus(makeStatusBytes({ mediaWidthMm: 100, mediaTypeByte: 0x0a }));
+    expect(status.detectedMedia).toBeUndefined();
   });
 
-  it('returns null mediaType for unknown byte', () => {
-    const status = parseStatus(makeStatusBytes({ mediaTypeByte: 0xff }));
-    expect(status.mediaType).toBeNull();
+  it('leaves mediaLoaded=false when width is 0', () => {
+    const status = parseStatus(makeStatusBytes({ mediaWidthMm: 0, mediaTypeByte: 0 }));
+    expect(status.mediaLoaded).toBe(false);
   });
 
-  it('parses error info 1 bits', () => {
-    const status = parseStatus(makeStatusBytes({ errInfo1: 0b00000001 })); // No media
-    expect(status.errors).toContain('No media');
+  it('surfaces no_media error code for err1 bit 0', () => {
+    const status = parseStatus(makeStatusBytes({ errInfo1: 0b00000001 }));
+    expect(status.errors.map(e => e.code)).toContain('no_media');
     expect(status.ready).toBe(false);
   });
 
-  it('parses error info 2 bits', () => {
-    const status = parseStatus(makeStatusBytes({ errInfo2: 0b00010000 })); // Cover open
-    expect(status.errors).toContain('Cover open');
+  it('surfaces cover_open error code for err2 bit 4', () => {
+    const status = parseStatus(makeStatusBytes({ errInfo2: 0b00010000 }));
+    expect(status.errors.map(e => e.code)).toContain('cover_open');
     expect(status.ready).toBe(false);
   });
 
+  it('surfaces cutter_jam error code for err1 bit 2', () => {
+    const status = parseStatus(makeStatusBytes({ errInfo1: 0b00000100 }));
+    expect(status.errors.map(e => e.code)).toContain('cutter_jam');
+  });
+
   it('ready=false when statusType is error (0x02)', () => {
     const status = parseStatus(makeStatusBytes({ statusType: 0x02 }));
     expect(status.ready).toBe(false);
@@ -82,7 +91,7 @@ describe('parseStatus', () => {
     expect(status.rawBytes).toEqual(bytes);
   });
 
-  it('editorLiteMode is false (detected at discovery time, not from status bytes)', () => {
+  it('editorLiteMode is on the BrotherQLStatus extension', () => {
     const status = parseStatus(makeStatusBytes());
     expect(status.editorLiteMode).toBe(false);
   });

package/src/colour.ts

@@ -0,0 +1,101 @@
+/* eslint-disable @typescript-eslint/no-non-null-assertion --
+ *   Uint8Array indexed reads are typed `number | undefined` under
+ *   `noUncheckedIndexedAccess`, but every index in this file is bounded
+ *   by `src.length` (a multiple of 4) or `Math.min(a.length, b.length)`.
+ *   The `!` assertions collapse the unreachable `undefined` branches so
+ *   branch coverage doesn't count them. See also `non-nullable-type-
+ *   assertion-style` which rules out the alternative `as number` form.
+ */
+import { renderImage, type LabelBitmap, type RawImageData } from '@mbtech-nl/bitmap';
+
+export interface TwoColorResult {
+  black: LabelBitmap;
+  red: LabelBitmap;
+}
+
+export interface TwoColorOptions {
+  threshold?: number;
+  dither?: boolean;
+}
+
+/**
+ * A pixel is "red-ish" when the red channel clearly dominates and
+ * alpha is opaque enough to matter. The thresholds come from testing
+ * against DK-22251 output — wider tolerances let non-red warm tones
+ * bleed into the red plane.
+ */
+export function isRedish(r: number, g: number, b: number, a: number): boolean {
+  if (a < 128) return false;
+  return r > 180 && g < 100 && b < 100;
+}
+
+function extractRedPixels(image: RawImageData): RawImageData {
+  const src = image.data;
+  const dst = new Uint8Array(src.length);
+  for (let i = 0; i < src.length; i += 4) {
+    const r = src[i]!;
+    const g = src[i + 1]!;
+    const b = src[i + 2]!;
+    const a = src[i + 3]!;
+    if (isRedish(r, g, b, a)) {
+      dst[i] = r;
+      dst[i + 1] = g;
+      dst[i + 2] = b;
+      dst[i + 3] = a;
+    }
+  }
+  return { data: dst, width: image.width, height: image.height };
+}
+
+function extractNonRedPixels(image: RawImageData): RawImageData {
+  const src = image.data;
+  const dst = new Uint8Array(src.length);
+  for (let i = 0; i < src.length; i += 4) {
+    const r = src[i]!;
+    const g = src[i + 1]!;
+    const b = src[i + 2]!;
+    const a = src[i + 3]!;
+    if (!isRedish(r, g, b, a)) {
+      dst[i] = r;
+      dst[i + 1] = g;
+      dst[i + 2] = b;
+      dst[i + 3] = a;
+    }
+  }
+  return { data: dst, width: image.width, height: image.height };
+}
+
+/**
+ * Where both planes have a set bit at the same position, black wins.
+ * Done by masking the red bits with the inverse of the black bits.
+ */
+function resolveOverlap(black: LabelBitmap, red: LabelBitmap): void {
+  const blackData = black.data;
+  const redData = red.data;
+  const len = Math.min(blackData.length, redData.length);
+  for (let i = 0; i < len; i++) {
+    redData[i] = redData[i]! & ~blackData[i]!;
+  }
+}
+
+/**
+ * Split an RGBA image into black and red 1bpp planes for Brother QL
+ * two-colour media (DK-22251).
+ *
+ * The rendering path matches `renderImage(image, { dither: true })`
+ * used by `print()` for single-colour media, so overall print density
+ * stays consistent regardless of media.
+ */
+export function splitTwoColor(image: RawImageData, options?: TwoColorOptions): TwoColorResult {
+  const { threshold = 128, dither = true } = options ?? {};
+
+  const blackImage = extractNonRedPixels(image);
+  const redImage = extractRedPixels(image);
+
+  const black = renderImage(blackImage, { threshold, dither });
+  const red = renderImage(redImage, { threshold, dither });
+
+  resolveOverlap(black, red);
+
+  return { black, red };
+}