@forgesworn/qr 0.0.0-seed.0

package/CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+
+## 0.1.0
+
+- First release: encoder (versions 1-40, levels L/M/Q/H, numeric,
+  alphanumeric and byte modes, UTF-8 ECI) with SVG, canvas and terminal
+  renderers.
+- Decoder: RGBA or greyscale frames, local-threshold binarisation, finder
+  and alignment search, perspective sampling, Reed-Solomon correction,
+  inverted and mirrored codes, numeric, alphanumeric, byte, kanji (as
+  bytes), ECI, structured append and FNC1 segments. `decodeModules` for a
+  module grid.
+- Encode vectors from ZXing core 3.5.3; jsQR round-trip tests; decoder
+  tests on synthetic distorted frames with jsQR as the bar.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 TheCryptoDonkey
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,112 @@
+# @forgesworn/qr
+
+A QR code encoder and decoder for browsers, workers and Node, with no
+dependencies. Versions 1-40, all four error correction levels, numeric,
+alphanumeric and byte modes, optional UTF-8 ECI, and SVG, canvas and
+terminal output. The decoder reads a code from camera or screenshot pixels.
+
+The tests compare 114 symbols module for module with an independent encoder
+(ZXing, as a test-time oracle), covering every version and mask, and have an
+independent decoder (jsQR) read back random payloads and every renderer's
+output. Neither ships in the package.
+[SPEC.md](SPEC.md) defines the behaviour exactly, so ports in other
+languages can produce identical output.
+
+The decoder tests draw codes through synthetic camera effects (rotation,
+perspective, small modules, blur, noise, uneven light, inversion and
+mirroring) and require it to read at least as many of those frames as jsQR
+does. They are synthetic; real phone photographs are not yet part of the
+test set.
+
+## Install
+
+```bash
+npm install @forgesworn/qr
+```
+
+ESM only, Node.js 22.13 or later, or any modern browser.
+
+## Use
+
+```ts
+import { drawCanvas, encode, isDark, toSvg, toTerminal } from '@forgesworn/qr'
+
+const qr = encode('https://example.com/', { ecc: 'Q' })
+qr.version   // 2
+qr.size      // 25 modules per side, quiet zone not included
+isDark(qr, 0, 0) // true: the top-left finder
+
+const svg = toSvg(qr, { margin: 4, dark: '#111', light: '#fff', title: 'Link to example.com' })
+
+drawCanvas(document.querySelector('canvas')!, qr, { width: 320 }) // or an OffscreenCanvas
+console.log(toTerminal(qr))  // half-block text for a dark terminal; { ink: 'dark' } for a light one
+```
+
+`encode(data, options)` takes a string (encoded as UTF-8) or a
+`Uint8Array`. Options:
+
+| Option | Default | |
+|---|---|---|
+| `ecc` | `'M'` | `'L'`, `'M'`, `'Q'` or `'H'` |
+| `version` | smallest that fits | 1-40; throws `QrCapacityError` if the data does not fit |
+| `minVersion` | 1 | lower bound when choosing a version |
+| `mask` | lowest penalty | 0-7 |
+| `mode` | most compact | `'numeric'`, `'alphanumeric'` or `'byte'` |
+| `eci` | `false` | in byte mode, mark the data as UTF-8 |
+
+The result's `modules` is a row-major `Uint8Array` of `size * size`
+entries, 1 for dark, with no quiet zone.
+
+Renderers, each with `margin` (quiet zone in modules, default 4):
+
+- `toSvg(qr, { dark, light, title })`: an SVG string, one path, `light: null` for no background.
+- `drawCanvas(canvas, qr, { width, dark, light })`: sizes the canvas to `width` pixels
+  square (default 8 per module) with module edges on whole pixels.
+- `toTerminal(qr, { ink })`: two rows per line in half blocks; `ink: 'light'` (default)
+  for dark terminals, `'dark'` for light ones.
+
+### Reading
+
+```ts
+import { decode } from '@forgesworn/qr'
+
+const frame = ctx.getImageData(0, 0, width, height) // RGBA, as a canvas gives
+const found = decode(frame)
+found?.text      // the payload as text: UTF-8 when it is valid UTF-8, else Latin-1, unless an ECI says
+found?.bytes     // the raw bytes
+found?.location  // picture coordinates of the three finders
+```
+
+`decode(image, options)` takes `{ data, width, height }` with RGBA or
+greyscale bytes and returns `undefined` when it finds no readable code.
+Options: `rowStride` (pixels a row, for padded camera planes), `channels`
+(1 or 4; worked out from the data length by default) and `inversion`
+(`'both'` by default, or `'normal'` or `'inverted'`). The result also says
+whether the code was `mirrored` or `inverted`, and its `version`, `ecc` and
+`mask`. Kanji segments are kept as bytes and show as U+FFFD in `text`. A frame with no code in it costs more than one with a code; on a
+1280x720 frame of pure noise, expect a few hundred milliseconds on a
+laptop, so throttle camera loops.
+
+`decodeModules(modules, size)` reads a module grid you already have.
+
+## Development
+
+```bash
+npm install
+npm run check              # typecheck and tests
+npm run build              # compile to dist/
+npm run generate-vectors   # regenerate the ZXing vectors (needs a JDK and network once)
+```
+
+## Support
+
+For issues and feature requests, see [GitHub Issues](https://github.com/forgesworn/qr/issues).
+
+If you find this library useful, consider sending a tip:
+
+- **Lightning:** `profusemeat89@walletofsatoshi.com`
+- **Nostr zaps:** `npub1mgvlrnf5hm9yf0n5mf9nqmvarhvxkc6remu5ec3vf8r0txqkuk7su0e7q2`
+
+## Licence
+
+MIT

package/SPEC.md

@@ -0,0 +1,136 @@
+# Specification
+
+This is what every implementation of `@forgesworn/qr` (TypeScript now,
+Kotlin and Rust later) must do, so that the same input gives the same
+symbol byte for byte. `vectors/encode-vectors.json` is the test of it.
+Section numbers refer to ISO/IEC 18004:2015.
+
+## Input
+
+- Text is encoded as UTF-8. Lone surrogates become U+FFFD.
+- Bytes are encoded as given, always in byte mode.
+
+## Mode
+
+One segment per symbol. Unless the caller names a mode, text whose every
+character is a digit is numeric; text whose every character is in
+`0-9 A-Z space $ % * + - . / :` is alphanumeric; anything else, and the
+empty string, is byte. Kanji mode and mixed segments are not produced.
+
+With `eci: true`, a byte-mode symbol starts with the ECI designator
+`0111` and assignment 26 (UTF-8) as 8 bits (section 7.4.2). Numeric and
+alphanumeric symbols never carry one.
+
+## Version and level
+
+Level M unless the caller names one. The version is the smallest, from
+`minVersion` (default 1), whose data capacity holds the header (ECI if any,
+4-bit mode, character count in the width for that version band:
+1-9, 10-26, 27-40) and the data, and whose count field can hold the
+character count. A requested version that cannot hold the data is an
+error, never a silent upgrade.
+
+## Bit stream and error correction
+
+Terminator of up to four zero bits, zero bits to a byte boundary, then
+pad bytes `0xEC`, `0x11` alternately (section 7.4.10). Codewords split into
+blocks as Table 9 gives (group 2 blocks hold one more data codeword);
+Reed-Solomon over GF(256) with polynomial `0x11D`, generator roots
+`α^0 .. α^(n-1)`. Data codewords are interleaved by index across blocks,
+then error correction codewords the same way.
+
+## Matrix
+
+Finder patterns with separators, the dark module at (8, size - 8),
+alignment patterns at every pair of Annex E centres except those on a
+finder, timing patterns on row and column 6, then format and version
+areas reserved. Data fills two-module columns from the bottom right,
+upward first, skipping column 6 and every reserved module; remainder
+bits are light before masking.
+
+Format information is `(level bits << 3 | mask)` with level bits L=01,
+M=00, Q=11, H=10, BCH(15,5) with generator `0x537`, XOR `0x5412`. Bit
+`i` (least significant first) goes at the i-th of (8,0) (8,1) (8,2) (8,3)
+(8,4) (8,5) (8,7) (8,8) (7,8) (5,8) (4,8) (3,8) (2,8) (1,8) (0,8), as
+(x, y), and again at (size - 1 - i, 8) for `i < 8` or (8, size - 15 + i)
+otherwise. Version information (version 7 and up) is BCH(18,6) with
+generator `0x1F25`; bit `k` (least significant first) goes at
+(k / 3, size - 11 + k % 3) and its transpose.
+
+## Mask
+
+Unless the caller names one, every mask 0-7 is applied to the finished
+symbol (format and version information included) and scored with the four
+penalty rules of section 7.8.3: N1 = 3 per run of five or more same-colour
+modules plus one per module beyond five, rows and columns; N2 = 3 per 2x2
+same-colour block, overlapping; N3 = 40 per `1011101` with four light
+modules before or after, rows and columns; N4 = 10 per whole 5 per cent
+that dark modules deviate from half, rounded down. The lowest score wins;
+ties go to the lower mask.
+
+One choice the standard leaves open: for N3, four light modules that would
+lie outside the symbol do not count (the quiet zone is not scored). ZXing
+makes the same choice, so masks chosen here match it.
+
+## Output
+
+A square of `17 + 4 * version` modules, row-major, 1 for dark, with no
+quiet zone. Renderers add the quiet zone; the default is four modules.
+
+Renderers are not covered by the vectors and need not match byte for byte
+across ports, but must keep these properties: the quiet zone is light;
+a canvas or bitmap renderer puts module edges on whole pixels (edge of
+module `i` at `round(i * width / side)`); a terminal renderer packs two
+module rows per line with U+2580 (upper half), U+2584 (lower half), U+2588
+(full) and space, inking light modules by default.
+
+## Vectors
+
+`vectors/encode-vectors.json` holds module matrices produced by ZXing core
+3.5.3 (`scripts/generate-vectors.sh`). They cover every version at full
+capacity, every mask, every level, all three modes, both count-length band
+edges, the empty string and UTF-8 with ECI. ZXing is a development-time
+oracle only and is not part of the package.
+
+## Decoder
+
+The decoder is not bound by the vectors in the same way: ports may find
+codes differently, but must return the same payload for any symbol they
+read. The TypeScript pipeline, for reference:
+
+1. Luminance: RGBA to grey as `(77 R + 150 G + 29 B) >> 8`, with alpha
+   blended onto white, so a code drawn on a transparent canvas reads.
+2. Binarisation: 8x8 blocks; each block's threshold is the mean of the
+   block averages in the 5x5 blocks around it; a block with a range of 24
+   or less borrows its neighbours' level. Pictures under 40 pixels a side
+   use one global threshold.
+3. Finders: row scans for 1:1:3:1:1 runs, each checked down the column,
+   back across the row and along a diagonal, with a strict and then a looser
+   ratio tolerance. Centres within a module of each other merge.
+4. Triples: three finders of similar module size forming a near right
+   isosceles triangle; the cross product puts the top-right finder on the
+   right.
+5. Size and alignment: size from finder distances over module size,
+   rounded to `1 (mod 4)`. From version 2, alignment candidates are found
+   near the corner the finders imply, and ranked by how well the 5x5 pattern
+   around each matches along the code's axes; the parallelogram corner is
+   the last resort. Sizes four and eight modules either side are retried.
+6. Sampling: a perspective map from module centres to the picture, then
+   format and version information, unmasking and Reed-Solomon correction
+   (section 7.5 and annex B). A failed read is retried transposed, for
+   mirrored codes, and the whole search is repeated on the inverted
+   picture.
+7. Segments: numeric, alphanumeric, byte, kanji (kept as Shift_JIS bytes),
+   ECI, structured append (header skipped) and FNC1 (indicators skipped).
+   Byte text is UTF-8 under ECI 26 or when it is valid UTF-8, and Latin-1
+   otherwise or under ECI 1 or 3.
+
+## Decode fixtures
+
+`vectors/decode-frames/` holds 36 synthetic frames as 8-bit greyscale PNG,
+and `vectors/decode-frames.json` gives each one's exact text, the drawing
+parameters, and whether this decoder and jsQR read it when the frames were
+made. A port must read every frame marked `"typescript": true`. The frames
+are drawn by `test/fixtures.test.ts` (`QR_WRITE_FIXTURES=1` regenerates
+them); every payload in them is made up. Real photographs will join them as
+a separate set.

package/dist/binarise.d.ts

@@ -0,0 +1,26 @@
+/** A greyscale picture: one byte per pixel, 0 black to 255 white. */
+export interface Luminance {
+    readonly data: Uint8Array;
+    readonly width: number;
+    readonly height: number;
+}
+/** A black-and-white picture: 1 for dark. */
+export interface BitImage {
+    readonly data: Uint8Array;
+    readonly width: number;
+    readonly height: number;
+}
+/**
+ * Greyscale from RGBA (4 bytes a pixel) or grey (1 byte a pixel) data, with
+ * an optional row stride in pixels for padded camera planes. Transparent
+ * pixels count as white, so a code drawn on a transparent canvas still reads.
+ */
+export declare function toLuminance(data: Uint8Array | Uint8ClampedArray, width: number, height: number, channels: 1 | 4, rowStride?: number): Luminance;
+/**
+ * Local-threshold binarisation: each 8x8 block's threshold is the mean of the
+ * block averages in the 5x5 blocks around it, and a flat block borrows its
+ * neighbours' threshold, so shadows and gradients across the frame do not
+ * swallow the code. Pictures under 40 pixels a side use one global threshold.
+ */
+export declare function binarise(image: Luminance): BitImage;
+export declare function invert(image: BitImage): BitImage;

package/dist/binarise.js

@@ -0,0 +1,115 @@
+/**
+ * Greyscale from RGBA (4 bytes a pixel) or grey (1 byte a pixel) data, with
+ * an optional row stride in pixels for padded camera planes. Transparent
+ * pixels count as white, so a code drawn on a transparent canvas still reads.
+ */
+export function toLuminance(data, width, height, channels, rowStride = width) {
+    const out = new Uint8Array(width * height);
+    for (let y = 0; y < height; y++) {
+        for (let x = 0; x < width; x++) {
+            const i = (y * rowStride + x) * channels;
+            if (channels === 1) {
+                out[y * width + x] = data[i];
+            }
+            else {
+                const a = data[i + 3];
+                const grey = (data[i] * 77 + data[i + 1] * 150 + data[i + 2] * 29) >> 8;
+                out[y * width + x] = (grey * a + 255 * (255 - a)) / 255;
+            }
+        }
+    }
+    return { data: out, width, height };
+}
+const BLOCK = 8;
+const MIN_DYNAMIC_RANGE = 24;
+/**
+ * Local-threshold binarisation: each 8x8 block's threshold is the mean of the
+ * block averages in the 5x5 blocks around it, and a flat block borrows its
+ * neighbours' threshold, so shadows and gradients across the frame do not
+ * swallow the code. Pictures under 40 pixels a side use one global threshold.
+ */
+export function binarise(image) {
+    const { data, width, height } = image;
+    const out = new Uint8Array(width * height);
+    if (width < 40 || height < 40) {
+        let sum = 0;
+        let min = 255;
+        let max = 0;
+        for (const v of data) {
+            sum += v;
+            if (v < min)
+                min = v;
+            if (v > max)
+                max = v;
+        }
+        const threshold = max - min < MIN_DYNAMIC_RANGE ? -1 : (min + max) / 2;
+        for (let i = 0; i < data.length; i++)
+            out[i] = data[i] <= threshold ? 1 : 0;
+        return { data: out, width, height };
+    }
+    const across = Math.ceil(width / BLOCK);
+    const down = Math.ceil(height / BLOCK);
+    const levels = new Float64Array(across * down);
+    for (let by = 0; by < down; by++) {
+        const top = Math.min(by * BLOCK, height - BLOCK);
+        for (let bx = 0; bx < across; bx++) {
+            const left = Math.min(bx * BLOCK, width - BLOCK);
+            let sum = 0;
+            let min = 255;
+            let max = 0;
+            for (let y = top; y < top + BLOCK; y++) {
+                for (let x = left; x < left + BLOCK; x++) {
+                    const v = data[y * width + x];
+                    sum += v;
+                    if (v < min)
+                        min = v;
+                    if (v > max)
+                        max = v;
+                }
+            }
+            let level = sum / (BLOCK * BLOCK);
+            if (max - min <= MIN_DYNAMIC_RANGE) {
+                // A flat block: assume it is background unless its neighbours say otherwise.
+                level = min / 2;
+                if (bx > 0 && by > 0) {
+                    const around = (levels[(by - 1) * across + bx] + 2 * levels[by * across + bx - 1] + levels[(by - 1) * across + bx - 1]) / 4;
+                    if (min < around)
+                        level = around;
+                }
+            }
+            levels[by * across + bx] = level;
+        }
+    }
+    for (let by = 0; by < down; by++) {
+        const top = Math.min(by * BLOCK, height - BLOCK);
+        const cy = Math.min(Math.max(by, 2), down - 3);
+        for (let bx = 0; bx < across; bx++) {
+            const left = Math.min(bx * BLOCK, width - BLOCK);
+            const cx = Math.min(Math.max(bx, 2), across - 3);
+            let sum = 0;
+            let n = 0;
+            for (let dy = -2; dy <= 2; dy++) {
+                for (let dx = -2; dx <= 2; dx++) {
+                    const yy = cy + dy;
+                    const xx = cx + dx;
+                    if (yy < 0 || xx < 0 || yy >= down || xx >= across)
+                        continue;
+                    sum += levels[yy * across + xx];
+                    n++;
+                }
+            }
+            const threshold = sum / n;
+            for (let y = top; y < top + BLOCK; y++) {
+                for (let x = left; x < left + BLOCK; x++)
+                    out[y * width + x] = data[y * width + x] <= threshold ? 1 : 0;
+            }
+        }
+    }
+    return { data: out, width, height };
+}
+export function invert(image) {
+    const out = new Uint8Array(image.data.length);
+    for (let i = 0; i < out.length; i++)
+        out[i] = image.data[i] ^ 1;
+    return { data: out, width: image.width, height: image.height };
+}

package/dist/canvas.d.ts

@@ -0,0 +1,29 @@
+import { type QrCode } from './encode.js';
+/** The slice of a 2D context the renderer uses, so it needs no DOM types. */
+export interface Canvas2dLike {
+    fillStyle: unknown;
+    fillRect(x: number, y: number, width: number, height: number): void;
+}
+/** An `HTMLCanvasElement`, an `OffscreenCanvas`, or anything shaped like one. */
+export interface CanvasLike {
+    width: number;
+    height: number;
+    getContext(type: '2d'): Canvas2dLike | null;
+}
+export interface CanvasOptions {
+    /** Width and height of the canvas in pixels. Default 8 pixels per module. */
+    width?: number;
+    /** Quiet zone in modules on every side. Default 4, the standard's minimum. */
+    margin?: number;
+    /** Colour of dark modules. Default `'#000'`. */
+    dark?: string;
+    /** Background colour, or `null` to leave the canvas transparent. Default `'#fff'`. */
+    light?: string | null;
+}
+/**
+ * Draws a code onto a canvas, resizing it to `width` square and replacing
+ * whatever it held. Module edges fall on whole pixels, so nothing is
+ * anti-aliased; when `width` is not a multiple of the module count, modules
+ * differ in size by at most one pixel.
+ */
+export declare function drawCanvas(canvas: CanvasLike, qr: QrCode, options?: CanvasOptions): void;

package/dist/canvas.js

@@ -0,0 +1,44 @@
+/**
+ * Draws a code onto a canvas, resizing it to `width` square and replacing
+ * whatever it held. Module edges fall on whole pixels, so nothing is
+ * anti-aliased; when `width` is not a multiple of the module count, modules
+ * differ in size by at most one pixel.
+ */
+export function drawCanvas(canvas, qr, options = {}) {
+    const margin = options.margin ?? 4;
+    if (!Number.isInteger(margin) || margin < 0)
+        throw new RangeError('Margin must be a whole number of modules');
+    const side = qr.size + margin * 2;
+    const width = options.width ?? side * 8;
+    if (!Number.isInteger(width) || width < side) {
+        throw new RangeError(`Width must be a whole number of pixels, at least ${side} for this code`);
+    }
+    canvas.width = width;
+    canvas.height = width;
+    const context = canvas.getContext('2d');
+    if (context === null)
+        throw new Error('The canvas has no 2D context');
+    const light = options.light === undefined ? '#fff' : options.light;
+    const edge = (module) => Math.round((module * width) / side);
+    if (light !== null) {
+        context.fillStyle = light;
+        context.fillRect(0, 0, width, width);
+    }
+    context.fillStyle = options.dark ?? '#000';
+    for (let y = 0; y < qr.size; y++) {
+        const top = edge(y + margin);
+        const height = edge(y + margin + 1) - top;
+        let x = 0;
+        while (x < qr.size) {
+            if (qr.modules[y * qr.size + x] !== 1) {
+                x++;
+                continue;
+            }
+            const start = x;
+            while (x < qr.size && qr.modules[y * qr.size + x] === 1)
+                x++;
+            const left = edge(start + margin);
+            context.fillRect(left, top, edge(x + margin) - left, height);
+        }
+    }
+}

package/dist/decode.d.ts

@@ -0,0 +1,42 @@
+import { type Point } from './locate.js';
+import { type Payload } from './symbol.js';
+/** Pixels to read: RGBA (4 bytes a pixel, as ImageData gives) or greyscale (1 byte a pixel). */
+export interface ImageLike {
+    readonly data: Uint8Array | Uint8ClampedArray;
+    readonly width: number;
+    readonly height: number;
+}
+export interface DecodeOptions {
+    /** Pixels from the start of one row to the next, for padded camera planes. Default: width. */
+    readonly rowStride?: number;
+    /** Bytes a pixel. Default: worked out from the data length. */
+    readonly channels?: 1 | 4;
+    /** Which way round to look for dark modules. Default 'both': dark on light first, then light on dark. */
+    readonly inversion?: 'normal' | 'inverted' | 'both';
+}
+/** A symbol found in a picture. */
+export interface DecodeResult extends Payload {
+    /** The symbol was mirrored (read transposed). */
+    readonly mirrored: boolean;
+    /** The symbol was light on dark. */
+    readonly inverted: boolean;
+    /** Picture coordinates of the finder pattern centres, and of the alignment pattern if one was used. */
+    readonly location: {
+        readonly topLeft: Point;
+        readonly topRight: Point;
+        readonly bottomLeft: Point;
+        readonly alignment: Point | undefined;
+    };
+}
+/**
+ * Finds and reads one QR code in a picture. Returns undefined when no
+ * readable code is found.
+ */
+export declare function decode(image: ImageLike, options?: DecodeOptions): DecodeResult | undefined;
+/**
+ * Reads a symbol from its module grid, `size` by `size`, row by row, truthy
+ * for dark, with no quiet zone. Mirrored grids read too.
+ */
+export declare function decodeModules(modules: ArrayLike<number | boolean>, size: number): (Payload & {
+    readonly mirrored: boolean;
+}) | undefined;

package/dist/decode.js

@@ -0,0 +1,98 @@
+import { binarise, invert, toLuminance } from './binarise.js';
+import { finderTriples, findFinders, locate } from './locate.js';
+import { readSymbol } from './symbol.js';
+const MAX_TRIPLES = 6;
+function channelsFor(image, stride) {
+    const { data, width, height } = image;
+    const last = stride * (height - 1) + width;
+    if (data.length >= last * 4)
+        return 4;
+    if (data.length >= last)
+        return 1;
+    throw new RangeError(`The data is too short for a ${width}x${height} picture`);
+}
+/**
+ * Finds and reads one QR code in a picture. Returns undefined when no
+ * readable code is found.
+ */
+export function decode(image, options = {}) {
+    const { width, height } = image;
+    if (!Number.isInteger(width) || !Number.isInteger(height) || width < 1 || height < 1) {
+        throw new RangeError('Width and height must be positive integers');
+    }
+    const stride = options.rowStride ?? width;
+    if (!Number.isInteger(stride) || stride < width)
+        throw new RangeError('rowStride must be an integer of at least width');
+    const channels = options.channels ?? channelsFor(image, stride);
+    const bits = binarise(toLuminance(image.data, width, height, channels, stride));
+    const inversion = options.inversion ?? 'both';
+    if (inversion !== 'inverted') {
+        const found = search(bits, false);
+        if (found)
+            return found;
+    }
+    if (inversion !== 'normal')
+        return search(invert(bits), true);
+    return undefined;
+}
+function search(image, inverted) {
+    // A strict pass first; a looser one for blurred or small codes.
+    for (const tolerance of [0.5, 0.8]) {
+        const triples = finderTriples(findFinders(image, tolerance)).slice(0, MAX_TRIPLES);
+        for (const triple of triples) {
+            const first = locate(image, triple);
+            if (first.length === 0)
+                continue;
+            // The size estimate can be a version out; try the neighbours too.
+            for (const delta of [0, -4, 4, -8, 8]) {
+                for (const location of delta === 0 ? first : locate(image, triple, first[0].size + delta)) {
+                    const result = read(image, location, inverted);
+                    if (result)
+                        return result;
+                }
+            }
+        }
+    }
+    return undefined;
+}
+function read(image, location, inverted) {
+    const { size, project } = location;
+    const modules = new Uint8Array(size * size);
+    for (let y = 0; y < size; y++) {
+        for (let x = 0; x < size; x++) {
+            const p = project(x, y);
+            const px = Math.floor(p.x);
+            const py = Math.floor(p.y);
+            if (px >= 0 && py >= 0 && px < image.width && py < image.height)
+                modules[y * size + x] = image.data[py * image.width + px];
+        }
+    }
+    const where = {
+        topLeft: location.topLeft,
+        topRight: location.topRight,
+        bottomLeft: location.bottomLeft,
+        alignment: location.alignment,
+    };
+    const straight = readSymbol((x, y) => modules[y * size + x] === 1, size);
+    if (straight)
+        return { ...straight, mirrored: false, inverted, location: where };
+    const mirrored = readSymbol((x, y) => modules[x * size + y] === 1, size);
+    if (mirrored)
+        return { ...mirrored, mirrored: true, inverted, location: where };
+    return undefined;
+}
+/**
+ * Reads a symbol from its module grid, `size` by `size`, row by row, truthy
+ * for dark, with no quiet zone. Mirrored grids read too.
+ */
+export function decodeModules(modules, size) {
+    if (modules.length < size * size)
+        throw new RangeError('Fewer modules than size x size');
+    const at = (i) => Boolean(modules[i]);
+    const straightRead = (x, y) => at(y * size + x);
+    const straight = readSymbol(straightRead, size);
+    if (straight)
+        return { ...straight, mirrored: false };
+    const mirrored = readSymbol((x, y) => at(x * size + y), size);
+    return mirrored ? { ...mirrored, mirrored: true } : undefined;
+}