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

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)', () => {
@@ -100,4 +130,260 @@ describe('Media registry invariants', () => {
     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);
+      }
+    }
+  });
 });