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

package/src/devices.ts

@@ -1,199 +1,214 @@
-import { type DeviceDescriptor } from './types.js';
+import { type BrotherQLDevice } from './types.js';
 
 const MASS_STORAGE_PIDS = new Set([0x20aa, 0x20ab]);
 
 export const DEVICES = {
   QL_820NWB: {
     name: 'QL-820NWB',
+    family: 'brother-ql',
+    transports: ['usb', 'webusb', 'tcp', 'serial', 'web-serial'],
     vid: 0x04f9,
     pid: 0x20a7,
     headPins: 720,
     bytesPerRow: 90,
     twoColor: true,
     network: 'wifi+wired',
-    bluetooth: false,
     autocut: true,
     compression: true,
     editorLite: true,
   },
   QL_820NWBc: {
     name: 'QL-820NWBc',
+    family: 'brother-ql',
+    transports: ['usb', 'webusb', 'tcp', 'serial', 'web-serial'],
     vid: 0x04f9,
     pid: 0x209d,
     headPins: 720,
     bytesPerRow: 90,
     twoColor: true,
     network: 'wifi+wired',
-    bluetooth: false,
     autocut: true,
     compression: true,
     editorLite: true,
   },
   QL_810W: {
     name: 'QL-810W',
+    family: 'brother-ql',
+    transports: ['usb', 'webusb', 'tcp'],
     vid: 0x04f9,
     pid: 0x209c,
     headPins: 720,
     bytesPerRow: 90,
     twoColor: true,
     network: 'wifi',
-    bluetooth: false,
     autocut: true,
     compression: true,
     editorLite: true,
   },
   QL_800: {
     name: 'QL-800',
+    family: 'brother-ql',
+    transports: ['usb', 'webusb'],
     vid: 0x04f9,
     pid: 0x209b,
     headPins: 720,
     bytesPerRow: 90,
     twoColor: true,
     network: 'none',
-    bluetooth: false,
     autocut: true,
     compression: true,
     editorLite: true,
   },
   QL_720NW: {
     name: 'QL-720NW',
+    family: 'brother-ql',
+    transports: ['usb', 'webusb', 'tcp'],
     vid: 0x04f9,
     pid: 0x2045,
     headPins: 720,
     bytesPerRow: 90,
     twoColor: false,
     network: 'wired',
-    bluetooth: false,
     autocut: true,
     compression: true,
     editorLite: false,
   },
   QL_710W: {
     name: 'QL-710W',
+    family: 'brother-ql',
+    transports: ['usb', 'webusb', 'tcp'],
     vid: 0x04f9,
     pid: 0x2044,
     headPins: 720,
     bytesPerRow: 90,
     twoColor: false,
     network: 'wifi',
-    bluetooth: false,
     autocut: true,
     compression: true,
     editorLite: true,
   },
   QL_700: {
     name: 'QL-700',
+    family: 'brother-ql',
+    transports: ['usb', 'webusb'],
     vid: 0x04f9,
     pid: 0x2042,
     headPins: 720,
     bytesPerRow: 90,
     twoColor: false,
     network: 'none',
-    bluetooth: false,
     autocut: true,
     compression: true,
     editorLite: true,
   },
   QL_600: {
     name: 'QL-600',
+    family: 'brother-ql',
+    transports: ['usb', 'webusb'],
     vid: 0x04f9,
     pid: 0x2100,
     headPins: 720,
     bytesPerRow: 90,
     twoColor: false,
     network: 'none',
-    bluetooth: false,
     autocut: true,
     compression: true,
     editorLite: false,
   },
   QL_580N: {
     name: 'QL-580N',
+    family: 'brother-ql',
+    transports: ['usb', 'webusb', 'tcp'],
     vid: 0x04f9,
     pid: 0x201b,
     headPins: 720,
     bytesPerRow: 90,
     twoColor: false,
     network: 'wired',
-    bluetooth: false,
     autocut: true,
     compression: true,
     editorLite: false,
   },
   QL_570: {
     name: 'QL-570',
+    family: 'brother-ql',
+    transports: ['usb', 'webusb'],
     vid: 0x04f9,
     pid: 0x2019,
     headPins: 720,
     bytesPerRow: 90,
     twoColor: false,
     network: 'none',
-    bluetooth: false,
     autocut: true,
     compression: true,
     editorLite: false,
   },
   QL_560: {
     name: 'QL-560',
+    family: 'brother-ql',
+    transports: ['usb', 'webusb'],
     vid: 0x04f9,
     pid: 0x2018,
     headPins: 720,
     bytesPerRow: 90,
     twoColor: false,
     network: 'none',
-    bluetooth: false,
     autocut: true,
     compression: false,
     editorLite: false,
   },
   QL_550: {
     name: 'QL-550',
+    family: 'brother-ql',
+    transports: ['usb', 'webusb'],
     vid: 0x04f9,
     pid: 0x2016,
     headPins: 720,
     bytesPerRow: 90,
     twoColor: false,
     network: 'none',
-    bluetooth: false,
     autocut: false,
     compression: false,
     editorLite: false,
   },
   QL_500: {
     name: 'QL-500',
+    family: 'brother-ql',
+    transports: ['usb', 'webusb'],
     vid: 0x04f9,
     pid: 0x2013,
     headPins: 720,
     bytesPerRow: 90,
     twoColor: false,
     network: 'none',
-    bluetooth: false,
     autocut: false,
     compression: false,
     editorLite: false,
   },
   QL_650TD: {
     name: 'QL-650TD',
+    family: 'brother-ql',
+    transports: ['usb', 'webusb'],
     vid: 0x04f9,
     pid: 0x201c,
     headPins: 720,
     bytesPerRow: 90,
     twoColor: false,
     network: 'none',
-    bluetooth: false,
     autocut: true,
     compression: true,
     editorLite: false,
   },
   QL_1100: {
     name: 'QL-1100',
+    family: 'brother-ql',
+    transports: ['usb', 'webusb'],
     vid: 0x04f9,
     pid: 0x20a8,
     headPins: 1296,
     bytesPerRow: 162,
     twoColor: false,
     network: 'none',
-    bluetooth: false,
     autocut: true,
     compression: true,
     editorLite: true,
@@ -201,13 +216,14 @@ export const DEVICES = {
   },
   QL_1110NWB: {
     name: 'QL-1110NWB',
+    family: 'brother-ql',
+    transports: ['usb', 'webusb', 'tcp'],
     vid: 0x04f9,
     pid: 0x20a9,
     headPins: 1296,
     bytesPerRow: 162,
     twoColor: false,
     network: 'wifi+wired',
-    bluetooth: false,
     autocut: true,
     compression: true,
     editorLite: true,
@@ -215,46 +231,49 @@ export const DEVICES = {
   },
   QL_1115NWB: {
     name: 'QL-1115NWB',
+    family: 'brother-ql',
+    transports: ['usb', 'webusb', 'tcp'],
     vid: 0x04f9,
     pid: 0x20ac,
     headPins: 1296,
     bytesPerRow: 162,
     twoColor: false,
     network: 'wifi+wired',
-    bluetooth: false,
     autocut: true,
     compression: true,
     editorLite: true,
   },
   QL_1050: {
     name: 'QL-1050',
+    family: 'brother-ql',
+    transports: ['usb', 'webusb'],
     vid: 0x04f9,
     pid: 0x2027,
     headPins: 1296,
     bytesPerRow: 162,
     twoColor: false,
     network: 'none',
-    bluetooth: false,
     autocut: true,
     compression: true,
     editorLite: false,
   },
   QL_1060N: {
     name: 'QL-1060N',
+    family: 'brother-ql',
+    transports: ['usb', 'webusb', 'tcp'],
     vid: 0x04f9,
     pid: 0x2028,
     headPins: 1296,
     bytesPerRow: 162,
     twoColor: false,
     network: 'wired',
-    bluetooth: false,
     autocut: true,
     compression: true,
     editorLite: false,
   },
-} as const satisfies Record<string, DeviceDescriptor>;
+} as const satisfies Record<string, BrotherQLDevice>;
 
-export function findDevice(vid: number, pid: number): DeviceDescriptor | undefined {
+export function findDevice(vid: number, pid: number): BrotherQLDevice | undefined {
   return Object.values(DEVICES).find(d => d.vid === vid && d.pid === pid);
 }
 

package/src/index.ts

@@ -1,22 +1,44 @@
 export type { LabelBitmap, RawImageData } from '@mbtech-nl/bitmap';
 export { renderText, renderImage, rotateBitmap, flipHorizontal } from '@mbtech-nl/bitmap';
 
+export type {
+  DeviceDescriptor,
+  MediaDescriptor,
+  PreviewOptions,
+  PreviewPlane,
+  PreviewResult,
+  PrintOptions,
+  PrinterAdapter,
+  PrinterError,
+  PrinterStatus,
+  Transport,
+  TransportType,
+} from '@thermal-label/contracts';
+
+export { MediaNotSpecifiedError, UnsupportedOperationError } from '@thermal-label/contracts';
+
 export { DEVICES, findDevice, isMassStorageMode } from './devices.js';
-export { MEDIA, findMedia, findMediaByWidth } from './media.js';
+export {
+  DEFAULT_MEDIA,
+  MEDIA,
+  findMedia,
+  findMediaByDimensions,
+  findMediaByWidth,
+} from './media.js';
 export { encodeJob } from './protocol.js';
 export { parseStatus, STATUS_REQUEST } from './status.js';
+export { isRedish, splitTwoColor, type TwoColorOptions, type TwoColorResult } from './colour.js';
+export { createPreviewOffline } from './preview.js';
 
 export type {
-  MediaType,
-  HeadWidth,
+  BrotherQLDevice,
+  BrotherQLMedia,
+  BrotherQLStatus,
   ColorMode,
+  HeadWidth,
+  JobOptions,
+  MediaType,
   NetworkSupport,
-  DeviceDescriptor,
-  MediaDescriptor,
   PageData,
   PageOptions,
-  JobOptions,
-  PrinterStatus,
-  TextPrintOptions,
-  ImagePrintOptions,
 } from './types.js';

package/src/media.ts

@@ -1,13 +1,23 @@
-import { type MediaDescriptor, type MediaType } from './types.js';
+import { type BrotherQLMedia, type MediaType } from './types.js';
 
-export const MEDIA: Record<number, MediaDescriptor> = {
+/**
+ * Registry of supported Brother QL consumables.
+ *
+ * Entries are keyed by the firmware media id — the same number the
+ * printer reports in the 32-byte status response. `heightMm` is
+ * omitted for continuous media (variable length) and set for die-cut
+ * labels (fixed length). Only DK-22251 has `colorCapable: true` — the
+ * driver uses that to run two-colour plane separation before sending
+ * the raster.
+ */
+export const MEDIA: Record<number, BrotherQLMedia> = {
   // Continuous length tape
   257: {
     id: 257,
     name: '12mm continuous',
     type: 'continuous',
     widthMm: 12,
-    lengthMm: 0,
+    colorCapable: false,
     printAreaDots: 106,
     leftMarginPins: 585,
     rightMarginPins: 29,
@@ -17,7 +27,7 @@ export const MEDIA: Record<number, MediaDescriptor> = {
     name: '29mm continuous (DK-22210)',
     type: 'continuous',
     widthMm: 29,
-    lengthMm: 0,
+    colorCapable: false,
     printAreaDots: 306,
     leftMarginPins: 408,
     rightMarginPins: 6,
@@ -27,7 +37,7 @@ export const MEDIA: Record<number, MediaDescriptor> = {
     name: '38mm continuous (DK-22225)',
     type: 'continuous',
     widthMm: 38,
-    lengthMm: 0,
+    colorCapable: false,
     printAreaDots: 413,
     leftMarginPins: 295,
     rightMarginPins: 12,
@@ -37,7 +47,7 @@ export const MEDIA: Record<number, MediaDescriptor> = {
     name: '50mm continuous (DK-22246)',
     type: 'continuous',
     widthMm: 50,
-    lengthMm: 0,
+    colorCapable: false,
     printAreaDots: 554,
     leftMarginPins: 154,
     rightMarginPins: 12,
@@ -47,7 +57,7 @@ export const MEDIA: Record<number, MediaDescriptor> = {
     name: '54mm continuous (DK-22214)',
     type: 'continuous',
     widthMm: 54,
-    lengthMm: 0,
+    colorCapable: false,
     printAreaDots: 590,
     leftMarginPins: 130,
     rightMarginPins: 0,
@@ -57,7 +67,7 @@ export const MEDIA: Record<number, MediaDescriptor> = {
     name: '62mm continuous (DK-22205)',
     type: 'continuous',
     widthMm: 62,
-    lengthMm: 0,
+    colorCapable: false,
     printAreaDots: 696,
     leftMarginPins: 12,
     rightMarginPins: 12,
@@ -67,18 +77,17 @@ export const MEDIA: Record<number, MediaDescriptor> = {
     name: '62mm continuous two-color (DK-22251)',
     type: 'continuous',
     widthMm: 62,
-    lengthMm: 0,
+    colorCapable: true,
     printAreaDots: 696,
     leftMarginPins: 12,
     rightMarginPins: 12,
-    twoColorTape: true,
   },
   260: {
     id: 260,
     name: '102mm continuous (DK-22243)',
     type: 'continuous',
     widthMm: 102,
-    lengthMm: 0,
+    colorCapable: false,
     printAreaDots: 1164,
     leftMarginPins: 76,
     rightMarginPins: 56,
@@ -90,7 +99,8 @@ export const MEDIA: Record<number, MediaDescriptor> = {
     name: '17×54mm die-cut (DK-11204)',
     type: 'die-cut',
     widthMm: 17,
-    lengthMm: 54,
+    heightMm: 54,
+    colorCapable: false,
     printAreaDots: 165,
     leftMarginPins: 0,
     rightMarginPins: 0,
@@ -101,7 +111,8 @@ export const MEDIA: Record<number, MediaDescriptor> = {
     name: '17×87mm die-cut (DK-11203)',
     type: 'die-cut',
     widthMm: 17,
-    lengthMm: 87,
+    heightMm: 87,
+    colorCapable: false,
     printAreaDots: 165,
     leftMarginPins: 0,
     rightMarginPins: 0,
@@ -112,7 +123,8 @@ export const MEDIA: Record<number, MediaDescriptor> = {
     name: '23×23mm die-cut',
     type: 'die-cut',
     widthMm: 23,
-    lengthMm: 23,
+    heightMm: 23,
+    colorCapable: false,
     printAreaDots: 236,
     leftMarginPins: 0,
     rightMarginPins: 0,
@@ -123,7 +135,8 @@ export const MEDIA: Record<number, MediaDescriptor> = {
     name: '29×90mm die-cut (DK-11201)',
     type: 'die-cut',
     widthMm: 29,
-    lengthMm: 90,
+    heightMm: 90,
+    colorCapable: false,
     printAreaDots: 306,
     leftMarginPins: 0,
     rightMarginPins: 0,
@@ -134,7 +147,8 @@ export const MEDIA: Record<number, MediaDescriptor> = {
     name: '38×90mm die-cut (DK-11218)',
     type: 'die-cut',
     widthMm: 38,
-    lengthMm: 90,
+    heightMm: 90,
+    colorCapable: false,
     printAreaDots: 413,
     leftMarginPins: 0,
     rightMarginPins: 0,
@@ -145,7 +159,8 @@ export const MEDIA: Record<number, MediaDescriptor> = {
     name: '39×48mm die-cut (DK-11219)',
     type: 'die-cut',
     widthMm: 39,
-    lengthMm: 48,
+    heightMm: 48,
+    colorCapable: false,
     printAreaDots: 425,
     leftMarginPins: 0,
     rightMarginPins: 0,
@@ -156,7 +171,8 @@ export const MEDIA: Record<number, MediaDescriptor> = {
     name: '52×29mm die-cut',
     type: 'die-cut',
     widthMm: 52,
-    lengthMm: 29,
+    heightMm: 29,
+    colorCapable: false,
     printAreaDots: 578,
     leftMarginPins: 0,
     rightMarginPins: 0,
@@ -167,7 +183,8 @@ export const MEDIA: Record<number, MediaDescriptor> = {
     name: '62×29mm die-cut (DK-11209)',
     type: 'die-cut',
     widthMm: 62,
-    lengthMm: 29,
+    heightMm: 29,
+    colorCapable: false,
     printAreaDots: 696,
     leftMarginPins: 0,
     rightMarginPins: 0,
@@ -178,7 +195,8 @@ export const MEDIA: Record<number, MediaDescriptor> = {
     name: '62×100mm die-cut (DK-11202)',
     type: 'die-cut',
     widthMm: 62,
-    lengthMm: 100,
+    heightMm: 100,
+    colorCapable: false,
     printAreaDots: 696,
     leftMarginPins: 0,
     rightMarginPins: 0,
@@ -189,7 +207,8 @@ export const MEDIA: Record<number, MediaDescriptor> = {
     name: '102×51mm die-cut (DK-11240)',
     type: 'die-cut',
     widthMm: 102,
-    lengthMm: 51,
+    heightMm: 51,
+    colorCapable: false,
     printAreaDots: 1164,
     leftMarginPins: 0,
     rightMarginPins: 0,
@@ -200,7 +219,8 @@ export const MEDIA: Record<number, MediaDescriptor> = {
     name: '102×152mm die-cut (DK-11241)',
     type: 'die-cut',
     widthMm: 102,
-    lengthMm: 152,
+    heightMm: 152,
+    colorCapable: false,
     printAreaDots: 1164,
     leftMarginPins: 0,
     rightMarginPins: 0,
@@ -211,7 +231,8 @@ export const MEDIA: Record<number, MediaDescriptor> = {
     name: '12mm Ø die-cut',
     type: 'die-cut',
     widthMm: 12,
-    lengthMm: 12,
+    heightMm: 12,
+    colorCapable: false,
     printAreaDots: 94,
     leftMarginPins: 0,
     rightMarginPins: 0,
@@ -222,7 +243,8 @@ export const MEDIA: Record<number, MediaDescriptor> = {
     name: '24mm Ø die-cut (DK-11221)',
     type: 'die-cut',
     widthMm: 24,
-    lengthMm: 24,
+    heightMm: 24,
+    colorCapable: false,
     printAreaDots: 236,
     leftMarginPins: 0,
     rightMarginPins: 0,
@@ -233,7 +255,8 @@ export const MEDIA: Record<number, MediaDescriptor> = {
     name: '58mm Ø die-cut (DK-11207)',
     type: 'die-cut',
     widthMm: 58,
-    lengthMm: 58,
+    heightMm: 58,
+    colorCapable: false,
     printAreaDots: 618,
     leftMarginPins: 0,
     rightMarginPins: 0,
@@ -241,10 +264,46 @@ export const MEDIA: Record<number, MediaDescriptor> = {
   },
 };
 
-export function findMedia(id: number): MediaDescriptor | undefined {
+/**
+ * Default media when `createPreview()` is called without media and
+ * without a detected roll. 62mm continuous (DK-22205) is the common
+ * single-colour shipping roll.
+ */
+// eslint-disable-next-line @typescript-eslint/no-non-null-assertion -- DK-22205 is a hard-coded registry key
+export const DEFAULT_MEDIA: BrotherQLMedia = MEDIA[259]!;
+
+export function findMedia(id: number): BrotherQLMedia | undefined {
   return MEDIA[id];
 }
 
-export function findMediaByWidth(widthMm: number, type: MediaType): MediaDescriptor[] {
+export function findMediaByWidth(widthMm: number, type: MediaType): BrotherQLMedia[] {
   return Object.values(MEDIA).filter(m => m.widthMm === widthMm && m.type === type);
 }
+
+/**
+ * Match status-response dimensions to a media registry entry.
+ *
+ * @param widthMm     media width in mm (status byte 10)
+ * @param heightMm    media length in mm (status byte 17) — 0 = continuous
+ * @param twoColorMode true when the status response indicates the
+ *                     printer is configured for two-colour media. When
+ *                     both DK-22205 (259) and DK-22251 (251) match the
+ *                     dimensions, the flag picks the right one.
+ */
+export function findMediaByDimensions(
+  widthMm: number,
+  heightMm: number,
+  twoColorMode = false,
+): BrotherQLMedia | undefined {
+  if (heightMm === 0) {
+    const continuousMatches = Object.values(MEDIA).filter(
+      m => m.type === 'continuous' && m.widthMm === widthMm,
+    );
+    if (continuousMatches.length === 0) return undefined;
+    const preferred = continuousMatches.find(m => m.colorCapable === twoColorMode);
+    return preferred ?? continuousMatches[0];
+  }
+  return Object.values(MEDIA).find(
+    m => m.type === 'die-cut' && m.widthMm === widthMm && m.heightMm === heightMm,
+  );
+}

package/src/preview.ts

@@ -0,0 +1,34 @@
+/* eslint-disable import-x/consistent-type-specifier-style */
+import { renderImage, type RawImageData } from '@mbtech-nl/bitmap';
+import type { PreviewResult } from '@thermal-label/contracts';
+import { splitTwoColor } from './colour.js';
+import { type BrotherQLMedia } from './types.js';
+
+/**
+ * Offline preview without a live printer connection.
+ *
+ * Two-colour aware: when `media.colorCapable` is true (DK-22251), the
+ * image is split into a black and a red plane via `splitTwoColor()` —
+ * exactly what `print()` does for that media. Single-colour media
+ * returns one black plane.
+ */
+export function createPreviewOffline(image: RawImageData, media: BrotherQLMedia): PreviewResult {
+  if (media.colorCapable) {
+    const { black, red } = splitTwoColor(image);
+    return {
+      planes: [
+        { name: 'black', bitmap: black, displayColor: '#000000' },
+        { name: 'red', bitmap: red, displayColor: '#ff0000' },
+      ],
+      media,
+      assumed: false,
+    };
+  }
+
+  const bitmap = renderImage(image, { dither: true });
+  return {
+    planes: [{ name: 'black', bitmap, displayColor: '#000000' }],
+    media,
+    assumed: false,
+  };
+}

package/src/protocol.ts

@@ -1,5 +1,5 @@
 import { getRow, createBitmap } from '@mbtech-nl/bitmap';
-import { type MediaDescriptor, type PageData, type JobOptions, type PageOptions } from './types.js';
+import { type BrotherQLMedia, type PageData, type JobOptions, type PageOptions } from './types.js';
 
 export function buildInvalidate(): Uint8Array {
   return new Uint8Array(200);
@@ -22,7 +22,7 @@ export function buildStatusNotification(enabled: boolean): Uint8Array {
 }
 
 export function buildPrintInfo(
-  media: MediaDescriptor,
+  media: BrotherQLMedia,
   rowCount: number,
   pageIndex: number,
 ): Uint8Array {
@@ -38,7 +38,7 @@ export function buildPrintInfo(
   buf[3] = validFlags;
   buf[4] = mediaType;
   buf[5] = media.widthMm;
-  buf[6] = media.lengthMm;
+  buf[6] = media.heightMm ?? 0;
   // rowCount little-endian at bytes 7-8 (offsets 4-5 in param block)
   buf[7] = rowCount & 0xff;
   buf[8] = (rowCount >> 8) & 0xff;
@@ -161,12 +161,12 @@ export function encodeJob(pages: PageData[], options: JobOptions = {}): Uint8Arr
     const compress = opts.compress ?? false;
     const { bitmap, media } = page;
 
-    // twoColorTape media (e.g. DK-22251) requires two-color mode even for black-only jobs.
+    // colorCapable media (e.g. DK-22251) requires two-color mode even for black-only jobs.
     // Auto-create an empty red plane when the tape demands it but caller didn't supply one.
-    const twoColor = page.redBitmap !== undefined || media.twoColorTape === true;
+    const twoColor = page.redBitmap !== undefined || media.colorCapable;
     const redBitmap =
       page.redBitmap ??
-      (media.twoColorTape ? createBitmap(bitmap.widthPx, bitmap.heightPx) : undefined);
+      (media.colorCapable ? createBitmap(bitmap.widthPx, bitmap.heightPx) : undefined);
 
     if (twoColor && redBitmap !== undefined) {
       if (bitmap.widthPx !== redBitmap.widthPx || bitmap.heightPx !== redBitmap.heightPx) {