rapier-jxl 2.0.0 → 2.2.0

package/AGENTS.md

@@ -11,7 +11,11 @@
    `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.
+   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.
@@ -22,3 +26,8 @@
 
 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.
+
+For lossless acceleration with unchanged bytes, use `rapier-jxl/wasm` (or its single-file `wasm.min.mjs`)
+in place of the effort door. It falls back to JavaScript when SIMD is missing or blocked. `KERNELS.md`
+describes the 3 MiB private arena, controls and source build. Do not combine separate minified bundles
+to share kernel controls: use the one-file accelerated door.

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 | 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 |
+| Rapier JXL core | 2.2.0 | 21,326 | 9,271 | 8-bit lossless RGBA, lossy modular with exact alpha |
+| Rapier JXL effort door | 2.2.0 | 33,584 | 13,793 | The core, and the weighted predictor searched for lossless |
+| Rapier JXL JPEG door | 2.2.0 | 32,354 | 13,505 | JPEG coefficients, orientation; no JPEG reconstruction |
+| Rapier JXL photo door | 2.2.0 | 33,011 | 13,616 | 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 |
@@ -117,7 +117,7 @@ and paint-0002 at q80 and q90.
 
 `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;
+accepted original exactly. So a smaller Rapier row is not a like-for-like win. Seven inputs are tiny conformance fixtures;
 Grace is the one photograph.
 
 | JPEG input | Original bytes | Rapier carrier | Native reversible | JPEG rebuilt by native |
@@ -154,7 +154,7 @@ bundled Geist fonts and pinned `@napi-rs/canvas` 0.1.100. Grace is the public-do
 
 ```sh
 cjxl INPUT.pam OUTPUT.jxl --distance=D --effort=7 --num_threads=0 \
-  --alpha_distance=0 --keep_invisible=1 --premultiply=0 --container=0 \
+  --alpha_distance=0 --resampling=1 --ec_resampling=1 --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

package/KERNELS.md

@@ -0,0 +1,58 @@
+# Optional integer kernels
+
+The small `index.mjs` and `effort.mjs` doors remain JavaScript. To opt in, import
+`encode` / `encodeSteps` from `rapier-jxl/wasm` instead of `rapier-jxl/effort`.
+This door keeps the effort API, automatically tries SIMD, and falls back to the
+reference JavaScript if WebAssembly or SIMD is absent or blocked by policy.
+It changes neither lossless bytes nor the hurry rule. Rapier's full image worker
+opts in automatically; the document-only worker still ships no encoder.
+
+The public repository also builds **`wasm.min.mjs`**, one self-contained module.
+The package marks these two entry modules as side-effectful so bundlers retain
+their automatic backend configuration.
+Do not combine `kernels.min.mjs` with a separately bundled core: each bundle would
+own different hooks. There is deliberately no separate minified control door.
+Readable modules can share controls through `rapier-jxl/kernels`:
+
+```js
+import {encode, configureKernels, kernelMode} from 'rapier-jxl/wasm';
+configureKernels('auto'); // 'off', 'scalar', or 'simd' are explicit alternatives
+const bytes = encode(rgba, width, height, {effort: 3, quality: 100});
+console.log(kernelMode()); // the actual backend, not merely the requested one
+```
+
+Configure once before an encode, not inside its progress callback. Controls are
+per JavaScript realm; workers have independent arenas. A second argument selects
+kernels for deterministic benchmarks, for example `{channel: true, weighted:
+false, fill: false}`. This only changes where arithmetic runs, never its result.
+
+## What ships
+
+`kernels-scalar.wat` implements prediction, weighted prediction and property
+extraction, token histograms and a bulk bit writer. `kernels-simd.wat` implements
+four-pixel average/gradient prediction and RGBA-to-planar conversion; rows and
+odd tails take an explicit scalar path. Weighted prediction stays scalar: its
+west-error state is sequential. Both modules use bounded integer arithmetic,
+including signed i64 floor division for the weighted average. No relaxed SIMD,
+floating-point WASM, imports other than private memory, network access, shared
+memory, threads, or runtime dependencies are used.
+
+The private arena is 3 MiB per enabled realm, reused synchronously. No views escape.
+Groups are at most 65,536 samples; Int16 planes, unit multipliers and bounded
+offsets are admitted. Other planes and custom writers keep the JavaScript path.
+Non-little-endian hosts keep JavaScript as well. The existing input and output
+limits remain in force. SIMD detection calls `WebAssembly.validate` on the tiny
+`kernels-probe.wat` module; failure does not disable the encoder.
+
+## Rebuild
+
+The checked-in `kernels-bytes.mjs` contains generated base64 bytes, not source to
+edit. In the Rapier tree run `node repo/images/build-jxl-kernels.mjs`; in a staged
+public repository run `node build-jxl-kernels.mjs`. Install **wabt 1.0.37** only as
+a build tool. `WABT_MODULE` may point to its `index.js` outside the source tree.
+Add `--check` to reject a generated file that differs. No compiler ships in the
+inline encoder. Source and build script are retained in the public package.
+
+The JX/3 handoff records the bootstrap compiler used in its network-restricted
+sandbox and the outstanding independent wabt rebuild. Do not describe that
+handoff as a wabt-certified build until `--check` has been run with wabt.

package/README.md

@@ -1,20 +1,43 @@
 # Rapier JXL
 
-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).
+A JPEG XL encoder in pure JavaScript, for writing `.jxl` from canvas pixels or a JPEG in a browser, a worker, Node
+or Deno. The core needs no WebAssembly; an optional SIMD door accelerates the same arithmetic. No server.
+
+- The core is one file of 21.3 kB, 9.3 kB gzipped: the smallest JavaScript or WebAssembly JPEG XL
+  encoder among the payloads [we measured](ENCODER-COMPARISON.md).
+- Lossless and lossy in one `encode` call; alpha stays exact at every quality.
+- Photographs, JPEGs carried without decoding, and smaller exact files at more time are optional doors, added
+  only when imported.
+- The same input writes the same bytes in every JavaScript engine; quality is measured against libjxl 0.12.0.
+- No dependencies, MIT. An agent adding it to an app reads `AGENTS.md`.
+
+```sh
+npm install rapier-jxl
+```
+
+The encoder inside [Rapier](https://rapier.website), published on its own.
+
+## What it does
 
 - **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
+- **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.
+- **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.
 
+For the accelerated effort door, use `rapier-jxl/wasm` or the self-contained `wasm.min.mjs`.
+It falls back to JavaScript when SIMD is unavailable and writes identical lossless bytes.
+See [KERNELS.md](KERNELS.md) for controls, memory, source and rebuild instructions.
+
 ## Use it
 
 ```js
@@ -35,12 +58,19 @@ const {bytes, width: w, height: h, orientation} = transcode(new Uint8Array(await
 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`, each readable, so a
+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
 
 Encoding is synchronous. Run it off the main thread:
@@ -63,9 +93,30 @@ Each door has a twin that does the same work in steps: `encodeSteps`, `transcode
 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
+`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.2.0 adds the `kernels` and `wasm` doors (integer WebAssembly under the lossless hot loops, JavaScript
+fallback), a worker pool for large exact pictures, exact hybrid-integer codes, and a colour-transform search at effort 4.
+Exact pictures stay lossless; 27 of the 154 test streams change bytes, none larger.
+
+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 and a 16 MiB stream. Each door's `LIMITS` sets its pixels by its
@@ -97,23 +148,29 @@ New: `rapier-jxl/effort`, each door's twin in steps with `hurry`, `colorSpace: '
 
 | 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`
+| `rapier-jxl.min.mjs`, the core: `encode` | 21,326 | 9,271 | 8,233 | |
+| `effort.min.mjs`: `encode` with effort | 33,584 | 13,793 | 12,173 | 4,522 |
+| `wasm.min.mjs`: accelerated effort, JS fallback | 43,535 | 18,533 | 16,239 | 9,262 |
+| `jpeg.min.mjs`: `transcode` | 32,354 | 13,505 | 11,946 | 8,524 |
+| `photo.min.mjs`: `encodePhoto` | 33,011 | 13,616 | 12,048 | 6,249 |
+| `jpeg-ans.min.mjs`: optional ANS carrier | 35,491 | 14,608 | 12,892 | 9,580 |
+| `photo-ans.min.mjs`: optional ANS photo | 35,994 | 14,650 | 12,975 | 7,315 |
+| every door in one bundle | 74,625 | 30,285 | 26,433 | |
+| all readable modules | 211,215 | 67,195 | | |
+
+Exact bytes of release 2.2.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
+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. Lossy through Squeeze
+channel and each channel's integer code (one of four hybrid configurations) chosen by exact cost; at effort 2 and 3
+also the weighted predictor, its contexts split by its own error; at 4 local modelling of palette indices and a
+sampled search of the 42 reversible colour transforms, kept only when its complete stream is smaller; 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.
 
@@ -131,7 +188,7 @@ headers, `npm run fuzz:scale -- --out fuzz-run --workers 4` repeats the fixed bu
 
 ## Why
 
-Rapier keeps pictures inside Markdown, and its standard says a raster picture in Markdown is JPEG XL: exact where
+Rapier keeps pictures inside Markdown, and its standard defaults to JPEG XL for raster pictures in Markdown: 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`.

package/admit.mjs

@@ -29,8 +29,12 @@ export function admitPixels(data, width, height, limits) {
   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) {
-  if (bytes.length > LIMITS.bytes) throw fault('JXL_SIZE', 'The encoded picture exceeds 16 MiB.');
+  admitOutputSize(bytes.length);
   return bytes;
 }
 

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

@@ -71,10 +71,13 @@ export class BitWriter {
 // 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;
+  let step, reply;
+  while (!(step = steps.next(reply)).done) reply = yield scaled(step.value, done => (index + done) / count);
   return step.value;
 }
+// A step's fraction mapped by `f`. A pass handed to a pool (frame.mjs, groupPass) is one step carrying its fractions as
+// `at`, mapped alike; its reply passes back unchanged.
+export const scaled = (value, f) => typeof value === 'number' ? f(value) : {...value, at: g => f(value.at(g))};
 
 // 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; }

package/build-jxl-kernels.mjs

@@ -0,0 +1,29 @@
+// SPDX-License-Identifier: MIT
+// Build-time only. npm install --no-save wabt@1.0.37 (or set WABT_MODULE to its index.js).
+// node repo/images/build-jxl-kernels.mjs [--check]
+import {readFile, writeFile} from 'node:fs/promises';
+import {fileURLToPath, pathToFileURL} from 'node:url';
+import {resolve} from 'node:path';
+import {existsSync} from 'node:fs';
+const directory = new URL(existsSync(new URL('jxl/kernels-scalar.wat', import.meta.url)) ? 'jxl/' : './', import.meta.url);
+const specifier = process.env.WABT_MODULE ? pathToFileURL(resolve(process.env.WABT_MODULE)).href : 'wabt';
+let factory;
+try { ({default: factory} = await import(specifier)); }
+catch (cause) { throw new Error('The kernel build needs build-time wabt@1.0.37. Set WABT_MODULE to its index.js when installed outside this tree.', {cause}); }
+const wabt = await factory();
+let text = '// Generated from kernels-*.wat. MIT. Do not edit.\n';
+for (const [name, symbol] of [['scalar','SCALAR'], ['simd','SIMD'], ['probe','SIMD_PROBE']]) {
+  const source = new URL(`kernels-${name}.wat`, directory);
+  const wat = wabt.parseWat(fileURLToPath(source), await readFile(source, 'utf8'), {simd: true});
+  try {
+    wat.resolveNames(); wat.validate({simd: true});
+    const {buffer} = wat.toBinary({log: false, canonicalize_lebs: true, write_debug_names: false});
+    if (!WebAssembly.validate(buffer)) throw new Error(`Invalid ${name} module`);
+    text += `export const ${symbol} = ${JSON.stringify(Buffer.from(buffer).toString('base64'))};\n`;
+    console.log(`${name}: ${buffer.length} WebAssembly bytes`);
+  } finally { wat.destroy(); }
+}
+const target = new URL('kernels-bytes.mjs', directory);
+if (process.argv.includes('--check')) {
+  if (text !== await readFile(target, 'utf8')) throw new Error('kernels-bytes.mjs differs from the WAT build');
+} else await writeFile(target, text);

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;
+}

package/coefficient-effort.mjs

@@ -0,0 +1,62 @@
+// SPDX-License-Identifier: MIT
+// Entropy search shared by the JPEG and photograph doors; coefficients and quantisation never change here.
+import {varDCTSteps} from './vardct.mjs';
+import {ZIGZAG} from './jfif.mjs';
+import {complete} from './bits.mjs';
+
+// Frequently nonzero positions first, counted in buckets of eight blocks. Ties keep the natural transposed
+// zigzag, and DC stays first. Integer counts and an explicit tie rule make the permutation deterministic.
+export function coefficientOrders(components) { return complete(coefficientOrderSteps(components)); }
+
+export function* coefficientOrderSteps(components) {
+  const scan = ZIGZAG.map(n => ((n & 7) << 3) | (n >> 3));
+  const histograms = components.map(() => new Uint32Array(64)), total = components.reduce((n, c) => n + c.coeffs.length, 0);
+  let done = 0;
+  for (let c = 0; c < components.length; c++) {
+    const {coeffs} = components[c], counts = histograms[c];
+    // At most one 256-pixel group's coefficient count between yields, including JPEG padding blocks.
+    for (let from = 0; from < coeffs.length; from += 65536) {
+      const end = Math.min(from + 65536, coeffs.length);
+      for (let at = from; at < end; at += 64) for (let k = 1; k < 64; k++) if (coeffs[at + scan[k]]) counts[k]++;
+      done += end - from;
+      if (yield done / total) return null;
+    }
+  }
+  return histograms.map(counts => [0, ...Array.from({length: 63}, (_, k) => k + 1).sort((a, b) => Math.floor(counts[b] / 8) - Math.floor(counts[a] / 8) || a - b)]);
+}
+
+// Rung 3 tries a 32-cluster budget at cost 160; rung 4 also tries one learned order. Complete earlier streams
+// remain available on a tie, hurry, memory failure or candidate above the stream limit. No input is mutated.
+// A supplied fallback is already written; it also makes the first writer interruptible for a lossy candidate.
+export function* coefficientEffortSteps(jpeg, effort, fallback) {
+  if (effort < 3 && !fallback) return yield* varDCTSteps(jpeg);
+  let best = fallback;
+  try {
+    const first = varDCTSteps(jpeg); let step, hurry;
+    while (!(step = first.next()).done) {
+      hurry = yield step.value / 2;
+      if (hurry && best && step.value < 1) { first.return(); return best; }
+    }
+    if (!best || step.value.length < best.length) best = step.value;
+    if (hurry || effort < 3) return best;
+    const parts = effort < 4 ? 1 : 3, clustered = varDCTSteps(jpeg, {clusters: {maxClusters: 32, newClusterCost: 160}});
+    while (!(step = clustered.next()).done) {
+      hurry = yield 0.5 + step.value / (2 * parts);
+      // The final group has already been written. Finish its stream before honoring a late hurry.
+      if (hurry && step.value < 1) { clustered.return(); return best; }
+    }
+    if (step.value.length < best.length) best = step.value;
+    if (hurry || effort < 4) return best;
+    const learning = coefficientOrderSteps(jpeg.components);
+    while (!(step = learning.next()).done) if (yield 0.5 + (1 + step.value) / 6) { learning.return(); return best; }
+    const candidate = varDCTSteps(jpeg, {orders: step.value});
+    while (!(step = candidate.next()).done) {
+      hurry = yield 0.5 + (2 + step.value) / 6;
+      if (hurry && step.value < 1) { candidate.return(); return best; }
+    }
+    return step.value.length < best.length ? step.value : best;
+  } catch (error) {
+    if (!best || !(error instanceof RangeError && !error.code) && error.code !== 'JXL_SIZE') throw error;
+    return best;
+  }
+}