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

package/src/media.ts

@@ -8,7 +8,7 @@ export { MEDIA };
  * Resolve per-head-family geometry for a media entry against the
  * engine that's about to print it.
  *
- * DK entries fall back to the flat `printAreaDots` / `leftMarginPins` /
+ * DK entries fall back to the flat `printableDots` / `leftMarginPins` /
  * `rightMarginPins` fields on the entry — the same values every QL
  * code path read before the head-family split landed. TZe and HSe
  * entries dispatch on `engine.headDots`: 128 picks `geometry.narrow`,
@@ -23,14 +23,14 @@ export function resolveTapeGeometry(
 ): TapeGeometry {
   if (media.tapeSystem === 'dk') {
     if (
-      typeof media.printAreaDots !== 'number' ||
+      typeof media.printableDots !== 'number' ||
       typeof media.leftMarginPins !== 'number' ||
       typeof media.rightMarginPins !== 'number'
     ) {
       throw new Error(`DK media ${media.id.toString()} missing flat geometry fields`);
     }
     return {
-      printAreaDots: media.printAreaDots,
+      printableDots: media.printableDots,
       leftMarginPins: media.leftMarginPins,
       rightMarginPins: media.rightMarginPins,
     };

package/src/protocol.ts

@@ -229,14 +229,14 @@ function resolveEncoderGeometry(
 ): TapeGeometry {
   if (media.tapeSystem === 'dk') {
     if (
-      typeof media.printAreaDots !== 'number' ||
+      typeof media.printableDots !== 'number' ||
       typeof media.leftMarginPins !== 'number' ||
       typeof media.rightMarginPins !== 'number'
     ) {
       throw new Error(`DK media ${media.id.toString()} missing flat geometry fields`);
     }
     return {
-      printAreaDots: media.printAreaDots,
+      printableDots: media.printableDots,
       leftMarginPins: media.leftMarginPins,
       rightMarginPins: media.rightMarginPins,
     };
@@ -329,10 +329,10 @@ function encodeRasterJob(pages: PageData[], options: JobOptions, ctx: EncodeCont
     if (compress) chunks.push(buildCompression(true));
 
     // Each raster row must cover the full print head width (derived from media geometry).
-    // leftMarginPins + printAreaDots + rightMarginPins = head pin count (720 / 1296 / 128 / 560).
+    // leftMarginPins + printableDots + rightMarginPins = head pin count (720 / 1296 / 128 / 560).
     const geometry = resolveEncoderGeometry(media, engine);
     const leftMarginPins = geometry.leftMarginPins;
-    const totalPins = leftMarginPins + geometry.printAreaDots + geometry.rightMarginPins;
+    const totalPins = leftMarginPins + geometry.printableDots + geometry.rightMarginPins;
     const rowByteLen = Math.ceil(totalPins / 8);
 
     // Rows interleaved per raster line (matches Python brother_ql behaviour).

package/src/status.ts

@@ -1,4 +1,4 @@
-import type { PrintEngine, PrinterError } from '@thermal-label/contracts';
+import type { PrintEngine, PrinterError, StatusDetail } from '@thermal-label/contracts';
 import type { BrotherQLStatus } from './types.js';
 import { findMediaByDimensions } from './media.js';
 
@@ -37,15 +37,18 @@ 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 19 — phase type (0x00 receiving, 0x01 printing)
+ *   byte 22 — notification (0x03 cooling started, 0x04 cooling finished)
  *   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
- * extension on `BrotherQLStatus` — the status-type byte doesn't
- * actually report it, but keeping the field here means callers can
- * set it from other signals (e.g. mass-storage PID detected during
- * discovery) without changing the return type.
+ * `findMediaByDimensions`.
+ *
+ * `details` carries the contracts-standard `StatusDetail[]` diagnostic
+ * rows the harness renders verbatim: the print phase (always present)
+ * and the head-cooling notification (only when the printer reports
+ * one).
  */
 export function parseStatus(
   bytes: Uint8Array,
@@ -62,6 +65,8 @@ export function parseStatus(
   const mediaTypeByte = view.getUint8(11);
   const mediaLengthMm = view.getUint8(17);
   const statusType = view.getUint8(18);
+  const phaseType = view.getUint8(19);
+  const notification = view.getUint8(22);
   const twoColorFlag = (view.getUint8(25) & 0x80) !== 0;
 
   const errors: PrinterError[] = [];
@@ -81,9 +86,43 @@ export function parseStatus(
     ready: errors.length === 0 && statusType !== 0x02,
     mediaLoaded,
     ...(detected === undefined ? {} : { detectedMedia: detected }),
-    ...(mediaLoaded ? { twoColorRoll: twoColorFlag } : {}),
     errors,
-    editorLiteMode: false,
+    details: buildStatusDetails(phaseType, notification),
     rawBytes: bytes,
   };
 }
+
+/**
+ * Build the contracts-standard `StatusDetail[]` rows for a parsed
+ * Brother QL status.
+ *
+ * - The print-phase row (byte 19) is always emitted — it is the most
+ *   useful "is the device doing anything" signal for a stuck report.
+ * - The head-cooling row (byte 22) is emitted only when the printer
+ *   reports a cooling notification; `0x00` (none) produces no row so a
+ *   normal idle status stays uncluttered. "Cooling started" is a
+ *   `warn` (printing is paused), "cooling finished" is plain `info`.
+ */
+function buildStatusDetails(phaseType: number, notification: number): StatusDetail[] {
+  const details: StatusDetail[] = [];
+
+  details.push({
+    label: 'Print phase',
+    value: phaseType === 0x01 ? 'printing' : 'receiving',
+  });
+
+  if (notification === 0x03) {
+    details.push({
+      label: 'Head cooling',
+      value: 'cooling started',
+      severity: 'warn',
+    });
+  } else if (notification === 0x04) {
+    details.push({
+      label: 'Head cooling',
+      value: 'cooling finished',
+    });
+  }
+
+  return details;
+}

package/src/types.ts

@@ -25,13 +25,13 @@ export type TapeSystem = 'dk' | 'tze' | 'hse-2to1' | 'hse-3to1';
  *
  * 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
+ * `printableDots` / `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;
+  printableDots: number;
   leftMarginPins: number;
   rightMarginPins: number;
 }
@@ -104,7 +104,7 @@ export interface BrotherQLMedia extends MediaDescriptor {
    */
   geometry?: { narrow?: TapeGeometry; wide?: TapeGeometry };
   /** DK-only flat geometry. PT-* entries populate `geometry` instead. */
-  printAreaDots?: number;
+  printableDots?: number;
   leftMarginPins?: number;
   rightMarginPins?: number;
   /** Die-cut masked area in dots (registration windows). */
@@ -112,18 +112,11 @@ export interface BrotherQLMedia extends MediaDescriptor {
 }
 
 /**
- * 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).
+ * Brother QL status — the plain contract `PrinterStatus`. Brother QL
+ * adds no structural extension: driver-specific diagnostic facts (print
+ * phase, head cooling) ride in the contract-standard `details[]` rows.
  */
-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 type BrotherQLStatus = PrinterStatus;
 
 export interface PageData {
   bitmap: LabelBitmap;