# 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.