rapier-jxl 1.1.19 → 2.0.0

package/AGENTS.md

@@ -1,27 +1,24 @@
 # For an agent adding Rapier JXL to an app
 
-1. Install: `npm install rapier-jxl`, or copy one file from this repository's root into the app: `rapier-jxl.min.mjs`
-   (the core), `lossless.min.mjs`, `jpeg.min.mjs` or `photo.min.mjs` (one checked function each), or the readable
-   `.mjs` files with `index.mjs` as the core entry and `photo.mjs` as the optional photo entry. No build needed.
-2. Import `encode` and `transcode` from `rapier-jxl` (the readable modules), `rapier-jxl/min` (the one minified
-   file), or `encodeLosslessRGBA` from `rapier-jxl/lossless` and `transcode` from `rapier-jxl/jpeg`.
-3. Encode pixels: `encode(rgba, width, height, {quality})`, `rgba` being straight (not premultiplied) RGBA bytes
-   row by row, as `CanvasRenderingContext2D.getImageData` gives them; `quality` 100 (the default) is lossless,
-   1 to 99 lossy. Alpha is exact at every quality. For photographic VarDCT, import `encodePhotoRGBA` from
-   `rapier-jxl/photo` and call `encodePhotoRGBA(rgba, width, height, {quality: 90})`. It defaults to 90; 100 is
-   exact, including RGB beneath transparent pixels. Quality numbers across encoders are not equivalent PSNR.
-   Each answer is a `Uint8Array` of JPEG XL codestream bytes: save it as `.jxl` or wrap it in a `Blob` of type `image/jxl`.
-4. Carry a JPEG: `transcode(jpegBytes)` returns `{bytes, width, height, orientation}`; do not decode the JPEG
-   first. If it throws `JXL_JPEG` (a form the carrier does not take, a colour profile other than sRGB, a file cut
-   short), decode it (an `<img>` and a canvas) and call `encode` on the pixels.
-5. Run it in a worker for anything larger than an icon. Calls are synchronous: cancel by terminating that worker,
-   disregard obsolete request IDs and start a replacement worker. A transferred input buffer is no longer owned
-   by the sender; keep a copy first if cancellation must retain the original pixels.
-6. Handle the five error codes (`JXL_INPUT`, `JXL_DIMENSIONS`, `JXL_SIZE`, `JXL_MEMORY`, `JXL_JPEG`); there are no
-   others from the checked entries. The committed conformance cases are decoded by jxl-oxide and native libjxl;
-   this evidence does not prove every possible input. Keep original pixels until encoding and storage succeed.
-7. Show the result only where the browser decodes JPEG XL (`image/jxl` in `<picture>` with a fallback, or a
-   feature test on a one-pixel stream); keep the original where it does not.
+1. `npm install rapier-jxl`, or copy one file from this repository's root: `rapier-jxl.min.mjs` (the core),
+   `effort.min.mjs`, `jpeg.min.mjs` or `photo.min.mjs`. No build.
+2. `import {encode} from 'rapier-jxl'` (or `rapier-jxl/min`), `transcode` from `rapier-jxl/jpeg`, `encodePhoto`
+   from `rapier-jxl/photo`. For smaller lossless files at more time, `encode` from `rapier-jxl/effort` with
+   `{effort: 3}`.
+3. Pixels: `encode(rgba, width, height, {quality})`, straight RGBA row by row as `getImageData` gives it; from a
+   Display P3 canvas, add `colorSpace: 'display-p3'`. Quality 100 (the default) is lossless, 1 to 99 lossy, alpha
+   exact at every quality. Photographs:
+   `encodePhoto(rgba, width, height, {quality: 90})`. The answer is a `Uint8Array` of codestream bytes: save it
+   as `.jxl` or in a `Blob` of type `image/jxl`.
+4. A JPEG: `transcode(jpegBytes)` gives `{bytes, width, height, orientation}` without decoding. On `JXL_JPEG`,
+   decode it and call `encodePhoto` on the pixels.
+5. Anything larger than an icon runs in a worker. Calls are synchronous, so cancel by terminating the worker, or
+   loop over the door's twin (`encodeSteps`, `transcodeSteps`, `encodePhotoSteps`) and leave the loop. A
+   transferred buffer is gone from the sender: copy first if you may retry.
+6. The error codes are `JXL_INPUT`, `JXL_DIMENSIONS`, `JXL_SIZE`, `JXL_MEMORY` and `JXL_JPEG`, no others;
+   `JXL_DIMENSIONS` is past the door's own `LIMITS` (24 million pixels for the core and `effort`, 40 million for
+   `photo`, 64 million for a carried JPEG). Keep the original pixels until the encode and its storage succeed.
+7. Show the result only where the browser decodes JPEG XL (`<picture>` with a fallback, or a one-pixel feature test).
 
-Nothing here reads files, fetches, or touches the DOM; the module is safe to run in a worker, in Node and in
-Deno alike. Do not vendor a minified copy under another name: publish the version you took and its licence.
+Nothing here reads files, fetches or touches the DOM: it runs in a worker, Node or Deno alike. Publish the version
+you took and its licence; do not vendor a minified copy under another name.

package/ENCODER-COMPARISON.md

@@ -1,68 +1,185 @@
 # Encoder payloads measured on 30 September 2026
 
-Rapier JXL is the smallest JavaScript/WebAssembly JPEG XL encoder **among the published payloads measured here**.
-This is a bounded survey, not proof of the smallest possible implementation. The alternatives implement different
-subsets of JPEG XL. In particular, Rapier's JPEG carrier preserves coefficients but cannot reconstruct the original
-JPEG file; libjxl's reversible JPEG mode can. Larger codecs also offer features Rapier does not, including HDR,
-ICC profiles, animation, perceptual search and more compression tools.
+Rapier JXL is the smallest JavaScript or WebAssembly JPEG XL encoder among the published payloads measured here.
+A bounded survey, not proof of a global minimum; the encoders differ in what they cover.
 
 | Encoder / entry | Version | Minified JS + WASM bytes | gzip bytes | Included capability |
 | --- | --- | ---: | ---: | --- |
-| Rapier JXL core | this release | 40,286 | 15,904 | 8-bit lossless RGBA, lossy modular with exact alpha, JPEG coefficients |
-| Rapier JXL lossless | this release | 16,085 | 6,747 | 8-bit exact RGBA |
-| Rapier JXL JPEG | this release | 30,624 | 12,274 | JPEG coefficients, orientation; no JPEG reconstruction |
-| Rapier JXL photo | this release | 25,418 | 10,409 | 8-bit photographic VarDCT, exact alpha; q100 lossless |
+| Rapier JXL core | 2.0.0 | 19,495 | 8,475 | 8-bit lossless RGBA, lossy modular with exact alpha |
+| Rapier JXL effort door | 2.0.0 | 25,229 | 10,606 | The core, and the weighted predictor searched for lossless |
+| Rapier JXL JPEG door | 2.0.0 | 29,592 | 12,533 | JPEG coefficients, orientation; no JPEG reconstruction |
+| Rapier JXL photo door | 2.0.0 | 25,646 | 10,804 | 8-bit photographic VarDCT, exact alpha; q100 lossless |
 | [jSquash](https://github.com/jamsinclair/jSquash/tree/main/packages/jxl) | 1.3.0 | 1,388,572 | 525,782 | 8-bit lossless/lossy RGBA |
-| [Discourse's jSquash package](https://www.npmjs.com/package/@discourse/jxl) | 1.3.0 | 1,388,572 | 525,782 | Same measured encoder bytes as jSquash |
-| [Lacinak's jSquash fork](https://github.com/kelaci/jSquash) | 1.3.0-kelaci.0 | 2,071,514 | 844,866 | Additional high bit-depth input options |
+| [Discourse's jSquash package](https://www.npmjs.com/package/@discourse/jxl) | 1.3.0 | 1,388,572 | 525,782 | The same encoder bytes as jSquash |
+| [Lacinak's jSquash fork](https://github.com/kelaci/jSquash) | 1.3.0-kelaci.0 | 2,071,514 | 844,866 | High bit-depth input options |
 | [squoosh-kit](https://github.com/bnowak008/squoosh-kit/tree/main/packages/jxl) | 0.2.10 | 1,371,789 | 511,927 | 8-bit lossless/lossy RGBA |
-| [icodec](https://github.com/Kaciras/icodec) | 0.6.0 | 2,474,954 | 900,957 | 8–16-bit lossless/lossy pixels |
-| [Cornerstone libjxl](https://github.com/cornerstonejs/codecs/tree/main/packages/libjxl) | 1.1.1 | 2,575,008 | 936,242 | 1–16-bit grayscale/RGB; DICOM-oriented API |
+| [icodec](https://github.com/Kaciras/icodec) | 0.6.0 | 2,474,954 | 900,957 | 8 to 16-bit lossless/lossy pixels |
+| [Cornerstone libjxl](https://github.com/cornerstonejs/codecs/tree/main/packages/libjxl) | 1.1.1 | 2,575,008 | 936,242 | 1 to 16-bit grayscale/RGB; DICOM-oriented API |
 | [jxl-wasm](https://github.com/saschanaz/jxl-wasm) | 0.7.0 | 2,533,758 | 961,538 | libjxl CLI, pixels and reversible JPEG |
-| [jpeg-to-jxl](https://github.com/ChefJulio/jpeg-to-jxl) | 0.2.0 | 2,732,858 | 1,063,406 | Reversible JPEG recompression; includes decode/JPEG fallback |
+| [jpeg-to-jxl](https://github.com/ChefJulio/jpeg-to-jxl) | 0.2.0 | 2,732,858 | 1,063,406 | Reversible JPEG recompression, with decode |
 | [Squoosh library](https://github.com/GoogleChromeLabs/squoosh/tree/dev/libsquoosh) | 0.5.3 | 1,615,596 | 539,210 | Shared multi-codec JavaScript and one JXL encoder WASM |
 
-Bytes are decimal, not KiB. Every listed file, upstream URL, npm archive integrity and SHA-256 is in
-[`public/encoder-sizes.json`](public/encoder-sizes.json). JavaScript is minified with Terser 5.51.2
-(`compress.passes=2`, mangling, license comments retained); shipped WASM is unchanged. Each resource is gzipped
-independently at level 9, then sizes are summed. These are delivery bytes, not npm tarball sizes. Rapier's
-`sizes.json` records its independently optimized single-file builds and complete MIT banner.
-
-The jSquash, fork, squoosh-kit and icodec rows count the low-level encoder factory and its WASM. Optional
-convenience wrappers, threaded variants, workers and decoders are excluded. This favors those alternatives;
-it does not pretend the entire npm package is needed to encode one picture. The Squoosh library has shared
-JavaScript, so that file is included whole. The JPEG-to-JXL package also exposes reverse conversion from the
-same WASM; it is not an encoder-only custom rebuild. Size measurements do not establish the other packages'
-correctness or compression quality.
+Bytes are decimal. JavaScript is minified with Terser 5.51.2 (two compress passes, mangling, licence comments
+kept), WASM is unchanged, each resource is gzipped alone at level 9, then summed: delivery bytes, not tarball
+sizes. Every file, URL, npm integrity and SHA-256 is in [`public/encoder-sizes.json`](public/encoder-sizes.json).
+The jSquash, fork, squoosh-kit and icodec rows count the encoder factory and its WASM only, without wrappers,
+workers or decoders, which favours them. Size says nothing about correctness or compression quality.
 
 ## Reproduce
 
-In a checkout of this public repository:
-
 ```sh
 npm install --ignore-scripts
 node public/measure-encoders.mjs .encoder-size-cache encoder-sizes.json
 ```
 
-The script fetches only pinned npm archives from `public/encoders.json`, validates their integrity, reads the
-listed members in memory and minifies their JavaScript. It never installs or executes downloaded competitor
-code. The cache makes repeats offline. Rapier's own byte receipt is generated by its source stager, not by
-this survey. For a standalone copy of the script, install `terser@5.51.2` first.
+The script fetches the pinned npm archives in `public/encoders.json`, checks their integrity, reads the listed
+members in memory and minifies them. It never runs downloaded code. Rapier's own bytes come from its stager.
+
+## Quality at matched bytes, 30 September 2026
+
+A small encoder does not mean small or good pictures. This measures Rapier's readable source against the
+[libjxl v0.12.0 reference](https://github.com/libjxl/libjxl/releases/tag/v0.12.0) (`cjxl`, `djxl` and
+`butteraugli_main` from the official Linux x86-64 static archive, SHA-256
+`5318a1ea40adad76d023e0c17a03d4627f8282f83cb2b575e69be8e74f1ff456`) on eleven inputs: four synthetic
+textures, the bundled Grace Hopper JPEG, three generated drawings and three generated paintings. It is not a
+representative collection. Each Rapier stream sets a byte budget; the native encoder, at effort 7 with its mode
+left to `cjxl`, is searched over distances for the largest stream within that budget (a gap of at most 0.5%
+counts as matched). Where native distance 0 already fits, the row is marked **†**: an exact stream in fewer
+bytes, not a match. Both outputs are decoded by the same pinned `djxl` to 8-bit sRGB; alpha is byte-exact in
+every selected decode. PSNR and RGB SSIM are computed over the three RGB channels (single-scale SSIM, 11 × 11
+Gaussian, no downsampling); alpha-bearing inputs are matted on white for the table. Butteraugli is the
+reference tool at 80 nits, the worse of the white and black mattes for alpha inputs. Higher PSNR and SSIM and
+lower Butteraugli are that metric's preference, not a human verdict. **R / N** is Rapier / native.
+
+### The photo door
+
+Native is within 0.402% of the budget in all 20 rows, and better on PSNR and SSIM in 19 of 20 and on
+Butteraugli in 19 of 20; the exceptions are Grace q99 (Rapier's PSNR and SSIM) and lit surface q99 (Rapier's
+Butteraugli).
+
+| Input · Rapier q | Rapier bytes | Native bytes | Native d | PSNR dB R / N ↑ | RGB SSIM R / N ↑ | Butteraugli R / N ↓ |
+| --- | ---: | ---: | ---: | ---: | ---: | ---: |
+| Wood grain · 50 | 6,351 | 6,335 | 5.061 | 33.459 / 37.501 | 0.833394 / 0.920358 | 7.9959 / 3.8476 |
+| Wood grain · 80 | 11,640 | 11,632 | 2.246 | 36.866 / 39.628 | 0.900685 / 0.942440 | 4.0035 / 1.8251 |
+| Wood grain · 90 | 18,713 | 18,713 | 1.226 | 38.910 / 40.727 | 0.929675 / 0.953458 | 2.3318 / 1.5172 |
+| Wood grain · 99 | 76,863 | 76,842 | 0.327 | 45.530 / 47.954 | 0.983684 / 0.991316 | 0.9762 / 0.6128 |
+| Landscape · 50 | 4,729 | 4,710 | 4.944 | 34.594 / 38.053 | 0.852275 / 0.908469 | 8.5642 / 3.4545 |
+| Landscape · 80 | 7,932 | 7,921 | 2.438 | 37.305 / 39.502 | 0.891356 / 0.921732 | 4.1410 / 2.1015 |
+| Landscape · 90 | 12,725 | 12,723 | 1.508 | 39.050 / 40.389 | 0.912417 / 0.931579 | 3.1272 / 1.6892 |
+| Landscape · 99 | 64,221 | 64,192 | 0.377 | 45.545 / 47.492 | 0.977931 / 0.986445 | 1.0067 / 0.6164 |
+| Folded texture · 50 | 3,563 | 3,552 | 5.427 | 35.334 / 38.643 | 0.839685 / 0.908679 | 7.2341 / 4.0082 |
+| Folded texture · 80 | 6,525 | 6,514 | 2.468 | 38.175 / 40.176 | 0.894762 / 0.927122 | 3.6812 / 2.2637 |
+| Folded texture · 90 | 10,046 | 10,046 | 1.668 | 39.618 / 40.820 | 0.917830 / 0.934923 | 2.2918 / 1.6726 |
+| Folded texture · 99 | 57,111 | 57,111 | 0.412 | 45.611 / 47.539 | 0.979148 / 0.986739 | 0.9172 / 0.7164 |
+| Lit surface · 50 | 2,825 | 2,825 | 2.909 | 38.241 / 40.292 | 0.891825 / 0.915090 | 4.4182 / 2.4656 |
+| Lit surface · 80 | 4,107 | 4,107 | 2.314 | 39.474 / 40.530 | 0.903290 / 0.918372 | 3.1575 / 2.1072 |
+| Lit surface · 90 | 5,465 | 5,453 | 1.988 | 40.214 / 40.738 | 0.912497 / 0.921402 | 2.2827 / 1.9999 |
+| Lit surface · 99 | 47,155 | 47,152 | 0.466 | 45.664 / 46.636 | 0.975682 / 0.980349 | 0.9476 / 1.1255 |
+| Grace Hopper · 50 | 15,990 | 15,982 | 5.451 | 29.546 / 30.676 | 0.778970 / 0.807254 | 6.6973 / 4.5990 |
+| Grace Hopper · 80 | 34,419 | 34,409 | 2.338 | 33.675 / 34.477 | 0.862229 / 0.899859 | 3.8410 / 3.0344 |
+| Grace Hopper · 90 | 56,543 | 56,519 | 1.110 | 38.605 / 38.944 | 0.950222 / 0.970007 | 2.3300 / 1.4546 |
+| Grace Hopper · 99 | 110,542 | 110,533 | 0.173 | 49.948 / 47.182 | 0.996348 / 0.995977 | 0.4889 / 0.3406 |
+
+### The core's lossy modular on drawings and paintings
+
+Fourteen rows are matched within 0.127%. In the ten **†** rows an exact native stream fits in 3.052% to
+51.144% fewer bytes. Native SSIM and Butteraugli are better in all 24 rows; PSNR favours Rapier for paint-0001
+and paint-0002 at q80 and q90.
+
+| Input · Rapier q | Rapier bytes | Native bytes | Native d | PSNR dB R / N ↑ | RGB SSIM R / N ↑ | Butteraugli R / N ↓ |
+| --- | ---: | ---: | ---: | ---: | ---: | ---: |
+| recipe-0000 · 50 | 14,972 | 14,953 | 1.102 | 37.276 / 45.992 | 0.989901 / 0.996956 | 3.9870 / 1.0352 |
+| recipe-0000 · 80 | 20,051 | 19,439† | 0 | 42.493 / ∞ | 0.995389 / 1.000000 | 2.6508 / 0.0000 |
+| recipe-0000 · 90 | 25,232 | 19,439† | 0 | 46.614 / ∞ | 0.997777 / 1.000000 | 1.4840 / 0.0000 |
+| recipe-0000 · 99 | 39,788 | 19,439† | 0 | 58.188 / ∞ | 0.999803 / 1.000000 | 0.5505 / 0.0000 |
+| recipe-0001 · 50 | 31,284 | 31,279 | 1.642 | 44.663 / 51.571 | 0.998111 / 0.999252 | 3.6761 / 0.9379 |
+| recipe-0001 · 80 | 37,226 | 35,491† | 0 | 49.928 / ∞ | 0.999293 / 1.000000 | 2.1718 / 0.0000 |
+| recipe-0001 · 90 | 43,439 | 35,491† | 0 | 53.998 / ∞ | 0.999699 / 1.000000 | 0.7681 / 0.0000 |
+| recipe-0001 · 99 | 60,225 | 35,491† | 0 | 63.163 / ∞ | 0.999953 / 1.000000 | 0.2608 / 0.0000 |
+| recipe-0002 · 50 | 18,746 | 18,736 | 1.651 | 34.484 / 40.065 | 0.978619 / 0.992176 | 5.0667 / 1.4144 |
+| recipe-0002 · 80 | 27,036 | 27,025 | 0.749 | 39.856 / 43.976 | 0.990765 / 0.995802 | 2.5048 / 1.0876 |
+| recipe-0002 · 90 | 35,330 | 35,306 | 0.425 | 44.044 / 46.482 | 0.995583 / 0.997393 | 1.7128 / 0.6129 |
+| recipe-0002 · 99 | 59,624 | 36,102† | 0 | 55.523 / ∞ | 0.999602 / 1.000000 | 0.5762 / 0.0000 |
+| paint-0000 · 50 | 45,505 | 45,498 | 1.336 | 36.020 / 40.143 | 0.975668 / 0.991663 | 4.7640 / 1.5576 |
+| paint-0000 · 80 | 54,652 | 54,618 | 0.684 | 39.900 / 43.518 | 0.988270 / 0.995770 | 2.7126 / 0.9569 |
+| paint-0000 · 90 | 65,877 | 65,843 | 0.289 | 43.809 / 47.922 | 0.994447 / 0.998212 | 1.5637 / 0.6630 |
+| paint-0000 · 99 | 97,769 | 74,658† | 0 | 54.474 / ∞ | 0.999312 / 1.000000 | 0.5388 / 0.0000 |
+| paint-0001 · 50 | 61,462 | 61,442 | 1.680 | 33.606 / 34.830 | 0.956089 / 0.972432 | 7.1021 / 1.8314 |
+| paint-0001 · 80 | 75,929 | 75,926 | 0.830 | 37.751 / 37.312 | 0.980393 / 0.982498 | 3.5325 / 1.1308 |
+| paint-0001 · 90 | 93,451 | 93,451 | 0.343 | 41.285 / 40.730 | 0.990186 / 0.990973 | 1.9406 / 0.8474 |
+| paint-0001 · 99 | 143,736 | 124,100† | 0 | 51.793 / ∞ | 0.998622 / 1.000000 | 0.6179 / 0.0000 |
+| paint-0002 · 50 | 81,312 | 81,304 | 2.020 | 32.334 / 34.083 | 0.937986 / 0.962754 | 5.7590 / 2.1400 |
+| paint-0002 · 80 | 98,676 | 98,622 | 1.055 | 36.749 / 36.598 | 0.972358 / 0.976745 | 3.1658 / 1.3790 |
+| paint-0002 · 90 | 119,652 | 119,651 | 0.472 | 40.420 / 39.711 | 0.986313 / 0.987143 | 1.8052 / 1.1247 |
+| paint-0002 · 99 | 187,934 | 170,069† | 0 | 50.304 / ∞ | 0.997853 / 1.000000 | 0.5696 / 0.0000 |
+
+### The JPEG carrier against reversible recompression
+
+`transcode` against `cjxl --lossless_jpeg=1`. The contracts differ: Rapier carries the coefficients and the
+orientation and cannot rebuild the JPEG file; native also stores the reconstruction data and rebuilt every
+original exactly. So a smaller Rapier row is not a like-for-like win. Six inputs are tiny conformance fixtures;
+Grace is the one photograph.
+
+| JPEG input | Original bytes | Rapier carrier | Native reversible | JPEG rebuilt by native |
+| --- | ---: | ---: | ---: | --- |
+| grey-sequential.jpg | 141 | 117 | 177 | yes |
+| quant-before-scan.jpg | 141 | 120 | 181 | yes |
+| quant-after-scan.jpg | 210 | 120 | refused | no reconstruction data possible |
+| colour-sequential.jpg | 925 | 499 | 662 | yes |
+| colour-progressive-restarts.jpg | 1,367 | 464 | 820 | yes |
+| decoder-difference.jpg | 925 | 499 | 662 | yes |
+| reconstruction-difference.jpg | 925 | 510 | 676 | yes |
+| grace-hopper.jpg | 86,089 | 60,543 | 58,773 | yes |
+
+### Inputs and commands
+
+Textures are the first four `synthetic-photo` seeds of `tools/corpus/jxl-images.mjs` at 512 × 384; drawings and
+paintings the first three seeds of each kind at the same size, through the real Draw and Paint owners with the
+bundled Geist fonts and pinned `@napi-rs/canvas` 0.1.100. Grace is the public-domain fixture in
+`public/test/photo-corpus/`, decoded once with `ffmpeg -pix_fmt rgba` at its native size.
+
+| Input | Dimensions | Seed | Pixels with alpha < 255 | RGBA SHA-256 |
+| --- | ---: | ---: | ---: | --- |
+| Wood grain | 512 × 384 | 3399228925 | 0 | `cfc2495231eb53c4d423ab5ea7692e3cafce6160f07cc51942b910a89d5ffab7` |
+| Landscape | 512 × 384 | 1351084136 | 0 | `c6c33cc695b19538ec6780647e32fd4f22b24872292d22707f26ab9ad1a0cef2` |
+| Folded texture | 512 × 384 | 3597906643 | 0 | `57a0f40e8e14eb0b9fe5286dbfec7bc7783b1e748c6888ea44791f088b0ea106` |
+| Lit surface | 512 × 384 | 1549761854 | 0 | `d998747e1c427144424c4d59f6795f88a2d2983a341dcba54b5a6b346e4f0a0d` |
+| Grace Hopper | 512 × 600 | — | 0 | `af6a4dc548da3797b814f4be1b4489effe658ad13ba842d839628d01ba3ee39f` |
+| recipe-0000 | 512 × 384 | 2385324683 | 23,538 | `6d8240cac5db3c3db509125658ba32cb919537b113ae9f0877856fe6c091e67f` |
+| recipe-0001 | 512 × 384 | 337179894 | 163,701 | `7a5acaf7274bbadfabaa351f0dd3a7931818a438424d17ae555a2c2f72338b9f` |
+| recipe-0002 | 512 × 384 | 2584002401 | 20,928 | `08ce520f30a10897b4acbb630e8d39aeeb97d53e02b50ac721ad80260fd2484c` |
+| paint-0000 | 512 × 384 | 744793156 | 194,804 | `ad9467838000b99434d7f7cb041111cd0bad8f64fe2511ce98d0d106ebd147a3` |
+| paint-0001 | 512 × 384 | 2991615663 | 193,919 | `a3af498e21cade0969d0b3fa63118316a18601aa23bd1b35ffc561e70a123237` |
+| paint-0002 | 512 × 384 | 943470874 | 191,708 | `d2c586460a91e5bcb4c213080f46e4945d674ed6920230f50b2ab396076ea3c1` |
+
+```sh
+cjxl INPUT.pam OUTPUT.jxl --distance=D --effort=7 --num_threads=0 \
+  --alpha_distance=0 --keep_invisible=1 --premultiply=0 --container=0 \
+  -x color_space=RGB_D65_SRG_Per_SRG --quiet
+djxl INPUT.jxl OUTPUT.pam --bits_per_sample=8 --color_space=RGB_D65_SRG_Per_SRG --num_threads=0 --quiet
+butteraugli_main REFERENCE.ppm DECODED.ppm --intensity_target 80
+cjxl INPUT.jpg OUTPUT.jxl --lossless_jpeg=1 --effort=7 --num_threads=0 --quiet
+djxl OUTPUT.jxl RECONSTRUCTED.jpg --reconstruct_jpeg --num_threads=0 --quiet
+```
+
+From `repo/` in the development checkout, `tools/probes/jxl-quality.mjs --section=photo|modular|jpeg` makes
+the inputs, encodes, runs the bracket search and writes `photo.json`, `modular.json` and `jpeg.json`;
+`tools/probes/jxl-quality-metrics.py` computes the metrics (Python 3.12, NumPy 2.3, SciPy 1.17). The full
+candidate pools, byte brackets, hashes and metric components are in the development receipts.
 
 ## Found but not ranked
 
-| Project | What was found | Why it is outside the numeric encoder ranking |
-| --- | --- | --- |
-| [jxl-oxide-wasm](https://github.com/tirr-c/jxl-oxide-wasm) 0.12.6 | 1,707,757 minified JS + WASM bytes; 612,548 gzip | Decoder only; cannot encode pixels or JPEGs |
-| [jxl.js](https://github.com/niutech/jxl.js), jxl-rs-polyfill, TurboJXL, PureJsImage's JXL codec | Browser decoders | Decoding support is not encoding support |
-| [libjxl](https://github.com/libjxl/libjxl/blob/main/doc/building_wasm.md) | WASM build instructions; official browser demo is a decoder | Encoder builds are represented by the measured libjxl-based packages; no single canonical encoder payload is published by this demo |
-| [jixel](https://github.com/awxkee/jixel), revision `d84b45ff22d23895c76f58875358676d99e3081b` | Rust encoder, WASM-specific source; releases 0.3.2 and earlier have no downloadable WASM assets | No pinned public executable WASM package found; source bytes are not executable bytes |
-| [libjxl-tiny](https://github.com/libjxl/libjxl-tiny), revision `8eae18172059d54f5c734ca814f23b96eebff859` | Small C++ encoder and WASM build instructions | No published WASM payload found; an unmeasured custom build cannot support a size ranking |
-| [Hydrium](https://github.com/Traneptora/hydrium), revision `45227f35a222fadfd094a37325f937a6e9442c48` | Streaming C encoder; releases offer native executables | No JavaScript/WASM payload found |
-| [Imazen jxl-encoder](https://github.com/imazen/jxl-encoder), revision `0d79a23e30da9504cd5f1e1b8a849cb930feb5fe` | Rust encoder and WASM benchmark example | No published WASM payload found |
-| webcvt's jsquash-jxl adapter | Wrapper around `@jsquash/jxl` | Same encoder already measured; wrapper is additional application code |
-| sharp/libvips packages and `cjxl` npm wrapper | Native binaries | Not JavaScript or WebAssembly encoder payloads |
-
-Search covered npm's `jpeg-xl`, `jpegxl`, `jxl` and `jixel` results, upstream repositories and web searches for
-JavaScript/WASM encoders. A package not found or not measured is not evidence for a universal record. If a
-smaller usable encoder is published, it belongs in this table and the claim must change.
+| Project | Why not |
+| --- | --- |
+| [jxl-oxide-wasm](https://github.com/tirr-c/jxl-oxide-wasm) 0.12.6 (1,707,757 bytes, 612,548 gzip) | Decoder only |
+| [jxl.js](https://github.com/niutech/jxl.js), jxl-rs-polyfill, TurboJXL, PureJsImage's codec | Decoders |
+| [libjxl](https://github.com/libjxl/libjxl/blob/main/doc/building_wasm.md) WASM build | No published encoder payload; the libjxl-based packages above stand for it |
+| [jixel](https://github.com/awxkee/jixel) `d84b45ff` | No published WASM |
+| [libjxl-tiny](https://github.com/libjxl/libjxl-tiny) `8eae1817` | No published WASM |
+| [Hydrium](https://github.com/Traneptora/hydrium) `45227f35` | Native executables only |
+| [Imazen jxl-encoder](https://github.com/imazen/jxl-encoder) `0d79a23e` | No published WASM |
+| webcvt's jsquash-jxl adapter | The jSquash encoder, already measured |
+| sharp, libvips, the `cjxl` npm wrapper | Native binaries |
+
+Searched: npm's `jpeg-xl`, `jpegxl`, `jxl` and `jixel` results, upstream repositories, the web. A smaller usable
+encoder published later belongs in this table, and the claim changes with it.

package/README.md

@@ -1,69 +1,54 @@
 # Rapier JXL
 
-A JPEG XL encoder in pure JavaScript. No WebAssembly, no build step, no dependency, nothing fetched at run
-time. It is the encoder inside [Rapier](https://rapier.website), the single-file Markdown editor, offered on its
-own so any app can write JPEG XL pictures with the bytes it can afford: one file of 40.3 kB,
-15.9 kB gzipped, MIT. The smallest JavaScript/WebAssembly JPEG XL encoder among the published
-payloads [we measured](ENCODER-COMPARISON.md); the table explains the scope and how to reproduce it.
-
-- **Lossless.** Every pixel comes back as it went in. 8-bit grey, grey with alpha, RGB and RGBA.
-- **Lossy.** Quality 1 to 99, on libjxl's modular path (the Squeeze transform), for drawings, screenshots and
-  pictures of few colours; alpha stays exact. A picture of few colours is answered exact when that is fewer bytes.
-- **Photographs, optionally.** Import `rapier-jxl/photo` for DCT8 photographic compression with exact alpha.
-  This separate module shares the JPEG carrier's VarDCT writer and adds no bytes to the core import.
-- **A JPEG carried as its coefficients.** A JPEG's quantised DCT coefficients, quantisation tables, subsampling
-  and Exif orientation go into a JPEG XL frame the way libjxl transcodes them, so the picture decodes to the
-  JPEG's own pixels at about a fifth fewer bytes, in one call, without decoding. Not carried: the JPEG
-  reconstruction data (the JPEG file cannot be rebuilt from the stream), ICC, Exif beyond the orientation, XMP.
-
-The retained corpus and seeded fuzz cases are decoded through jxl-oxide and native libjxl (below).
+A JPEG XL encoder in pure JavaScript: one file, 19.5 kB, 8.5 kB gzipped, no WebAssembly, no
+dependencies, MIT. The encoder inside [Rapier](https://rapier.website), published on its own. The smallest
+JavaScript or WebAssembly JPEG XL encoder among the payloads [we measured](ENCODER-COMPARISON.md).
+
+- **Lossless.** Every pixel back as it went in: 8-bit grey, grey with alpha, RGB, RGBA.
+- **Lossy**, quality 1 to 99, for flat-colour rasters (screenshots, pixel art, scanned line art). Alpha stays exact.
+  A picture of few colours is written exact when that is smaller.
+- **Smaller exact pictures, slower**: `rapier-jxl/effort`, the same `encode` with `{effort: 2}` or `3`, each never
+  larger than the effort below. Effort 1, its default, is the core's bytes.
+- **Photographs**: `rapier-jxl/photo`, DCT8 compression with exact alpha, a door of its own.
+- **A JPEG carried as its coefficients**: `rapier-jxl/jpeg`, one call, no decode, the way libjxl transcodes. Not
+  carried: the reconstruction data (the JPEG file cannot be rebuilt), the ICC bytes, Exif beyond the orientation, XMP.
+- **sRGB or Display P3.** `{colorSpace: 'display-p3'}` declares a wide-gamut canvas's samples. A JPEG's profile is
+  read by what it does, not what it says: sRGB and Display P3 are carried and declared.
 
 ## Use it
 
 ```js
-import {encode, transcode} from 'rapier-jxl';
+import {encode} from 'rapier-jxl';
+import {transcode} from 'rapier-jxl/jpeg';
+import {encodePhoto} from 'rapier-jxl/photo';
 
-// Pixels from a canvas (straight RGBA, row by row) to a JPEG XL codestream.
 const {data, width, height} = context.getImageData(0, 0, canvas.width, canvas.height);
 const exact = encode(data, width, height);                  // lossless
 const small = encode(data, width, height, {quality: 80});   // lossy
+const photo = encodePhoto(data, width, height);             // quality 90; 100 is exact
 const blob = new Blob([small], {type: 'image/jxl'});
 
-// A JPEG file to JPEG XL, its pixels kept.
-const jpeg = new Uint8Array(await file.arrayBuffer());
-const {bytes, width: w, height: h, orientation} = transcode(jpeg);
+const {bytes, width: w, height: h, orientation} = transcode(new Uint8Array(await file.arrayBuffer()));
 ```
 
-`encode(data, width, height, {quality = 100})` takes a `Uint8Array` or `Uint8ClampedArray` of `width * height * 4`
-bytes and returns a `Uint8Array` holding a bare JPEG XL codestream (the `.jxl` file's bytes). `transcode(jpeg)`
-takes a JPEG's bytes and returns `{bytes, width, height, orientation}`; the width and height are the picture's as
-shown (swapped when the Exif orientation turns it), and the orientation is kept in the JPEG XL header.
+`encode(data, width, height, {quality = 100})` takes straight RGBA bytes, row by row, and returns a `Uint8Array`
+holding a bare JPEG XL codestream; `encodePhoto` takes the same. `transcode(jpeg)` returns
+`{bytes, width, height, orientation}`: the size as shown, the orientation kept in the header.
 
-Four complete ES modules carry their MIT notice inside: `rapier-jxl.min.mjs` (core; `rapier-jxl/min`),
-`lossless.min.mjs` (`encodeLosslessRGBA`, `LIMITS`; `rapier-jxl/lossless`), `jpeg.min.mjs` (`transcode`, `LIMITS`;
-`rapier-jxl/jpeg`), and `photo.min.mjs` (`encodePhotoRGBA`, `LIMITS`; `rapier-jxl/photo`). The readable modules
-are beside them, `index.mjs` the core entry and `photo.mjs` the optional photo entry. Copy a complete bundle
-into an app, or install the package. The checked entries are `encode`, `encodeLosslessRGBA`,
-`encodeLossyRGBA`, `encodePhotoRGBA` and `transcode`; the raw
-`encodeLossless`, `encodeLossy`, `transcodeJPEG`, `parseJPEG` and `inspectPixels` beneath them take input the
-checked entries have already admitted and may throw plain errors on anything else.
-
-```js
-import {encodePhotoRGBA} from 'rapier-jxl/photo';
-const photo = encodePhotoRGBA(data, width, height, {quality: 90});
-```
-
-The photo entry defaults to quality 90; quality 100 is exact lossless. Its 1–99 range controls photographic
-quantisation, while `encode` retains its artwork-oriented modular path. Quality numbers do not promise
-identical PSNR between codecs or images. Neither lossy entry promises fewer bytes than lossless for every input.
+Doors: `rapier-jxl` (the core), `rapier-jxl/effort`, `rapier-jxl/jpeg`, `rapier-jxl/photo`, each readable, so a
+bundler carries their shared modules once; `rapier-jxl/min` is the core as one minified file. `rapier-jxl/writer`
+gives a module's author the layers beneath the doors (readable only; they change only with the major version).
+TypeScript declarations sit beside each door, and a worker and a page are under `public/examples/`. Quality numbers
+are not the same fidelity across encoders or pictures, and lossy is not always smaller than lossless.
 
 ### In a worker
 
-Encoding is synchronous; large pictures can take seconds, so run it off the main thread. A complete worker is this:
+Encoding is synchronous. Run it off the main thread:
 
 ```js
 // jxl-worker.mjs
-import {encode, transcode} from 'rapier-jxl';
+import {encode} from 'rapier-jxl';
+import {transcode} from 'rapier-jxl/jpeg';
 self.onmessage = ({data: {id, op, ...ask}}) => {
   try {
     const out = op === 'transcode' ? transcode(ask.jpeg) : {bytes: encode(ask.data, ask.width, ask.height, {quality: ask.quality})};
@@ -72,67 +57,86 @@ self.onmessage = ({data: {id, op, ...ask}}) => {
 };
 ```
 
-Post `{id, op: 'encode', data, width, height, quality}` or `{id, op: 'transcode', jpeg}`; receive `{id, ok: true,
-bytes, ...}` or `{id, ok: false, code, message}`, the output bytes transferred. To cancel synchronous work,
-terminate that dedicated worker and discard its request ID. A queued abort message cannot interrupt a
-synchronous encode. Keep the input buffer in the caller if retry is needed; posting it without a transfer list
-copies it, while transferring it gives ownership to the worker.
+To cancel, terminate the worker and drop its request id. Keep the input in the caller if you may retry.
+
+Each door has a twin that does the same work in steps: `encodeSteps`, `transcodeSteps`, `encodePhotoSteps` return a
+job, `for (const done of job)` runs one group of one pass per step (`done` is the fraction, the last exactly 1), and
+`job.bytes` is the stream after the loop, the same bytes the door writes. Leaving the loop cancels, so a worker can
+take messages and report progress between steps (`public/examples/worker.mjs`). `job.hurry = true` (the example's
+`deadline` sets it) ends the effort door's search at its next step with the smallest stream written so far, never
+larger than effort 1's.
 
 ### Limits and errors
 
-One picture at a time, at most 16,384 pixels on a side, 24 million pixels, and a 16 MiB stream. The arguments are
-read before any work, and a JPEG's header before a byte of it is allocated. A refusal is an `Error` whose `code`
-is one of `JXL_INPUT` (the arguments), `JXL_DIMENSIONS`, `JXL_SIZE`, `JXL_MEMORY` (the engine ran out of memory)
-or `JXL_JPEG`: a JPEG the carrier does not take (arithmetic coding, 12-bit, lossless, CMYK, a DNL height, a colour
-profile other than sRGB), or a JPEG cut short or out of order, which is refused rather than carried with pixels
-invented; decode such a JPEG and encode its pixels instead. A checked call returns a stream or throws one of these.
+One picture at a time, at most 16,384 pixels a side and a 16 MiB stream. Each door's `LIMITS` sets its pixels by its
+memory, so that none needs more at its limit than the core at its own: 24 million for the core and `effort` (a lossy
+picture holds its planes whole, 15.7 bytes a pixel at its peak besides the input), 40 million for `photo` (6.5), and
+64 million for a JPEG that `jpeg` carries (3.3 at 4:2:0, 6.4 at 4:4:4), so a phone's 24 and 48 megapixel
+photographs are carried. Arguments are checked before any work. A refusal is an `Error` whose `code` is `JXL_INPUT`,
+`JXL_DIMENSIONS`, `JXL_SIZE`, `JXL_MEMORY` or `JXL_JPEG` (arithmetic coding, 12-bit, lossless, CMYK, a DNL height, a
+colour profile other than sRGB or Display P3, or a JPEG cut short: decode it and encode the pixels instead).
+
+### From 1.x
+
+2.0.0 is the package's own version (1.x took Rapier's), and the core is pixels only:
+
+- `transcode` is in `rapier-jxl/jpeg`, and `encodePhotoRGBA` is `encodePhoto` in `rapier-jxl/photo`.
+- `encodeLosslessRGBA(data, width, height)` and `rapier-jxl/lossless` are `encode(data, width, height)`;
+  `encodeLossyRGBA(data, width, height, quality)` is `encode(data, width, height, {quality})`.
+- `encodeLossless`, `encodeLossy`, `inspectPixels`, `parseJPEG` and `transcodeJPEG` are in `rapier-jxl/writer`.
+- A JPEG's colour profile is read by what it does: Display P3 (an iPhone's) is carried and declared, where 1.x
+  refused it; a profile of lookup tables is refused, even one named sRGB.
+- Lossless streams and carried JPEGs are 1.x's bytes. Lossy streams of a picture wider or taller than 256 pixels,
+  or of a colour picture one pixel wide or high, and every photo stream changed where Chrome's decoder (jxl-rs
+  0.7.4) misread a valid stream; each decodes to the same pixels as before through jxl-oxide and libjxl.
+
+New: `rapier-jxl/effort`, each door's twin in steps with `hurry`, `colorSpace: 'display-p3'`, each door's own
+`LIMITS`.
 
 ## Sizes
 
-| file | bytes | gzip | Brotli |
-| --- | ---: | ---: | ---: |
-| `rapier-jxl.min.mjs`, core | 40,286 | 15,904 | 14,096 |
-| `lossless.min.mjs`, `encodeLosslessRGBA` alone | 16,085 | 6,747 | 5,948 |
-| `jpeg.min.mjs`, `transcode` alone | 30,624 | 12,274 | 10,866 |
-| `photo.min.mjs`, photographic pixels | 25,418 | 10,409 | 9,209 |
-| all readable modules, including photo | 103,193 | 31,376 | |
-
-Exact bytes of this release's files, measured by the script that stages this repository; `sizes.json` carries
-their hashes and the tools (terser 5.51.2, Node v22.22.2; gzip at level 9, Brotli at quality 11). A minified
-file keeps every check and every export it names, and is proved at staging to encode what the readable source
-encodes; the readable modules' gzip is of their concatenation.
-
-What it writes, so a decoder's author knows what to expect: bare codestreams (no container box), 8-bit only,
-prefix codes only (never ANS), one frame, no preview, no animation, no ICC profile (sRGB is declared, and a JPEG
-with another profile is refused), no XYB, no chroma-from-luma, no filters. Lossless pictures use modular mode,
-comparing a palette of up to 512 colours with direct encoding by actual stream length, in groups of 256 by 256
-pixels. Measured prediction and colour-transform choices keep smooth artwork and independent channels small.
-Lossy artwork uses the Squeeze transform with exact alpha. Carried JPEGs use VarDCT with the JPEG's quantisation
-tables as raw dequantisation matrices. The photo entry produces DCT8 coefficients from pixels for the same writer.
-
-## Why it exists
-
-Rapier keeps pictures inside Markdown documents, and the standard it publishes says the best way to embed a
-picture in a Markdown document is JPEG XL: exact where it must be exact, small where it may be small, one format
-for photographs, paintings and diagrams alike. An editor that follows the standard needs an encoder it can carry
-offline in a page that must stay small, and none existed at the size, so Rapier wrote one. This repository is
-that encoder, unchanged, republished from Rapier's tree at each of its releases.
-
-If your app embeds pictures in Markdown, the standard is at [rapier.website](https://rapier.website) and the
-encoder is this one: tell your agent to add `rapier-jxl` (see `AGENTS.md`) and it is done.
-
-## How it is checked
-
-Tests and deterministic structure-aware fuzzing live in `public/test/`, with small JPEG seeds and generated pixel
-cases. Install the development dependencies and run `npm test`. The workflow requires both
-[jxl-oxide](https://github.com/tirr-c/jxl-oxide) 0.12.6 and FFmpeg's native libjxl decoder; a missing native oracle
-is explicitly reported locally and is a failure in CI. Cases compare exact pixels and alpha where promised,
-lossy fidelity where relevant, accepted JPEG content, and refusal of malformed inputs. Staging also proves each
-minified entry returns the same bytes as its readable source. The 30 September audit's 131 pixel cases and
-36 JPEG forms remain the acceptance baseline. These checks cover their inputs, not every possible codestream
-or every decoder implementation.
+| file | bytes | gzip | Brotli | added to the core, gzip |
+| --- | ---: | ---: | ---: | ---: |
+| `rapier-jxl.min.mjs`, the core: `encode` | 19,495 | 8,475 | 7,494 | |
+| `effort.min.mjs`: `encode` with effort | 25,229 | 10,606 | 9,351 | 2,131 |
+| `jpeg.min.mjs`: `transcode` | 29,592 | 12,533 | 11,072 | 7,673 |
+| `photo.min.mjs`: `encodePhoto` | 25,646 | 10,804 | 9,537 | 4,242 |
+| every door in one bundle | 47,499 | 19,228 | 16,977 | |
+| all readable modules | 136,580 | 42,707 | | |
+
+Exact bytes of release 2.0.0's files, measured by the script that stages this repository; `sizes.json`
+carries their hashes and tools (terser 5.51.2, Node v22.22.2; gzip 9, Brotli 11). Each minified file stands alone
+and is proved at staging to write the same bytes as its readable source; the last column is what a door adds to a
+bundle that already holds the core. `effort`'s `encode` is the core's at effort 1, so it takes the core's place, in
+that column and in the bundle of every door.
+
+What it writes: bare codestreams, 8-bit, prefix codes (never ANS), one frame, no preview, animation, ICC (sRGB or
+Display P3 is declared), XYB, chroma-from-luma or filters. Lossless in modular mode, a palette of up to 2,048
+colours weighed against direct coding by actual length, groups of 256, reversible YCoCg, a predictor chosen per
+channel; at effort 2 and 3 also the weighted predictor, its contexts split by its own error. Lossy through Squeeze
+with exact alpha. Carried JPEGs in VarDCT with the JPEG's own tables. The photo door
+writes DCT8 coefficients for the same writer.
+
+## Checked
+
+Tests and seeded structure-aware fuzzing in `public/test/`: `npm test`, decoded through
+[jxl-oxide](https://github.com/tirr-c/jxl-oxide) 0.12.6 and FFmpeg's native libjxl (a missing native decoder is
+reported, and fails in CI). Exact pixels and alpha where promised, fidelity where relevant, the accepted JPEG
+forms, refusal of malformed input. The same input writes the same bytes in every JavaScript engine: nothing that
+decides a byte uses a function engines round differently, and `public/test/bytes.test.mjs` holds the streams' hashes
+under Node and Bun. The 30 September run put 2,000,000 JPEG mutations and 32,768 pixel cases
+through both decoders. The two decoders differ by one RGB unit on some JPEG and photo streams (floating-point
+reconstruction), kept in `public/test/seeds/`; alpha and modular output are exact. With a C compiler and libjxl
+headers, `npm run fuzz:scale -- --out fuzz-run --workers 4` repeats the fixed budget.
+
+## Why
+
+Rapier keeps pictures inside Markdown, and its standard says a raster picture in Markdown is JPEG XL: exact where
+it must be, small where it may be. Drawings stay SVG. An editor carrying an encoder offline in a small page needed
+one this size, and none existed. The standard is at [rapier.website](https://rapier.website); for an agent, see
+`AGENTS.md`.
 
 ## Licence
 
-MIT, copyright rapier.website. The design follows the JPEG XL specification (ISO/IEC 18181) and libjxl's
-encoders, whose sources were read; none of their code is here.
+MIT, copyright rapier.website. The design follows ISO/IEC 18181 and libjxl's encoders, whose sources were read;
+none of their code is here.