rapier-jxl 1.1.16

package/AGENTS.md

@@ -0,0 +1,18 @@
+# For an agent adding Rapier JXL to an app
+
+1. Install: `npm install rapier-jxl` (or copy the eleven `.mjs` files at this repository's root into the app; no build needed).
+2. Import `encode` and `transcode` from `rapier-jxl` (or from `index.mjs`).
+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. The 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`, 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; the README shows a complete one in eight lines.
+6. Handle the five error codes (`JXL_INPUT`, `JXL_DIMENSIONS`, `JXL_SIZE`, `JXL_MEMORY`, `JXL_JPEG`); there are no
+   others, and a call that returns has returned a stream every JPEG XL decoder reads.
+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.
+
+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.

package/LICENSE

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

package/README.md

@@ -0,0 +1,108 @@
+# 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: 24.7 KB gzipped
+(83.7 KB of readable source), MIT.
+
+- **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; a picture of few colours is answered exact when that is fewer bytes.
+- **A JPEG carried whole.** A JPEG's coefficients go into a JPEG XL frame untouched, the way libjxl transcodes one,
+  so the picture decodes to the JPEG's own pixels at about a fifth fewer bytes, in one call, without decoding.
+
+Every browser that reads JPEG XL reads these streams; so do libjxl, jxl-oxide and everything built on them.
+
+## Use it
+
+```js
+import {encode, transcode} from 'rapier-jxl';
+
+// 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 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);
+```
+
+`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.
+
+Named entries for a tighter bundle: `encodeLosslessRGBA`, `encodeLossyRGBA`, `transcode`, and the raw
+`encodeLossless`, `encodeLossy`, `transcodeJPEG`, `parseJPEG`, `inspectPixels` beneath them. The whole module is
+the eleven `.mjs` files at the root of this repository: copy them into an app as they are, or install the package.
+
+### In a worker
+
+Encoding is synchronous and takes tens to hundreds of milliseconds on a large picture, so do it off the main
+thread. A complete worker is this:
+
+```js
+// jxl-worker.mjs
+import {encode, transcode} from 'rapier-jxl';
+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})};
+    self.postMessage({id, ok: true, ...out}, [out.bytes.buffer]);
+  } catch (error) { self.postMessage({id, ok: false, code: error.code || 'JXL_ERROR', message: String(error.message || error)}); }
+};
+```
+
+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 bytes transferred, never copied.
+
+### Limits and errors
+
+One picture at a time, at most 16,384 pixels on a side, 24 million pixels, and a 16 MiB stream. Anything else is
+refused before any work with 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 or a DNL height; decode it and encode its pixels instead). There is no
+other failure: a call either returns a stream every decoder reads or throws one of these.
+
+## Sizes
+
+| what | source | gzipped |
+| --- | --- | --- |
+| the whole module (the eleven files) | 83.7 KB | 24.7 KB |
+| lossless only (`encodeLosslessRGBA`) | 35.7 KB | 11.0 KB |
+| the JPEG carrier only (`transcode`) | 60.1 KB | 18.0 KB |
+
+Measured on this release's files by the script that stages this repository, gzip at level 9, before any
+minifier. A bundler that drops what you do not import lands between the rows.
+
+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), no
+XYB, no chroma-from-luma, no filters. Lossless pictures use the modular mode with a palette of up to 512
+colours, the reversible YCoCg transform, the clamped-gradient predictor and one prefix code per channel, in
+groups of 256 by 256 pixels. Lossy pictures use the modular mode with the Squeeze transform. Carried JPEGs use
+the VarDCT mode with the JPEG's own quantisation tables as raw dequantisation matrices.
+
+## 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
+
+Rapier's own tree holds the tests: every stream this encoder writes is decoded again through
+[jxl-oxide](https://github.com/tirr-c/jxl-oxide) and compared pixel by pixel (exact where exactness is promised,
+above 38 dB where it is not, one stream for every JPEG form of one picture), and the page's retained checks run
+the same before each release. This repository is republished from that tree at each release, so what is here has
+passed them.
+
+## 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.

package/bits.mjs

@@ -0,0 +1,71 @@
+// Rapier's JPEG XL encoder: the bit writer. MIT (LICENSE).
+// JPEG XL packs bits least-significant first; `write` takes up to 32 bits at a time.
+
+export class BitWriter {
+  constructor(capacity = 4096) {
+    this.bytes = new Uint8Array(capacity);
+    this.at = 0;       // whole bytes written
+    this.acc = 0;      // the pending bits, as a number below 2^40
+    this.pending = 0;  // how many bits `acc` holds, always below 8 between calls
+  }
+  write(count, value) {
+    if (count > 32 || value < 0 || value >= 2 ** count) throw new Error('bit write out of range: ' + count + ' bits, ' + value);
+    let acc = this.acc + value * 2 ** this.pending, pending = this.pending + count;
+    if (this.at + 5 >= this.bytes.length) this.grow();
+    const bytes = this.bytes;
+    while (pending >= 8) { bytes[this.at++] = acc & 255; acc = Math.floor(acc / 256); pending -= 8; }
+    this.acc = acc; this.pending = pending;
+  }
+  // The U32 field of the specification: a two-bit selector, then that choice's bits (`offset` plus the bits).
+  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; }
+    }
+    throw new Error('U32 value out of range: ' + value);
+  }
+  zeroPadToByte() {
+    if (!this.pending) return;
+    if (this.at + 1 >= this.bytes.length) this.grow();
+    this.bytes[this.at++] = this.acc; this.acc = 0; this.pending = 0;
+  }
+  get bitLength() { return this.at * 8 + this.pending; }
+  grow(need = 0) {
+    const next = new Uint8Array(Math.max(this.bytes.length * 2, this.at + need + 16));
+    next.set(this.bytes.subarray(0, this.at)); this.bytes = next;
+  }
+  // Appends another writer's bits at the current bit position.
+  append(other) {
+    if (this.at + other.at + 8 >= this.bytes.length) this.grow(other.at + 8);
+    if (!this.pending) { this.bytes.set(other.bytes.subarray(0, other.at), this.at); this.at += other.at; }
+    else for (let i = 0; i < other.at; i++) this.write(8, other.bytes[i]);
+    if (other.pending) this.write(other.pending, other.acc);
+  }
+  // The bytes so far, the last partial byte zero-padded.
+  finish() {
+    const length = this.at + (this.pending ? 1 : 0), out = new Uint8Array(length);
+    out.set(this.bytes.subarray(0, this.at));
+    if (this.pending) out[this.at] = this.acc;
+    return out;
+  }
+}
+
+// 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; }
+
+export function floorLog2(value) { return 31 - Math.clz32(value); }
+export function ceilLog2(value) { return value <= 1 ? 0 : 32 - Math.clz32(value - 1); }
+
+// IEEE half precision, round to nearest even, as the specification's F16 fields.
+export function float16Bits(value) {
+  if (value === 0) return 0;
+  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; }
+  let m = Math.round(mantissa * 1024);
+  if (m === 1024) { m = 0; exponent++; }
+  return sign | ((exponent + 15) << 10) | m;
+}

package/entropy.mjs

@@ -0,0 +1,99 @@
+// Rapier's JPEG XL encoder: token coding over many contexts. MIT (LICENSE).
+// The AC coefficients of a VarDCT frame are coded in hundreds of contexts; the contexts are clustered into a few
+// dozen histograms by greedy merging (the cheapest entropy increase first), each histogram takes the hybrid
+// integer split that costs least on its own values, and a prefix code is built per histogram.
+import {buildCode, uintConfig, hybridToken} from './prefix.mjs';
+import {floorLog2} from './bits.mjs';
+
+const CONFIGS = [uintConfig(0), uintConfig(1), uintConfig(2), uintConfig(3), uintConfig(4), uintConfig(4, 1, 1), uintConfig(5, 1, 1), uintConfig(2, 0, 1), uintConfig(3, 0, 1)];
+const CLUSTER_CONFIG = uintConfig(4, 1, 1);
+
+// Value counts per context: values below 64 in a table, larger ones in a map per context.
+export class TokenCounts {
+  constructor(contexts) { this.contexts = contexts; this.small = new Uint32Array(contexts * 64); this.large = Array.from({length: contexts}, () => null); this.totals = new Float64Array(contexts); }
+  add(ctx, value) {
+    this.totals[ctx]++;
+    if (value < 64) { this.small[ctx * 64 + value]++; return; }
+    const map = this.large[ctx] || (this.large[ctx] = new Map());
+    map.set(value, (map.get(value) || 0) + 1);
+  }
+  // Token histogram of a set of contexts under a configuration.
+  tokens(contexts, config, size = 64) {
+    const freqs = new Uint32Array(size);
+    for (const ctx of contexts) {
+      const base = ctx * 64;
+      for (let v = 0; v < 64; v++) if (this.small[base + v]) freqs[hybridTokenOf(config, v)] += this.small[base + v];
+      const map = this.large[ctx];
+      if (map) for (const [v, n] of map) freqs[hybridTokenOf(config, v)] += n;
+    }
+    return freqs;
+  }
+  // The bits a set of contexts costs under a configuration: token entropy plus the raw bits.
+  cost(contexts, config) {
+    const freqs = this.tokens(contexts, config);
+    let total = 0, bits = 0;
+    for (const f of freqs) total += f;
+    for (const f of freqs) if (f) bits += f * Math.log2(total / f);
+    for (const ctx of contexts) {
+      const base = ctx * 64;
+      for (let v = config.splitToken; v < 64; v++) if (this.small[base + v]) bits += this.small[base + v] * (floorLog2(v) - config.msb - config.lsb);
+      const map = this.large[ctx];
+      if (map) for (const [v, n] of map) bits += n * (floorLog2(v) - config.msb - config.lsb);
+    }
+    return bits;
+  }
+}
+
+const slots = [0, 0, 0];
+function hybridTokenOf(config, value) { hybridToken(config, value, slots); return slots[0]; }
+
+function entropyBits(freqs) {
+  let total = 0, bits = 0;
+  for (const f of freqs) total += f;
+  for (const f of freqs) if (f) bits += f * Math.log2(total / f);
+  return bits;
+}
+
+// Clusters the used contexts (unused ones join cluster 0) and builds one prefix code per cluster. Returns the
+// context map and histograms for writeHistograms, and a writer for tokens.
+export function buildTokenCoding(counts, {maxClusters = 48, newClusterCost = 320} = {}) {
+  const used = [];
+  for (let ctx = 0; ctx < counts.contexts; ctx++) if (counts.totals[ctx] > 0) used.push(ctx);
+  used.sort((a, b) => counts.totals[b] - counts.totals[a]);
+  const clusters = [];  // {contexts, freqs, bits}
+  for (const ctx of used) {
+    const own = counts.tokens([ctx], CLUSTER_CONFIG), ownBits = entropyBits(own);
+    let best = -1, bestIncrease = Infinity;
+    for (let i = 0; i < clusters.length; i++) {
+      const cluster = clusters[i], merged = new Uint32Array(64);
+      for (let t = 0; t < 64; t++) merged[t] = cluster.freqs[t] + own[t];
+      const increase = entropyBits(merged) - cluster.bits - ownBits;
+      if (increase < bestIncrease) { bestIncrease = increase; best = i; }
+    }
+    if (best < 0 || (clusters.length < maxClusters && bestIncrease > newClusterCost)) clusters.push({contexts: [ctx], freqs: own, bits: ownBits});
+    else {
+      const cluster = clusters[best];
+      cluster.contexts.push(ctx);
+      for (let t = 0; t < 64; t++) cluster.freqs[t] += own[t];
+      cluster.bits = entropyBits(cluster.freqs);
+    }
+  }
+  if (!clusters.length) clusters.push({contexts: [], freqs: new Uint32Array(64), bits: 0});
+  const contextMap = new Uint8Array(counts.contexts);
+  let bits = counts.contexts * 2;  // the context map's entries, roughly
+  const histograms = clusters.map((cluster, index) => {
+    for (const ctx of cluster.contexts) contextMap[ctx] = index;
+    let config = CONFIGS[0], bestCost = Infinity;
+    for (const candidate of CONFIGS) { const cost = counts.cost(cluster.contexts, candidate); if (cost < bestCost) { bestCost = cost; config = candidate; } }
+    const code = buildCode(counts.tokens(cluster.contexts, config, 128));
+    bits += bestCost + code.alphabetSize * 3 + 40;
+    return {config, code};
+  });
+  const write = (w, ctx, value) => {
+    const histogram = histograms[contextMap[ctx]];
+    hybridToken(histogram.config, value, slots);
+    w.write(histogram.code.lengths[slots[0]], histogram.code.codes[slots[0]]);
+    if (slots[1]) w.write(slots[1], slots[2]);
+  };
+  return {contextMap, histograms, write, bits};
+}

package/frame.mjs

@@ -0,0 +1,100 @@
+// Rapier's JPEG XL encoder: the codestream around a frame. MIT (LICENSE).
+// A bare codestream (no container): signature, size header, image metadata, one frame with its table of contents.
+import {BitWriter} from './bits.mjs';
+
+export const GROUP_DIM = 256, DC_GROUP_DIM = 2048;
+
+function writeSize(w, size) {
+  if (size <= 1 << 9) { w.write(2, 0); w.write(9, size - 1); }
+  else if (size <= 1 << 13) { w.write(2, 1); w.write(13, size - 1); }
+  else if (size <= 1 << 18) { w.write(2, 2); w.write(18, size - 1); }
+  else { w.write(2, 3); w.write(30, size - 1); }
+}
+
+// 8 bits per sample; `colour` 1 (grey) or 3 (sRGB); an 8-bit alpha channel when `alpha`. Frames start byte-aligned.
+export function writeImageHeader(w, width, height, colour, alpha, {xyb = false, orientation = 1} = {}) {
+  w.write(16, 0x0AFF);
+  w.write(1, 0);          // not the small size form
+  writeSize(w, height);
+  w.write(3, 0);          // no aspect ratio shortcut
+  writeSize(w, width);
+  w.write(1, 0);          // metadata not all default
+  const extra = orientation !== 1;
+  w.write(1, extra ? 1 : 0);  // extra fields: only an orientation (the Exif value, as a JPEG carried it)
+  if (extra) { w.write(3, orientation - 1); w.write(1, 0); w.write(1, 0); w.write(1, 0); }  // no intrinsic size, preview or animation
+  w.write(1, 0);          // integer samples
+  w.write(2, 0);          // 8 bits per sample
+  w.write(1, 1);          // 16-bit buffers suffice
+  if (alpha) { w.write(2, 1); w.write(1, 1); }  // one extra channel, all default: 8-bit alpha
+  else w.write(2, 0);
+  w.write(1, xyb ? 1 : 0);  // xyb_encoded
+  if (colour === 3) w.write(1, 1);  // colour encoding all default: sRGB
+  else {
+    w.write(1, 0); w.write(1, 0);   // not default, no ICC
+    w.write(2, 1);                  // grey
+    w.write(2, 1);                  // D65
+    w.write(1, 0);                  // no gamma
+    w.write(2, 2); w.write(4, 11);  // transfer function: sRGB
+    w.write(2, 1);                  // relative rendering intent
+  }
+  if (extra) w.write(1, 1);  // default tone mapping
+  w.write(2, 0);          // no extensions
+  w.write(1, 1);          // default transform data
+  w.zeroPadToByte();
+}
+
+// A lossless modular frame, the last frame, no filters, one pass, 256-pixel groups, replace blending.
+export function writeModularFrameHeader(w, {alpha}) {
+  w.write(1, 0);  // not all default
+  w.write(2, 0);  // regular frame
+  w.write(1, 1);  // modular
+  w.write(2, 0);  // default flags
+  w.write(1, 0);  // not YCbCr
+  w.write(2, 0);  // no upsampling
+  if (alpha) w.write(2, 0);  // no extra-channel upsampling
+  w.write(2, 1);  // group size shift 1: 256
+  w.write(2, 0);  // one pass
+  w.write(1, 0);  // no custom size or origin
+  w.write(2, 0);  // replace blending
+  if (alpha) w.write(2, 0);  // replace for the extra channel
+  w.write(1, 1);  // the last frame
+  w.write(2, 0);  // no name
+  w.write(1, 0);  // loop filter not default:
+  w.write(1, 0);  //   no gaborish
+  w.write(2, 0);  //   no edge-preserving filter
+  w.write(2, 0);  //   no filter extensions
+  w.write(2, 0);  // no frame header extensions
+}
+
+const TOC_OFFSET = [0, 1024, 17408, 4211712], TOC_BITS = [12, 16, 24, 32];
+
+export function writeTOC(w, sizes) {
+  w.write(1, 0);  // no permutation
+  w.zeroPadToByte();
+  for (const size of sizes) {
+    let bucket = 0;
+    while (bucket < 3 && size >= TOC_OFFSET[bucket + 1]) bucket++;
+    w.write(2, bucket);
+    w.write(TOC_BITS[bucket] - 2, size - TOC_OFFSET[bucket]);
+  }
+  w.zeroPadToByte();
+}
+
+export function groupLayout(width, height) {
+  const groupsX = Math.ceil(width / GROUP_DIM), groupsY = Math.ceil(height / GROUP_DIM);
+  const dcGroupsX = Math.ceil(width / DC_GROUP_DIM), dcGroupsY = Math.ceil(height / DC_GROUP_DIM);
+  return {groupsX, groupsY, dcGroupsX, dcGroupsY, single: groupsX === 1 && groupsY === 1};
+}
+
+// Sections in the specification's order: DC global, the DC groups, AC global, the AC groups (one pass). A single
+// group frame has one section holding everything. Every section ends on a byte.
+export function assembleCodestream(header, sections) {
+  const sizes = sections.map(section => section.length);
+  writeTOC(header, sizes);
+  const head = header.finish();
+  const out = new Uint8Array(head.length + sizes.reduce((a, b) => a + b, 0));
+  out.set(head);
+  let at = head.length;
+  for (const section of sections) { out.set(section, at); at += section.length; }
+  return out;
+}

package/index.mjs

@@ -0,0 +1,77 @@
+// SPDX-License-Identifier: MIT
+// Rapier JXL: a JPEG XL encoder in pure JavaScript, the one Rapier's page carries. This is the module's face for
+// other apps; Rapier's own worker takes the modules directly (images/encoder.mjs). No WebAssembly, no build step,
+// no dependency, nothing read or fetched at run time: pixels in, a bare codestream out.
+import {inspectPixels, encodeLossless} from './lossless.mjs';
+import {encodeLossy} from './lossy.mjs';
+import {transcodeJPEG} from './vardct.mjs';
+import {parseJPEG} from './jpeg.mjs';
+
+// What one call takes at most: the 16 MiB codestream, 24 million pixels, 16,384 on a side. Larger asks are refused
+// with a coded error before any work, the way a decoder would refuse them after it.
+export const LIMITS = Object.freeze({bytes: 16 * 1024 * 1024, pixels: 24_000_000, edge: 16384});
+
+const fault = (code, message) => Object.assign(new Error(message), {code});
+function admitSize(width, height) {
+  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.');
+}
+function admitPixels(data, width, height) {
+  admitSize(width, height);
+  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.');
+}
+function answer(bytes) {
+  if (bytes.length > LIMITS.bytes) throw fault('JXL_SIZE', 'The encoded picture exceeds 16 MiB.');
+  return bytes;
+}
+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; }
+}
+
+// Exact: every pixel comes back as it went in. An opaque alpha is dropped, a grey picture keeps one channel,
+// up to 512 colours become a palette, colour goes through the reversible YCoCg transform.
+export function encodeLosslessRGBA(data, width, height) {
+  admitPixels(data, width, height);
+  return guard(() => answer(encodeLossless(data, width, height, {shape: inspectPixels(data, width, height)})));
+}
+
+// Lossy modular at a quality from 1 to 99 (90 is libjxl's distance 1.0); a picture of few colours is answered
+// exact when that is fewer bytes. Quality 100 is the lossless answer.
+export function encodeLossyRGBA(data, width, height, quality = 90) {
+  admitPixels(data, width, height);
+  if (!Number.isFinite(quality) || quality < 1 || quality > 100) throw fault('JXL_INPUT', 'Quality is a number from 1 to 100.');
+  return guard(() => {
+    const shape = inspectPixels(data, width, height);
+    if (quality >= 100) return answer(encodeLossless(data, width, height, {shape}));
+    let bytes = encodeLossy(data, width, height, {quality, shape});
+    if (shape.palette) { const exact = encodeLossless(data, width, height, {shape}); if (exact.length <= bytes.length) bytes = exact; }
+    return answer(bytes);
+  });
+}
+
+// One call for both: quality 100 (the default) is exact, anything lower is lossy.
+export function encode(data, width, height, {quality = 100} = {}) {
+  return quality >= 100 ? encodeLosslessRGBA(data, width, height) : encodeLossyRGBA(data, width, height, quality);
+}
+
+// A JPEG carried whole into JPEG XL: its coefficients, quantisation tables, colour and subsampling kept, only the
+// entropy coding changed, so the picture decodes to the JPEG's own pixels at about a fifth fewer bytes. Baseline,
+// extended sequential and progressive scans, with restarts; 8-bit; grey or YCbCr/RGB; an Exif orientation kept.
+// A JPEG this path does not take (arithmetic coding, 12-bit, lossless, CMYK, a DNL height) is refused as
+// JXL_JPEG; decode it and encode its pixels instead.
+export function transcode(jpeg) {
+  if (!(jpeg instanceof Uint8Array) || !jpeg.length) throw fault('JXL_INPUT', 'A JPEG is a non-empty Uint8Array.');
+  if (jpeg.length > LIMITS.bytes) throw fault('JXL_SIZE', 'A JPEG is at most 16 MiB.');
+  return guard(() => {
+    const parsed = parseJPEG(jpeg);
+    admitSize(parsed.width, parsed.height);
+    const bytes = answer(transcodeJPEG(jpeg, parsed));
+    const swapped = parsed.orientation >= 5;
+    return {bytes, width: swapped ? parsed.height : parsed.width, height: swapped ? parsed.width : parsed.height, orientation: parsed.orientation};
+  });
+}
+
+export {encodeLossless, encodeLossy, transcodeJPEG, parseJPEG, inspectPixels};