UNPKG

@forgesworn/qr

Version:

Dependency-free QR code encoder and decoder for TypeScript, browsers, workers and Node, with optional WebAssembly and tracked camera scanning.

360 lines (326 loc) • 21.9 kB
# Changelog ## 0.3.14 - After all earlier reads fail, sample one quadratic surface from the first fully measured 3×3 alignment lattice and the actual finder anchors. Preserve earlier successful results and strict format, version and payload checks; add no finder or alignment search. Mirror the recovery in all three ports. - Recover 143 additional synthetic curved frames: 861/1,376 exact reads versus 718/1,376 in 0.3.13 and 646/1,376 for pinned ZXing-WASM 3.1.7. The separate 256-frame set frozen before evaluation reads 118 versus ZXing's 77. No earlier successful result is lost or changed, and QR returns no wrong payload in these comparisons. ZXing still reads 14 curved frames QR misses. - Preserve the 888-case regression outcomes, including 180/184 photographs and rejection of all 64 negative controls. Add five shared conformance fixtures for the new geometric recovery. - Keep the eight legacy second looks and add at most one terminal threshold computation, 4,761 module samples and one symbol read. Retain 18 doubles (144 logical bytes) plus metadata. Legacy Work counters exclude the new terminal pass; equal counters do not mean equal CPU work or allocation. - Qualify the runtime trade-off on native M4: the twelve sampled new reads increase WASM median latency by 0.18–4.27% and TypeScript by 0.66–6.06%. The packaged WASM grows by 8,908 bytes to 261,831 bytes. Random-noise rejection remains about 2.6× slower than ZXing; see PERFORMANCE.md. ## 0.3.13 - After the selected refined-grid header read fails, try its strict orientation and format hypothesis once on the direct mesh captured by the same refinement call. Preserve every earlier successful result, with no new image sampling, alignment search or secondary attempt. - Recover five more codes across 1,120 evaluated curved images: 653 correct reads against 569 for ZXing-WASM 3.1.7. The separate 128-image set frozen before evaluation improves from 77 to 78 reads, against ZXing's 69. Earlier successful results, metadata and work counts remain identical in these checks; these are dataset results, not a universal accuracy claim. - Mirror the recovery in TypeScript, Rust and Kotlin. Add two conformance frames while preserving all 82 previous entries. The 888-case regression suite, its 64 negative controls and all 2,944 photograph views retain their earlier outcomes, with no incorrect payloads observed. - Keep the eight-second-look, 720-map and 11,500,000-alignment-probe limits. Retaining one more existing grid raises the conservative retained-grid bound to 281,961 module bytes, excluding active buffers and metadata. One additional strict symbol read is not counted by `Work`. The packaged WASM is 252,923 bytes, 404 bytes larger than 0.3.12. - Record the measured TypeScript trade-off: clean-frame medians rise 3.77–6.15% and blank-frame medians 4.32–4.78% in two paired M4 runs. The five new WASM reads cost 0.19–0.89% more than their previous misses. ## 0.3.12 - After all earlier paths fail, read one different strict format hypothesis discovered on an existing refined grid. Preserve ordinary version, Reed–Solomon and segment checks and every earlier successful result. - Recover eleven more codes across 992 evaluated curved images: 571 correct reads against 500 for ZXing-WASM 3.1.7. This includes one additional read in a separate 128-image set frozen before evaluation. These are dataset results, not a claim of universal accuracy. - Apply the recovery to TypeScript, Rust and Kotlin. Add two conformance frames while preserving all 80 previous entries, results and work counts. - Keep the eight-second-look, 720-map and 11,500,000-alignment-probe limits. Retain at most one additional existing grid and perform at most one extra strict symbol validation. Existing `Work` counters do not count that validation or the bounded format checks; unchanged counts do not imply unchanged CPU time. ## 0.3.11 - After all earlier paths fail, validate one retained orientation and format hypothesis against an already sampled refinement grid. Preserve strict validation and the priority of every earlier successful result. - Recover two more codes across the previous 736 curved images, increasing correct reads from 438 to 440 against ZXing's 390. A separate 128-image set frozen before evaluation remains at 62 reads against ZXing's 57. These are measured datasets, not a claim of universal accuracy. - Keep the limits at eight second looks, 720 maps and 11,500,000 alignment probes. The recovery adds no image sampling; it can retain one grid pair and perform up to two additional strict symbol validations. Existing `Work` counters do not measure those validations. ## 0.3.10 - After all earlier paths fail, refine one retained map with an exact version word, a weak contradictory peer and two agreeing format copies. Keep strict final validation and every earlier successful result and its metadata. - Improve the earlier distortion set from 106 to 108/128 against ZXing’s 106/128, and curved sheets from nine to ten reads out of 18. The separate newly frozen 128-case set remains at 67 reads against ZXing’s 53. - Mirror the recovery across TypeScript, Rust and Kotlin. Bound work to eight second looks and 11,500,000 alignment probes, with the map cap still 720. This adds work to qualifying difficult failures in return for more correct reads. ## 0.3.9 - After every earlier decoder path fails, give one retained curved map that received only ordinary refinement the late alignment pass. Match its exact map, header hypothesis and luminance basis; retain strict final validation and the priority of all earlier successful results and metadata. - Improve the earlier distortion set from 103 to 106/128, matching ZXing, and two evaluated holdouts from 62 to 63/128 and 71 to 72/128. A new set frozen before policy evaluation improves from 79 to 80/128, compared with ZXing's 70/128. Curved sheets improve from six to nine reads out of 18. No earlier successful result changes in these checks. - Mirror the recovery across TypeScript, Rust and Kotlin with three new shared regression frames. Bound refinement to seven second looks and 10,062,500 alignment probes; the 720-map limit and existing admission rules are unchanged. This trades additional work on some difficult failures for more correct reads. ## 0.3.8 - Retain one full-size curved map whose format copies disagree, with exact version evidence and a uniquely stronger format copy. Prefer the first zero/one-error copy over a two-error copy when the conflicting peer needs three corrections. Try it only after every earlier path fails; final two-copy format, version, Reed-Solomon and payload checks remain unchanged. - Improve the evaluated distortion sets from 44 to 48/96, 89 to 103/128 and 53 to 62/128. A separate set frozen before evaluation improves from 58 to 71/128, compared with ZXing's 67/128. Earlier curved sheets improve from four to six reads out of 18. No earlier successful result changes in these checks; ZXing still leads on one evaluated distortion set. - Bound the new recovery to one retained candidate and one terminal attempt, raising the maximum to six second looks and 8,625,000 alignment probes. Earlier attempts keep their order. This trades additional work on some difficult frames for more correct reads. ## 0.3.7 - After every earlier decoder path fails, allow one retained curved map that never received a full-size refinement attempt. It must already have an exact version anchor and non-conflicting readable headers. Strict final format, version and payload validation remain required; existing successful results and metadata retain priority. - Improve the evaluated 96-case distortion set from 37 to 44 correct reads, the earlier 128-case set from 81 to 89, and a separately frozen 128-case set from 48 to 53. ZXing reads 42, 106 and 52 respectively. No earlier read is lost in these checks; significant curvature limitations remain. - Keep TypeScript, Rust, Kotlin and packaged WASM aligned with three new shared fixtures covering normal, inverted and mirrored recovery. The terminal retry explicitly raises the maximum refinement attempts to five and the alignment probe bound to 7,187,500. The original four attempts and map budget remain unchanged; extra recovery work trades time for accuracy. ## 0.3.6 - Retain up to four failed alignment-mesh grids and read them only after all earlier decoder paths fail. Timing and edge corrections can displace an already readable mesh; deferred validation recovers it without changing existing successful results or their metadata. Strict header, version and payload checks remain in force. - Improve the evaluated 96-case distortion set from 30 to 37 correct reads, a separately frozen 128-case set from 78 to 81, and the earlier curved-sheet set from two to three reads out of 18. No lost or incorrect reads occur in these sets. ZXing still leads overall on both distortion sets. - Keep reduced-image coordinates and inverted polarity consistent across TypeScript, Rust, Kotlin and packaged WASM. Two shared conformance fixtures cover the recovered paths. Retained grids add bounded storage and sampling; map, alignment-search and second-look limits do not increase. ## 0.3.5 - Continue fully trusted alignment cells to the symbol boundary, fitting the three synthetic corners to the actual finder centres. Unmeasured outer cells retain the previous clamp; no search budgets or acceptance gates change. - Recover both remaining views of the dense curved photograph: 16/16 target transformations and 2,872/2,944 across the photo set, with no lost reads. Recover two of the 18 evaluated curved sheets and one additional image in a separate 96-case distortion set. Significant curvature failures remain. - Keep TypeScript, Rust, packaged WASM and Kotlin aligned through two new shared conformance sheets and stronger orientation tests. Previously readable payloads remain unchanged; correction counts and optional alignment locations can change because sampling or the successful placement changes. ## 0.3.4 - Preserve curved-map candidates from the existing inverse-luminance fallback and refine them with the same polarity-specific thresholds. Earlier reads retain priority; the 720-map and four-second-look limits remain unchanged. - Recover seven inverted views of the dense curved photograph, raising its transformed-image result from 7/16 to 14/16. Across all 2,944 transformations of the 184-photo set, preserve earlier reads and add those seven successes. - Keep TypeScript, Rust, packaged WASM and Kotlin aligned, with public photo regressions covering inversion options, orientation and input preservation. No public API changes. ## 0.3.3 - Recover a dense curved QR photograph with a deferred alignment retry. One exact version word anchors admission; final format, version, error-correction and segment checks remain required. Existing successful paths retain priority. - Revisit missed alignment patterns once using frozen accepted neighbours, retaining the four-second-look and 720-map limits. The conservative maximum alignment-probe allowance doubles only for the deferred path. - Apply the same behaviour to TypeScript, Rust, packaged WASM and Kotlin. Raise the photograph regression floor from 179/184 to 180/184; preserve all earlier outcomes across 888 checked cases, including 64 negative controls. - Publish the limited curvature results and remaining failures alongside the comparison evidence. No public API changes. ## 0.3.2 - Recover additional difficult QR images when the correct finder triple ranks below the first six. The late fallback requires agreeing format and version information, shares the existing frame limits, and preserves earlier reads. - Apply the same behaviour to TypeScript, Rust, packaged WASM and Kotlin, with a shared perspective regression and exact result/work conformance. - Add four correct reads across the existing synthetic regression suites, with no lost success or wrong payload. The separate fresh qualification remains 69/128 for both old and new QR, versus 55/128 for ZXing-WASM 3.1.7. - Align all registry versions on 0.3.2; JSR 0.3.1 was the packaging fix for library 0.3.0. No public API changes. ## 0.3.0 - Optional `@forgesworn/qr/wasm` backend with a bundled module, complete decoded results and platform character-set support. Load it explicitly; ordinary TypeScript imports require no WebAssembly setup. - `createDecoder()` sessions for repeated camera frames in TypeScript and WASM. Sessions read fresh pixels, search the previous region first, and fall back to the full frame in the same call. Reset and disposal are explicit. - Improved inverted-image recovery and faster encoding and decoding across TypeScript, Kotlin and Rust. Lazy sampling, earlier format/error-correction rejection, reusable storage and exhausted-search guards reduce avoidable work. - Version-directed recovery for misestimated large symbols: agreeing format and version copies can trigger a final bounded retry. This recovers the previously missed blurred version-40 regression image in all three ports without increasing map or second-look budgets. - Reproducible WASM builds with pinned Rust 1.96.0 and an independent Linux byte comparison. Published npm tarballs must match across two independent release builds, with trusted publishing and provenance. - Published accuracy and performance evidence against pinned independent readers, including per-photograph regression checks and a frozen stress set. Accuracy preservation takes priority over faster rejection; unsuccessful strict-finder experiments are documented and excluded from the decoder. - Fixed a native Rust invalid-size overflow in `decode_modules`; invalid QR dimensions now return `None` before multiplying the supplied size. - Native `forgesworn-qr` crate with registry metadata, standalone package tests, Rust API documentation and checked renderer dimensions. - Public static documentation, a library-selection guide, updated integration examples, security reporting, and generated full plain-text documentation. CI checks documentation links and generated text for drift. ## 0.2.0 - CI downloads and verifies the real-photograph set for both TypeScript and Kotlin, and runs the WebAssembly result, option, encoder, module-grid and memory checks, plus native renderer comparisons. Local tests use at most two workers, and the damage suites inherit the shared timeout. - Text without a `mode` is split into the numeric, alphanumeric and byte segments with the fewest bits, so payment URIs with an uppercase body fit smaller versions. `QrCode` gains `segments`. Symbols for text that one mode already covers are unchanged. - The decoder reports `structuredAppend` and `fnc1`, reads kanji segments and the other ECI character sets as text, and reads Shift_JIS byte data that carries no ECI. Windows 1252 (ECI 23) is read by hand, because one supported Node release reads that set as Latin-1. - A test set of 184 real photographs, fetched by hash at test time and not committed, with a floor on how many are read and a rule that none may decode to the wrong text. - The decoder reads steeply tilted codes: finders stretched by perspective, triples whose far side is much narrower, and an alignment search placed by a projective map. A symbol of version 7 or above whose two version blocks are both unreadable is read from its size. - When the ordinary search reads nothing, the decoder looks once more at up to four placements whose two format copies agree, moving module centres onto the timing patterns and edges the picture shows and sampling grey. It reads codes on curved or warped surfaces that were missed before; tests of damaged symbols require nothing or the original text. - From version 7 that second look first bends the placement onto the alignment patterns it can find, so large symbols photographed through a lens or on paper that is not flat read. It makes no more reads than before, and a placement whose version information names another size no longer takes one of the four places. - Fixed: a version 40 symbol whose size estimate came out just past 177 modules was given up on without trying 177. - Fixed: a texture matching a mask pattern beside finder patterns (a checkerboard, stripes, a screen's moire) could be returned as a read with empty text. A symbol whose data codewords are all zero now reads as nothing; an empty payload as `encode('')` writes it still reads. - The decoder refuses a block that needed more corrections than Table 9 allows it. That changes versions 1-L, 1-M and 2-L only, where the standard holds back check codewords to catch a misdecode and Reed-Solomon alone would correct one error more (3, 5 and 5 against 2, 4 and 4). A damaged symbol at those three sizes that was read on its last correctable error now reads as nothing; one photograph of the test set is lost to it, so the floor is 177. - When nothing reads at full size, the decoder searches the picture again shrunk by 8, 4 and 2, so close-ups whose large modules carry scan lines, a screen's moire or grain read. The reduced sizes share the frame's caps on maps and second looks, and a read there counts only if both format copies agree with its level and mask. The caps are unchanged, but a frame with no code in it now costs more on average. Two more photographs of the test set read, so the floor is 179. - A conformance pack for ports in other languages, `vectors/conformance.json` with `vectors/README.md`: greyscale conversion, module grids, and for 58 pictures the binarised image, the reduced sizes, the finder candidates, the triples, sizes and sampling maps, the result and the work counted. Both ports are held to it. - A Rust port in `rust/`, with no dependencies: the encoder, SVG and terminal renderers and the whole decoder, held to the same vectors and giving the same reads, locations and counted work as the TypeScript on 603 pictures at four turns each, from sets kept outside the repository. It builds to WebAssembly and decodes in about half the TypeScript's time there. It bundles no character tables, so its text can differ from the other ports', and it refuses hanzi symbols. Not published as a package yet. - SPEC.md states every stage of the decoder exactly, and the details of the encoder that were left to the code; lengths are a square root of squares so that ports agree to the last place. - Text under an ECI the platform cannot read, or one that names no set the decoder knows, is no longer guessed as UTF-8 or Latin-1: what cannot be read is U+FFFD, with ASCII kept under the single-byte sets. `bytes` and `eci` are unchanged. Greek under ECI 9, read where there is no decoder for it, used to come back as accented Latin letters. - The decoder reads hanzi segments (GB2312). - Decoding is faster with no change to what is read or to the work counted. The row scans for finder and alignment patterns walk each row's changes of colour, found once and shared by both polarities, and the three reduced sizes come from one pass over the picture. Measured in Node on one arm64 machine, on the photographs used in development (about 4 megapixels on average): the median frame that read took 6.7 ms against 10.6, the median frame that did not 11.3 ms against 28.2, and the totals over the set, which the slowest frames dominate, fell to about 40% and 30%. A clean code that reads at the first try gains little, and a frame of pure noise about a fifth. The Kotlin port's total was roughly half on a desktop JVM. The rows' changes of colour are kept while a frame is searched: up to 4 bytes a pixel more on a picture that is all fine texture, and 6 to 10 MB more at the peak on 12-megapixel photographs. - The locator's work on a frame full of finder-like patterns is bounded. - `encode` takes only a string or a `Uint8Array` and says what it was given otherwise; input no version can hold is refused before anything is built from it, so a named mode with over-long text now throws `QrCapacityError` first. `decode` takes only `Uint8Array` or `Uint8ClampedArray` data, refuses a buffer of three bytes a pixel unless `channels` is named, and checks `inversion`. `null` options mean none in both. - The tests read every version at every level, filled to the last byte, back with an independent decoder; one vector added, version 23 at level L. - Fixed: `decode` checks the data length when `channels` is given; `isDark` is false outside the symbol; a fixed `version` below `minVersion` throws; `toSvg` output always parses as XML, and an empty `title` adds no image role. - Kotlin port of the encoder and decoder in `kotlin/`, pure JVM 17, checked against the shared encode vectors and decode frames, with an independent library as a test-only oracle; a `kotlin` job in CI. ## 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 an independent encoder; round-trip tests through an independent decoder; decoder tests on synthetic distorted frames with that decoder as the bar.