@@ -13,10 +13,11 @@
 
 ---
 
-**ImageScript** decodes, edits and encodes images in pure TypeScript: no WebAssembly, no native binaries, no
-dependencies. It runs in Node.js 22.13+, Deno, Bun, browsers and edge runtimes (Cloudflare Workers, Vercel's Edge
-Runtime, Deno Deploy), works with both `import` and `require()`, and ships with type definitions. Large images are
-encoded and decoded on several threads wherever the runtime supports workers.
+**ImageScript** decodes, edits and encodes images in pure TypeScript: no WebAssembly, no native binaries, and no
+runtime dependencies. It runs in Node.js 22.13+, Deno, Bun, browsers and edge runtimes (Cloudflare Workers, Vercel's
+Edge Runtime, Deno Deploy), works with `import` and, on supported Node.js versions, `require()`, and ships with type
+definitions. Large AVIF and JPEG XL operations, and lossless WebP encoding, can use multiple CPU cores when the runtime
+supports it.
 
 ```sh
 npm install imagescript              # Node.js, Bun and bundlers
@@ -29,7 +30,7 @@ Without a bundler, import it from jsDelivr in the browser:
 
 ```html
 <script type="module">
-  import { Image } from 'https://cdn.jsdelivr.net/npm/imagescript@3/+esm';
+  import { Image } from 'https://cdn.jsdelivr.net/npm/imagescript@4/+esm';
 
   const image = await Image.decode(await fetch('photo.jpg').then(r => r.arrayBuffer()));
   image.resize({ width: 256 });
@@ -73,17 +74,23 @@ await writeFile('output.png', await image.encodePNG());
 | GIF, APNG (animations) | ✓ | ✓ |
 | BMP, QOI, TGA, Netpbm | ✓ | ✓ |
 | TIFF, ICO/CUR, Radiance HDR | ✓ | |
-| [HDR gain maps](https://imagescript.dev/classes/GainMap.html) (Ultra HDR and iPhone JPEGs, AVIF, JPEG XL) | ✓ | ✓, kept through edits |
+| [HDR gain maps](https://imagescript.dev/classes/GainMap.html) (brighter highlights on HDR displays; JPEG, AVIF, JPEG XL) | ✓ | ✓ |
 
 [Animations](https://imagescript.dev/classes/Animation.html) can be decoded from GIF, APNG, WebP and JPEG XL,
 and encoded as GIF, APNG or WebP, all at once or
-[frame by frame](https://imagescript.dev/classes/Animation.html#webpencoder). Embedded color profiles (Display
-P3, Adobe RGB, ...) are converted to sRGB when decoding, so images look the way browsers show them.
+[frame by frame](https://imagescript.dev/classes/Animation.html#webpencoder). Lossless encoding keeps every pixel
+exactly; lossy encoding makes smaller files by approximating some image detail.
 
-- [Text rendering](https://imagescript.dev/classes/Image.html#rendertext) with TrueType, OpenType and WOFF fonts:
-  all scripts, color emoji, variable fonts
+Embedded color profiles are converted to sRGB, the standard color format for most screens, where supported. CMYK and
+lookup-table profiles are left unchanged.
+
+Supported image operations preserve gain maps; editing pixels directly with `image.bitmap` or `setPixelAt()` does not.
+
+- [Text rendering](https://imagescript.dev/classes/Image.html#rendertext) with TrueType, OpenType and WOFF fonts
+  (not WOFF2; some OpenType outline formats are unsupported): right-to-left text and scripts where letters connect or
+  combine, plus color emoji and variable TrueType fonts
 - [SVG rendering](https://imagescript.dev/classes/Image.html#rendersvg), including text (with fonts you pass
-  or fonts embedded in the SVG)
+  or fonts embedded in the SVG); no automatic fetching of external images or fonts
 - [Resizing](https://imagescript.dev/classes/Image.html#resize),
   [cropping](https://imagescript.dev/classes/Image.html#crop),
   [rotating](https://imagescript.dev/classes/Image.html#rotate),
 
@@ -1,9 +1,8 @@
 # ImageScript benchmark
 
-How [ImageScript](https://github.com/imagescript/ImageScript) compares to other image libraries for Node.js: speed, file
-sizes and what installing each takes. ImageScript is plain JavaScript with no dependencies, so it runs wherever
-JavaScript does, like Jimp, image-js and PureJsImage; sharp and @napi-rs/canvas wrap native libraries (libvips, Skia),
-Photon is WebAssembly, and so is jsquash (Squoosh's libavif and libjxl, for AVIF and JPEG XL).
+This benchmark compares processing speed, output-file size and install size. Lower times and smaller files are better,
+but compare lossy files alongside their quality scores. Results depend on the machine, so compare libraries within a
+single run. The Method section explains the test inputs and measurements.
 
 <img src="charts/overview-portable.svg" alt="Time per operation of the libraries that run everywhere, colored by the distance to the fastest">
 
@@ -53,7 +52,8 @@ Time per operation (less is faster), measured 2026-11-08 with Node.js v24.22.2 o
 | render SVG | **172 ms** | – | – | – | – | 43 ms | – | 19 ms |
 | thumbnail, keeping HDR | **180 ms** | – | – | – | – | 167 ms | – | – |
 
-Encoded sizes:
+Encoded sizes. For lossy files, the dB score estimates how closely the decoded image matches the source; higher is
+closer.
 
 | | **ImageScript** | **Jimp** | **image-js** | **PureJsImage** | **Photon** | **sharp** | **jsquash** | **@napi-rs/canvas** |
 |---|--:|--:|--:|--:|--:|--:|--:|--:|
@@ -87,10 +87,11 @@ Encoded sizes:
   when the benchmark starts, PNG, lossy WebP, AVIF by sharp (libaom) and JPEG XL by jsquash (libjxl), at the
   qualities below), a 1434×1434 graphic with transparency (PNG), a 445×445 diagram with transparency placed on
   the photo (PNG), a 300×300 GIF with 101 frames (and made from it, an animated WebP by sharp at quality 80).
-- Lossy WebP, AVIF and JPEG XL are encoded at the same nominal quality (80, 60 and 90); as the libraries'
-  scales differ, the file sizes come with their PSNR (of the color over black, decoded by libwebp, libavif and
-  libjxl). jsquash's libjxl runs at the effort ImageScript's default matches (cjxl's 5 lossy, 3 lossless; its own
-  default is 7). PureJsImage's AVIF
+- Lossy WebP, AVIF and JPEG XL are encoded at the same nominal quality (80, 60 and 90). Because each library uses a
+  different quality scale, file sizes are shown with PSNR (peak signal-to-noise ratio), a measure of how closely the
+  decoded colors match the original; higher is closer. Colors are compared over black after decoding with libwebp,
+  libavif and libjxl. jsquash's JPEG XL encoder uses effort settings chosen to match ImageScript's defaults.
+  PureJsImage's AVIF
   encoder has no quality option, and its JPEG XL decoder doesn't support everything libjxl's files use, which shows as
   failing. jsquash only encodes and decodes AVIF and JPEG XL (it gets the other inputs as pixels); @napi-rs/canvas
   decodes both with Skia's codecs, but doesn't encode them.
@@ -101,17 +102,18 @@ Encoded sizes:
   clone first, sharp runs a pipeline from raw pixels back to raw pixels, PureJsImage (which has no decoded images) one
   from a BMP back to a BMP, @napi-rs/canvas draws into a new canvas. PureJsImage has no blur, composite, rendering or
   animated GIFs.
-- Where the library lets you choose, resizing is bilinear (or bicubic, in its own row), the thumbnail covers 400×400
-  (cropping the sides), blurring is gaussian with a radius or sigma of 5, sharpening an unsharp mask of radius or
-  sigma 1 (Photon: its 3×3 sharpening kernel), rotating by 30° grows the image to fit, brightness and contrast go up
+- Where the library lets you choose, resizing is bilinear (smooth) or bicubic (a sharper smoothing filter, in its own
+  row), the thumbnail covers 400×400 (cropping the sides), blurring is gaussian (softening) with a radius or sigma of
+  5, sharpening uses an unsharp mask (edge enhancement) of radius or sigma 1 (Photon: its 3×3 sharpening kernel),
+  rotating by 30° grows the image to fit, brightness and contrast go up
   20% (Jimp's and Photon's scales converted). image-js's and sharp's greyscale make one grey channel (and alpha). Each library uses its own defaults
   otherwise, e.g. its PNG compression level.
 - Threads: ImageScript uses worker threads where they pay off (the processors available, at most 8), and sharp gets
   as many (`sharp.concurrency()`; its default on glibc Linux without jemalloc, like on CI, is one). The other
   libraries run on one thread (jsquash turns its threaded builds off in Node).
 - [tinybench](https://github.com/tinylibs/tinybench), at least 1.5 seconds and 3 runs per measurement, every library
   in its own process.
-- The release workflow runs the benchmark for every release and commits the results, on a GitHub Actions runner;
+- The release workflow runs the benchmark for every regular release and commits the results, on a GitHub Actions runner;
   runners vary, so compare libraries within one run rather than between runs.
 - Install sizes: `npm install <library>` in an empty project, the apparent size of `node_modules`.
 
 
@@ -158,19 +158,22 @@ Search your code for: `.rotate(`.
 
 ### JPEG composites transparent pixels onto black
 
-JPEG has no alpha channel. In 3.x, `encodeJPEG()` dropped the alpha and kept the color, so a fully transparent pixel
-showed whatever RGB it had stored (often black, but not always). In 4.0, an image with transparent or translucent pixels
-is composited onto a background first, black by default, the way a viewer would show it on black. Pass `background`
-for another color: `image.encodeJPEG({ background: 0xffffffff })`. Opaque images encode as before, byte for byte.
-The new `subsampling` option can select `'4:4:4'` or `'4:2:0'`; its default remains 4:2:0 up to quality 90 and 4:4:4
-above.
+JPEG does not store transparency (also called an alpha channel). In 3.x, `encodeJPEG()` dropped the alpha and kept the
+color, so a fully transparent pixel showed its stored red, green and blue values (often black, but not always). In
+4.0, an image with transparent or translucent pixels is combined with a background first, black by default, the way
+a viewer would show it on black. Pass `background` for another color: `image.encodeJPEG({ background: 0xffffffff })`.
+Opaque images encode as before, byte for byte.
+The new `subsampling` option controls how much color detail to keep: `'4:4:4'` keeps it all; `'4:2:0'` stores less
+color detail to make a smaller file. Its default remains 4:2:0 up to quality 90 and 4:4:4 above.
 
 Search your code for: `encodeJPEG(` on images that can have transparency.
 
 ### `quantize()` dithers by default
 
-`image.quantize()` now dithers with Floyd-Steinberg at a strength of `0.85` by default, like the GIF encoders. In 3.x
-it didn't dither unless you passed `dither`. For the old result, pass `dither: 'none'`:
+`image.quantize()` reduces an image to a limited color palette. It now uses dithering by default: a pattern of small
+color changes that helps smooth the result when colors are reduced. The default method is Floyd-Steinberg, with a
+strength of `0.85`, like the GIF encoders. In 3.x it didn't dither unless you passed `dither`. For the old result,
+pass `dither: 'none'`:
 
 | 3.x | 4.0 |
 | --- | --- |
@@ -279,8 +282,9 @@ image.red(0.5, true);
 for (let i = 0; i < image.bitmap.length; i += 4) image.bitmap[i] = 0.5 * 255;
 ```
 
-`bitmap` is RGBA, four bytes per pixel. Writing it directly skips the gain map of an HDR image, so do not use it on
-images that have one. `absolute` on `lightness()` and `saturation()` sets the value of every pixel and keeps its hue.
+`bitmap` stores four bytes per pixel: red, green, blue and transparency (alpha). Writing it directly skips the gain map
+of a high-dynamic-range (HDR) image, so do not use it on images that have one. `absolute` on `lightness()` and
+`saturation()` sets the value of every pixel and keeps its hue.
 Do it per pixel: read the color with `Colors.toHSLA()`, set the lightness or saturation, and write the pixel back with
 `Colors.fromHSLA()`.
 
 
@@ -60,16 +60,18 @@ export interface AnimationEncodeOptions extends EncodeOptions {
 /** Options of {@link Animation.encodeWebP} */
 export interface WebPAnimationEncodeOptions extends AnimationEncodeOptions {
     /**
-     * Lossy frames (0-100, like libwebp's quality: 75 is its default), much smaller than lossless ones. Without it the
-     * frames are lossless. Optimized lossy frames, like libwebp's, leave out 8x8 blocks that only changed a little (by
-     * up to 3 per channel at quality 85, 1 at 100)
+     * Lossy compression quality (0-100): higher values usually preserve more detail but make larger files. Without
+     * this option, frames are encoded losslessly
      */
     quality?: number;
-    /** How much effort the frames take (0-6, lossy and lossless), see {@link WebPEncodeOptions.effort}. Default: `2` */
+    /**
+     * Compression effort (0-6): higher effort can make smaller files but takes longer, see
+     * {@link WebPEncodeOptions.effort}. Default: `2`
+     */
     effort?: number;
-    /** Lossy frames: libwebp's sharp YUV conversion, see {@link WebPEncodeOptions.sharpYuv}. Default: `false` */
+    /** For lossy frames, improve color detail around sharp edges. Default: `false` */
     sharpYuv?: boolean;
-    /** Lossy frames: the alpha planes' quality (0-100), see {@link WebPEncodeOptions.alphaQuality}. Default: `100` */
+    /** For lossy frames, the quality of the transparency channel (0-100). Default: `100` */
     alphaQuality?: number;
 }
 
 
@@ -15,21 +15,24 @@ export type GainMapChannelValues = number | readonly [red: number, green: number
 
 /** Options of the {@link GainMap} constructor */
 export interface GainMapOptions {
-    /** log2 of the boost of the map's value 0 (`-1`: half as bright; hdrgm's GainMapMin). Default: `0` */
+    /** Extra brightness at the map's darkest value (0); `-1` means half as bright. Default: `0` (no change) */
     min?: GainMapChannelValues;
-    /** log2 of the boost of the map's value 255 (`2`: 4 times as bright; hdrgm's GainMapMax). Default: `2` */
+    /** Extra brightness at the map's brightest value (255); `2` means four times as bright. Default: `2` */
     max?: GainMapChannelValues;
-    /** the gamma the map's values are stored with. Default: `1` */
+    /** How quickly the brightness changes between `min` and `max`; `1` changes it evenly. Default: `1` */
     gamma?: GainMapChannelValues;
-    /** added to the SDR image's linear values before the boost (keeps black from being boosted forever). Default: `1/64` */
+    /**
+     * Small brightness offset added before applying the boost, to keep black from being boosted indefinitely.
+     * Default: `1/64`
+     */
     offsetSDR?: GainMapChannelValues;
-    /** subtracted from the HDR result. Default: `1/64` */
+    /** Small brightness offset subtracted from the result. Default: `1/64` */
     offsetHDR?: GainMapChannelValues;
-    /** log2 of the display headroom from which on the map starts to apply. Default: `0` */
+    /** How bright a display must be before the map starts to apply; `0` is standard-screen brightness. Default: `0` */
     hdrCapacityMin?: number;
-    /** log2 of the display headroom at which it applies fully. Default: `max`'s largest value */
+    /** How bright a display must be for the map to apply fully. Default: the largest value in `max` */
     hdrCapacityMax?: number;
-    /** whether the boost applies in the SDR image's color space (`false`: in the HDR image's). Default: `true` */
+    /** Whether the boost uses the original image's colors (`false`: the brighter HDR colors). Default: `true` */
     useBaseColorSpace?: boolean;
 }
 
@@ -41,13 +44,14 @@ const perChannel = (value: GainMapChannelValues, name: string): number[] => {
 };
 
 /**
- * A gain map: a small image saying how much brighter each part of an image gets on an HDR display, as Ultra HDR
- * (JPEG-R) photos from phones carry it. HDR displays show the image boosted by it, the others the image as it is.
+ * A gain map is a small companion image that tells a high-dynamic-range (HDR) display how much brighter to show each
+ * part of a photo. Standard displays ignore it and show the regular-brightness image.
  *
- * {@link Image.decode} reads the gain maps of JPEGs, AVIFs and JPEG XLs into {@link Image.gainMap},
- * {@link Image.encodeJPEG}, {@link Image.encodeAVIF} and {@link Image.encodeJXL} write them. The map covers the whole image, at any resolution (phones
- * write a quarter of the width and height). Its value `v` (0-255, per channel or one for all) boosts the linear
- * light of the image by `2^(min + (max - min) * (v / 255)^(1 / gamma))`.
+ * {@link Image.decode} reads gain maps from supported JPEG, AVIF and JPEG XL images into {@link Image.gainMap};
+ * {@link Image.encodeJPEG}, {@link Image.encodeAVIF} and {@link Image.encodeJXL} can write them. The map covers the
+ * whole image, at any resolution. Each pixel's value (0-255) controls how much extra brightness to add at that
+ * location. For developers who need the exact calculation, the boost is
+ * `2^(min + (max - min) * (v / 255)^(1 / gamma))`, per color channel.
  *
  * The parameters are checked when they are set: a value that isn't finite (or an array of other than 1 or 3 of them)
  * throws, and the map keeps its value