@sythos/js_barcode_universal 1.0.0 → 1.1.0

package/README.md

@@ -90,8 +90,8 @@ const svg = toSVG(encodeQR('https://example.com', { ecc: 'M' }), { scale: 8 });
 | `@sythos/js_barcode_universal/core` | `BitMatrix`, `GaloisField`, Reed–Solomon, the error classes |
 | `@sythos/js_barcode_universal/image` | `LuminanceSource`, the binarizers, grid sampling, `PerspectiveTransform` |
 | `@sythos/js_barcode_universal/oned` | The per-format 1D writers (`encodeEAN13`, `encodeCode128`, …) and `decodeOneD` |
-| `@sythos/js_barcode_universal/qr` | `encodeQR`, `decodeQR`, `detectQR`, `detectAndDecodeQR` |
-| `@sythos/js_barcode_universal/datamatrix` | `encodeDataMatrix`, `decodeDataMatrix`, `detectDataMatrix`, `detectAndDecodeDataMatrix` |
+| `@sythos/js_barcode_universal/qr` | `encodeQR`, `decodeQR`, `detectQR`, `detectAndDecodeQR` |
+| `@sythos/js_barcode_universal/datamatrix` | `encodeDataMatrix`, `decodeDataMatrix`, `detectDataMatrix`, `detectAndDecodeDataMatrix` |
 | `@sythos/js_barcode_universal/render` | Every renderer plus `isWebGL2Available` / `isWebGPUAvailable` |
 | `@sythos/js_barcode_universal/render/svg` | `toSVG`, `toSVGDataURI` |
 | `@sythos/js_barcode_universal/render/png` | `toPNG`, `toPNGDataURI` |
@@ -103,8 +103,8 @@ The `unpkg` and `jsdelivr` fields point at the IIFE bundle, so a CDN needs no in
 
 ```html
 <script src="https://unpkg.com/@sythos/js_barcode_universal"></script>
-<script src="https://unpkg.com/@sythos/js_barcode_universal@1.0.0"></script>
-<script src="https://cdn.jsdelivr.net/npm/@sythos/js_barcode_universal@1.0.0"></script>
+<script src="https://unpkg.com/@sythos/js_barcode_universal@1.1.0"></script>
+<script src="https://cdn.jsdelivr.net/npm/@sythos/js_barcode_universal@1.1.0"></script>
 ```
 
 Pin the version for anything you ship; the unpinned form resolves to `latest` and will move under
@@ -209,8 +209,9 @@ time.
 | Pharmacode | `pharmacode` | 1D | ✅ | — |
 | QR Code | `qr` | 2D | ✅ | ✅ |
 | Data Matrix ECC 200 | `datamatrix` | 2D | ✅ | ✅ |
+| Aztec Code | `aztec` | 2D | ✅ | ✅ |
 
-Seventeen formats, all writable, fourteen readable. **Code 11, MSI Plessey and Pharmacode are
+Eighteen formats, all writable, fifteen readable. **Code 11, MSI Plessey and Pharmacode are
 write-only** — they encode correctly, but there is no reader for them, and `decode` will never
 return one.
 
@@ -219,35 +220,55 @@ they decode under that base id: a GS1-128 comes back as `code128`, an ITF-14 as
 as `ean13`. The payload is intact either way — a GS1-128 *is* a Code 128 with a leading FNC1, an
 ITF-14 *is* an ITF fixed at fourteen digits, and an ISBN barcode *is* an EAN-13 with a 978/979
 prefix. Match on `result.format === 'code128'` rather than `'gs1128'`, or a
-condition on the sub-variant id will silently never fire.
+condition on the sub-variant id will silently never fire.
+
+### Data Matrix ECC 200
+
+`datamatrix` writes and reads the 30 classic ECC 200 square and rectangular symbol sizes. The
+encoder supports ASCII compaction (including numeric pairs), Base256 binary payloads, automatic
+or forced square/rectangular shape, Reed–Solomon error correction and GS1 FNC1 in the first
+position. DMRE is not included.
+
+```js
+import { encodeDataMatrix, decodeDataMatrix } from '@sythos/js_barcode_universal/datamatrix';
+
+const symbol = encodeDataMatrix('0101234567890128', { gs1: true, shape: 'square' });
+const result = decodeDataMatrix(symbol);
+console.log(result.text, result.gs1); // 0101234567890128 true
+```
+
+Binary content is accepted as a `Uint8Array` with `encoding: 'base256'`. The current high-level
+decoder handles ASCII and Base256 codewords; C40, Text, X12 and EDIFACT input symbols are not yet
+decoded. The current detector accepts axis-aligned square or rectangular symbols; the normal
+`decode(image, { formats: ['datamatrix'] })` pipeline also retries quarter-turn rotations.
+Arbitrary-angle and perspective-skewed Data Matrix photographs are not yet guaranteed.
 
-### Data Matrix ECC 200
+### Aztec Code
 
-`datamatrix` writes and reads the 30 classic ECC 200 square and rectangular symbol sizes. The
-encoder supports ASCII compaction (including numeric pairs), Base256 binary payloads, automatic
-or forced square/rectangular shape, Reed–Solomon error correction and GS1 FNC1 in the first
-position. DMRE is not included.
+`aztec` writes Compact layers 1–4 and Full layers 1–32, selecting a fitting symbol automatically
+unless `layers` and `compact` are forced. It supports the five Aztec text tables and UTF-8 byte
+payloads through Binary Shift, with `eccPercent` (default 23) controlling the requested
+error-correction level.
+ECI is not yet a configurable public option.
 
 ```js
-import { encodeDataMatrix, decodeDataMatrix } from '@sythos/js_barcode_universal/datamatrix';
+import { encodeAztec, decodeAztec } from '@sythos/js_barcode_universal/aztec';
 
-const symbol = encodeDataMatrix('0101234567890128', { gs1: true, shape: 'square' });
-const result = decodeDataMatrix(symbol);
-console.log(result.text, result.gs1); // 0101234567890128 true
+const symbol = encodeAztec('Ciao, mondo 👋', { eccPercent: 23 });
+const result = decodeAztec(symbol);
+console.log(result.text); // Ciao, mondo 👋
 ```
 
-Binary content is accepted as a `Uint8Array` with `encoding: 'base256'`. The current high-level
-decoder handles ASCII and Base256 codewords; C40, Text, X12 and EDIFACT input symbols are not yet
-decoded. The current detector accepts axis-aligned square or rectangular symbols; the normal
-`decode(image, { formats: ['datamatrix'] })` pipeline also retries quarter-turn rotations.
-Arbitrary-angle and perspective-skewed Data Matrix photographs are not yet guaranteed.
+The image detector handles rotation, inverted polarity and quadrilateral sampling around the
+central bull’s-eye. Severe photographic perspective remains an interoperability and robustness
+gate rather than a guaranteed capability.
 
 ### Not implemented
-
-**PDF417, Aztec, GS1 DataBar and MaxiCode are not implemented** — neither writing
-nor reading. Data Matrix ECC 200 is implemented for its classic square and rectangular symbols;
-DMRE remains outside the current scope. Some scaffolding for the remaining formats exists in the core (the Galois field code already handles
-the prime field PDF417 needs), but none of those remaining symbologies is usable today. See [`PLAN.md`](PLAN.md)
+
+**PDF417, GS1 DataBar and MaxiCode are not implemented** — neither writing
+nor reading. Data Matrix ECC 200 is implemented for its classic square and rectangular symbols;
+DMRE remains outside the current scope. Some scaffolding for the remaining formats exists in the core (the Galois field code already handles
+the prime field PDF417 needs), but none of those remaining symbologies is usable today. See [`PLAN.md`](PLAN.md)
 for where they sit.
 
 ---
@@ -255,7 +276,9 @@ for where they sit.
 ## Live examples
 
 Two self-contained pages, each loading the IIFE bundle with a plain `<script>` tag. **Both open
-directly from disk** — double-click the file, no server and no build.
+directly from disk** — double-click the file, no server and no build. This `examples/` directory is
+the single canonical source; the development workspace references these files instead of keeping
+a second copy.
 
 ### [`examples/create.html`](examples/create.html)
 
@@ -289,15 +312,18 @@ hatch.
 encode(text, options?) → BitMatrix
 ```
 
-`options`: `format` (default `'qr'`), `ecc` (`'L'|'M'|'Q'|'H'`), `version` (QR 1–40, auto if
+`options`: `format` (default `'qr'`), `ecc` (`'L'|'M'|'Q'|'H'`), `version` (QR 1–40, auto if
 omitted), `checkDigit`, `fullAscii` (Code 39 extended), `gs1` (emit a leading FNC1). Data Matrix
 ECC 200 accepts `shape: 'any' | 'square' | 'rectangular'` and `encoding: 'ascii' | 'base256'`.
+Aztec accepts `layers`, `compact` and `eccPercent`; it transports UTF-8 byte payloads through
+Binary Shift, and it does not expose configurable ECI yet.
 
 ```js
 encode('5901234123457', { format: 'ean13' })
 encode('ABC-123', { format: 'code39', fullAscii: true, checkDigit: true })
-encode('https://example.com', { format: 'qr', ecc: 'H', version: 7 })
+encode('https://example.com', { format: 'qr', ecc: 'H', version: 7 })
 encode('0101234567890128', { format: 'datamatrix', gs1: true })
+encode('Ciao, mondo 👋', { format: 'aztec', eccPercent: 23 })
 ```
 
 ```js
@@ -379,12 +405,12 @@ margin ends up uniform on all four sides.
 RGBA bytes → luminance → binarize → detect → sample → error-correct → decode
 ```
 
-Luminance conversion flattens the image to greyscale. Binarization turns that into a `BitMatrix`,
-either globally or with a hybrid local threshold that survives uneven lighting. Detection locates
-a symbol and its corners in that bit plane. Detectors that recover four perspective-aware corners
-(currently QR) sample the symbol back through a perspective transform. Data Matrix currently uses
-an axis-aligned bounding box plus quarter-turn retries. Error correction repairs what the camera
-lost. Only then is the payload decoded.
+Luminance conversion flattens the image to greyscale. Binarization turns that into a `BitMatrix`,
+either globally or with a hybrid local threshold that survives uneven lighting. Detection locates
+a symbol and its corners in that bit plane. Detectors that recover four perspective-aware corners
+(currently QR) sample the symbol back through a perspective transform. Data Matrix currently uses
+an axis-aligned bounding box plus quarter-turn retries. Error correction repairs what the camera
+lost. Only then is the payload decoded.
 
 **Reed–Solomon is generic over the finite field.** The `GaloisField` class is constructed with a
 field order and a primitive polynomial rather than hard-coding GF(256), which is what lets one
@@ -435,15 +461,15 @@ authorship — and from constant tables generated by this project's own scripts
 derivable rather than arbitrary. There is consequently no upstream licence to carry and no
 co-author to credit.
 
-**Trademark is not licence.** QR Code® is a registered trademark of DENSO WAVE; Aztec Code,
-MaxiCode and GS1 DataBar are likewise marks of their owners. A trademark does not restrict
-implementing a symbology, but it does constrain branding — which is why this package is named
-descriptively rather than after any mark.
-
-Data Matrix ECC 200 is governed by ISO/IEC 16022:2024; GS1 DataMatrix additionally uses the GS1
-General Specifications and a leading FNC1. Its engineering provenance, patent and trademark
-research notes are recorded in [`licenses/data-matrix.license`](licenses/data-matrix.license),
-with unresolved claims kept explicitly marked `[TO VERIFY]`.
+**Trademark is not licence.** QR Code® is a registered trademark of DENSO WAVE; Aztec Code,
+MaxiCode and GS1 DataBar are likewise marks of their owners. A trademark does not restrict
+implementing a symbology, but it does constrain branding — which is why this package is named
+descriptively rather than after any mark.
+
+Data Matrix ECC 200 is governed by ISO/IEC 16022:2024; GS1 DataMatrix additionally uses the GS1
+General Specifications and a leading FNC1. Its engineering provenance, patent and trademark
+research notes are recorded in [`licenses/data-matrix.license`](licenses/data-matrix.license),
+with unresolved claims kept explicitly marked `[TO VERIFY]`.
 
 [`LICENSE`](LICENSE) carries the full MIT text plus an informational appendix inventorying the
 specification copyrights, patent history and trademarks that surround these symbologies. None of