@thermal-label/brother-ql-core 0.3.0 → 0.5.0

package/src/status.ts

@@ -1,4 +1,4 @@
-import type { PrinterError } from '@thermal-label/contracts';
+import type { PrintEngine, PrinterError } from '@thermal-label/contracts';
 import type { BrotherQLStatus } from './types.js';
 import { findMediaByDimensions } from './media.js';
 
@@ -37,6 +37,8 @@ const ERROR_INFO_2: { bit: number; code: string; message: string }[] = [
  *   byte 11 — media type (0x0A continuous, 0x0B die-cut)
  *   byte 17 — media length (mm), 0 for continuous
  *   byte 18 — status type (0x02 = error response)
+ *   byte 25 — bit 7 set when the loaded roll is two-color (DK-22251);
+ *             clear on single-color rolls. See scripts/STATUS-CAPTURE.md.
  *
  * `detectedMedia` is resolved against the media registry via
  * `findMediaByDimensions`. `editorLiteMode` is a driver-specific
@@ -45,7 +47,10 @@ const ERROR_INFO_2: { bit: number; code: string; message: string }[] = [
  * set it from other signals (e.g. mass-storage PID detected during
  * discovery) without changing the return type.
  */
-export function parseStatus(bytes: Uint8Array): BrotherQLStatus {
+export function parseStatus(
+  bytes: Uint8Array,
+  engine?: Pick<PrintEngine, 'headDots' | 'mediaCompatibility'>,
+): BrotherQLStatus {
   if (bytes.length < 32) {
     throw new Error(`Status response too short: ${bytes.length.toString()} bytes`);
   }
@@ -57,6 +62,7 @@ export function parseStatus(bytes: Uint8Array): BrotherQLStatus {
   const mediaTypeByte = view.getUint8(11);
   const mediaLengthMm = view.getUint8(17);
   const statusType = view.getUint8(18);
+  const twoColorFlag = (view.getUint8(25) & 0x80) !== 0;
 
   const errors: PrinterError[] = [];
   for (const { bit, code, message } of ERROR_INFO_1) {
@@ -68,13 +74,14 @@ export function parseStatus(bytes: Uint8Array): BrotherQLStatus {
 
   const mediaLoaded = mediaWidthMm > 0 && mediaTypeByte !== 0;
   const detected = mediaLoaded
-    ? findMediaByDimensions(mediaWidthMm, mediaLengthMm, false)
+    ? findMediaByDimensions(mediaWidthMm, mediaLengthMm, twoColorFlag, engine)
     : undefined;
 
   return {
     ready: errors.length === 0 && statusType !== 0x02,
     mediaLoaded,
     ...(detected === undefined ? {} : { detectedMedia: detected }),
+    ...(mediaLoaded ? { twoColorRoll: twoColorFlag } : {}),
     errors,
     editorLiteMode: false,
     rawBytes: bytes,

package/src/types.ts

@@ -1,7 +1,8 @@
 import type { LabelBitmap } from '@mbtech-nl/bitmap';
 import type {
-  DeviceDescriptor,
+  DeviceEntry,
   MediaDescriptor,
+  PrintEngineCapabilities,
   PrintOptions,
   PrinterStatus,
 } from '@thermal-label/contracts';
@@ -9,36 +10,73 @@ import type {
 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';
 
 /**
- * Brother QL device descriptor.
+ * Tape-system discriminator on `BrotherQLMedia`. DK is the QL series'
+ * paper-label system; TZe is the laminated-tape system used by the
+ * PT-P / PT-E line; HSe 2:1 and HSe 3:1 are heat-shrink tubing systems
+ * supported by most P900-series and PT-E550W. Lookup paths gate on
+ * this so a QL printer never resolves a TZe entry, and vice versa.
+ */
+export type TapeSystem = 'dk' | 'tze' | 'hse-2to1' | 'hse-3to1';
+
+/**
+ * Per-head-family geometry on `BrotherQLMedia`.
  *
- * Extends the contracts base with QL-specific fields: head geometry,
- * protocol feature flags, and the optional mass-storage PID for Editor
- * Lite mode.
+ * Brother's PT-P / PT-E line ships two head families with different
+ * per-tape pin layouts. The same TZe id maps to different
+ * `printAreaDots` / `leftMarginPins` / `rightMarginPins` values on a
+ * 128-pin head (PT-E550W, PT-P750W) versus a 560-pin head (PT-P900,
+ * P900W, P950NW, P910BT). DK media leaves these unset and resolves via
+ * the flat fields on `BrotherQLMedia` directly.
+ */
+export interface TapeGeometry {
+  printAreaDots: number;
+  leftMarginPins: number;
+  rightMarginPins: number;
+}
+
+/**
+ * Brother-specific engine capabilities.
  *
- * **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.
+ * Extends the contracts-defined `PrintEngineCapabilities` (which
+ * carries the multi-vendor named flags `autocut` and `mediaDetection`)
+ * with the driver-side `twoColor` flag — Brother-only today, so it
+ * lands here via the contracts open index signature. Promote to a
+ * named contracts key when a second vendor implements the same
+ * capability with compatible semantics.
  */
-export interface BrotherQLDevice extends DeviceDescriptor {
-  family: 'brother-ql';
-  vid: number;
-  pid: number;
-  headPins: HeadWidth;
-  bytesPerRow: number;
-  twoColor: boolean;
-  network: NetworkSupport;
-  autocut: boolean;
-  compression: boolean;
-  editorLite: boolean;
-  /** Alternate PID seen when the printer is in Editor Lite mass-storage mode. */
-  massStoragePid?: number;
+export interface BrotherEngineCapabilities extends PrintEngineCapabilities {
+  /** Two-colour ribbon path — black + red plane raster encoding. */
+  twoColor?: boolean;
+  /**
+   * Doubled-density mode along the feed axis (`ESC i K` bit 6).
+   * `360` on PT-E550W / PT-P750W (native 180); `720` on the PT-P900
+   * family (native 360). Undefined on QL and PT models that don't
+   * support high-res. The encoder branches on this when
+   * `BrotherQLPrintOptions.highRes` is set.
+   */
+  highResDpi?: 360 | 720;
 }
 
+/**
+ * Brother QL device entry — alias for the contracts `DeviceEntry`
+ * shape. Re-exported under a driver-named type so consumers don't
+ * have to import contracts directly. Per-device chassis-level
+ * capabilities (`editorLite`, `massStoragePid`) ride on the open
+ * index signature of `DeviceEntry.capabilities`; engine-level flags
+ * (`autocut`, `mediaDetection`, `twoColor`) ride on
+ * `engines[].capabilities`.
+ *
+ * **Bluetooth on the QL-820NWB / 820NWBc**: not exposed over GATT.
+ * Classic Bluetooth SPP is paired at the OS level — declared as the
+ * `bluetooth-spp` transport. The runtime's serial implementation
+ * satisfies that transport key by opening the OS-paired RFCOMM
+ * device path. macOS dropped classic Bluetooth SPP — no SPP route
+ * there.
+ */
+export type BrotherQLDevice = DeviceEntry;
+
 /**
  * Brother QL media descriptor.
  *
@@ -49,9 +87,26 @@ export interface BrotherQLDevice extends DeviceDescriptor {
 export interface BrotherQLMedia extends MediaDescriptor {
   id: number;
   type: MediaType;
-  printAreaDots: number;
-  leftMarginPins: number;
-  rightMarginPins: number;
+  /**
+   * Tape system this entry belongs to. Drives lookup gating in
+   * `findMediaByDimensions(width, height, engine)` so QL engines never
+   * resolve TZe / HSe entries and vice versa.
+   */
+  tapeSystem: TapeSystem;
+  /**
+   * Per-head-family geometry. `narrow` = 128-pin head (PT-E550W,
+   * PT-P750W); `wide` = 560-pin head (PT-P900 family). DK entries
+   * leave both unset and use the flat fields below; TZe / HSe entries
+   * leave the flat fields undefined and populate `narrow` and/or
+   * `wide` per the *Raster Command Reference* PDFs. `undefined` on a
+   * head family means "this tape doesn't fit this head" (e.g. 36 mm
+   * TZe and 31 mm HSe-3:1 have no `narrow` entry).
+   */
+  geometry?: { narrow?: TapeGeometry; wide?: TapeGeometry };
+  /** DK-only flat geometry. PT-* entries populate `geometry` instead. */
+  printAreaDots?: number;
+  leftMarginPins?: number;
+  rightMarginPins?: number;
   /** Die-cut masked area in dots (registration windows). */
   dieCutMaskedAreaDots?: number;
 }
@@ -63,6 +118,11 @@ export interface BrotherQLMedia extends MediaDescriptor {
  */
 export interface BrotherQLStatus extends PrinterStatus {
   editorLiteMode: boolean;
+  /**
+   * True when the loaded roll reports two-color capability via byte 25
+   * bit 7 of the status response. Undefined when no media is loaded.
+   */
+  twoColorRoll?: boolean;
 }
 
 export interface PageData {
@@ -94,4 +154,10 @@ export interface JobOptions {
  */
 export interface BrotherQLPrintOptions extends PrintOptions {
   rotate?: 'auto' | 0 | 90 | 180 | 270;
+  /**
+   * Opt into high-resolution mode (doubles dpi along the feed axis).
+   * Requires the engine's `capabilities.highResDpi` to be set; throws
+   * at job-build time otherwise. PT-* only — QL ignores the option.
+   */
+  highRes?: boolean;
 }