@nfcard/validation 0.10.0 → 0.13.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nfcard/validation",
-  "version": "0.10.0",
+  "version": "0.13.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.9.0"
+    "@nfcard/types": "0.12.0"
   },
   "devDependencies": {
     "tsup": "^8.0.0"

package/src/elements.test.ts

@@ -0,0 +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 })
+  })
+})

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 ─────────────────────────────────────────

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)
+      })
+    }
+  })
+})

package/src/printability.ts

@@ -0,0 +1,213 @@
+/**
+ * Manufacturing-printability envelope for the free-transform element layer
+ * (NFCARD-197/198). This is the SINGLE canonical source for the placement math +
+ * the per-element hard constraints: the editor (nfcard-web) imports it for live
+ * warnings, @nfcard/validation runs it as the hard order gate (superRefine), and
+ * cardgen `validate.py` ports it 1:1. A golden-fixture CI test keeps the TS and the
+ * Python port from drifting — without that, the live preview silently diverges from
+ * the printed card.
+ *
+ * All geometry is card-local millimetres, centre-origin, +x right / +y up (the
+ * cardgen frame). Pure functions only — no zod, no IO.
+ *
+ * Thresholds marked "provisional" are conservative defaults to be calibrated against
+ * cardgen's own `validate_spec` / `_thin_stroke_warnings`; they are deliberately set
+ * so they never reject a design the legacy auto-layout already prints.
+ */
+import type { CardElement, CardAsset, ElementTransform } from '@nfcard/types'
+
+// ── Card + manufacturing geometry (mirror @nfcard/pattern-engine + cardgen) ──
+export const CARD_W_MM = 85.6
+export const CARD_H_MM = 54.0
+export const EDGE_MARGIN_MM = 1.5
+/** Ø27.5 solid chip island (pattern-engine CHIP_RADIUS_MM). */
+export const CHIP_RADIUS_MM = 13.75
+export const MIN_WALL_MM = 0.8
+
+// ── NFC coil: a fixed Ø25 mm COTS part (cardgen NfcSpec defaults) ──
+export const NFC_COIL_DIAMETER_MM = 25
+export const NFC_RADIAL_CLEARANCE_MM = 0.2
+/**
+ * Chip island is GROW-ONLY. Shrinking the visual island does NOT shrink the coil —
+ * it collapses the solid wall between the coil pocket and the perforation. The floor
+ * keeps `pocket_r + MIN_WALL ≤ CHIP_RADIUS·scale` (cardgen spec.py:507-512), so the
+ * chip can only grow. ≈ (12.5 + 0.2 + 0.8) / 13.75 ≈ 0.982.
+ */
+export const CHIP_SCALE_FLOOR =
+  (NFC_COIL_DIAMETER_MM / 2 + NFC_RADIAL_CLEARANCE_MM + MIN_WALL_MM) / CHIP_RADIUS_MM
+
+// ── QR scannability ──
+/** Keep the printed module ≥ ~0.8 mm (≈4 nozzle widths) for reliable phone scans. */
+export const QR_MODULE_MIN_MM = 0.8
+/** v1 (21×21) matrix + a 2-module quiet zone each side. */
+export const QR_MATRIX_CELLS = 25
+export const QR_MIN_SIZE_MM = QR_MODULE_MIN_MM * QR_MATRIX_CELLS // = 20
+
+// ── Raised-text minimum (provisional; calibrate vs cardgen _thin_stroke_warnings) ──
+// The legacy auto-content already prints em heights down to ~2.1 mm, so the HARD
+// floor matches that (below it, FDM raised glyphs vanish). The 2–4 mm "thin" band is
+// a SOFT editor warning, not a gate, so free text never regresses the auto-layout.
+export const TEXT_MIN_EM_MM = 2.0
+
+const EPS = 1e-6
+
+export interface Pt {
+  x: number
+  y: number
+}
+
+function isFiniteNum(n: unknown): n is number {
+  return typeof n === 'number' && Number.isFinite(n)
+}
+export function isFiniteTransform(t: ElementTransform): boolean {
+  return (
+    isFiniteNum(t.xMm) &&
+    isFiniteNum(t.yMm) &&
+    isFiniteNum(t.rotationDeg) &&
+    isFiniteNum(t.scale) &&
+    isFiniteNum(t.z) &&
+    t.scale > 0
+  )
+}
+
+/** The 4 corners of a `wMm × hMm` box (centre-origin local) under a transform. */
+export function obbCorners(t: ElementTransform, wMm: number, hMm: number): Pt[] {
+  const hw = (wMm * t.scale) / 2
+  const hh = (hMm * t.scale) / 2
+  const r = (t.rotationDeg * Math.PI) / 180
+  const c = Math.cos(r)
+  const s = Math.sin(r)
+  const local: [number, number][] = [
+    [-hw, -hh],
+    [hw, -hh],
+    [hw, hh],
+    [-hw, hh],
+  ]
+  return local.map(([x, y]) => ({ x: t.xMm + x * c - y * s, y: t.yMm + x * s + y * c }))
+}
+
+/** Are all corners inside the ID-1 rim minus the safety margin? */
+export function cornersOnCard(corners: Pt[], margin = EDGE_MARGIN_MM): boolean {
+  const maxX = CARD_W_MM / 2 - margin
+  const maxY = CARD_H_MM / 2 - margin
+  return corners.every((p) => Math.abs(p.x) <= maxX + EPS && Math.abs(p.y) <= maxY + EPS)
+}
+
+// ── Chip 3×3-grid ⇄ free-mm projection (legacy dual-write) ──
+// The exact `chip_centre_mm` math from @nfcard/pattern-engine / cardgen pattern.py.
+const ANCHOR_NORM = [-0.85, 0, 0.85] as const
+export type ChipAxis = 0 | 1 | 2
+
+function chipMaxXY(): { maxX: number; maxY: number } {
+  return {
+    maxX: CARD_W_MM / 2 - EDGE_MARGIN_MM - CHIP_RADIUS_MM - 1,
+    maxY: CARD_H_MM / 2 - EDGE_MARGIN_MM - CHIP_RADIUS_MM - 1,
+  }
+}
+
+/** Grid cell → card-local mm centre (matches pattern-engine `chipCentreForAnchor`). */
+export function chipAnchorToMm(col: ChipAxis, row: ChipAxis): Pt {
+  const { maxX, maxY } = chipMaxXY()
+  return { x: ANCHOR_NORM[col] * maxX, y: ANCHOR_NORM[row] * maxY }
+}
+
+/** Free mm → nearest grid cell (matches pattern-engine `nearestChipAnchor`). The
+ *  lossy legacy shadow the editor dual-writes into `layout.chipAnchor`. */
+export function mmToNearestChipAnchor(p: Pt): { col: ChipAxis; row: ChipAxis } {
+  const { maxX, maxY } = chipMaxXY()
+  const near = (v: number): ChipAxis => {
+    let best: ChipAxis = 0
+    let bd = Infinity
+    ;([0, 1, 2] as ChipAxis[]).forEach((i) => {
+      const d = Math.abs(ANCHOR_NORM[i] - v)
+      if (d < bd) {
+        bd = d
+        best = i
+      }
+    })
+    return best
+  }
+  return { col: near(maxX ? p.x / maxX : 0), row: near(maxY ? p.y / maxY : 0) }
+}
+
+// ── Per-element printability ──
+export interface PrintabilityCtx {
+  /** A CardDesign is always 3D (CardDesignMaterial excludes plastic). */
+  assetsById: Map<string, CardAsset>
+}
+export interface Violation {
+  code: string
+  elementId: string
+  message: string
+}
+
+/** Estimated card footprint (w×h, pre-scale) used for the on-card OBB check. The
+ *  editor measures real glyph widths; this is the schema-side backstop. */
+function footprintOf(el: CardElement): { w: number; h: number } {
+  switch (el.type) {
+    case 'chip':
+      return { w: 2 * CHIP_RADIUS_MM, h: 2 * CHIP_RADIUS_MM }
+    case 'qr':
+      return { w: el.sizeMm, h: el.sizeMm }
+    case 'image':
+    case 'logo':
+      return { w: el.widthMm, h: el.heightMm }
+    case 'text': {
+      // Coarse: ~0.6 em per glyph wide, ~1.3 em tall. Editor does the precise check.
+      const w = Math.max(1, el.text.length) * el.sizeMm * 0.6
+      return { w, h: el.sizeMm * 1.3 }
+    }
+  }
+}
+
+/** All hard manufacturing violations for one element. Empty ⇒ printable. */
+export function elementPrintability(el: CardElement, ctx: PrintabilityCtx): Violation[] {
+  const out: Violation[] = []
+  const push = (code: string, message: string) => out.push({ code, elementId: el.id, message })
+
+  if (!isFiniteTransform(el.transform)) {
+    push('transformInvalid', 'Element transform is not a finite, positive-scale value.')
+    return out
+  }
+
+  switch (el.type) {
+    case 'chip':
+      if (el.transform.scale < CHIP_SCALE_FLOOR - EPS) {
+        push('chipScaleBelowCoil', 'The chip cannot shrink below the 25 mm NFC coil.')
+      }
+      break
+    case 'qr':
+      if (el.sizeMm * el.transform.scale < QR_MIN_SIZE_MM - EPS) {
+        push('qrTooSmall', 'The QR code is below the scannable size floor.')
+      }
+      if (!el.url || !el.url.trim()) {
+        push('qrEmptyUrl', 'The QR code has no target URL.')
+      }
+      break
+    case 'text':
+      if (!el.text.trim()) {
+        push('textEmpty', 'The text element is empty.')
+      }
+      if (el.sizeMm * el.transform.scale < TEXT_MIN_EM_MM - EPS) {
+        push('textTooSmall', 'The text is too small to print reliably.')
+      }
+      break
+    case 'image':
+    case 'logo': {
+      const asset = ctx.assetsById.get(el.assetRef)
+      if (!asset) {
+        push('assetMissing', 'The element references a missing asset.')
+      } else if (asset.kind !== 'vector') {
+        // Vector-only on 3D: FDM extrudes vector outlines (raster is PVC-only).
+        push('rasterImageOn3d', 'Raster images are not printable on 3D cards — use a vector (SVG).')
+      }
+      break
+    }
+  }
+
+  const fp = footprintOf(el)
+  if (!cornersOnCard(obbCorners(el.transform, fp.w, fp.h))) {
+    push('elementOffCard', 'The element extends past the printable card area.')
+  }
+  return out
+}