Initial Commit

openspec/archive/2026-04-19-enterprise-qrcode/proposal.md

@@ -0,0 +1,45 @@
+# OpenSpec Change: enterprise-qrcode
+
+- **Change ID**: enterprise-qrcode
+- **Package**: `@suaveplan/qrcode`
+- **Category**: universal
+- **Target path**: `universal/media/qrcode`
+- **Status**: PROPOSED
+- **Date**: 2026-04-19
+- **Reference spec**: `/mnt/s/web/suaveplan/enterprise/qrcode.md`
+
+## Summary
+
+QR code generator + reader: numeric / alphanumeric / byte modes, ECC levels L/M/Q/H, module-shape styling, colour gradients, logo overlay with quiet-zone preservation, SVG / PNG / Data URL export, and batch generation with progress reporting.
+
+## Current-state audit (genesis)
+
+Package does not exist yet — fresh build.
+
+## Dependencies
+
+- Workspace: `@suaveplan/error`, `@suaveplan/types`
+- External (via catalog): `zod`, `tslib`, `@opentelemetry/api`
+- Dev (via catalog): `vitest`, `@vitest/coverage-istanbul`, `fast-check`, `mitata`
+
+## Preserved public surface
+
+- `QrGenerator`, `QrError`, `QrErrorCode`
+- `QrReader`
+- `generateBatch`, `generateBatchAsync`, `generateBatchWithProgress`
+- `toDataUrl`, `toSvg`
+- `generateStyledSvg`, `getLogoModuleArea`
+- Codes: `QrCodeErrorCode`, `registerQrErrorCodes`
+- Types: `AlignmentPatternPositions`, `BatchItem`, `BatchOptions`, `BatchProgressCallback`, `EcInfo`, `ErrorCorrectionLevel`, `ModuleShape`, `QrCode`, `QrExportOptions`, `QrGradient`, `QrImageData`, `QrLogoOptions`, `QrMatrix`, `QrMode`, `QrOptions`, `QrSegment`, `StyledQrOptions`
+
+## New genesis additions
+
+- Codes: `QRCODE.ENCODE_FAILED`, `QRCODE.DECODE_FAILED`, `QRCODE.CAPACITY_EXCEEDED`, `QRCODE.LOGO_TOO_LARGE`.
+- Zod schemas for every option type.
+- OTel histograms `qrcode.encode.duration_ms`, `qrcode.decode.duration_ms`; counters.
+- Property tests: `QrReader.read(QrGenerator.generate(x)) === x` at ECC level H.
+
+## Impact
+
+- Adds one new package: `universal/media/qrcode`
+- Adds one new spec capability: `qrcode`

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.

openspec/archive/2026-04-19-enterprise-qrcode/tasks.md

@@ -0,0 +1,43 @@
+# Tasks: enterprise-qrcode
+
+## 1. Scaffold
+
+- [x] 1.1 `universal/media/qrcode/`; 100/100/100/100; guard tests; CLAUDE/README/FOLDERS.
+
+## 2. Errors + schemas
+
+- [x] 2.1 `src/error-codes.ts` — codes + side-effect register.
+- [x] 2.2 Zod schemas per option type.
+
+## 3. Encoder
+
+- [x] 3.1 `src/generator/segmenter.ts` — mode selection (numeric / alphanumeric / byte / kanji).
+- [x] 3.2 `src/generator/rs.ts` — Reed-Solomon codewords.
+- [x] 3.3 `src/generator/mask-evaluator.ts` — 8-mask evaluator.
+- [x] 3.4 `src/generator/qr-generator.ts` — `QrGenerator` orchestrator + `QrError`.
+
+## 4. Decoder
+
+- [x] 4.1 `src/reader/qr-reader.ts` — binarisation, locator-pattern detection, perspective correction, decoding.
+
+## 5. Styled export
+
+- [x] 5.1 `src/styled/styled-qr.ts` — `generateStyledSvg`, `getLogoModuleArea`, gradients + module shapes.
+
+## 6. Export
+
+- [x] 6.1 `src/export/qr-exporter.ts` — `toDataUrl`, `toSvg`.
+
+## 7. Batch
+
+- [x] 7.1 `src/batch/batch-generator.ts` — sync / async / progress variants.
+
+## 8. Docs / barrel / subpath exports / README
+
+## 9. Benchmarks
+
+- [x] 9.1 Encode / decode benchmarks at version 5 / 10 / 40.
+
+## 10. Ship gate
+
+- [x] 10.1 Verification sequence; fold + archive.