@nfcard/validation 0.12.0 → 0.14.0

package/src/printability.ts

@@ -1,213 +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
-}
+/**
+ * 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
+}