rapier-jxl 1.1.21 → 2.0.0

package/effort.mjs

@@ -0,0 +1,217 @@
+// SPDX-License-Identifier: MIT
+// Rapier JXL's effort door: the core's `encode` with a search above it. {effort: 1} (the default) writes the core's
+// stream byte for byte; a higher effort prices more candidates for every channel of an exact picture and keeps the
+// smallest stream: never larger than the effort below it, effort 1's on a tie. The rungs, each from its effort up:
+// 2. the specification's self-correcting (weighted) predictor, one context per channel;
+// 3. the weighted predictor with its channel's tokens split by the predictor's own error, neighbouring intervals of
+//    libjxl's cut points merged wherever a shared prefix code costs less.
+// A lossy request is effort 1's. Above effort 1 an exact picture's job spends its first half (fractions up to 0.5)
+// writing effort 1's stream and its second searching, so a caller's clock can tell the search's own pace; `hurry`
+// ends the search at its next step with the smallest stream written so far. Every choice is integer arithmetic: the
+// same input and options write the same bytes everywhere.
+import {LIMITS, BitWriter, complete, part} from './bits.mjs';
+import {writeImageHeader, writeModularFrameHeader, groupLayout, assembleCodestream, GROUP_DIM} from './frame.mjs';
+import {buildCode, writePrefixCode} from './prefix.mjs';
+import {AVERAGE_PREDICTOR, GRADIENT_PREDICTOR, ALPHABET, leaf, split, channelTree, writeTree, writeModularHeader, writeChannelHistograms, codeChannel} from './modular.mjs';
+import {inspectPixels, losslessSteps} from './lossless.mjs';
+import {lossySteps} from './lossy.mjs';
+import {WEIGHTED_PREDICTOR, WEIGHTED_PROPERTY, WEIGHTED_CUTS, codeWeighted} from './weighted.mjs';
+import {fault, admitOptions, admitPixels, job} from './admit.mjs';
+
+export {LIMITS};
+
+export function encode(data, width, height, options) { return complete(encodeSteps(data, width, height, options)); }
+
+// The options as every door reads them, and the effort, which this door alone reads (the core, one rung, does not): a
+// whole number from 1 to 9, 1 when absent.
+export function encodeSteps(data, width, height, options) {
+  const {quality, colorSpace} = admitOptions(options), effort = options?.effort === undefined ? 1 : options.effort;
+  if (!Number.isInteger(effort) || effort < 1 || effort > 9) throw fault('JXL_INPUT', 'Effort is a whole number from 1 to 9.');
+  admitPixels(data, width, height);
+  return job(effortSteps(data, width, height, quality, colorSpace, effort));
+}
+
+// Effort 1 is the core's work (index.mjs), step for step; the rungs run after it and keep a smaller stream if they
+// find one. A search that runs out of memory leaves effort 1's stream standing.
+function* effortSteps(data, width, height, quality, colorSpace, effort) {
+  const shape = inspectPixels(data, width, height);
+  if (quality < 100) {
+    if (!shape.palette) return yield* lossySteps(data, width, height, {quality, shape, colorSpace});
+    const exact = yield* part(losslessSteps(data, width, height, {shape, colorSpace}), 0, 2);
+    let bytes;
+    try { bytes = yield* part(lossySteps(data, width, height, {quality, shape, colorSpace}), 1, 2); }
+    catch (error) { if (!(error instanceof RangeError) || error.code) throw error; bytes = exact; }
+    return exact.length <= bytes.length ? exact : bytes;
+  }
+  if (effort < 2) return yield* losslessSteps(data, width, height, {shape, colorSpace});
+  let best = yield* part(losslessSteps(data, width, height, {shape, colorSpace}), 0, 2);
+  try {
+    const bytes = yield* part(searchSteps(data, width, height, shape.palette ? {...shape, palette: null} : shape, colorSpace, effort), 1, 2);
+    if (bytes && bytes.length < best.length) best = bytes;
+  } catch (error) { if (!(error instanceof RangeError) || error.code) throw error; }
+  return best;
+}
+
+// A token's raw bits: a residual token s above zero carries s - 1 of them, an LZ77 length token above 235 s - 236.
+const raw = s => Math.max(0, s < 224 ? s - 1 : s - 236);
+// A histogram's complete cost in bits: its prefix code's header and every token's code and raw bits.
+function cost(freqs) {
+  const code = buildCode(freqs), writer = new BitWriter(128);
+  writePrefixCode(writer, code);
+  let bits = writer.bitLength;
+  for (let s = 0; s < freqs.length; s++) if (freqs[s]) bits += freqs[s] * (code.lengths[s] + raw(s));
+  return bits;
+}
+const sum = histograms => { const out = new Uint32Array(ALPHABET); for (const h of histograms) for (let s = 0; s < ALPHABET; s++) out[s] += h[s]; return out; };
+
+// The direct plan of lossless.mjs (YCoCg, 256-pixel groups), every channel counted over the whole picture under effort
+// 1's predictor (chosen by samples, as the core chooses it) and under the weighted one; each rung's plan takes every
+// channel's cheapest, and the plans are written the cheapest way. Nothing written (null) when no plan leaves effort 1.
+function* searchSteps(rgba, width, height, shape, colorSpace, effort) {
+  const {channels} = shape, layout = groupLayout(width, height), groups = layout.groupsX * layout.groupsY;
+  const planes = Array.from({length: channels}, () => new Int16Array(GROUP_DIM * GROUP_DIM));
+  const fill = (x0, y0, w, h) => {
+    for (let y = 0; y < h; y++) {
+      let i = ((y0 + y) * width + x0) * 4, at = y * w;
+      for (let x = 0; x < w; x++, i += 4, at++) {
+        if (channels >= 3) {
+          const r = rgba[i], g = rgba[i + 1], b = rgba[i + 2];
+          const co = r - b, tmp = b + (co >> 1), cg = g - tmp;
+          planes[0][at] = tmp + (cg >> 1); planes[1][at] = co; planes[2][at] = cg;
+          if (channels === 4) planes[3][at] = rgba[i + 3];
+        } else { planes[0][at] = rgba[i]; if (channels === 2) planes[1][at] = rgba[i + 3]; }
+      }
+    }
+  };
+  const group = (g, visit) => {
+    const x0 = g % layout.groupsX * GROUP_DIM, y0 = (g / layout.groupsX | 0) * GROUP_DIM, w = Math.min(GROUP_DIM, width - x0), h = Math.min(GROUP_DIM, height - y0);
+    fill(x0, y0, w, h);
+    visit(w, h);
+  };
+  // Effort 1's predictor per channel: three 32-pixel samples priced under gradient and average, as the core does.
+  const sw = Math.min(width, 32), sh = Math.min(height, 32);
+  const sampled = [GRADIENT_PREDICTOR, AVERAGE_PREDICTOR].map(predictor => ({predictor, freqs: planes.map(() => new Uint32Array(ALPHABET))}));
+  for (const fraction of [0, 0.5, 1]) {
+    fill(Math.floor((width - sw) * fraction), Math.floor((height - sh) * fraction), sw, sh);
+    for (const candidate of sampled) for (let c = 0; c < channels; c++) codeChannel(null, candidate.freqs[c], planes[c], sw, sh, leaf(candidate.predictor));
+  }
+  const first = planes.map((_, c) => leaf(sampled[cost(sampled[1].freqs[c]) < cost(sampled[0].freqs[c]) ? 1 : 0].predictor));
+  // Every channel counted under effort 1's predictor and under the weighted one, its tokens kept by error interval.
+  // A step is a group of the counting pass (the first half of the search's fractions) or of a plan's writing (the
+  // second half, shared by the plans written), so the pace of the steps holds whether one plan is written or two.
+  const contexts = WEIGHTED_CUTS.length + 1, identity = Int32Array.from({length: contexts}, (_, k) => k);
+  const firstCounts = planes.map(() => new Uint32Array(ALPHABET)), intervals = planes.map(() => Array.from({length: contexts}, () => new Uint32Array(ALPHABET)));
+  let done = 0;
+  for (let g = 0; g < groups; g++) {
+    group(g, (w, h) => {
+      for (let c = 0; c < channels; c++) {
+        codeChannel(null, firstCounts[c], planes[c], w, h, first[c]);
+        codeWeighted(null, intervals[c], planes[c], w, h, 0, identity);
+      }
+    });
+    if (yield ++done / (2 * groups)) return null;
+  }
+  // Rung 2: each channel's cheaper of effort 1's predictor and the weighted one in one context.
+  const rung2 = planes.map((_, c) => {
+    const plan = {cost: cost(firstCounts[c]), leaves: [first[c]], freqs: [firstCounts[c]], cuts: []};
+    const whole = sum(intervals[c]), single = cost(whole);
+    return single < plan.cost ? {cost: single, leaves: [leaf(WEIGHTED_PREDICTOR)], freqs: [whole], cuts: []} : plan;
+  });
+  // Rung 3: or its intervals grouped into runs of neighbours, the grouping of least cost found exactly by dynamic
+  // programming. best[j] is the least cost of intervals 0..j-1 grouped, `from[j]` where its last group begins; an
+  // interval no token reaches leaves the merged cost as it was.
+  const rung3 = effort < 3 ? rung2 : rung2.map((plan, c) => {
+    const filled = intervals[c].map(h => h.some(v => v));
+    const best = new Float64Array(contexts + 1).fill(Infinity), from = new Int32Array(contexts + 1);
+    best[0] = 0;
+    for (let j = 1; j <= contexts; j++) {
+      const merged = new Uint32Array(ALPHABET);
+      let bits = 0;
+      for (let i = j - 1; i >= 0; i--) {
+        if (filled[i]) { const h = intervals[c][i]; for (let s = 0; s < ALPHABET; s++) merged[s] += h[s]; bits = cost(merged); }
+        // Every group is a leaf of the tree and an entry of the context map: 24 bits more, so an interval no token
+        // reaches joins its neighbour.
+        const price = best[i] + bits + 24;
+        if (price < best[j]) { best[j] = price; from[j] = i; }
+      }
+    }
+    if (!(best[contexts] < plan.cost)) return plan;
+    const groupsOf = [];
+    for (let j = contexts; j > 0; j = from[j]) groupsOf.unshift([from[j], j]);
+    return {cost: best[contexts], leaves: groupsOf.map(() => leaf(WEIGHTED_PREDICTOR)), freqs: groupsOf.map(([i, j]) => sum(intervals[c].slice(i, j))), cuts: groupsOf.slice(0, -1).map(([, j]) => WEIGHTED_CUTS[j - 1]),
+      contextOf: Int32Array.from({length: contexts}, (_, k) => groupsOf.findIndex(([i, j]) => k >= i && k < j))};
+  });
+  const candidates = [rung2, rung3].filter((plans, k) => k ? plans.some((plan, c) => plan !== rung2[c]) : plans.some((plan, c) => plan.leaves[0] !== first[c]));
+  if (!candidates.length) return null;
+  // The tree: one subtree per channel on the channel property, and inside a split channel a balanced tree on the
+  // weighted predictor's property, values above a cut to the left.
+  const byError = (leaves, cuts) => {
+    const build = (lo, hi) => { if (lo === hi) return leaves[lo]; const mid = (lo + hi) >> 1; return split(WEIGHTED_PROPERTY, cuts[mid], build(mid + 1, hi), build(lo, mid)); };
+    return build(0, leaves.length - 1);
+  };
+  const assemble = plans => ({tree: channelTree(plans.map(plan => byError(plan.leaves, plan.cuts))), leaves: plans.flatMap(plan => plan.leaves), freqs: plans.flatMap(plan => plan.freqs)});
+  // A plan's price in bits: its tree and histograms as written, and every token's code and raw bits. Two plans' streams
+  // differ by their prices and at most 27 bits a section more (a section's padding, and its size's field in the table
+  // of contents, 12 to 32 bits) and a byte: a plan that far cheaper is written alone, closer plans both.
+  const price = plans => {
+    const {tree, leaves, freqs} = assemble(plans), w = new BitWriter(4096);
+    const histograms = writeChannelHistograms(w, writeTree(w, tree), freqs, l => leaves.indexOf(l));
+    let bits = w.bitLength;
+    freqs.forEach((f, i) => { const {lengths} = histograms[i + 1].code; for (let s = 0; s < f.length; s++) if (f[s]) bits += f[s] * (lengths[s] + raw(s)); });
+    return bits;
+  };
+  let chosen = candidates;
+  if (candidates.length > 1) {
+    const [a, b] = candidates.map(price), margin = 27 * (layout.single ? 1 : groups + 1) + 8;
+    if (b + margin <= a) chosen = [candidates[1]];
+    else if (a + margin <= b) chosen = [candidates[0]];
+  }
+  let written = 0;
+  const next = () => 0.5 + ++written / (2 * chosen.length * groups);
+  let smallest = null;
+  for (const plans of chosen) {
+    const bytes = yield* write(plans);
+    if (!bytes) return smallest;
+    if (!smallest || bytes.length < smallest.length) smallest = bytes;
+  }
+  return smallest;
+
+  // A plan's stream, a group per step; null when hurried.
+  function* write(plans) {
+    const {tree, leaves, freqs} = assemble(plans);
+    const transforms = channels >= 3 ? [{type: 'rct', beginC: 0, rctType: 6}] : [];
+    const header = new BitWriter(256);
+    writeImageHeader(header, width, height, shape.colour, shape.alpha, {colorSpace});
+    writeModularFrameHeader(header, {alpha: shape.alpha});
+    const global = new BitWriter(4096);
+    global.write(1, 1);  // default DC quantisation
+    global.write(1, 1);  // a global tree
+    const histograms = writeChannelHistograms(global, writeTree(global, tree), freqs, l => leaves.indexOf(l));
+    writeModularHeader(global, {useGlobalTree: true, transforms});
+    const codes = plans.map(plan => plan.leaves.map(l => histograms[leaves.indexOf(l) + 1].code));
+    const code = (w, c, width, height) => {
+      const plan = plans[c];
+      if (plan.leaves[0].predictor === WEIGHTED_PREDICTOR) codeWeighted(w, codes[c], planes[c], width, height, 0, plan.contextOf);
+      else codeChannel(w, codes[c][0], planes[c], width, height, plan.leaves[0]);
+    };
+    const sections = [];
+    if (layout.single) {
+      group(0, (w, h) => { for (let c = 0; c < channels; c++) code(global, c, w, h); });
+      if (yield next()) return null;
+      sections.push(global.finish());
+    } else {
+      sections.push(global.finish());
+      for (let i = 0; i < layout.dcGroupsX * layout.dcGroupsY + 1; i++) sections.push(new Uint8Array(0));
+      for (let g = 0; g < groups; g++) {
+        group(g, (w, h) => {
+          const section = new BitWriter(w * h * channels + 64);
+          writeModularHeader(section, {useGlobalTree: true, transforms: []});
+          for (let c = 0; c < channels; c++) code(section, c, w, h);
+          sections.push(section.finish());
+        });
+        if (yield next()) return null;
+      }
+    }
+    return assembleCodestream(header, sections);
+  }
+}

package/entropy.mjs

@@ -45,10 +45,25 @@ export class TokenCounts {
 const slots = [0, 0, 0];
 function hybridTokenOf(config, value) { hybridToken(config, value, slots); return slots[0]; }
 
+// log2 in arithmetic every engine rounds alike (Math.log2 does not): the exponent from the integer part's leading
+// zeros and exact powers of two, then 2 atanh(z) / ln 2 as its series, z = (x - 1) / (x + 1) below 0.172 in magnitude.
+const HALVES = [1];
+for (let e = 1; e < 32; e++) HALVES.push(HALVES[e - 1] / 2);
+function log2(x) {
+  let exponent = 0;
+  if (x >= 2 && x < 4294967296) { exponent = 31 - Math.clz32(x); x *= HALVES[exponent]; }
+  while (x >= 1.4142135623730951) { x /= 2; exponent++; }
+  while (x < 0.7071067811865476) { x *= 2; exponent--; }
+  const z = (x - 1) / (x + 1), z2 = z * z;
+  let term = z, sum = z;
+  for (let k = 3; k < 30; k += 2) sum += (term *= z2) / k;
+  return exponent + sum * 2.885390081777927;
+}
+
 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);
+  for (const f of freqs) if (f) bits += f * log2(total / f);
   return bits;
 }
 

package/frame.mjs

@@ -8,8 +8,9 @@ function writeSize(w, size) {
   w.writeU32([[9, 1], [13, 1], [18, 1], [30, 1]], size);
 }
 
-// 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} = {}) {
+// 8 bits per sample; `colour` 1 (grey) or 3 (sRGB, or Display P3 when `colorSpace` says so); an 8-bit alpha channel
+// when `alpha`. Frames start byte-aligned.
+export function writeImageHeader(w, width, height, colour, alpha, {xyb = false, orientation = 1, colorSpace} = {}) {
   w.write(16, 0x0AFF);
   w.write(1, 0);          // not the small size form
   writeSize(w, height);
@@ -23,7 +24,11 @@ export function writeImageHeader(w, width, height, colour, alpha, {xyb = false,
   if (alpha) w.write(3, 0b1_01);  // one extra channel (2), all default (1): 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
+  if (colour === 3 && colorSpace === 'display-p3') {
+    // Display P3, fields in reverse order as below: not default (1), no ICC (1), RGB (2), D65 (2), the P3 primaries
+    // (selector 2 and 11 - 2 in 4), no gamma (1), the sRGB curve (selector 2 and 13 - 2 in 4), relative intent (2).
+    w.write(21, 0b01_1011_10_0_1001_10_01_00_0_0);
+  } else if (colour === 3) w.write(1, 1);  // colour encoding all default: sRGB
   else {
     // Fixed grey encoding. Groups below are the fields in reverse order because the writer sends the low bits
     // first: not default (1), no ICC (1), grey (2), D65 (2), no gamma (1), sRGB selector (2) and enum (4), intent (2).
@@ -35,13 +40,14 @@ export function writeImageHeader(w, width, height, colour, alpha, {xyb = false,
   w.zeroPadToByte();
 }
 
-// A lossless modular frame, the last frame, no filters, one pass, 256-pixel groups, replace blending.
-export function writeModularFrameHeader(w, {alpha}) {
+// A modular frame, the last frame, no filters, one pass, groups of 128 << shift pixels (256 unless asked), replace
+// blending.
+export function writeModularFrameHeader(w, {alpha, shift = 1}) {
   // Fixed beginning, low bits first: not all default (1), regular frame (2), modular (1), default flags (2),
   // not YCbCr (1), no upsampling (2).
   w.write(9, 0b00_0_00_1_00_0);
   if (alpha) w.write(2, 0);  // no extra-channel upsampling
-  w.write(2, 1);  // group size shift 1: 256
+  w.write(2, shift);  // the group size shift
   writeFrameHeaderEnd(w, alpha);
 }
 
@@ -61,9 +67,10 @@ export function writeTOC(w, sizes) {
   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);
+// The groups of a frame whose groups are `dim` pixels on a side, its DC groups eight times that.
+export function groupLayout(width, height, dim = GROUP_DIM) {
+  const groupsX = Math.ceil(width / dim), groupsY = Math.ceil(height / dim);
+  const dcGroupsX = Math.ceil(width / (8 * dim)), dcGroupsY = Math.ceil(height / (8 * dim));
   return {groupsX, groupsY, dcGroupsX, dcGroupsY, single: groupsX === 1 && groupsY === 1};
 }
 

package/index.d.mts

@@ -1,27 +1,23 @@
 // SPDX-License-Identifier: MIT
-// Rapier JXL: the types of the checked entries, the limits and the error codes. The raw entries beneath the
-// checked ones take input the checked entries have already admitted; their shapes are the modules' own.
+// Rapier JXL's core: the type of encode, the shape of the limits (each door has its own, by its memory) and the error
+// codes every door shares.
 export type Pixels = Uint8Array | Uint8ClampedArray;
 export interface Limits { readonly bytes: number; readonly pixels: number; readonly edge: number; }
-/** The 16 MiB codestream, 24 million pixels, 16,384 on a side; a larger ask is refused before any work. */
+/** The core's limits: the 16 MiB codestream, 24 million pixels, 16,384 on a side; a larger ask is refused before any
+ * work. The photo door takes 40 million pixels and the JPEG carrier 64 million, each by its memory. */
 export const LIMITS: Limits;
-export interface EncodeOptions { /** 1 to 100; 100 (the default) is exact. */ quality?: number; }
-export interface Transcoded {
-  /** A bare JPEG XL codestream, the .jxl file's bytes. */ bytes: Uint8Array;
-  /** The picture's size as shown, swapped when the Exif orientation turns it. */ width: number; height: number;
-  /** The Exif orientation, 1 to 8, kept in the JPEG XL header. */ orientation: number;
+export interface EncodeOptions {
+  /** 1 to 100; 100 is exact. */ quality?: number;
+  /** The samples' colour space, declared in the header; 'srgb' by default. */ colorSpace?: 'srgb' | 'display-p3';
+  /** 1 to 9, a whole number, read by /effort, which runs its highest rung at or below it; the core has rung 1 alone. */ effort?: number;
 }
 export type ErrorCode = 'JXL_INPUT' | 'JXL_DIMENSIONS' | 'JXL_SIZE' | 'JXL_MEMORY' | 'JXL_JPEG';
 /** Every refusal is an Error carrying one of the five codes. */
 export interface EncoderError extends Error { code: ErrorCode; }
 /** Straight RGBA bytes, row by row, to a bare JPEG XL codestream; quality 100 (the default) is exact. */
 export function encode(data: Pixels, width: number, height: number, options?: EncodeOptions): Uint8Array;
-export function encodeLosslessRGBA(data: Pixels, width: number, height: number): Uint8Array;
-export function encodeLossyRGBA(data: Pixels, width: number, height: number, quality?: number): Uint8Array;
-/** A JPEG's bytes to JPEG XL, its coefficients carried; a JPEG this path does not take is refused as JXL_JPEG. */
-export function transcode(jpeg: Uint8Array): Transcoded;
-export function encodeLossless(data: Pixels, width: number, height: number, options?: {shape?: unknown}): Uint8Array;
-export function encodeLossy(data: Pixels, width: number, height: number, options: {quality: number; shape?: unknown}): Uint8Array;
-export function transcodeJPEG(jpeg: Uint8Array, parsed: unknown): Uint8Array;
-export function parseJPEG(jpeg: Uint8Array): unknown;
-export function inspectPixels(data: Pixels, width: number, height: number): unknown;
+/** A door's work as steps: iterate for the fraction done, in (0, 1], the last exactly 1; `bytes` holds the stream after
+ * the last step. Leaving the loop cancels. `hurry` asks a search to finish with the best candidate it has priced. */
+export interface Job extends Generator<number, Uint8Array, undefined> { bytes: Uint8Array | null; hurry: boolean; }
+/** encode's work and bytes, a group of one pass per step; the call is admitted at once. */
+export function encodeSteps(data: Pixels, width: number, height: number, options?: EncodeOptions): Job;

package/index.mjs

@@ -1,94 +1,41 @@
 // 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';
-import {LIMITS} from './bits.mjs';
+// Rapier JXL: a JPEG XL encoder in pure JavaScript, the one Rapier's page carries. This is the core: pixels in, a bare
+// codestream out, exact or lossy, alpha exact. A JPEG is carried by jpeg.mjs and a photograph written by photo.mjs;
+// a module's author takes the layers from writer.mjs. No WebAssembly, no build step, no dependency, nothing read or
+// fetched at run time.
+import {inspectPixels, losslessSteps} from './lossless.mjs';
+import {lossySteps} from './lossy.mjs';
+import {LIMITS, complete, part} from './bits.mjs';
+import {admitOptions, admitPixels, job} from './admit.mjs';
 
 // What one call takes at most (bits.mjs): 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 {LIMITS};
 
-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 admitQuality(quality) {
-  if (typeof quality !== 'number' || !Number.isFinite(quality) || quality < 1 || quality > 100) throw fault('JXL_INPUT', 'Quality is a number from 1 to 100.');
-}
-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; }
-}
+// Straight RGBA bytes, row by row, to a codestream. Quality 100 (the default) is exact: an opaque alpha is dropped, a
+// grey picture keeps one channel, up to 2048 colours use a palette when its complete stream is smaller, and direct
+// colour goes through reversible YCoCg with gradient or average prediction chosen by samples. Quality 1 to 99 is lossy
+// modular on libjxl's quality-to-distance curve (not equivalent PSNR), alpha still exact; a picture of few colours is
+// answered exact when that is fewer bytes. The samples are sRGB, or Display P3 with {colorSpace: 'display-p3'}: the
+// header declares the space and the samples are written as they are. The options are read before any work.
+export function encode(data, width, height, options) { return complete(encodeSteps(data, width, height, options)); }
 
-// Exact: every pixel comes back as it went in. An opaque alpha is dropped, a grey picture keeps one channel,
-// up to 2048 colours may use a palette when its complete stream wins. Direct colour uses reversible YCoCg
-// with sampled gradient/average prediction; compare the complete direct and palette streams by actual bytes.
-export function encodeLosslessRGBA(data, width, height) {
+// The same work as a job (admit.mjs): the call admitted at once, then a group of one pass per step, the same bytes.
+export function encodeSteps(data, width, height, options) {
+  const {quality, colorSpace} = admitOptions(options);
   admitPixels(data, width, height);
-  return guard(() => answer(encodeLossless(data, width, height, {shape: inspectPixels(data, width, height)})));
+  return job(pixelSteps(data, width, height, quality, colorSpace));
 }
 
-// Lossy modular at a quality from 1 to 99, using libjxl's quality-to-distance curve (not equivalent PSNR).
-// Alpha stays exact. 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);
-  admitQuality(quality);
-  return guard(() => {
-    const shape = inspectPixels(data, width, height);
-    if (quality >= 100) return answer(encodeLossless(data, width, height, {shape}));
-    if (!shape.palette) return answer(encodeLossy(data, width, height, {quality, shape}));
-    // The exact stream of a few-colour picture is cheap to make (256-pixel sections), so it is made first: a lossy
-    // attempt that runs out of memory (its planes and Squeeze copies cost eight bytes a pixel and more) still answers.
-    const exact = encodeLossless(data, width, height, {shape});
-    let bytes;
-    try { bytes = encodeLossy(data, width, height, {quality, shape}); }
-    catch (error) { if (!(error instanceof RangeError) || error.code) throw error; bytes = exact; }
-    return answer(exact.length <= bytes.length ? exact : bytes);
-  });
+function* pixelSteps(data, width, height, quality, colorSpace) {
+  const shape = inspectPixels(data, width, height);
+  if (quality >= 100) return yield* losslessSteps(data, width, height, {shape, colorSpace});
+  if (!shape.palette) return yield* lossySteps(data, width, height, {quality, shape, colorSpace});
+  // The exact stream of a few-colour picture is cheap to make (256-pixel sections), so it is made first: a lossy
+  // attempt that runs out of memory (its planes and Squeeze copies cost eight bytes a pixel and more) still answers.
+  const exact = yield* part(losslessSteps(data, width, height, {shape, colorSpace}), 0, 2);
+  let bytes;
+  try { bytes = yield* part(lossySteps(data, width, height, {quality, shape, colorSpace}), 1, 2); }
+  catch (error) { if (!(error instanceof RangeError) || error.code) throw error; bytes = exact; }
+  return exact.length <= bytes.length ? exact : bytes;
 }
-
-// One call for both: quality 100 (the default) is exact, anything lower is lossy. The options are read before any
-// work: a quality that is not a number from 1 to 100 is JXL_INPUT, never a silent choice.
-export function encode(data, width, height, options = {}) {
-  if (options === null || typeof options !== 'object') throw fault('JXL_INPUT', 'Options are an object: {quality}.');
-  const quality = options.quality === undefined ? 100 : options.quality;
-  admitQuality(quality);
-  return quality >= 100 ? encodeLosslessRGBA(data, width, height) : encodeLossyRGBA(data, width, height, quality);
-}
-
-// A JPEG carried as its coefficients into JPEG XL: the quantised DCT 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, YCbCr or RGB;
-// an Exif orientation kept. Not carried: the JPEG reconstruction data (the JPEG file itself cannot be rebuilt from
-// the stream), ICC, Exif beyond the orientation, XMP. A JPEG this path does not take (arithmetic coding, 12-bit,
-// lossless, CMYK, a DNL height, a colour profile other than sRGB, a file cut short) 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};