Initial Commit

openspec/archive/2026-04-19-enterprise-qrcode/specs/qrcode/spec.md

@@ -0,0 +1,37 @@
+# Capability Spec: qrcode
+
+**Package**: `@suaveplan/qrcode`
+**Version**: 0.0.0 (genesis)
+**Status**: ADDED
+
+---
+
+## ADDED Requirements
+
+### QR-01 — Spec conformance
+
+The package MUST implement ISO/IEC 18004 QR code versions 1–40 with ECC levels L/M/Q/H. Mode selection MUST cover numeric, alphanumeric, byte, and kanji segments. Oversized payloads MUST throw `QRCODE.CAPACITY_EXCEEDED` with the minimum required version in context.
+
+### QR-02 — Encoder contract
+
+`QrGenerator.generate(data, options)` MUST return `QrCode { matrix, version, mask, ecc, mode, segments }`. Reed-Solomon codewords MUST be computed via the reference algorithm and mask evaluation MUST minimise the penalty across all 8 masks.
+
+### QR-03 — Decoder contract
+
+`QrReader.read(input)` MUST accept `ImageData`, `Uint8Array`, `Blob`, or `File` and return the decoded payload and mode. Failures MUST throw `QRCODE.DECODE_FAILED`.
+
+### QR-04 — Styled export
+
+`generateStyledSvg(qr, options)` MUST render custom module shapes (`'square' | 'dot' | 'rounded'`), linear/radial gradients, and optional logo overlay. `getLogoModuleArea(qr, logoOptions)` MUST return the module indices blanked for the logo. Logos that exceed the ECC-safe area MUST throw `QRCODE.LOGO_TOO_LARGE`.
+
+### QR-05 — Data URL / SVG export
+
+`toSvg(qr, options?)` MUST return a standalone SVG string. `toDataUrl(qr, options?)` MUST return a base64 PNG Data URL.
+
+### QR-06 — Batch API
+
+`generateBatch`, `generateBatchAsync`, and `generateBatchWithProgress` MUST all return `BatchResult` with per-item error capture; `generateBatchWithProgress` MUST invoke `BatchProgressCallback` once per item.
+
+### QR-07 — Observability
+
+Every encode / decode MUST record `qrcode.encode.duration_ms` / `qrcode.decode.duration_ms` histograms and outcome counters.