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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thermal-label/brother-ql-core",
-  "version": "0.2.1",
+  "version": "0.4.0",
   "description": "Protocol encoding, device registry, and media registry for Brother QL label printers",
   "keywords": [
     "brother",
@@ -35,10 +35,12 @@
   "files": [
     "dist",
     "src",
+    "data/devices.json",
+    "data/media.json",
     "README.md"
   ],
   "engines": {
-    "node": ">=24.0.0"
+    "node": ">=20.9.0"
   },
   "publishConfig": {
     "access": "public"
@@ -53,20 +55,22 @@
     }
   },
   "dependencies": {
-    "@mbtech-nl/bitmap": "^0.1.0",
-    "@thermal-label/contracts": "^0.1.2"
+    "@mbtech-nl/bitmap": "^1.3.0",
+    "@thermal-label/contracts": "^0.3.1"
   },
   "devDependencies": {
-    "@mbtech-nl/tsconfig": "^1.0.0",
+    "@mbtech-nl/tsconfig": "^1.1.0",
     "@types/node": "^22.0.0",
     "@vitest/coverage-v8": "^2.1.9",
+    "json5": "^2.2.3",
     "typescript": "~5.5.0",
     "vitest": "^2.0.0"
   },
   "scripts": {
-    "build": "tsc -p tsconfig.json",
-    "typecheck": "tsc -p tsconfig.json --noEmit",
-    "test": "vitest run",
-    "test:coverage": "vitest run --coverage"
+    "compile-data": "node ../../scripts/compile-data.mjs",
+    "build": "pnpm run compile-data && tsc -p tsconfig.json",
+    "typecheck": "pnpm run compile-data && tsc -p tsconfig.json --noEmit",
+    "test": "pnpm run compile-data && vitest run",
+    "test:coverage": "pnpm run compile-data && vitest run --coverage"
   }
 }

package/src/__tests__/devices.test.ts

@@ -1,26 +1,27 @@
 import { describe, it, expect } from 'vitest';
-import { DEVICES, findDevice, isMassStorageMode } from '../devices.js';
+import { DEVICES, findDevice, getUsbIds, isMassStorageMode } from '../devices.js';
 
 describe('findDevice', () => {
-  it('returns correct descriptor for QL-820NWB', () => {
-    const dev = findDevice(0x04f9, 0x20a7);
+  it('returns correct entry for QL-820NWBc (PID shared with QL-820NWB)', () => {
+    const dev = findDevice(0x04f9, 0x209d);
     expect(dev).toBeDefined();
-    expect(dev!.name).toBe('QL-820NWB');
-    expect(dev!.twoColor).toBe(true);
+    expect(dev!.name).toBe('QL-820NWBc');
+    expect(dev!.engines[0]?.capabilities?.twoColor).toBe(true);
   });
 
-  it('returns correct descriptor for QL-820NWBc', () => {
-    const dev = findDevice(0x04f9, 0x209d);
+  it('returns correct entry for QL-1100', () => {
+    const dev = findDevice(0x04f9, 0x20a7);
     expect(dev).toBeDefined();
-    expect(dev!.name).toBe('QL-820NWBc');
-    expect(dev!.twoColor).toBe(true);
+    expect(dev!.name).toBe('QL-1100');
+    expect(dev!.engines[0]?.headDots).toBe(1296);
   });
 
-  it('returns correct descriptor for QL-500', () => {
+  it('returns correct entry for QL-500', () => {
     const dev = findDevice(0x04f9, 0x2013);
     expect(dev).toBeDefined();
     expect(dev!.name).toBe('QL-500');
-    expect(dev!.autocut).toBe(false);
+    // QL-500 has no autocut — the capability flag is absent.
+    expect(dev!.engines[0]?.capabilities?.autocut).toBeUndefined();
   });
 
   it('returns undefined for unknown PID', () => {
@@ -28,39 +29,44 @@ describe('findDevice', () => {
   });
 
   it('returns undefined for unknown VID', () => {
-    expect(findDevice(0x1234, 0x20a7)).toBeUndefined();
+    expect(findDevice(0x1234, 0x209d)).toBeUndefined();
   });
 });
 
 describe('isMassStorageMode', () => {
-  it('returns true for 0x20AA (QL-1100 mass storage)', () => {
+  it('returns true for 0x20a9 (QL-1100 mass storage)', () => {
+    expect(isMassStorageMode(0x20a9)).toBe(true);
+  });
+
+  it('returns true for 0x20aa (QL-1110NWB mass storage)', () => {
     expect(isMassStorageMode(0x20aa)).toBe(true);
   });
 
-  it('returns true for 0x20AB (QL-1110NWB mass storage)', () => {
-    expect(isMassStorageMode(0x20ab)).toBe(true);
+  it('returns true for 0x20ac (QL-1115NWB mass storage)', () => {
+    expect(isMassStorageMode(0x20ac)).toBe(true);
   });
 
   it('returns false for all printer-class PIDs', () => {
     for (const dev of Object.values(DEVICES)) {
-      expect(isMassStorageMode(dev.pid)).toBe(false);
+      const ids = getUsbIds(dev);
+      if (ids) expect(isMassStorageMode(ids.pid)).toBe(false);
     }
   });
 });
 
 describe('Device registry invariants', () => {
-  it('every two-color device has bytesPerRow 90', () => {
+  it('every two-color device has a 720-dot engine', () => {
     for (const dev of Object.values(DEVICES)) {
-      if (dev.twoColor) {
-        expect(dev.bytesPerRow).toBe(90);
+      if (dev.engines[0]?.capabilities?.twoColor) {
+        expect(dev.engines[0].headDots).toBe(720);
       }
     }
   });
 
-  it('every device with headPins 1296 has bytesPerRow 162', () => {
+  it('every device with headDots 1296 belongs to the QL-1xxx series', () => {
     for (const dev of Object.values(DEVICES)) {
-      if (dev.headPins === 1296) {
-        expect(dev.bytesPerRow).toBe(162);
+      if (dev.engines[0]?.headDots === 1296) {
+        expect(dev.name).toMatch(/^QL-1\d{3}/);
       }
     }
   });
@@ -71,19 +77,103 @@ describe('Device registry invariants', () => {
     }
   });
 
-  it('QL-820NWB(c) advertise serial/web-serial for OS-paired Bluetooth', () => {
-    for (const key of ['QL_820NWB', 'QL_820NWBc'] as const) {
-      const dev = DEVICES[key];
-      expect(dev.transports).toContain('serial');
-      expect(dev.transports).toContain('web-serial');
+  it('every device declares a USB transport with hex-string vid+pid', () => {
+    for (const dev of Object.values(DEVICES)) {
+      expect(dev.transports.usb).toBeDefined();
+      expect(dev.transports.usb!.vid).toMatch(/^0x[0-9a-f]+$/);
+      expect(dev.transports.usb!.pid).toMatch(/^0x[0-9a-f]+$/);
     }
   });
+});
 
-  it('no device descriptor declares web-bluetooth', () => {
-    // Bluetooth on the 820 series is classic SPP, not GATT — the
-    // serial transports cover it. See packages/core/src/types.ts.
-    for (const dev of Object.values(DEVICES)) {
-      expect(dev.transports).not.toContain('web-bluetooth');
+describe('PT-* device entries', () => {
+  const PT_KEYS = ['PT_E550W', 'PT_P750W', 'PT_P900', 'PT_P900W', 'PT_P950NW', 'PT_P910BT'];
+
+  it('every PT entry resolves by (vid, pid)', () => {
+    const expected: Record<string, number> = {
+      PT_E550W: 0x2060,
+      PT_P750W: 0x2062,
+      PT_P900: 0x2083,
+      PT_P900W: 0x2085,
+      PT_P950NW: 0x2086,
+      PT_P910BT: 0x20c7,
+    };
+    for (const key of PT_KEYS) {
+      const pid = expected[key]!;
+      const dev = findDevice(0x04f9, pid);
+      expect(dev, key).toBeDefined();
+      expect(dev!.key).toBe(key);
+    }
+  });
+
+  it('every PT engine uses the pt-raster protocol', () => {
+    for (const key of PT_KEYS) {
+      const dev = DEVICES[key as keyof typeof DEVICES];
+      expect(dev.engines[0]?.protocol, key).toBe('pt-raster');
+    }
+  });
+
+  it('every PT engine has headDots in {128, 560}', () => {
+    for (const key of PT_KEYS) {
+      const dev = DEVICES[key as keyof typeof DEVICES];
+      expect([128, 560]).toContain(dev.engines[0]?.headDots);
+    }
+  });
+
+  it('PT high-res dpi is exactly 2× the native dpi', () => {
+    for (const key of PT_KEYS) {
+      const dev = DEVICES[key as keyof typeof DEVICES];
+      const engine = dev.engines[0]!;
+      const dpi = engine.dpi;
+      const highResDpi = engine.capabilities?.highResDpi as number | undefined;
+      expect(highResDpi, `${key} highResDpi`).toBeDefined();
+      expect(highResDpi).toBe(dpi * 2);
+    }
+  });
+
+  it('128-dot family is 180 dpi, 560-dot family is 360 dpi', () => {
+    for (const key of PT_KEYS) {
+      const dev = DEVICES[key as keyof typeof DEVICES];
+      const engine = dev.engines[0]!;
+      if (engine.headDots === 128) expect(engine.dpi).toBe(180);
+      else if (engine.headDots === 560) expect(engine.dpi).toBe(360);
     }
   });
+
+  it('every PT entry ships untested', () => {
+    for (const key of PT_KEYS) {
+      const dev = DEVICES[key as keyof typeof DEVICES];
+      expect(dev.support.status).toBe('untested');
+    }
+  });
+
+  it('PT-P910BT is TZe-only (no HSe in mediaCompatibility)', () => {
+    const dev = DEVICES.PT_P910BT;
+    expect(dev.engines[0]?.mediaCompatibility).toEqual(['tze']);
+  });
+
+  it('all other PT models declare TZe + HSe 2:1 + HSe 3:1', () => {
+    for (const key of ['PT_E550W', 'PT_P750W', 'PT_P900', 'PT_P900W', 'PT_P950NW']) {
+      const dev = DEVICES[key as keyof typeof DEVICES];
+      expect(dev.engines[0]?.mediaCompatibility, key).toEqual(['tze', 'hse-2to1', 'hse-3to1']);
+    }
+  });
+
+  it('PT-P750W carries both printer PID 0x2062 and mass-storage PID 0x2065', () => {
+    const dev = DEVICES.PT_P750W;
+    expect(dev.transports.usb?.pid).toBe('0x2062');
+    expect(dev.capabilities?.massStoragePid).toBe('0x2065');
+    expect(isMassStorageMode(0x2065)).toBe(true);
+  });
+
+  it('PT-P910BT declares bluetooth-spp transport', () => {
+    const dev = DEVICES.PT_P910BT;
+    expect(dev.transports['bluetooth-spp']).toBeDefined();
+    expect(dev.transports['bluetooth-spp']?.namePrefix).toBe('PT-P910');
+  });
+
+  it('PT-P900 is USB-only (no tcp / bluetooth)', () => {
+    const dev = DEVICES.PT_P900;
+    expect(Object.keys(dev.transports).sort()).toEqual(['usb']);
+  });
 });

package/src/__tests__/media.test.ts

@@ -1,5 +1,35 @@
 import { describe, it, expect } from 'vitest';
-import { MEDIA, findMedia, findMediaByWidth } from '../media.js';
+import { mediaCompatibleWith, type PrintEngine } from '@thermal-label/contracts';
+import {
+  MEDIA,
+  defaultMediaForEngine,
+  findMedia,
+  findMediaByDimensions,
+  findMediaByWidth,
+  resolveTapeGeometry,
+} from '../media.js';
+import { DEVICES } from '../devices.js';
+
+const NARROW_PT_ENGINE = {
+  protocol: 'pt-raster' as const,
+  headDots: 128,
+  mediaCompatibility: ['tze', 'hse-2to1', 'hse-3to1'],
+};
+const WIDE_PT_ENGINE = {
+  protocol: 'pt-raster' as const,
+  headDots: 560,
+  mediaCompatibility: ['tze', 'hse-2to1', 'hse-3to1'],
+};
+const TZE_ONLY_PT_ENGINE = {
+  protocol: 'pt-raster' as const,
+  headDots: 560,
+  mediaCompatibility: ['tze'],
+};
+const QL_ENGINE = {
+  protocol: 'ql-raster' as const,
+  headDots: 720,
+  mediaCompatibility: ['dk'],
+};
 
 describe('findMedia', () => {
   it('returns correct descriptor for 62mm continuous (ID 259)', () => {
@@ -63,19 +93,297 @@ describe('Media registry invariants', () => {
     }
   });
 
-  it('only DK-22251 is colorCapable', () => {
+  it('only DK-22251 carries a multi-ink palette', () => {
     for (const m of Object.values(MEDIA)) {
       if (m.id === 251) {
-        expect(m.colorCapable).toBe(true);
+        expect(m.palette).toBeDefined();
+        const palette = m.palette!;
+        expect(palette).toHaveLength(2);
+        expect(palette[0]!.name).toBe('black');
+        expect(palette[1]!.name).toBe('red');
       } else {
-        expect(m.colorCapable).toBe(false);
+        expect(m.palette).toBeUndefined();
       }
     }
   });
 
+  it('rectangular die-cut entries declare defaultOrientation: horizontal', () => {
+    const rectangularDieCutIds = [269, 270, 370, 271, 272, 367, 374, 274, 275, 365, 366];
+    for (const id of rectangularDieCutIds) {
+      const m = MEDIA[id]!;
+      expect(m, `entry ${id.toString()}`).toBeDefined();
+      expect(m.defaultOrientation, `entry ${id.toString()}`).toBe('horizontal');
+    }
+  });
+
+  it('round die-cut entries set cornerRadiusMm to widthMm / 2', () => {
+    const roundDieCutIds = [362, 363, 273];
+    for (const id of roundDieCutIds) {
+      const m = MEDIA[id]!;
+      expect(m, `entry ${id.toString()}`).toBeDefined();
+      expect(m.cornerRadiusMm, `entry ${id.toString()}`).toBe(m.widthMm / 2);
+    }
+  });
+
   it('all IDs are unique', () => {
     const ids = Object.values(MEDIA).map(m => m.id);
     const unique = new Set(ids);
     expect(unique.size).toBe(ids.length);
   });
+
+  it('every entry declares a tape system', () => {
+    for (const m of Object.values(MEDIA)) {
+      expect(m.tapeSystem, `entry ${m.id.toString()}`).toBeDefined();
+    }
+  });
+
+  it('TZe ids occupy the 401-419 range, HSe 421-459', () => {
+    for (const m of Object.values(MEDIA)) {
+      if (m.tapeSystem === 'tze') {
+        expect(m.id, m.name).toBeGreaterThanOrEqual(401);
+        expect(m.id, m.name).toBeLessThanOrEqual(419);
+      } else if (m.tapeSystem === 'hse-2to1') {
+        expect(m.id, m.name).toBeGreaterThanOrEqual(421);
+        expect(m.id, m.name).toBeLessThanOrEqual(439);
+      } else if (m.tapeSystem === 'hse-3to1') {
+        expect(m.id, m.name).toBeGreaterThanOrEqual(441);
+        expect(m.id, m.name).toBeLessThanOrEqual(459);
+      } else {
+        expect(m.tapeSystem, m.name).toBe('dk');
+      }
+    }
+  });
+
+  it('TZe / HSe pin sums equal the head-family pin count', () => {
+    for (const m of Object.values(MEDIA)) {
+      if (m.tapeSystem === 'dk') continue;
+      if (m.geometry?.narrow) {
+        const { leftMarginPins, printAreaDots, rightMarginPins } = m.geometry.narrow;
+        expect(leftMarginPins + printAreaDots + rightMarginPins, `${m.name} narrow head sum`).toBe(
+          128,
+        );
+      }
+      if (m.geometry?.wide) {
+        const { leftMarginPins, printAreaDots, rightMarginPins } = m.geometry.wide;
+        expect(leftMarginPins + printAreaDots + rightMarginPins, `${m.name} wide head sum`).toBe(
+          560,
+        );
+      }
+    }
+  });
+
+  it('36 mm TZe and 31 mm HSe-3:1 are wide-head only', () => {
+    expect(MEDIA[407]!.geometry?.narrow).toBeUndefined();
+    expect(MEDIA[407]!.geometry?.wide).toBeDefined();
+    expect(MEDIA[445]!.geometry?.narrow).toBeUndefined();
+    expect(MEDIA[445]!.geometry?.wide).toBeDefined();
+  });
+});
+
+describe('findMediaByDimensions — engine gating', () => {
+  it('legacy call (no engine) keeps DK-only behaviour for 12 mm continuous', () => {
+    const m = findMediaByDimensions(12, 0);
+    expect(m).toBeDefined();
+    expect(m!.tapeSystem).toBe('dk');
+    expect(m!.id).toBe(257);
+  });
+
+  it('QL engine for 12 mm returns the DK entry, never a TZe entry', () => {
+    const m = findMediaByDimensions(12, 0, false, QL_ENGINE);
+    expect(m!.tapeSystem).toBe('dk');
+    expect(m!.id).toBe(257);
+  });
+
+  it('narrow PT engine for 12 mm returns the 128-dot TZe entry', () => {
+    const m = findMediaByDimensions(12, 0, false, NARROW_PT_ENGINE);
+    expect(m!.tapeSystem).toBe('tze');
+    expect(m!.id).toBe(404);
+    expect(m!.geometry?.narrow).toBeDefined();
+  });
+
+  it('wide PT engine for 12 mm returns the same TZe row (geometry resolves later)', () => {
+    const m = findMediaByDimensions(12, 0, false, WIDE_PT_ENGINE);
+    expect(m!.tapeSystem).toBe('tze');
+    expect(m!.id).toBe(404);
+    expect(m!.geometry?.wide).toBeDefined();
+  });
+
+  it('narrow PT engine cannot reach 36 mm TZe', () => {
+    const m = findMediaByDimensions(36, 0, false, NARROW_PT_ENGINE);
+    expect(m).toBeUndefined();
+  });
+
+  it('wide PT engine resolves 36 mm TZe', () => {
+    const m = findMediaByDimensions(36, 0, false, WIDE_PT_ENGINE);
+    expect(m!.id).toBe(407);
+  });
+
+  it('narrow PT engine cannot reach 31 mm HSe-3:1', () => {
+    const m = findMediaByDimensions(31, 0, false, NARROW_PT_ENGINE);
+    expect(m).toBeUndefined();
+  });
+
+  it('wide PT engine resolves 31 mm HSe-3:1', () => {
+    const m = findMediaByDimensions(31, 0, false, WIDE_PT_ENGINE);
+    expect(m!.id).toBe(445);
+  });
+
+  it('TZe-only PT engine never returns HSe entries', () => {
+    expect(findMediaByDimensions(11.7, 0, false, TZE_ONLY_PT_ENGINE)).toBeUndefined();
+    expect(findMediaByDimensions(5.2, 0, false, TZE_ONLY_PT_ENGINE)).toBeUndefined();
+    expect(findMediaByDimensions(31, 0, false, TZE_ONLY_PT_ENGINE)).toBeUndefined();
+  });
+
+  it('TZe-only PT engine still resolves TZe widths', () => {
+    const m = findMediaByDimensions(24, 0, false, TZE_ONLY_PT_ENGINE);
+    expect(m!.tapeSystem).toBe('tze');
+  });
+});
+
+describe('resolveTapeGeometry', () => {
+  it('returns flat fields for DK entries regardless of engine head dots', () => {
+    const dk = MEDIA[259]!;
+    const geom = resolveTapeGeometry(dk, { headDots: 720 });
+    expect(geom.printAreaDots).toBe(696);
+  });
+
+  it('routes TZe through narrow / wide based on engine.headDots', () => {
+    const tze12 = MEDIA[404]!;
+    const narrow = resolveTapeGeometry(tze12, { headDots: 128 });
+    expect(narrow.printAreaDots).toBe(70);
+    const wide = resolveTapeGeometry(tze12, { headDots: 560 });
+    expect(wide.printAreaDots).toBe(150);
+  });
+
+  it('throws when the requested head family has no geometry', () => {
+    expect(() => resolveTapeGeometry(MEDIA[407]!, { headDots: 128 })).toThrow(/narrow/);
+    expect(() => resolveTapeGeometry(MEDIA[445]!, { headDots: 128 })).toThrow(/narrow/);
+  });
+});
+
+describe('defaultMediaForEngine', () => {
+  it('returns DK-22205 for QL engines', () => {
+    expect(defaultMediaForEngine({ protocol: 'ql-raster' }).id).toBe(259);
+  });
+
+  it('returns 12 mm TZe for PT engines', () => {
+    expect(defaultMediaForEngine({ protocol: 'pt-raster' }).id).toBe(404);
+  });
+});
+
+describe('Substrate-gate field-shape invariants', () => {
+  it('every entry declares a non-empty targetModels', () => {
+    for (const m of Object.values(MEDIA)) {
+      expect(m.targetModels, m.name).toBeDefined();
+      expect(m.targetModels!.length, m.name).toBeGreaterThan(0);
+    }
+  });
+
+  it('every entry declares a category', () => {
+    for (const m of Object.values(MEDIA)) {
+      expect(m.category, m.name).toBeDefined();
+    }
+  });
+
+  it('targetModels is consistent with tapeSystem', () => {
+    for (const m of Object.values(MEDIA)) {
+      // DK rolls allow either 'dk' or 'dk-wide' in targetModels — both
+      // are DK-substrate tags. Other tape systems carry the bare value.
+      if (m.tapeSystem === 'dk') {
+        const ok = m.targetModels!.includes('dk') || m.targetModels!.includes('dk-wide');
+        expect(ok, `${m.name} targetModels=${JSON.stringify(m.targetModels)}`).toBe(true);
+      } else {
+        expect(m.targetModels, m.name).toContain(m.tapeSystem);
+      }
+    }
+  });
+
+  it('every DK row with widthMm > 62 is tagged dk-wide', () => {
+    for (const m of Object.values(MEDIA)) {
+      if (m.tapeSystem === 'dk' && m.widthMm > 62) {
+        expect(m.targetModels, `${m.name} (id ${m.id.toString()})`).toContain('dk-wide');
+      }
+    }
+  });
+
+  it('every QL-1xxx engine accepts both dk and dk-wide', () => {
+    const wideKeys = ['QL_1050', 'QL_1060N', 'QL_1100', 'QL_1110NWB', 'QL_1115NWB'] as const;
+    for (const key of wideKeys) {
+      const compat = DEVICES[key].engines[0]!.mediaCompatibility;
+      expect(compat, key).toContain('dk');
+      expect(compat, key).toContain('dk-wide');
+    }
+  });
+
+  it('no narrow QL chassis lists dk-wide', () => {
+    for (const d of Object.values(DEVICES)) {
+      if (!d.key.startsWith('QL_')) continue;
+      // The five 1296-dot chassis are the wide tier; everything else is 720-dot.
+      const headDots = d.engines[0]!.headDots;
+      if (headDots === 720) {
+        expect(d.engines[0]!.mediaCompatibility, d.key).not.toContain('dk-wide');
+      }
+    }
+  });
+});
+
+describe('Substrate-gate enforcement matrix (mediaCompatibleWith)', () => {
+  // Representative engines for each compatibility class. The matrix
+  // walks every media row against each and asserts the cell — catches
+  // a row losing its targetModels (would falsely match every engine),
+  // an HSe row mistagged 'tze', a 102 mm row losing 'dk-wide', or a
+  // future engine dropping the substrate tag.
+  const CLASSES: Record<string, PrintEngine> = {
+    qlStandard: DEVICES.QL_700.engines[0]!,
+    qlWide: DEVICES.QL_1100.engines[0]!,
+    ptTzeHse: DEVICES.PT_P900.engines[0]!,
+    ptTzeOnly: DEVICES.PT_P910BT.engines[0]!,
+  };
+
+  type ClassKey = keyof typeof CLASSES;
+  // For a media row, returns the set of class keys that should accept it.
+  function expectedClassesFor(m: {
+    tapeSystem: string;
+    targetModels?: readonly string[];
+  }): Set<ClassKey> {
+    const isWide = m.targetModels?.includes('dk-wide') ?? false;
+    const set = new Set<ClassKey>();
+    if (m.tapeSystem === 'dk') {
+      if (isWide) {
+        set.add('qlWide');
+      } else {
+        set.add('qlStandard');
+        set.add('qlWide');
+      }
+    } else if (m.tapeSystem === 'tze') {
+      set.add('ptTzeHse');
+      set.add('ptTzeOnly');
+    } else if (m.tapeSystem === 'hse-2to1' || m.tapeSystem === 'hse-3to1') {
+      set.add('ptTzeHse');
+    }
+    return set;
+  }
+
+  it('every (engine class, media row) cell matches expectation', () => {
+    for (const m of Object.values(MEDIA)) {
+      const expected = expectedClassesFor(m);
+      for (const key of Object.keys(CLASSES)) {
+        const got = mediaCompatibleWith(m, CLASSES[key]!);
+        const want = expected.has(key);
+        expect(got, `${m.name} (id ${m.id.toString()}) on ${key}`).toBe(want);
+      }
+    }
+  });
+
+  it('PT-P910BT does not surface HSe media', () => {
+    // Strictly redundant with the matrix above, but worth keeping
+    // separately so a future bisect on a "P910BT shows HSe media"
+    // report finds a test named after the case.
+    const engine = DEVICES.PT_P910BT.engines[0]!;
+    for (const m of Object.values(MEDIA)) {
+      if (m.tapeSystem === 'hse-2to1' || m.tapeSystem === 'hse-3to1') {
+        expect(mediaCompatibleWith(m, engine), m.name).toBe(false);
+      }
+    }
+  });
 });

package/src/__tests__/pack-bits.test.ts

@@ -0,0 +1,92 @@
+import { describe, expect, it } from 'vitest';
+import { packBits } from '../pack-bits.js';
+
+// Reference TIFF PackBits decoder. Used to round-trip arbitrary inputs and
+// confirm the encoder emits a stream the canonical algorithm can decode.
+function unpackBits(input: Uint8Array): Uint8Array {
+  const out: number[] = [];
+  let i = 0;
+  while (i < input.length) {
+    const header = input[i]!;
+    const signed = header > 127 ? header - 256 : header;
+    if (signed >= 0) {
+      const n = signed + 1;
+      for (let j = 0; j < n; j++) out.push(input[i + 1 + j]!);
+      i += 1 + n;
+    } else if (signed >= -127) {
+      const n = 1 - signed;
+      for (let j = 0; j < n; j++) out.push(input[i + 1]!);
+      i += 2;
+    } else {
+      i++; // signed === -128: no-op
+    }
+  }
+  return new Uint8Array(out);
+}
+
+describe('packBits', () => {
+  it('emits empty output for empty input', () => {
+    expect(packBits(new Uint8Array(0)).length).toBe(0);
+  });
+
+  it('encodes a single byte as a 1-byte literal', () => {
+    expect(Array.from(packBits(new Uint8Array([0x42])))).toEqual([0x00, 0x42]);
+  });
+
+  it('encodes a 2-byte repeat as 2 wire bytes', () => {
+    // -(2-1) = -1 → 0xFF
+    expect(Array.from(packBits(new Uint8Array([0x42, 0x42])))).toEqual([0xff, 0x42]);
+  });
+
+  it('compresses an all-zero 90-byte row to 2 bytes (the common case)', () => {
+    const result = packBits(new Uint8Array(90));
+    // -(90-1) = -89 = 0xA7
+    expect(Array.from(result)).toEqual([0xa7, 0x00]);
+  });
+
+  it('caps repeat runs at 128 bytes — 130 zeros split into 128 + 2', () => {
+    const result = packBits(new Uint8Array(130));
+    // -(128-1) = -127 = 0x81; -(2-1) = -1 = 0xFF
+    expect(Array.from(result)).toEqual([0x81, 0x00, 0xff, 0x00]);
+  });
+
+  it('caps literal runs at 128 bytes', () => {
+    // 130 distinct bytes split into 128 + 2 literals.
+    const input = new Uint8Array(130);
+    for (let i = 0; i < 130; i++) input[i] = i & 0xff;
+    const result = packBits(input);
+    expect(result[0]).toBe(0x7f); // header for 128 literals
+    expect(result[129]).toBe(0x01); // header for 2 literals
+    expect(result.length).toBe(132);
+  });
+
+  it('mixes literal and repeat runs', () => {
+    // A A B C D D D E
+    const input = new Uint8Array([0x10, 0x10, 0x20, 0x30, 0x40, 0x40, 0x40, 0x50]);
+    expect(Array.from(packBits(input))).toEqual([
+      0xff,
+      0x10, // -1: 2 repeats of 0x10
+      0x01,
+      0x20,
+      0x30, // 1: 2 literals
+      0xfe,
+      0x40, // -2: 3 repeats of 0x40
+      0x00,
+      0x50, // 0: 1 literal
+    ]);
+  });
+
+  it('round-trips a label-like row (margins + bar + scattered) through the spec decoder', () => {
+    // Mimic a typical raster row: 12 zero-byte margin, 50 bytes of 0xFF
+    // (solid bar), 12 mixed bytes (text), 16 zero-byte trailing margin.
+    const original = new Uint8Array(90);
+    for (let i = 12; i < 62; i++) original[i] = 0xff;
+    for (let i = 62; i < 74; i++) original[i] = (i * 7) & 0xff;
+
+    const compressed = packBits(original);
+    const decoded = unpackBits(compressed);
+    expect(Array.from(decoded)).toEqual(Array.from(original));
+    // And it actually saves bytes — the whole point.
+    expect(compressed.length).toBeLessThan(original.length);
+  });
+});