@nfcard/validation 0.12.0 → 0.14.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nfcard/validation",
-  "version": "0.12.0",
+  "version": "0.14.0",
   "description": "Shared Zod validation schemas for the NFCard product family.",
   "type": "module",
   "main": "./dist/index.js",
@@ -17,7 +17,7 @@
   ],
   "dependencies": {
     "zod": "^3.24.0",
-    "@nfcard/types": "0.11.0"
+    "@nfcard/types": "0.13.0"
   },
   "devDependencies": {
     "tsup": "^8.0.0"

package/src/elements.test.ts

@@ -1,214 +1,214 @@
-import { describe, expect, it } from 'vitest'
-import { cardDesignSchema, cardAssetSchema } from './index'
-import {
-  CHIP_SCALE_FLOOR,
-  QR_MIN_SIZE_MM,
-  chipAnchorToMm,
-  mmToNearestChipAnchor,
-  elementPrintability,
-  type ChipAxis,
-} from './printability'
-
-// A legacy (grid-only) 3D card design — unchanged shape, no elements[].
-const legacyDesign = {
-  material: '3dprint_standard',
-  designType: 'custom',
-  thicknessMm: 1.8,
-  pattern: null,
-  layout: { chipAnchor: { col: 0, row: 1 } },
-  filaments: { background: '#F2F1ED', text: '#1A1A1A', accent: '#3FA34D' },
-}
-
-const chipEl = (over = {}) => ({
-  id: 'chip1',
-  type: 'chip',
-  shape: 0,
-  transform: { xMm: 0, yMm: 0, rotationDeg: 0, scale: 1, z: 0 },
-  ...over,
-})
-const textEl = (over = {}) => ({
-  id: 't1',
-  type: 'text',
-  text: 'Anna Kovács',
-  sizeMm: 4.4,
-  weight: 700,
-  role: 'text',
-  transform: { xMm: -18, yMm: -14, rotationDeg: 0, scale: 1, z: 1 },
-  ...over,
-})
-const qrEl = (over = {}) => ({
-  id: 'q1',
-  type: 'qr',
-  url: 'https://nfcard.hu',
-  sizeMm: 22,
-  frameRole: 'accent',
-  moduleRole: 'text',
-  transform: { xMm: 26, yMm: 12, rotationDeg: 0, scale: 1, z: 2 },
-  ...over,
-})
-
-// A valid CUSTOM design with a free-transform element layer. The chip element sits
-// dead-centre, so the dual-written layout.chipAnchor must be {1,1}.
-const withElements = (elements: unknown[], over = {}) => ({
-  ...legacyDesign,
-  contractVersion: 2,
-  layout: { chipAnchor: { col: 1, row: 1 } },
-  elements,
-  ...over,
-})
-
-const codes = (res: ReturnType<typeof cardDesignSchema.safeParse>): string[] =>
-  res.success ? [] : res.error.issues.map((i) => i.message)
-
-describe('cardDesignSchema — free-transform element layer (NFCARD-197/198)', () => {
-  it('legacy design with no elements still validates (zero regression)', () => {
-    expect(cardDesignSchema.safeParse(legacyDesign).success).toBe(true)
-  })
-
-  it('accepts a valid custom design with chip + text + qr elements', () => {
-    const res = cardDesignSchema.safeParse(withElements([chipEl(), textEl(), qrEl()]))
-    expect(res.success).toBe(true)
-  })
-
-  it('rejects a chip scaled below the NFC-coil floor (grow-only)', () => {
-    const res = cardDesignSchema.safeParse(withElements([chipEl({ transform: { xMm: 0, yMm: 0, rotationDeg: 0, scale: 0.5, z: 0 } })]))
-    expect(res.success).toBe(false)
-    expect(codes(res)).toContain('chipScaleBelowCoil')
-  })
-
-  it('accepts a chip scaled UP (decorative ring)', () => {
-    const res = cardDesignSchema.safeParse(withElements([chipEl({ transform: { xMm: 0, yMm: 0, rotationDeg: 0, scale: 1.3, z: 0 } })]))
-    expect(res.success).toBe(true)
-  })
-
-  it('rejects a QR below the scannable size floor', () => {
-    const res = cardDesignSchema.safeParse(withElements([chipEl(), qrEl({ sizeMm: 12 })]))
-    expect(res.success).toBe(false)
-    expect(codes(res)).toContain('qrTooSmall')
-  })
-
-  it('rejects a raster image asset on a 3D card (vector-only)', () => {
-    const res = cardDesignSchema.safeParse(
-      withElements(
-        [chipEl(), { id: 'img1', type: 'image', assetRef: 'a1', widthMm: 20, heightMm: 12, role: 'text', transform: { xMm: -15, yMm: 14, rotationDeg: 0, scale: 1, z: 1 } }],
-        { assets: [{ id: 'a1', kind: 'raster', rasterDataUrl: 'data:image/png;base64,AAAA' }] },
-      ),
-    )
-    expect(res.success).toBe(false)
-    expect(codes(res)).toContain('rasterImageOn3d')
-  })
-
-  it('accepts a vector image asset on a 3D card', () => {
-    const res = cardDesignSchema.safeParse(
-      withElements(
-        [chipEl(), { id: 'img1', type: 'image', assetRef: 'a1', widthMm: 20, heightMm: 12, role: 'text', transform: { xMm: -15, yMm: 14, rotationDeg: 0, scale: 1, z: 1 } }],
-        { assets: [{ id: 'a1', kind: 'vector', svg: '<svg/>' }] },
-      ),
-    )
-    expect(res.success).toBe(true)
-  })
-
-  it('rejects an element referencing a missing asset', () => {
-    const res = cardDesignSchema.safeParse(
-      withElements([chipEl(), { id: 'img1', type: 'image', assetRef: 'nope', widthMm: 20, heightMm: 12, role: 'text', transform: { xMm: -15, yMm: 14, rotationDeg: 0, scale: 1, z: 1 } }]),
-    )
-    expect(res.success).toBe(false)
-    expect(codes(res)).toContain('assetMissing')
-  })
-
-  it('rejects elements on a template (templates are fixed — custom-only)', () => {
-    const res = cardDesignSchema.safeParse(withElements([chipEl()], { designType: 'template', templateId: 'tpl-3d-flat' }))
-    expect(res.success).toBe(false)
-    expect(codes(res)).toContain('elementsCustomOnly')
-  })
-
-  it('rejects elements without contractVersion 2', () => {
-    const res = cardDesignSchema.safeParse(withElements([chipEl()], { contractVersion: undefined }))
-    expect(res.success).toBe(false)
-    expect(codes(res)).toContain('contractVersionRequired')
-  })
-
-  it('rejects a chipAnchor inconsistent with the chip element (dual-write tamper)', () => {
-    const res = cardDesignSchema.safeParse(withElements([chipEl()], { layout: { chipAnchor: { col: 0, row: 0 } } }))
-    expect(res.success).toBe(false)
-    expect(codes(res)).toContain('chipAnchorDualWriteMismatch')
-  })
-
-  it('requires exactly one chip element', () => {
-    const none = cardDesignSchema.safeParse(withElements([textEl()]))
-    expect(codes(none)).toContain('exactlyOneChip')
-    const two = cardDesignSchema.safeParse(withElements([chipEl(), chipEl({ id: 'chip2' })]))
-    expect(codes(two)).toContain('exactlyOneChip')
-  })
-
-  it('rejects an element that extends off the card', () => {
-    const res = cardDesignSchema.safeParse(withElements([chipEl(), textEl({ transform: { xMm: 60, yMm: 0, rotationDeg: 0, scale: 1, z: 1 } })]))
-    expect(res.success).toBe(false)
-    expect(codes(res)).toContain('elementOffCard')
-  })
-
-  it('rejects duplicate element ids', () => {
-    const res = cardDesignSchema.safeParse(withElements([chipEl(), textEl({ id: 'chip1' })]))
-    expect(res.success).toBe(false)
-    expect(codes(res)).toContain('duplicateElementId')
-  })
-
-  it('rejects empty text', () => {
-    const res = cardDesignSchema.safeParse(withElements([chipEl(), textEl({ text: '   ' })]))
-    expect(res.success).toBe(false)
-    expect(codes(res)).toContain('textEmpty')
-  })
-})
-
-describe('printability helpers', () => {
-  it('chip scale floor is just under 1 (grow-only, coil-bound)', () => {
-    expect(CHIP_SCALE_FLOOR).toBeGreaterThan(0.95)
-    expect(CHIP_SCALE_FLOOR).toBeLessThan(1)
-  })
-
-  it('QR min size keeps the module at the scan floor', () => {
-    expect(QR_MIN_SIZE_MM).toBe(20)
-  })
-
-  it('mmToNearestChipAnchor inverts chipAnchorToMm for all 9 cells', () => {
-    for (const col of [0, 1, 2] as ChipAxis[]) {
-      for (const row of [0, 1, 2] as ChipAxis[]) {
-        const mm = chipAnchorToMm(col, row)
-        expect(mmToNearestChipAnchor(mm)).toEqual({ col, row })
-      }
-    }
-  })
-
-  it('a centred chip projects to the centre cell', () => {
-    expect(mmToNearestChipAnchor({ x: 0, y: 0 })).toEqual({ col: 1, row: 1 })
-  })
-
-  it('elementPrintability passes a legal centred chip', () => {
-    const chip = chipEl() as Parameters<typeof elementPrintability>[0]
-    expect(elementPrintability(chip, { assetsById: new Map() })).toEqual([])
-  })
-})
-
-describe('per-element override fields survive validation (#1  P0 contract)', () => {
-  it('cardDesign RETAINS colour / italic / underline / bgRemoved / svgOverrides + vector-asset svg fields', () => {
-    const parsed = cardDesignSchema.parse(
-      withElements(
-        [
-          chipEl({ colour: 'black' }),
-          textEl({ colour: 'red', italic: true, underline: true }),
-          { id: 'img1', type: 'image', assetRef: 'a1', widthMm: 20, heightMm: 12, role: 'text', bgRemoved: true, svgOverrides: ['green', undefined], transform: { xMm: -15, yMm: 14, rotationDeg: 0, scale: 1, z: 1 } },
-        ],
-        { assets: [{ id: 'a1', kind: 'vector', svg: '<svg/>', svgColours: ['#ff0000', '#00ff00'], svgFils: ['red', 'green'] }] },
-      ),
-    ) as { elements: Record<string, unknown>[]; assets: Record<string, unknown>[] }
-    expect(parsed.elements[0].colour).toBe('black')
-    expect(parsed.elements[1]).toMatchObject({ colour: 'red', italic: true, underline: true })
-    expect(parsed.elements[2]).toMatchObject({ bgRemoved: true, svgOverrides: ['green', undefined] })
-    expect(parsed.assets[0]).toMatchObject({ svgColours: ['#ff0000', '#00ff00'], svgFils: ['red', 'green'] })
-  })
-
-  it('cardAssetSchema retains the raster bg-removal + aspect fields (PVC preview)', () => {
-    const a = cardAssetSchema.parse({ id: 'r1', kind: 'raster', rasterDataUrl: 'data:,', rasterBgDataUrl: 'data:,bg', rasterAspect: 1.5 })
-    expect(a).toMatchObject({ rasterBgDataUrl: 'data:,bg', rasterAspect: 1.5 })
-  })
-})
+import { describe, expect, it } from 'vitest'
+import { cardDesignSchema, cardAssetSchema } from './index'
+import {
+  CHIP_SCALE_FLOOR,
+  QR_MIN_SIZE_MM,
+  chipAnchorToMm,
+  mmToNearestChipAnchor,
+  elementPrintability,
+  type ChipAxis,
+} from './printability'
+
+// A legacy (grid-only) 3D card design — unchanged shape, no elements[].
+const legacyDesign = {
+  material: '3dprint_standard',
+  designType: 'custom',
+  thicknessMm: 1.8,
+  pattern: null,
+  layout: { chipAnchor: { col: 0, row: 1 } },
+  filaments: { background: '#F2F1ED', text: '#1A1A1A', accent: '#3FA34D' },
+}
+
+const chipEl = (over = {}) => ({
+  id: 'chip1',
+  type: 'chip',
+  shape: 0,
+  transform: { xMm: 0, yMm: 0, rotationDeg: 0, scale: 1, z: 0 },
+  ...over,
+})
+const textEl = (over = {}) => ({
+  id: 't1',
+  type: 'text',
+  text: 'Anna Kovács',
+  sizeMm: 4.4,
+  weight: 700,
+  role: 'text',
+  transform: { xMm: -18, yMm: -14, rotationDeg: 0, scale: 1, z: 1 },
+  ...over,
+})
+const qrEl = (over = {}) => ({
+  id: 'q1',
+  type: 'qr',
+  url: 'https://nfcard.hu',
+  sizeMm: 22,
+  frameRole: 'accent',
+  moduleRole: 'text',
+  transform: { xMm: 26, yMm: 12, rotationDeg: 0, scale: 1, z: 2 },
+  ...over,
+})
+
+// A valid CUSTOM design with a free-transform element layer. The chip element sits
+// dead-centre, so the dual-written layout.chipAnchor must be {1,1}.
+const withElements = (elements: unknown[], over = {}) => ({
+  ...legacyDesign,
+  contractVersion: 2,
+  layout: { chipAnchor: { col: 1, row: 1 } },
+  elements,
+  ...over,
+})
+
+const codes = (res: ReturnType<typeof cardDesignSchema.safeParse>): string[] =>
+  res.success ? [] : res.error.issues.map((i) => i.message)
+
+describe('cardDesignSchema — free-transform element layer (NFCARD-197/198)', () => {
+  it('legacy design with no elements still validates (zero regression)', () => {
+    expect(cardDesignSchema.safeParse(legacyDesign).success).toBe(true)
+  })
+
+  it('accepts a valid custom design with chip + text + qr elements', () => {
+    const res = cardDesignSchema.safeParse(withElements([chipEl(), textEl(), qrEl()]))
+    expect(res.success).toBe(true)
+  })
+
+  it('rejects a chip scaled below the NFC-coil floor (grow-only)', () => {
+    const res = cardDesignSchema.safeParse(withElements([chipEl({ transform: { xMm: 0, yMm: 0, rotationDeg: 0, scale: 0.5, z: 0 } })]))
+    expect(res.success).toBe(false)
+    expect(codes(res)).toContain('chipScaleBelowCoil')
+  })
+
+  it('accepts a chip scaled UP (decorative ring)', () => {
+    const res = cardDesignSchema.safeParse(withElements([chipEl({ transform: { xMm: 0, yMm: 0, rotationDeg: 0, scale: 1.3, z: 0 } })]))
+    expect(res.success).toBe(true)
+  })
+
+  it('rejects a QR below the scannable size floor', () => {
+    const res = cardDesignSchema.safeParse(withElements([chipEl(), qrEl({ sizeMm: 12 })]))
+    expect(res.success).toBe(false)
+    expect(codes(res)).toContain('qrTooSmall')
+  })
+
+  it('rejects a raster image asset on a 3D card (vector-only)', () => {
+    const res = cardDesignSchema.safeParse(
+      withElements(
+        [chipEl(), { id: 'img1', type: 'image', assetRef: 'a1', widthMm: 20, heightMm: 12, role: 'text', transform: { xMm: -15, yMm: 14, rotationDeg: 0, scale: 1, z: 1 } }],
+        { assets: [{ id: 'a1', kind: 'raster', rasterDataUrl: 'data:image/png;base64,AAAA' }] },
+      ),
+    )
+    expect(res.success).toBe(false)
+    expect(codes(res)).toContain('rasterImageOn3d')
+  })
+
+  it('accepts a vector image asset on a 3D card', () => {
+    const res = cardDesignSchema.safeParse(
+      withElements(
+        [chipEl(), { id: 'img1', type: 'image', assetRef: 'a1', widthMm: 20, heightMm: 12, role: 'text', transform: { xMm: -15, yMm: 14, rotationDeg: 0, scale: 1, z: 1 } }],
+        { assets: [{ id: 'a1', kind: 'vector', svg: '<svg/>' }] },
+      ),
+    )
+    expect(res.success).toBe(true)
+  })
+
+  it('rejects an element referencing a missing asset', () => {
+    const res = cardDesignSchema.safeParse(
+      withElements([chipEl(), { id: 'img1', type: 'image', assetRef: 'nope', widthMm: 20, heightMm: 12, role: 'text', transform: { xMm: -15, yMm: 14, rotationDeg: 0, scale: 1, z: 1 } }]),
+    )
+    expect(res.success).toBe(false)
+    expect(codes(res)).toContain('assetMissing')
+  })
+
+  it('rejects elements on a template (templates are fixed — custom-only)', () => {
+    const res = cardDesignSchema.safeParse(withElements([chipEl()], { designType: 'template', templateId: 'tpl-3d-flat' }))
+    expect(res.success).toBe(false)
+    expect(codes(res)).toContain('elementsCustomOnly')
+  })
+
+  it('rejects elements without contractVersion 2', () => {
+    const res = cardDesignSchema.safeParse(withElements([chipEl()], { contractVersion: undefined }))
+    expect(res.success).toBe(false)
+    expect(codes(res)).toContain('contractVersionRequired')
+  })
+
+  it('rejects a chipAnchor inconsistent with the chip element (dual-write tamper)', () => {
+    const res = cardDesignSchema.safeParse(withElements([chipEl()], { layout: { chipAnchor: { col: 0, row: 0 } } }))
+    expect(res.success).toBe(false)
+    expect(codes(res)).toContain('chipAnchorDualWriteMismatch')
+  })
+
+  it('requires exactly one chip element', () => {
+    const none = cardDesignSchema.safeParse(withElements([textEl()]))
+    expect(codes(none)).toContain('exactlyOneChip')
+    const two = cardDesignSchema.safeParse(withElements([chipEl(), chipEl({ id: 'chip2' })]))
+    expect(codes(two)).toContain('exactlyOneChip')
+  })
+
+  it('rejects an element that extends off the card', () => {
+    const res = cardDesignSchema.safeParse(withElements([chipEl(), textEl({ transform: { xMm: 60, yMm: 0, rotationDeg: 0, scale: 1, z: 1 } })]))
+    expect(res.success).toBe(false)
+    expect(codes(res)).toContain('elementOffCard')
+  })
+
+  it('rejects duplicate element ids', () => {
+    const res = cardDesignSchema.safeParse(withElements([chipEl(), textEl({ id: 'chip1' })]))
+    expect(res.success).toBe(false)
+    expect(codes(res)).toContain('duplicateElementId')
+  })
+
+  it('rejects empty text', () => {
+    const res = cardDesignSchema.safeParse(withElements([chipEl(), textEl({ text: '   ' })]))
+    expect(res.success).toBe(false)
+    expect(codes(res)).toContain('textEmpty')
+  })
+})
+
+describe('printability helpers', () => {
+  it('chip scale floor is just under 1 (grow-only, coil-bound)', () => {
+    expect(CHIP_SCALE_FLOOR).toBeGreaterThan(0.95)
+    expect(CHIP_SCALE_FLOOR).toBeLessThan(1)
+  })
+
+  it('QR min size keeps the module at the scan floor', () => {
+    expect(QR_MIN_SIZE_MM).toBe(20)
+  })
+
+  it('mmToNearestChipAnchor inverts chipAnchorToMm for all 9 cells', () => {
+    for (const col of [0, 1, 2] as ChipAxis[]) {
+      for (const row of [0, 1, 2] as ChipAxis[]) {
+        const mm = chipAnchorToMm(col, row)
+        expect(mmToNearestChipAnchor(mm)).toEqual({ col, row })
+      }
+    }
+  })
+
+  it('a centred chip projects to the centre cell', () => {
+    expect(mmToNearestChipAnchor({ x: 0, y: 0 })).toEqual({ col: 1, row: 1 })
+  })
+
+  it('elementPrintability passes a legal centred chip', () => {
+    const chip = chipEl() as Parameters<typeof elementPrintability>[0]
+    expect(elementPrintability(chip, { assetsById: new Map() })).toEqual([])
+  })
+})
+
+describe('per-element override fields survive validation (#1  P0 contract)', () => {
+  it('cardDesign RETAINS colour / italic / underline / bgRemoved / svgOverrides + vector-asset svg fields', () => {
+    const parsed = cardDesignSchema.parse(
+      withElements(
+        [
+          chipEl({ colour: 'black' }),
+          textEl({ colour: 'red', italic: true, underline: true }),
+          { id: 'img1', type: 'image', assetRef: 'a1', widthMm: 20, heightMm: 12, role: 'text', bgRemoved: true, svgOverrides: ['green', undefined], transform: { xMm: -15, yMm: 14, rotationDeg: 0, scale: 1, z: 1 } },
+        ],
+        { assets: [{ id: 'a1', kind: 'vector', svg: '<svg/>', svgColours: ['#ff0000', '#00ff00'], svgFils: ['red', 'green'] }] },
+      ),
+    ) as { elements: Record<string, unknown>[]; assets: Record<string, unknown>[] }
+    expect(parsed.elements[0].colour).toBe('black')
+    expect(parsed.elements[1]).toMatchObject({ colour: 'red', italic: true, underline: true })
+    expect(parsed.elements[2]).toMatchObject({ bgRemoved: true, svgOverrides: ['green', undefined] })
+    expect(parsed.assets[0]).toMatchObject({ svgColours: ['#ff0000', '#00ff00'], svgFils: ['red', 'green'] })
+  })
+
+  it('cardAssetSchema retains the raster bg-removal + aspect fields (PVC preview)', () => {
+    const a = cardAssetSchema.parse({ id: 'r1', kind: 'raster', rasterDataUrl: 'data:,', rasterBgDataUrl: 'data:,bg', rasterAspect: 1.5 })
+    expect(a).toMatchObject({ rasterBgDataUrl: 'data:,bg', rasterAspect: 1.5 })
+  })
+})

package/src/index.test.ts

@@ -490,6 +490,32 @@ describe('physicalConfigSchema / validatePhysicalConfig', () => {
     });
     expect(r.success).toBe(false);
   });
+
+  it('accepts + RETAINS top-level elements/assets for a PVC (2D) custom design', () => {
+    // PVC parity: the free-transform layer + raster image assets ride top-level
+    // on a plastic config (which has no cardDesign) and must NOT be stripped by
+    // the strict object parse — otherwise the order persists no renderable design.
+    const r = physicalConfigSchema.safeParse({
+      ...validPhysicalConfig,
+      elements: [
+        {
+          id: 'img1',
+          type: 'image',
+          assetRef: 'a1',
+          widthMm: 20,
+          heightMm: 12,
+          role: 'text',
+          transform: { xMm: -15, yMm: 14, rotationDeg: 0, scale: 1, z: 1 },
+        },
+      ],
+      assets: [{ id: 'a1', kind: 'raster', rasterDataUrl: 'https://cdn.example/card.webp' }],
+    });
+    expect(r.success).toBe(true);
+    if (r.success) {
+      expect(r.data.elements).toHaveLength(1);
+      expect(r.data.assets?.[0]?.rasterDataUrl).toBe('https://cdn.example/card.webp');
+    }
+  });
 });
 
 // ── digitalConfigSchema ─────────────────────────────────────────
@@ -523,6 +549,13 @@ describe('digitalConfigSchema / validateDigitalConfig', () => {
     expect(r.success).toBe(true);
   });
 
+  it('accepts the new family templateIds (classic/spotlight/marquee/riso)', () => {
+    for (const templateId of ['classic', 'spotlight', 'marquee', 'riso']) {
+      const r = validateDigitalConfig({ ...validDigitalConfig, templateId });
+      expect(r.success).toBe(true);
+    }
+  });
+
   it('rejects an empty fontKey', () => {
     const r = validateDigitalConfig({ ...validDigitalConfig, fontKey: '' });
     expect(r.success).toBe(false);

package/src/parity.test.ts

@@ -0,0 +1,89 @@
+import { describe, it, expect } from 'vitest'
+import { readFileSync, existsSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import type { CardElement, CardAsset } from '@nfcard/types'
+import {
+  elementPrintability,
+  chipAnchorToMm,
+  obbCorners,
+  CHIP_SCALE_FLOOR,
+  QR_MIN_SIZE_MM,
+  type ChipAxis,
+} from './printability'
+
+/**
+ * Cross-language PLACEMENT + PRINTABILITY parity — the TS half of the guard
+ * (NFCARD-247, doc 83).
+ *
+ * `cardgen.validate` (`validate_elements` / `obb_corners`) and `cardgen.pattern`
+ * (`chip_centre_for_anchor`) are by-hand Python ports of THIS file. The golden lives
+ * in the cardgen repo (its pytest, `test_parity_printability.py`, is the other half).
+ * This test pins printability.ts to that same committed golden, so a change to the
+ * gate, the chip Y-frame projection, or the OBB/rotation-sign formula here fails
+ * LOUDLY with a reminder to regenerate and update the Python side in lockstep —
+ * instead of silently drifting the printed card away from the live preview.
+ *
+ * Regenerate (both sides together):
+ *   node ../../nfcard-cardgen/tests/parity/gen_printability_parity.mjs
+ *
+ * Skips cleanly if nfcard-cardgen isn't checked out alongside (shared-only CI).
+ */
+const GOLDEN = fileURLToPath(
+  new URL('../../../nfcard-cardgen/tests/parity/printability_parity.json', import.meta.url),
+)
+const present = existsSync(GOLDEN)
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+const golden: any = present ? JSON.parse(readFileSync(GOLDEN, 'utf-8')) : { elementCases: [] }
+const TOL = 1e-9
+
+// Mirror cardgen `validate_elements`: per-element printability + the graph-level
+// exactly-one-chip rule (printability.ts leaves that to the schema superRefine).
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function expectedCodes(design: any): string[] {
+  const assetsById = new Map<string, CardAsset>(
+    (design.assets ?? []).map((a: CardAsset) => [a.id, a]),
+  )
+  const codes: string[] = []
+  let chipCount = 0
+  for (const el of design.elements as CardElement[]) {
+    if (el.type === 'chip') chipCount += 1
+    for (const v of elementPrintability(el, { assetsById })) codes.push(v.code)
+  }
+  if (chipCount !== 1) codes.push('chipCount')
+  return codes.sort()
+}
+
+describe.skipIf(!present)('printability parity golden (locks the TS source of truth)', () => {
+  it('shares the threshold constants the Python gate branches on', () => {
+    expect(golden.constants.chipScaleFloor).toBeCloseTo(CHIP_SCALE_FLOOR, 9)
+    expect(golden.constants.qrMinSizeMm).toBe(QR_MIN_SIZE_MM)
+  })
+
+  it('elementPrintability still reproduces the committed Violation codes', () => {
+    expect(golden.elementCases.length, 'golden has cases — regenerate if 0').toBeGreaterThan(0)
+    for (const c of golden.elementCases) {
+      expect(expectedCodes(c.design), `${c.name}: code drift — regenerate the golden`).toEqual(
+        c.expectedCodes,
+      )
+    }
+  })
+
+  it('chipAnchorToMm still reproduces the committed 3×3 grid → mm (the Y-frame)', () => {
+    for (const e of golden.chipAnchorMm) {
+      const p = chipAnchorToMm(e.col as ChipAxis, e.row as ChipAxis)
+      expect(Math.abs(p.x - e.x), `chip(${e.col},${e.row}).x`).toBeLessThan(TOL)
+      expect(Math.abs(p.y - e.y), `chip(${e.col},${e.row}).y`).toBeLessThan(TOL)
+    }
+  })
+
+  it('obbCorners still reproduces the committed corners (the rotation-sign)', () => {
+    for (const c of golden.obbCases) {
+      const got = obbCorners(c.transform, c.w, c.h)
+      expect(got.length).toBe(c.corners.length)
+      got.forEach((p, i) => {
+        expect(Math.abs(p.x - c.corners[i][0]), `${c.name} corner ${i}.x`).toBeLessThan(TOL)
+        expect(Math.abs(p.y - c.corners[i][1]), `${c.name} corner ${i}.y`).toBeLessThan(TOL)
+      })
+    }
+  })
+})