@nfcard/pattern-engine

Pure, dependency-free geometry for NFCard's perforated card face: the card dimensions, the chip-anchor math, and generateHoles() — the algorithm that turns a CardDesign pattern into the array of holes punched through the card.

It is the single source of that geometry. Two renderers consume it:

• the 2D configurator preview in nfcard-web (src/configurator/patternEngine.ts re-exports this package), and
• @nfcard/card3d, which extrudes the same holes into a 3D mesh.

Keeping it standalone (zero runtime deps, no DOM, no Three.js) means the 2D path never pulls in a 3D engine, and there is no second hole algorithm to drift.

Manufacturing geometry is not this engine — that is cardgen (Python). The web/3D preview and cardgen are the two-engine relationship gated by NFCARD-172; this package is the web side of it.

Usage

import { generateHoles, CARD_W, CARD_H, type PatternConfig } from '@nfcard/pattern-engine'

const holes = generateHoles(cfg, islands) // → { x, y, r, sides, rotation }[]

Build

pnpm build   # tsup → dist/index.js (ESM) + dist/index.d.ts
pnpm test    # vitest