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

package/src/media.ts

@@ -1,287 +1,49 @@
-import type { BrotherQLMedia, 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.
- *
- * 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).
- *
- * `palette` is set on multi-ink media (DK-22251, today's only entry) —
- * the driver routes those through `renderMultiPlaneImage` and emits the
- * second plane in the raster job. Single-ink rolls leave it undefined
- * and route through `renderImage` (dithered single-plane).
+ * Resolve per-head-family geometry for a media entry against the
+ * engine that's about to print it.
  *
- * Rectangular die-cut entries declare `defaultOrientation: 'horizontal'`
- * so landscape input auto-rotates to read along the tape feed direction.
- * Continuous wide tape leaves the hint undefined — users may go either
- * way.
- *
- * `cornerRadiusMm` is informational; previews use it to render the
- * actual paper outline. Round die-cut labels set the radius to
- * `widthMm / 2` so the rounded rectangle degenerates to a circle.
+ * 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,
-    printAreaDots: 106,
-    leftMarginPins: 585,
-    rightMarginPins: 29,
-  },
-  258: {
-    id: 258,
-    name: '29mm continuous (DK-22210)',
-    type: 'continuous',
-    widthMm: 29,
-    printAreaDots: 306,
-    leftMarginPins: 408,
-    rightMarginPins: 6,
-  },
-  264: {
-    id: 264,
-    name: '38mm continuous (DK-22225)',
-    type: 'continuous',
-    widthMm: 38,
-    printAreaDots: 413,
-    leftMarginPins: 295,
-    rightMarginPins: 12,
-  },
-  262: {
-    id: 262,
-    name: '50mm continuous (DK-22246)',
-    type: 'continuous',
-    widthMm: 50,
-    printAreaDots: 554,
-    leftMarginPins: 154,
-    rightMarginPins: 12,
-  },
-  261: {
-    id: 261,
-    name: '54mm continuous (DK-22214)',
-    type: 'continuous',
-    widthMm: 54,
-    printAreaDots: 590,
-    leftMarginPins: 130,
-    rightMarginPins: 0,
-  },
-  259: {
-    id: 259,
-    name: '62mm continuous (DK-22205)',
-    type: 'continuous',
-    widthMm: 62,
-    printAreaDots: 696,
-    leftMarginPins: 12,
-    rightMarginPins: 12,
-  },
-  251: {
-    id: 251,
-    name: '62mm continuous two-color (DK-22251)',
-    type: 'continuous',
-    widthMm: 62,
-    palette: [
-      { name: 'black', rgb: [0, 0, 0] },
-      { name: 'red', rgb: [255, 0, 0] },
-    ],
-    printAreaDots: 696,
-    leftMarginPins: 12,
-    rightMarginPins: 12,
-  },
-  260: {
-    id: 260,
-    name: '102mm continuous (DK-22243)',
-    type: 'continuous',
-    widthMm: 102,
-    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,
-    defaultOrientation: 'horizontal',
-    cornerRadiusMm: 3,
-    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,
-    defaultOrientation: 'horizontal',
-    cornerRadiusMm: 3,
-    printAreaDots: 165,
-    leftMarginPins: 0,
-    rightMarginPins: 0,
-    dieCutMaskedAreaDots: 956,
-  },
-  370: {
-    id: 370,
-    name: '23×23mm die-cut',
-    type: 'die-cut',
-    widthMm: 23,
-    heightMm: 23,
-    defaultOrientation: 'horizontal',
-    cornerRadiusMm: 3,
-    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,
-    defaultOrientation: 'horizontal',
-    cornerRadiusMm: 3,
-    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,
-    defaultOrientation: 'horizontal',
-    cornerRadiusMm: 3,
-    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,
-    defaultOrientation: 'horizontal',
-    cornerRadiusMm: 3,
-    printAreaDots: 425,
-    leftMarginPins: 0,
-    rightMarginPins: 0,
-    dieCutMaskedAreaDots: 495,
-  },
-  374: {
-    id: 374,
-    name: '52×29mm die-cut',
-    type: 'die-cut',
-    widthMm: 52,
-    heightMm: 29,
-    defaultOrientation: 'horizontal',
-    cornerRadiusMm: 3,
-    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,
-    defaultOrientation: 'horizontal',
-    cornerRadiusMm: 3,
-    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,
-    defaultOrientation: 'horizontal',
-    cornerRadiusMm: 3,
-    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,
-    defaultOrientation: 'horizontal',
-    cornerRadiusMm: 3,
-    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,
-    defaultOrientation: 'horizontal',
-    cornerRadiusMm: 3,
-    printAreaDots: 1164,
-    leftMarginPins: 0,
-    rightMarginPins: 0,
-    dieCutMaskedAreaDots: 1660,
-  },
-  362: {
-    id: 362,
-    name: '12mm Ø die-cut',
-    type: 'die-cut',
-    widthMm: 12,
-    heightMm: 12,
-    cornerRadiusMm: 6,
-    printAreaDots: 94,
-    leftMarginPins: 0,
-    rightMarginPins: 0,
-    dieCutMaskedAreaDots: 94,
-  },
-  363: {
-    id: 363,
-    name: '24mm Ø die-cut (DK-11221)',
-    type: 'die-cut',
-    widthMm: 24,
-    heightMm: 24,
-    cornerRadiusMm: 12,
-    printAreaDots: 236,
-    leftMarginPins: 0,
-    rightMarginPins: 0,
-    dieCutMaskedAreaDots: 236,
-  },
-  273: {
-    id: 273,
-    name: '58mm Ø die-cut (DK-11207)',
-    type: 'die-cut',
-    widthMm: 58,
-    heightMm: 58,
-    cornerRadiusMm: 29,
-    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
@@ -291,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];
 }
@@ -308,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.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/protocol.ts

@@ -1,9 +1,18 @@
 import { getRow, createBitmap } from '@mbtech-nl/bitmap';
+import type { PrintEngine } from '@thermal-label/contracts';
 import { packBits } from './pack-bits.js';
-import type { BrotherQLMedia, PageData, JobOptions, PageOptions } from './types.js';
+import { resolveTapeGeometry } from './media.js';
+import type {
+  BrotherEngineCapabilities,
+  BrotherQLMedia,
+  PageData,
+  JobOptions,
+  PageOptions,
+  TapeGeometry,
+} from './types.js';
 
-export function buildInvalidate(): Uint8Array {
-  return new Uint8Array(200);
+export function buildInvalidate(byteCount = 200): Uint8Array {
+  return new Uint8Array(byteCount);
 }
 
 export function buildStatusRequest(): Uint8Array {
@@ -58,11 +67,12 @@ export function buildExpandedMode(
   cutAtEnd: boolean,
   highRes: boolean,
   twoColor = false,
+  highResFlagBit = 0x10,
 ): Uint8Array {
   let flags = 0x00;
   if (twoColor) flags |= 0x01;
   if (cutAtEnd) flags |= 0x08;
-  if (highRes) flags |= 0x10;
+  if (highRes) flags |= highResFlagBit;
   return new Uint8Array([0x1b, 0x69, 0x4b, flags]);
 }
 
@@ -135,14 +145,133 @@ function concat(...arrays: Uint8Array[]): Uint8Array {
   return out;
 }
 
-export function encodeJob(pages: PageData[], options: JobOptions = {}): Uint8Array {
+/**
+ * Per-protocol wire-format constants.
+ *
+ * QL and PT raster differ in three numeric constants and one rule —
+ * everything else (status request, raster opcode, PackBits, two-colour
+ * plane encoding) is shared and lives in `encodeRasterJob`. Per the
+ * plan §4.2 / §7, these are protocol-internal and do not leak onto
+ * the device registry.
+ *
+ * - `feedMarginDots` — leading/trailing blank tape (`ESC i d`). QL = 35,
+ *   PT = 14. Per `brother_label/devices.py` and Brother's PT raster
+ *   manual; verify against print output during phase 4.
+ * - `invalidateBytes` — leading invalidate sequence. QL is 200 by
+ *   default but the encoder bumps it to 400 when the engine carries
+ *   `capabilities.twoColor`. PT is always 200 (no two-colour PT model
+ *   exists today).
+ * - `highResFlagBit` — bit set in `ESC i K` flags when `highRes`
+ *   is requested. QL uses bit 4 (0x10) for 300x600; PT uses bit 6
+ *   (0x40) for 180x360 / 360x720 (per nbuchwitz/ptouch).
+ * - `duplicateRasterLines` — when `highRes` is on, PT requires each
+ *   raster line to be sent twice. QL's high-res mode does not.
+ */
+export interface RasterProtocolConfig {
+  feedMarginDots: number;
+  invalidateBytes: number;
+  highResFlagBit: number;
+  duplicateRasterLines: boolean;
+}
+
+export const QL_PROTOCOL_CONFIG: RasterProtocolConfig = {
+  feedMarginDots: 35,
+  invalidateBytes: 200,
+  highResFlagBit: 0x10,
+  duplicateRasterLines: false,
+};
+
+export const PT_PROTOCOL_CONFIG: RasterProtocolConfig = {
+  feedMarginDots: 14,
+  invalidateBytes: 200,
+  highResFlagBit: 0x40,
+  duplicateRasterLines: true,
+};
+
+/** Engine shape consumed by the encoder — narrow `Pick` so unit tests can synthesise minimal stubs. */
+export type EncoderEngine = Pick<PrintEngine, 'protocol' | 'headDots'> & {
+  capabilities?: BrotherEngineCapabilities;
+};
+
+/**
+ * Cutter compression-required quirk.
+ *
+ * PT-E550W silently fails to cut when compression is disabled —
+ * documented in nbuchwitz/ptouch:PTE550W ("E550W requires compression
+ * ON for cutting to work"). Encoded as a per-name guard rather than a
+ * registry capability so we don't promote a one-model bug into the
+ * data shape.
+ */
+const COMPRESSION_REQUIRED_FOR_CUTTER = new Set(['PT-E550W']);
+
+function maybeCheckCutterCompressionQuirk(
+  deviceName: string | undefined,
+  autoCut: boolean,
+  compress: boolean,
+): void {
+  if (autoCut && !compress && deviceName && COMPRESSION_REQUIRED_FOR_CUTTER.has(deviceName)) {
+    throw new Error(
+      `${deviceName} requires compression to be enabled when autocut is on (per nbuchwitz/ptouch)`,
+    );
+  }
+}
+
+/**
+ * Resolve per-page geometry for the encoder.
+ *
+ * QL paths take the flat fields off the media row directly; PT paths
+ * delegate to `resolveTapeGeometry` so the head-family dispatch lives
+ * in one place. `engine` is required for PT and ignored for QL.
+ */
+function resolveEncoderGeometry(
+  media: BrotherQLMedia,
+  engine: EncoderEngine | undefined,
+): 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,
+    };
+  }
+  if (!engine) {
+    throw new Error(
+      `tape system "${media.tapeSystem}" requires an engine to resolve head-family geometry`,
+    );
+  }
+  return resolveTapeGeometry(media, engine);
+}
+
+interface EncodeContext {
+  config: RasterProtocolConfig;
+  engine?: EncoderEngine | undefined;
+  deviceName?: string | undefined;
+}
+
+function encodeRasterJob(pages: PageData[], options: JobOptions, ctx: EncodeContext): Uint8Array {
+  const { config, engine, deviceName } = ctx;
   const copies = options.copies ?? 1;
   const chunks: Uint8Array[] = [];
 
-  // Python brother_ql sequence: raster-mode first, then 200-byte invalidate, then init, then
+  // Two-colour invalidate-byte derivation (§7.1): QL bumps to 400 when
+  // the engine carries `twoColor`. PT has no two-colour models today;
+  // its config keeps invalidateBytes at 200 regardless.
+  const baseInvalidate = config.invalidateBytes;
+  const twoColorInvalidateBoost =
+    engine?.protocol === 'ql-raster' && engine.capabilities?.twoColor === true;
+  const invalidateBytes = twoColorInvalidateBoost ? baseInvalidate * 2 : baseInvalidate;
+
+  // Python brother_ql sequence: raster-mode first, then invalidate, then init, then
   // raster-mode again (matches observed working sequence for QL-820NWB).
   chunks.push(buildRasterMode());
-  chunks.push(buildInvalidate());
+  chunks.push(buildInvalidate(invalidateBytes));
   chunks.push(buildInitialize());
 
   const allPageInstances: PageData[] = [];
@@ -158,10 +287,23 @@ export function encodeJob(pages: PageData[], options: JobOptions = {}): Uint8Arr
     const autoCut = opts.autoCut ?? true;
     const cutAtEnd = opts.cutAtEnd ?? true;
     const highRes = opts.highResolution ?? false;
-    const marginDots = opts.marginDots ?? 35;
     const compress = opts.compress ?? false;
     const { bitmap, media } = page;
 
+    // High-res mode requires the engine to declare `capabilities.highResDpi`.
+    if (highRes && engine && engine.capabilities?.highResDpi === undefined) {
+      throw new Error(
+        `${deviceName ?? 'device'} does not support high-res mode (engine.capabilities.highResDpi is not set)`,
+      );
+    }
+
+    maybeCheckCutterCompressionQuirk(deviceName, autoCut, compress);
+
+    // Per §7.3: PT high-res doubles the feed margin and duplicates
+    // each raster line. QL high-res leaves both untouched.
+    const baseMargin = opts.marginDots ?? config.feedMarginDots;
+    const marginDots = config.duplicateRasterLines && highRes ? baseMargin * 2 : baseMargin;
+
     // Multi-ink 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 multiInk = media.palette !== undefined;
@@ -182,34 +324,41 @@ export function encodeJob(pages: PageData[], options: JobOptions = {}): Uint8Arr
     chunks.push(buildPrintInfo(media, rowCount, i));
     chunks.push(buildVariousMode(autoCut));
     chunks.push(buildCutEach(1));
-    chunks.push(buildExpandedMode(cutAtEnd, highRes, twoColor));
+    chunks.push(buildExpandedMode(cutAtEnd, highRes, twoColor, config.highResFlagBit));
     chunks.push(buildMargin(marginDots));
     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 or 1296).
-    const totalPins = media.leftMarginPins + media.printAreaDots + media.rightMarginPins;
+    // leftMarginPins + printAreaDots + 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 rowByteLen = Math.ceil(totalPins / 8);
 
     // Rows interleaved per raster line (matches Python brother_ql behaviour).
     // Two-color: black row then red row for each line. Single-color: black only.
     // When `compress` is on, each row's bytes are PackBits-encoded and the
-    // raster-row LEN byte carries the compressed length. The printer was
-    // already switched into compression mode by `buildCompression(true)`
-    // above, so it expects every subsequent row to be PackBits.
+    // raster-row LEN byte carries the compressed length.
+    //
+    // Per §7.3: PT high-res duplicates each raster line. QL doesn't.
+    const duplicate = config.duplicateRasterLines && highRes;
     for (let r = 0; r < rowCount; r++) {
       const blackSrc = getRow(bitmap, r);
       const blackBytes = new Uint8Array(rowByteLen);
-      placeBits(blackSrc, bitmap.widthPx, blackBytes, media.leftMarginPins);
+      placeBits(blackSrc, bitmap.widthPx, blackBytes, leftMarginPins);
       const blackPayload = compress ? packBits(blackBytes) : blackBytes;
-      chunks.push(buildRasterRow(blackPayload, 'black', twoColor));
+      const blackChunk = buildRasterRow(blackPayload, 'black', twoColor);
+      chunks.push(blackChunk);
+      if (duplicate) chunks.push(blackChunk);
 
       if (twoColor && redBitmap !== undefined) {
         const redSrc = getRow(redBitmap, r);
         const redBytes = new Uint8Array(rowByteLen);
-        placeBits(redSrc, redBitmap.widthPx, redBytes, media.leftMarginPins);
+        placeBits(redSrc, redBitmap.widthPx, redBytes, leftMarginPins);
         const redPayload = compress ? packBits(redBytes) : redBytes;
-        chunks.push(buildRasterRow(redPayload, 'red', twoColor));
+        const redChunk = buildRasterRow(redPayload, 'red', twoColor);
+        chunks.push(redChunk);
+        if (duplicate) chunks.push(redChunk);
       }
     }
 
@@ -218,3 +367,32 @@ export function encodeJob(pages: PageData[], options: JobOptions = {}): Uint8Arr
 
   return concat(...chunks);
 }
+
+/**
+ * Encode a QL job. Public legacy entry point — DK media only, no
+ * engine awareness, two-colour invalidate-byte boost not applied.
+ * Use `encodeJobForEngine` for PT or for QL with two-colour invalidate
+ * derivation from `engine.capabilities.twoColor`.
+ */
+export function encodeJob(pages: PageData[], options: JobOptions = {}): Uint8Array {
+  return encodeRasterJob(pages, options, { config: QL_PROTOCOL_CONFIG });
+}
+
+/**
+ * Encode a job for a specific engine. Dispatches on `engine.protocol`:
+ * `'ql-raster'` picks the QL config, `'pt-raster'` picks the PT config
+ * and threads `engine.headDots` through to head-family geometry
+ * resolution for TZe / HSe media.
+ *
+ * `deviceName` is optional; when supplied, it enables the per-name
+ * cutter-compression guard for PT-E550W (§7.2 / §12.12).
+ */
+export function encodeJobForEngine(
+  pages: PageData[],
+  options: JobOptions,
+  engine: EncoderEngine,
+  deviceName?: string,
+): Uint8Array {
+  const config = engine.protocol === 'pt-raster' ? PT_PROTOCOL_CONFIG : QL_PROTOCOL_CONFIG;
+  return encodeRasterJob(pages, options, { config, engine, deviceName });
+}