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

package/src/media.ts

@@ -1,268 +1,49 @@
-import { type BrotherQLMedia, type MediaType } from './types.js';
+import type { PrintEngine } from '@thermal-label/contracts';
+import type { BrotherQLMedia, MediaType, TapeGeometry } from './types.js';
+import { MEDIA } from './media.generated.js';
+
+export { MEDIA };
 
 /**
- * Registry of supported Brother QL consumables.
+ * Resolve per-head-family geometry for a media entry against the
+ * engine that's about to print it.
  *
- * 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.
+ * DK entries fall back to the flat `printAreaDots` / `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`,
+ * anything else picks `geometry.wide`. Throws when the requested head
+ * family has no entry (e.g. 36 mm TZe on a 128-dot head, or any HSe
+ * on PT-P910BT — those engines simply shouldn't reach this call site
+ * because `findMediaByDimensions` gates them upstream).
  */
-export const MEDIA: Record<number, BrotherQLMedia> = {
-  // Continuous length tape
-  257: {
-    id: 257,
-    name: '12mm continuous',
-    type: 'continuous',
-    widthMm: 12,
-    colorCapable: false,
-    printAreaDots: 106,
-    leftMarginPins: 585,
-    rightMarginPins: 29,
-  },
-  258: {
-    id: 258,
-    name: '29mm continuous (DK-22210)',
-    type: 'continuous',
-    widthMm: 29,
-    colorCapable: false,
-    printAreaDots: 306,
-    leftMarginPins: 408,
-    rightMarginPins: 6,
-  },
-  264: {
-    id: 264,
-    name: '38mm continuous (DK-22225)',
-    type: 'continuous',
-    widthMm: 38,
-    colorCapable: false,
-    printAreaDots: 413,
-    leftMarginPins: 295,
-    rightMarginPins: 12,
-  },
-  262: {
-    id: 262,
-    name: '50mm continuous (DK-22246)',
-    type: 'continuous',
-    widthMm: 50,
-    colorCapable: false,
-    printAreaDots: 554,
-    leftMarginPins: 154,
-    rightMarginPins: 12,
-  },
-  261: {
-    id: 261,
-    name: '54mm continuous (DK-22214)',
-    type: 'continuous',
-    widthMm: 54,
-    colorCapable: false,
-    printAreaDots: 590,
-    leftMarginPins: 130,
-    rightMarginPins: 0,
-  },
-  259: {
-    id: 259,
-    name: '62mm continuous (DK-22205)',
-    type: 'continuous',
-    widthMm: 62,
-    colorCapable: false,
-    printAreaDots: 696,
-    leftMarginPins: 12,
-    rightMarginPins: 12,
-  },
-  251: {
-    id: 251,
-    name: '62mm continuous two-color (DK-22251)',
-    type: 'continuous',
-    widthMm: 62,
-    colorCapable: true,
-    printAreaDots: 696,
-    leftMarginPins: 12,
-    rightMarginPins: 12,
-  },
-  260: {
-    id: 260,
-    name: '102mm continuous (DK-22243)',
-    type: 'continuous',
-    widthMm: 102,
-    colorCapable: false,
-    printAreaDots: 1164,
-    leftMarginPins: 76,
-    rightMarginPins: 56,
-  },
-
-  // Die-cut labels
-  269: {
-    id: 269,
-    name: '17×54mm die-cut (DK-11204)',
-    type: 'die-cut',
-    widthMm: 17,
-    heightMm: 54,
-    colorCapable: false,
-    printAreaDots: 165,
-    leftMarginPins: 0,
-    rightMarginPins: 0,
-    dieCutMaskedAreaDots: 566,
-  },
-  270: {
-    id: 270,
-    name: '17×87mm die-cut (DK-11203)',
-    type: 'die-cut',
-    widthMm: 17,
-    heightMm: 87,
-    colorCapable: false,
-    printAreaDots: 165,
-    leftMarginPins: 0,
-    rightMarginPins: 0,
-    dieCutMaskedAreaDots: 956,
-  },
-  370: {
-    id: 370,
-    name: '23×23mm die-cut',
-    type: 'die-cut',
-    widthMm: 23,
-    heightMm: 23,
-    colorCapable: false,
-    printAreaDots: 236,
-    leftMarginPins: 0,
-    rightMarginPins: 0,
-    dieCutMaskedAreaDots: 202,
-  },
-  271: {
-    id: 271,
-    name: '29×90mm die-cut (DK-11201)',
-    type: 'die-cut',
-    widthMm: 29,
-    heightMm: 90,
-    colorCapable: false,
-    printAreaDots: 306,
-    leftMarginPins: 0,
-    rightMarginPins: 0,
-    dieCutMaskedAreaDots: 991,
-  },
-  272: {
-    id: 272,
-    name: '38×90mm die-cut (DK-11218)',
-    type: 'die-cut',
-    widthMm: 38,
-    heightMm: 90,
-    colorCapable: false,
-    printAreaDots: 413,
-    leftMarginPins: 0,
-    rightMarginPins: 0,
-    dieCutMaskedAreaDots: 991,
-  },
-  367: {
-    id: 367,
-    name: '39×48mm die-cut (DK-11219)',
-    type: 'die-cut',
-    widthMm: 39,
-    heightMm: 48,
-    colorCapable: false,
-    printAreaDots: 425,
-    leftMarginPins: 0,
-    rightMarginPins: 0,
-    dieCutMaskedAreaDots: 495,
-  },
-  374: {
-    id: 374,
-    name: '52×29mm die-cut',
-    type: 'die-cut',
-    widthMm: 52,
-    heightMm: 29,
-    colorCapable: false,
-    printAreaDots: 578,
-    leftMarginPins: 0,
-    rightMarginPins: 0,
-    dieCutMaskedAreaDots: 271,
-  },
-  274: {
-    id: 274,
-    name: '62×29mm die-cut (DK-11209)',
-    type: 'die-cut',
-    widthMm: 62,
-    heightMm: 29,
-    colorCapable: false,
-    printAreaDots: 696,
-    leftMarginPins: 0,
-    rightMarginPins: 0,
-    dieCutMaskedAreaDots: 271,
-  },
-  275: {
-    id: 275,
-    name: '62×100mm die-cut (DK-11202)',
-    type: 'die-cut',
-    widthMm: 62,
-    heightMm: 100,
-    colorCapable: false,
-    printAreaDots: 696,
-    leftMarginPins: 0,
-    rightMarginPins: 0,
-    dieCutMaskedAreaDots: 1109,
-  },
-  365: {
-    id: 365,
-    name: '102×51mm die-cut (DK-11240)',
-    type: 'die-cut',
-    widthMm: 102,
-    heightMm: 51,
-    colorCapable: false,
-    printAreaDots: 1164,
-    leftMarginPins: 0,
-    rightMarginPins: 0,
-    dieCutMaskedAreaDots: 526,
-  },
-  366: {
-    id: 366,
-    name: '102×152mm die-cut (DK-11241)',
-    type: 'die-cut',
-    widthMm: 102,
-    heightMm: 152,
-    colorCapable: false,
-    printAreaDots: 1164,
-    leftMarginPins: 0,
-    rightMarginPins: 0,
-    dieCutMaskedAreaDots: 1660,
-  },
-  362: {
-    id: 362,
-    name: '12mm Ø die-cut',
-    type: 'die-cut',
-    widthMm: 12,
-    heightMm: 12,
-    colorCapable: false,
-    printAreaDots: 94,
-    leftMarginPins: 0,
-    rightMarginPins: 0,
-    dieCutMaskedAreaDots: 94,
-  },
-  363: {
-    id: 363,
-    name: '24mm Ø die-cut (DK-11221)',
-    type: 'die-cut',
-    widthMm: 24,
-    heightMm: 24,
-    colorCapable: false,
-    printAreaDots: 236,
-    leftMarginPins: 0,
-    rightMarginPins: 0,
-    dieCutMaskedAreaDots: 236,
-  },
-  273: {
-    id: 273,
-    name: '58mm Ø die-cut (DK-11207)',
-    type: 'die-cut',
-    widthMm: 58,
-    heightMm: 58,
-    colorCapable: false,
-    printAreaDots: 618,
-    leftMarginPins: 0,
-    rightMarginPins: 0,
-    dieCutMaskedAreaDots: 618,
-  },
-};
+export function resolveTapeGeometry(
+  media: BrotherQLMedia,
+  engine: Pick<PrintEngine, 'headDots'>,
+): TapeGeometry {
+  if (media.tapeSystem === 'dk') {
+    if (
+      typeof media.printAreaDots !== '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,
+      leftMarginPins: media.leftMarginPins,
+      rightMarginPins: media.rightMarginPins,
+    };
+  }
+  const family = engine.headDots === 128 ? 'narrow' : 'wide';
+  const geometry = media.geometry?.[family];
+  if (!geometry) {
+    throw new Error(
+      `${media.name} not supported on a ${engine.headDots.toString()}-dot head (no \`geometry.${family}\` entry)`,
+    );
+  }
+  return geometry;
+}
 
 /**
  * Default media when `createPreview()` is called without media and
@@ -272,6 +53,22 @@ export const MEDIA: Record<number, BrotherQLMedia> = {
 // 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]!;
 
+/**
+ * Default media keyed by engine protocol. QL falls back to 62 mm DK
+ * continuous (DK-22205, the common starter roll); PT falls back to
+ * 12 mm TZe (id 404, the most common PT starter tape).
+ */
+// eslint-disable-next-line @typescript-eslint/no-non-null-assertion -- 12 mm TZe is a hard-coded registry key
+export const DEFAULT_PT_MEDIA: BrotherQLMedia = MEDIA[404]!;
+
+/**
+ * Pick a default media entry for an engine. Used by `createPreview()`
+ * when neither user-supplied media nor a detected roll is available.
+ */
+export function defaultMediaForEngine(engine: Pick<PrintEngine, 'protocol'>): BrotherQLMedia {
+  return engine.protocol === 'pt-raster' ? DEFAULT_PT_MEDIA : DEFAULT_MEDIA;
+}
+
 export function findMedia(id: number): BrotherQLMedia | undefined {
   return MEDIA[id];
 }
@@ -289,21 +86,47 @@ export function findMediaByWidth(widthMm: number, type: MediaType): BrotherQLMed
  *                     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.
+ * @param engine      optional engine descriptor used to gate the
+ *                     lookup by tape-system and head-family. When
+ *                     omitted, the search is restricted to DK media —
+ *                     legacy QL behaviour. PT-* callers pass the
+ *                     primary engine so the search returns TZe / HSe
+ *                     entries with the right `narrow` / `wide`
+ *                     geometry, and so a 128-dot head never resolves
+ *                     a 36 mm TZe / 31 mm HSe-3:1 width and
+ *                     PT-P910BT (TZe-only) never resolves an HSe
+ *                     entry.
  */
 export function findMediaByDimensions(
   widthMm: number,
   heightMm: number,
   twoColorMode = false,
+  engine?: Pick<PrintEngine, 'headDots' | 'mediaCompatibility'>,
 ): BrotherQLMedia | undefined {
+  // When no engine is supplied we preserve the original DK-only
+  // behaviour so legacy callers don't suddenly resolve TZe or HSe
+  // entries on width-only ambiguity (e.g. 12 mm DK-22214 vs 12 mm TZe).
+  const tapeSystems: readonly string[] | undefined =
+    engine?.mediaCompatibility ?? (engine ? undefined : ['dk']);
+  const allowed = (m: BrotherQLMedia): boolean => {
+    if (tapeSystems && !tapeSystems.includes(m.tapeSystem)) return false;
+    if (engine && m.tapeSystem !== 'dk') {
+      // TZe / HSe — require the head-family geometry to exist.
+      const family = engine.headDots === 128 ? 'narrow' : 'wide';
+      if (!m.geometry?.[family]) return false;
+    }
+    return true;
+  };
+
   if (heightMm === 0) {
     const continuousMatches = Object.values(MEDIA).filter(
-      m => m.type === 'continuous' && m.widthMm === widthMm,
+      m => m.type === 'continuous' && m.widthMm === widthMm && allowed(m),
     );
     if (continuousMatches.length === 0) return undefined;
-    const preferred = continuousMatches.find(m => m.colorCapable === twoColorMode);
+    const preferred = continuousMatches.find(m => (m.palette !== undefined) === twoColorMode);
     return preferred ?? continuousMatches[0];
   }
   return Object.values(MEDIA).find(
-    m => m.type === 'die-cut' && m.widthMm === widthMm && m.heightMm === heightMm,
+    m => m.type === 'die-cut' && m.widthMm === widthMm && m.heightMm === heightMm && allowed(m),
   );
 }

package/src/orientation.ts

@@ -0,0 +1,11 @@
+import type { RotateDirection } from '@thermal-label/contracts';
+
+/**
+ * Direction the Brother QL print head rotates landscape input.
+ *
+ * `90` = clockwise. Verified once on hardware with a die-cut "F"
+ * landscape print (see plan §6 step 1). Identical across every QL
+ * model — this is a print-head/leading-edge mechanical fact, not a
+ * per-media setting.
+ */
+export const ROTATE_DIRECTION: RotateDirection = 90;

package/src/pack-bits.ts

@@ -0,0 +1,64 @@
+/* eslint-disable @typescript-eslint/no-non-null-assertion --
+ *   `noUncheckedIndexedAccess` types Uint8Array reads as `number | undefined`
+ *   but every index in this file is bounded by `i < input.length` or
+ *   `runEnd < input.length` checks. The `!` assertions collapse the
+ *   unreachable `undefined` branches so branch coverage doesn't count them.
+ */
+
+/**
+ * TIFF-style PackBits row encoder used by Brother QL when compression
+ * mode (`M 02`, emitted by `buildCompression(true)`) is enabled for a job.
+ *
+ * Header byte `n` (interpreted as a signed int8):
+ *   n in [0, 127]:    literal run — the next `n + 1` bytes follow verbatim.
+ *   n in [-127, -1]:  repeat run — the next byte is repeated `1 - n` times.
+ *   n = -128:         no-op. Unused by this encoder.
+ *
+ * The encoder switches to repeat mode for runs of two or more identical
+ * bytes (a 2-byte repeat costs 2 wire bytes; the equivalent 2-byte literal
+ * would cost 3). Both run kinds are capped at 128 bytes to fit the header.
+ *
+ * For a typical Brother QL raster row (90 bytes, mostly zeros in margins
+ * and long runs of `0x00` / `0xff` in print area), this compresses to 5–15
+ * bytes — a 6–18× reduction. Worst-case for highly random input is one
+ * extra byte per 128 (the literal-mode header), i.e. < 1 % expansion.
+ */
+export function packBits(input: Uint8Array): Uint8Array {
+  if (input.length === 0) return new Uint8Array(0);
+
+  const out: number[] = [];
+  let i = 0;
+
+  while (i < input.length) {
+    // How many identical bytes start at position i (cap at 128).
+    let runEnd = i + 1;
+    while (runEnd < input.length && runEnd - i < 128 && input[runEnd] === input[i]) {
+      runEnd++;
+    }
+    const runLen = runEnd - i;
+
+    if (runLen >= 2) {
+      // Repeat run: header is signed -(runLen - 1).
+      out.push((1 - runLen) & 0xff);
+      out.push(input[i]!);
+      i = runEnd;
+      continue;
+    }
+
+    // Otherwise emit a literal run. Stop at 128 bytes, or right before a
+    // 2+ repeat run starts (cheaper to encode that separately).
+    let litEnd = i + 1;
+    while (litEnd < input.length && litEnd - i < 128) {
+      if (litEnd + 1 < input.length && input[litEnd] === input[litEnd + 1]) {
+        break;
+      }
+      litEnd++;
+    }
+    const litLen = litEnd - i;
+    out.push(litLen - 1);
+    for (let x = i; x < litEnd; x++) out.push(input[x]!);
+    i = litEnd;
+  }
+
+  return new Uint8Array(out);
+}

package/src/preview.ts

@@ -1,24 +1,25 @@
-/* eslint-disable import-x/consistent-type-specifier-style */
-import { renderImage, type RawImageData } from '@mbtech-nl/bitmap';
+import { renderImage, renderMultiPlaneImage } from '@mbtech-nl/bitmap';
+import type { LabelBitmap, RawImageData } from '@mbtech-nl/bitmap';
 import type { PreviewResult } from '@thermal-label/contracts';
-import { splitTwoColor } from './colour.js';
-import { type BrotherQLMedia } from './types.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.
+ * Multi-ink aware: when `media.palette` is defined (DK-22251 today),
+ * the image is split per-plane via `renderMultiPlaneImage()` — the
+ * same code path `print()` takes for that media. Single-ink media
+ * returns one black plane via dithered `renderImage`.
  */
 export function createPreviewOffline(image: RawImageData, media: BrotherQLMedia): PreviewResult {
-  if (media.colorCapable) {
-    const { black, red } = splitTwoColor(image);
+  if (media.palette) {
+    const planes = renderMultiPlaneImage(image, {
+      palette: media.palette,
+    }) as Record<'black' | 'red', LabelBitmap>;
     return {
       planes: [
-        { name: 'black', bitmap: black, displayColor: '#000000' },
-        { name: 'red', bitmap: red, displayColor: '#ff0000' },
+        { name: 'black', bitmap: planes.black, displayColor: '#000000' },
+        { name: 'red', bitmap: planes.red, displayColor: '#ff0000' },
       ],
       media,
       assumed: false,