rapier-jxl 1.1.21 → 2.1.0

package/AGENTS.md

@@ -1,19 +1,27 @@
 # For an agent adding Rapier JXL to an app
 
 1. `npm install rapier-jxl`, or copy one file from this repository's root: `rapier-jxl.min.mjs` (the core),
-   `lossless.min.mjs`, `jpeg.min.mjs` or `photo.min.mjs`. No build.
-2. `import {encode, transcode} from 'rapier-jxl'` (or `rapier-jxl/min`); `encodeLosslessRGBA` from
-   `rapier-jxl/lossless`, `transcode` from `rapier-jxl/jpeg`, `encodePhotoRGBA` from `rapier-jxl/photo`.
-3. Pixels: `encode(rgba, width, height, {quality})`, straight RGBA row by row as `getImageData` gives it. Quality 100
-   (the default) is lossless, 1 to 99 lossy, alpha exact at every quality. Photographs:
-   `encodePhotoRGBA(rgba, width, height, {quality: 90})`. The answer is a `Uint8Array` of codestream bytes: save it
+   `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 `encode` on the pixels.
-5. Anything larger than an icon runs in a worker. Calls are synchronous, so cancel by terminating the worker. A
+   decode it and call `encodePhoto` on the pixels. Both doors accept `{effort: 4}` to try a smaller entropy
+   representation with identical reconstructed pixels; the default is 1.
+   For an additional ANS candidate, use the same API from `rapier-jxl/jpeg-ans` or `rapier-jxl/photo-ans` with
+   `{effort: 2}`. These optional imports cost about 1.1 kB gzip more than their ordinary door and keep the smaller
+   complete stream; benchmark the extra encode work for your use. Default effort 1 stays prefix-coded.
+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. Keep the
-   original pixels until the encode and its storage succeed.
+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: it runs in a worker, Node or Deno alike. Publish the version

package/ENCODER-COMPARISON.md

@@ -5,10 +5,10 @@ A bounded survey, not proof of a global minimum; the encoders differ in what the
 
 | Encoder / entry | Version | Minified JS + WASM bytes | gzip bytes | Included capability |
 | --- | --- | ---: | ---: | --- |
-| Rapier JXL core | this release | 36,284 | 14,987 | 8-bit lossless RGBA, lossy modular with exact alpha, JPEG coefficients |
-| Rapier JXL lossless | this release | 13,754 | 6,131 | 8-bit exact RGBA |
-| Rapier JXL JPEG | this release | 27,750 | 11,590 | JPEG coefficients, orientation; no JPEG reconstruction |
-| Rapier JXL photo | this release | 22,563 | 9,768 | 8-bit photographic VarDCT, exact alpha; q100 lossless |
+| Rapier JXL core | 2.1.0 | 19,539 | 8,511 | 8-bit lossless RGBA, lossy modular with exact alpha |
+| Rapier JXL effort door | 2.1.0 | 30,008 | 12,320 | The core, and the weighted predictor searched for lossless |
+| Rapier JXL JPEG door | 2.1.0 | 32,218 | 13,439 | JPEG coefficients, orientation; no JPEG reconstruction |
+| Rapier JXL photo door | 2.1.0 | 31,288 | 12,872 | 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 | 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 |
@@ -51,7 +51,7 @@ Gaussian, no downsampling); alpha-bearing inputs are matted on white for the tab
 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.
 
-### Photo entry
+### 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
@@ -80,7 +80,7 @@ Butteraugli).
 | 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 |
 
-### Lossy modular entry on drawings and paintings
+### 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

package/README.md

@@ -1,42 +1,56 @@
 # Rapier JXL
 
-A JPEG XL encoder in pure JavaScript: one file, 36.3 kB, 15.0 kB gzipped, no WebAssembly, no
+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.
-- **Photographs**, optionally: `rapier-jxl/photo`, DCT8 compression with exact alpha, adding nothing to the core.
-- **A JPEG carried as its coefficients**: one call, no decode, the way libjxl transcodes. Not carried: the
-  reconstruction data (the JPEG file cannot be rebuilt), ICC, Exif beyond the orientation, XMP.
+- **Smaller exact pictures, slower**: `rapier-jxl/effort`, the same `encode` with `{effort: 2}`, `3`, `4` or `6`, 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. Effort 5 searches
+  quantisation per block and keeps a candidate only when its complete stream is smaller.
+- **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.
+- **Optional ANS entropy coding**: import `transcode` from `rapier-jxl/jpeg-ans` or `encodePhoto` from
+  `rapier-jxl/photo-ans` and pass `{effort: 2}`. Each tries ANS after writing the prefix-coded floor and keeps
+  the smaller complete stream, with identical reconstructed pixels. These imports leave the core unchanged.
+- **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';
 
 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'});
 
 const {bytes, width: w, height: h, orientation} = transcode(new Uint8Array(await file.arrayBuffer()));
 ```
 
 `encode(data, width, height, {quality = 100})` takes straight RGBA bytes, row by row, and returns a `Uint8Array`
-holding a bare JPEG XL codestream. `transcode(jpeg)` returns `{bytes, width, height, orientation}`: the size as
-shown, the orientation kept in the header.
-
-```js
-import {encodePhotoRGBA} from 'rapier-jxl/photo';
-const photo = encodePhotoRGBA(data, width, height, {quality: 90});   // 100 is exact
-```
-
-Entries: `rapier-jxl` (the readable modules), `rapier-jxl/min` (one minified file), `rapier-jxl/lossless`,
-`rapier-jxl/jpeg`, `rapier-jxl/photo`. Each minified file carries its MIT notice, TypeScript declarations sit
-beside each entry, 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.
+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.
+
+Doors: `rapier-jxl` (the core), `rapier-jxl/effort`, `rapier-jxl/jpeg`, `rapier-jxl/photo`, and the two optional
+ANS doors above, 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.
+
+The photo door defaults to effort 1. Its higher efforts keep the preceding stream as a candidate; effort 5 also
+bounds effort 1's unclipped RGB sample reconstruction error on edge-extended DCT blocks, before clipping and integer output.
+Decoded integer RGB error can differ from that model. Quality 100 remains exact at every effort.
+The quantisation search keeps the preceding stream when its estimated memory would exceed the photo door's
+working budget; the door's 40-million-pixel admission stays the same.
 
 ### In a worker
 
@@ -44,7 +58,8 @@ 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})};
@@ -55,39 +70,92 @@ self.onmessage = ({data: {id, op, ...ask}}) => {
 
 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 a door's search at its next step with the smallest stream written so far, never
+larger than effort 1's.
+
+The JPEG and photograph doors also read effort: 3 tries a 32-cluster budget, and 4 also tries an order learned
+from coefficient counts. These entropy rungs keep the smaller complete stream and preserve every reconstructed pixel. Their
+default remains 1; effort 2 keeps the default plan. A hurried JPEG job finishes its effort-1 floor in its first
+half; through effort 4 the photo job first makes coefficients, then writes that floor, and searches in its final
+quarter. At effort 5, its first half finishes the preceding stream and its second half searches quantisation,
+keeping the completed floor on a hurry.
+
+The optional ANS doors keep default effort 1's prefix bytes. Effort 2 adds one ANS candidate; efforts 3 and 4
+also retain the ordinary prefix searches, and photo effort 5 retains its quantisation search. ANS uses a bounded
+group buffer of 1,376,256 bytes plus histogram tables; encoding both candidates costs more CPU and may raise peak
+RSS. Hurry keeps a completed candidate even when it arrives at the final group's yield.
+
+Version 2.1.0 fits the photo door's existing quantisation constants across thumbnail and source-sized photos.
+Lossy photo bytes change deliberately; lossless and ordinary JPEG streams retain their hashes. Pin a package
+version when exact lossy output bytes matter. Quality numbers remain a setting, not a guarantee of equal
+perceptual quality on every image.
+
 ### Limits and errors
 
-One picture at a time, at most 16,384 pixels a side, 24 million pixels and a 16 MiB stream. 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 a JPEG
-cut short: decode it and encode the pixels instead).
+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).
 
-## Sizes
+### From 1.x
+
+2.0.0 is the package's own version (1.x took Rapier's), and the core is pixels only:
 
-| file | bytes | gzip | Brotli |
-| --- | ---: | ---: | ---: |
-| `rapier-jxl.min.mjs`, core | 36,284 | 14,987 | 13,315 |
-| `lossless.min.mjs`, `encodeLosslessRGBA` alone | 13,754 | 6,131 | 5,401 |
-| `jpeg.min.mjs`, `transcode` alone | 27,750 | 11,590 | 10,217 |
-| `photo.min.mjs`, photographic pixels | 22,563 | 9,768 | 8,635 |
-| all readable modules, including photo | 102,565 | 31,745 | |
+- `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.
 
-Exact bytes of this release'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 is proved at
-staging to write the same bytes as its readable source.
+New: `rapier-jxl/effort`, each door's twin in steps with `hurry`, `colorSpace: 'display-p3'`, each door's own
+`LIMITS`.
+
+## Sizes
 
-What it writes: bare codestreams, 8-bit, prefix codes (never ANS), one frame, no preview, animation, ICC (sRGB 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. Lossy
-through Squeeze with exact alpha. Carried JPEGs in VarDCT with the JPEG's own tables. The photo entry writes DCT8
-coefficients for the same writer.
+| file | bytes | gzip | Brotli | added to the core, gzip |
+| --- | ---: | ---: | ---: | ---: |
+| `rapier-jxl.min.mjs`, the core: `encode` | 19,539 | 8,511 | 7,515 | |
+| `effort.min.mjs`: `encode` with effort | 30,008 | 12,320 | 10,860 | 3,809 |
+| `jpeg.min.mjs`: `transcode` | 32,218 | 13,439 | 11,874 | 8,497 |
+| `photo.min.mjs`: `encodePhoto` | 31,288 | 12,872 | 11,370 | 6,257 |
+| `jpeg-ans.min.mjs`: optional ANS carrier | 35,281 | 14,506 | 12,804 | 9,564 |
+| `photo-ans.min.mjs`: optional ANS photo | 34,293 | 13,899 | 12,295 | 7,298 |
+| every door in one bundle | 61,101 | 24,091 | 21,147 | |
+| all readable modules | 174,894 | 53,445 | | |
+
+Exact bytes of release 2.1.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 (or ANS in the optional doors), 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; at 4 local modelling of
+palette indices; at 6 local gradient-property splits. Effort 5 uses rung 4. 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 30 September run put 2,000,000 JPEG mutations and 32,768 pixel cases
+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.

package/admit.mjs

@@ -0,0 +1,60 @@
+// Rapier's JPEG XL encoder: what every door admits, and how each refuses. MIT (LICENSE).
+// One owner for the checked doors: the options read before any work, the limits, the five codes, and the size and
+// memory refusals after it. A module's door refuses the same way (writer.mjs).
+import {LIMITS} from './bits.mjs';
+
+export const fault = (code, message) => Object.assign(new Error(message), {code});
+
+// The options every door reads, before any work: an object, or nothing; quality a number from 1 to 100, the door's
+// own default when absent; the samples' colour space, the web platform's name for it, sRGB when absent.
+export function admitOptions(options = {}, quality = 100) {
+  if (options === null || typeof options !== 'object') throw fault('JXL_INPUT', 'Options are an object: {quality, colorSpace}.');
+  if (options.quality !== undefined) quality = options.quality;
+  if (typeof quality !== 'number' || !Number.isFinite(quality) || quality < 1 || quality > 100) throw fault('JXL_INPUT', 'Quality is a number from 1 to 100.');
+  const colorSpace = options.colorSpace === undefined ? 'srgb' : options.colorSpace;
+  if (colorSpace !== 'srgb' && colorSpace !== 'display-p3') throw fault('JXL_INPUT', 'The colour space is srgb or display-p3.');
+  return {quality, colorSpace};
+}
+
+// A door's size, against the door's own limits (the core's when none are named).
+export function admitSize(width, height, limits = LIMITS) {
+  if (!Number.isInteger(width) || !Number.isInteger(height) || width < 1 || height < 1) throw fault('JXL_INPUT', 'A picture is at least one pixel wide and high, in whole pixels.');
+  if (width > limits.edge || height > limits.edge) throw fault('JXL_DIMENSIONS', 'A picture is at most ' + limits.edge + ' pixels on a side.');
+  if (width * height > limits.pixels) throw fault('JXL_DIMENSIONS', 'A picture is at most ' + limits.pixels.toLocaleString('en-US') + ' pixels.');
+}
+
+export function admitPixels(data, width, height, limits) {
+  admitSize(width, height, limits);
+  if (!(data instanceof Uint8Array) && !(data instanceof Uint8ClampedArray)) throw fault('JXL_INPUT', 'Pixels are a Uint8Array or Uint8ClampedArray of RGBA bytes.');
+  if (data.length !== width * height * 4) throw fault('JXL_INPUT', 'Pixels are width * height * 4 bytes: straight (not premultiplied) RGBA, row by row.');
+}
+
+export function admitOutputSize(length) {
+  if (length > LIMITS.bytes) throw fault('JXL_SIZE', 'The encoded picture exceeds 16 MiB.');
+}
+
+export function answer(bytes) {
+  admitOutputSize(bytes.length);
+  return bytes;
+}
+
+// A plain RangeError from inside the work is the engine out of memory; a coded error passes through as it is.
+export function guard(work) {
+  try { return work(); }
+  catch (error) { if (error instanceof RangeError && !error.code) throw fault('JXL_MEMORY', 'Not enough memory for this picture.'); throw error; }
+}
+
+// A door's work as a job: iterate it for the fraction done, in (0, 1], the last exactly 1, and read `bytes` after the
+// last step (the job also returns them). Leaving the loop is a cancel with nothing to release. `hurry` asks a search to
+// finish with the best candidate it has priced; effort 1 searches nothing, so its bytes are the same either way.
+export function job(steps) {
+  const it = (function* () {
+    let step, last;
+    while (!(step = guard(() => steps.next(it.hurry))).done) yield last = step.value;
+    // A candidate given up (the stream limit, or memory for the lossy attempt beside an exact stream) ends early.
+    if (last < 1) yield 1;
+    return it.bytes = answer(step.value);
+  })();
+  it.bytes = null; it.hurry = false;
+  return it;
+}

package/ans.mjs

@@ -0,0 +1,157 @@
+// SPDX-License-Identifier: MIT
+// Optional JPEG XL ANS coding. The core imports none of this module.
+// The normative alias construction follows ISO/IEC 18181-1; libjxl 0.11.2's
+// ans_common.cc and enc_ans.cc were consulted for the wire layout.
+import {BitWriter, ceilLog2, floorLog2} from './bits.mjs';
+import {hybridToken, writeContextMap, writeUintConfig} from './prefix.mjs';
+import {buildTokenCoding} from './entropy.mjs';
+
+const LOG_LENGTHS = [5, 4, 4, 4, 4, 4, 3, 3, 3, 3, 3, 6, 7];
+const LOG_CODES = [17, 11, 15, 3, 9, 7, 4, 2, 5, 6, 0, 33, 1];
+// A VarDCT group has at most three 32x32-block planes. Each block emits one
+// nonzero-count token and at most 63 AC tokens; alpha uses its separate modular stream.
+const GROUP_TOKENS = 3 * 32 * 32 * 64;
+
+function varUint8(w, value) {
+  if (!value) { w.write(1, 0); return; }
+  const n = floorLog2(value);
+  w.write(1, 1); w.write(3, n); w.write(n, value - (1 << n));
+}
+
+// Correct the largest rounding error until the table totals exactly 4096.
+// Every represented symbol keeps a positive count, including rare symbols.
+function normalise(freqs) {
+  let total = 0, last = 0;
+  for (let i = 0; i < freqs.length; i++) {
+    total += freqs[i];
+    if (freqs[i]) last = i + 1;
+  }
+  const counts = new Uint16Array(last || 1);
+  if (!total) { counts[0] = 4096; return counts; }
+  let sum = 0;
+  for (let i = 0; i < last; i++) if (freqs[i]) sum += counts[i] = Math.max(1, Math.round(freqs[i] * 4096 / total));
+  while (sum !== 4096) {
+    const direction = sum < 4096 ? 1 : -1;
+    let chosen = -1, error = -Infinity;
+    for (let i = 0; i < last; i++) if (freqs[i] && (direction > 0 || counts[i] > 1)) {
+      const candidate = direction * (freqs[i] * 4096 - counts[i] * total);
+      if (candidate > error) { chosen = i; error = candidate; }
+    }
+    counts[chosen] += direction; sum += direction;
+  }
+  return counts;
+}
+
+function writeDistribution(w, counts) {
+  const used = [];
+  let omit = 0;
+  for (let i = 0; i < counts.length; i++) {
+    if (counts[i]) used.push(i);
+    if (counts[i] > counts[omit]) omit = i;
+  }
+  if (used.length <= 2) {
+    w.write(1, 1); w.write(1, used.length - 1);
+    for (const symbol of used) varUint8(w, symbol);
+    if (used.length === 2) w.write(12, counts[used[0]]);
+    return;
+  }
+  w.write(1, 0); w.write(1, 0);
+  // Full count precision: shift 12, encoded by the bounded gamma form.
+  w.write(3, 7); w.write(3, 5);
+  varUint8(w, counts.length - 3);
+  const logs = new Uint8Array(counts.length);
+  let omitLog = 0;
+  for (let i = 0; i < counts.length; i++) if (i !== omit && counts[i]) {
+    logs[i] = floorLog2(counts[i]) + 1;
+    omitLog = Math.max(omitLog, logs[i] + (i < omit ? 1 : 0));
+  }
+  logs[omit] = omitLog;
+  for (const log of logs) w.write(LOG_LENGTHS[log], LOG_CODES[log]);
+  for (let i = 0; i < counts.length; i++) if (i !== omit && logs[i] > 1) {
+    const bits = logs[i] - 1;
+    w.write(bits, counts[i] - (1 << bits));
+  }
+}
+
+// Invert the decoder's alias table once per histogram. State remainders then
+// use one indexed load, with no search or approximation in the symbol loop.
+function reverseAlias(counts, logAlphabet) {
+  const size = 1 << logAlphabet, entry = 4096 >> logAlphabet;
+  const starts = new Uint16Array(counts.length + 1), reverse = new Uint16Array(4096);
+  let single = -1;
+  for (let i = 0; i < counts.length; i++) {
+    starts[i + 1] = starts[i] + counts[i];
+    if (counts[i] === 4096) single = i;
+  }
+  if (single >= 0) {
+    for (let i = 0; i < 4096; i++) reverse[i] = i;
+    return {starts, reverse};
+  }
+  const cutoffs = new Int32Array(size), aliases = new Uint16Array(size), offsets = new Int32Array(size);
+  const under = [], over = [];
+  cutoffs.set(counts);
+  for (let i = 0; i < size; i++) {
+    if (cutoffs[i] < entry) under.push(i);
+    else if (cutoffs[i] > entry) over.push(i);
+  }
+  while (over.length) {
+    const from = over.pop(), to = under.pop(), taken = entry - cutoffs[to];
+    cutoffs[from] -= taken;
+    aliases[to] = from; offsets[to] = cutoffs[from] - cutoffs[to];
+    if (cutoffs[from] < entry) under.push(from);
+    else if (cutoffs[from] > entry) over.push(from);
+  }
+  for (let i = 0; i < size; i++) for (let j = 0; j < entry; j++) {
+    const own = j < cutoffs[i], symbol = own ? i : aliases[i], offset = own ? j : j + offsets[i];
+    reverse[starts[symbol] + offset] = i * entry + j;
+  }
+  return {starts, reverse};
+}
+
+export function buildAnsCoding(counts, options) {
+  const prefix = buildTokenCoding(counts, options);
+  const contexts = prefix.histograms.map(() => []);
+  for (let ctx = 0; ctx < counts.contexts; ctx++) if (counts.totals[ctx]) contexts[prefix.contextMap[ctx]].push(ctx);
+  const histograms = prefix.histograms.map(({config}, i) => ({config, counts: normalise(counts.tokens(contexts[i], config, 256))}));
+  const logAlphabet = Math.max(5, ceilLog2(Math.max(...histograms.map(h => h.counts.length))));
+  for (const histogram of histograms) Object.assign(histogram, reverseAlias(histogram.counts, logAlphabet));
+  const header = new BitWriter();
+  header.write(1, 0);
+  if (prefix.contextMap.length > 1) writeContextMap(header, prefix.contextMap);
+  header.write(1, 0); header.write(2, logAlphabet - 5);
+  for (const histogram of histograms) writeUintConfig(header, histogram.config, logAlphabet);
+  for (const histogram of histograms) writeDistribution(header, histogram.counts);
+
+  // One group's storage is reused for every group; image dimensions never
+  // multiply this reverse-order workspace. No input or coefficient is mutated.
+  // The shared cluster builder caps histogram IDs at 48, so metadata fits one byte.
+  const values = new Uint32Array(GROUP_TOKENS), metadata = new Uint8Array(GROUP_TOKENS), emitted = new Uint16Array(GROUP_TOKENS);
+  const slots = [0, 0, 0];
+  let length = 0;
+  const write = (_w, ctx, value) => {
+    values[length] = value; metadata[length++] = prefix.contextMap[ctx];
+  };
+  const flush = w => {
+    let state = 0x13 * 65536;
+    for (let i = length - 1; i >= 0; i--) {
+      const h = histograms[metadata[i]];
+      hybridToken(h.config, values[i], slots);
+      const symbol = slots[0], freq = h.counts[symbol];
+      values[i] = slots[2]; metadata[i] = slots[1];
+      if ((state >>> 20) >= freq) {
+        emitted[i] = state & 65535; metadata[i] |= 64; state >>>= 16;
+      }
+      const q = Math.floor(state / freq);
+      state = q * 4096 + h.reverse[h.starts[symbol] + state - q * freq];
+    }
+    w.write(32, state);
+    for (let i = 0; i < length; i++) {
+      if (metadata[i] & 64) w.write(16, emitted[i]);
+      const bits = metadata[i] & 63;
+      if (bits) w.write(bits, values[i]);
+    }
+    length = 0;
+  };
+  // Preserve the original bucket/context choice to isolate prefix versus ANS.
+  return {bits: prefix.bits, write, flush, writeHistograms: w => w.append(header)};
+}

package/bits.mjs

@@ -1,13 +1,20 @@
 // Rapier's JPEG XL encoder: the bit writer, and the limits every part keeps. MIT (LICENSE).
 // JPEG XL packs bits least-significant first; `write` takes up to 32 bits at a time.
 
-// What one call takes at most: the 16 MiB codestream, 24 million pixels, 16,384 on a side. The checked API refuses a
-// larger ask before any work, the JPEG reader before it allocates a plane, and a writer that would grow past the
-// stream's bound stops there instead of filling memory first.
+// What one call takes at most, door by door: the 16 MiB codestream, 16,384 pixels on a side, and as many pixels as the
+// door's memory allows within what the core's lossy path needs at its 24 million (a measured peak of 15.7 bytes a
+// pixel besides the input). The core and the effort door take 24 million; the photo door, 6.5 bytes a pixel at its
+// limit, 40 million; the JPEG carrier, 6.4 bytes a pixel at 4:4:4 and 3.3 at 4:2:0, 64 million. The checked API
+// refuses a larger ask before any work, the JPEG reader before it allocates a plane, and a writer that would grow past
+// the stream's bound stops there instead of filling memory first.
 export const LIMITS = Object.freeze({bytes: 16 * 1024 * 1024, pixels: 24_000_000, edge: 16384});
+export const PHOTO_LIMITS = /*#__PURE__*/ Object.freeze({bytes: 16 * 1024 * 1024, pixels: 40_000_000, edge: 16384});
+export const JPEG_LIMITS = /*#__PURE__*/ Object.freeze({bytes: 16 * 1024 * 1024, pixels: 64_000_000, edge: 16384});
 
-// The hot writer reuses exact powers; unusual counts retain the range check's arithmetic.
-const POWERS = Array.from({length: 33}, (_, count) => 2 ** count);
+// The hot writer's powers of two, made by doubling (`**` is not exact in every engine); a count outside 0 to 32 finds
+// none, so its value is out of range.
+const POWERS = [1];
+for (let count = 1; count <= 32; count++) POWERS.push(POWERS[count - 1] * 2);
 
 export class BitWriter {
   constructor(capacity = 4096) {
@@ -17,7 +24,7 @@ export class BitWriter {
     this.pending = 0;  // how many bits `acc` holds, always below 8 between calls
   }
   write(count, value) {
-    if (count > 32 || value < 0 || value >= (POWERS[count] ?? 2 ** count)) throw new Error('bit write out of range: ' + count + ' bits, ' + value);
+    if (!(value >= 0 && value < POWERS[count])) throw new Error('bit write out of range: ' + count + ' bits, ' + value);
     let acc = this.acc + value * (1 << this.pending), pending = this.pending + count;
     if (this.at + 5 >= this.bytes.length) this.grow();
     const bytes = this.bytes;
@@ -28,7 +35,7 @@ export class BitWriter {
   writeU32(choices, value) {
     for (let selector = 0; selector < 4; selector++) {
       const [bits, offset] = choices[selector];
-      if (value >= offset && value - offset < 2 ** bits) { this.write(2, selector); if (bits) this.write(bits, value - offset); return; }
+      if (value >= offset && value - offset < POWERS[bits]) { this.write(2, selector); if (bits) this.write(bits, value - offset); return; }
     }
     throw new Error('U32 value out of range: ' + value);
   }
@@ -59,6 +66,16 @@ export class BitWriter {
   }
 }
 
+// The work as steps: a stepped writer yields the fraction of its work done, counted in whole steps so the last is
+// exactly 1, receives whether its caller is in a hurry, and returns its bytes. `complete` runs one to the end; `part`
+// makes a nested one's fractions the index-th of `count` equal shares of its caller's.
+export function complete(steps) { let step; while (!(step = steps.next()).done); return step.value; }
+export function* part(steps, index, count) {
+  let step, hurry;
+  while (!(step = steps.next(hurry)).done) hurry = yield (index + step.value) / count;
+  return step.value;
+}
+
 // Residuals travel unsigned: 0, -1, 1, -2, 2 ... become 0, 1, 2, 3, 4 ...
 export function packSigned(value) { return value >= 0 ? value * 2 : -value * 2 - 1; }
 
@@ -71,9 +88,12 @@ export function float16Bits(value) {
   const sign = value < 0 ? 0x8000 : 0;
   value = Math.abs(value);
   if (!(value < 65520)) throw new Error('half float out of range: ' + value);
-  let exponent = Math.floor(Math.log2(value));
-  let mantissa = value / 2 ** exponent - 1;
-  if (exponent < -14) { mantissa = value / 2 ** -14; exponent = -15; }
+  // The exponent by halving and doubling, both exact (Math.log2 rounds differently in each engine).
+  let exponent = 0, mantissa = value;
+  while (mantissa >= 2) { mantissa /= 2; exponent++; }
+  while (mantissa < 1) { mantissa *= 2; exponent--; }
+  if (exponent < -14) { mantissa = value * 16384; exponent = -15; }
+  else mantissa -= 1;
   let m = Math.round(mantissa * 1024);
   if (m === 1024) { m = 0; exponent++; }
   return sign | ((exponent + 15) << 10) | m;

package/coefficient-ans.mjs

@@ -0,0 +1,26 @@
+// SPDX-License-Identifier: MIT
+// The optional doors add ANS at effort 2; earlier completed streams remain the
+// answer on a tie, hurry, allocation failure or candidate above the size limit.
+import {coefficientEffortSteps} from './coefficient-effort.mjs';
+import {varDCTSteps} from './vardct.mjs';
+import {part} from './bits.mjs';
+import {buildAnsCoding} from './ans.mjs';
+
+export function* coefficientAnsSteps(jpeg, effort, fallback) {
+  if (effort < 2) return yield* coefficientEffortSteps(jpeg, effort, fallback);
+  let best = yield* part(coefficientEffortSteps(jpeg, effort, fallback), 0, 2);
+  if (yield 0.5) return best;
+  try {
+    const candidate = varDCTSteps(jpeg, {coding: buildAnsCoding});
+    let step;
+    while (!(step = candidate.next()).done) {
+      // The final group has already been written at fraction 1. Let its bounded
+      // assembly finish before comparing; a hurry must not discard that work.
+      if ((yield 0.5 + step.value / 2) && step.value < 1) { candidate.return(); return best; }
+    }
+    if (step.value.length < best.length) best = step.value;
+  } catch (error) {
+    if (!(error instanceof RangeError && !error.code) && error.code !== 'JXL_SIZE') throw error;
+  }
+  return best;
+}