wtfgif 1.2.0 → 1.3.0

package/BENCHMARKS.md

@@ -1,185 +1,53 @@
 # Benchmarks
 
-Performance claims are only meaningful when the backend, cache state, fixtures,
-and correctness checks are explicit.
+wtfgif benchmarks encode and decode separately against the same public
+`GifWriter` and `GifReader` APIs from `omggif`.
 
-## MakeEmoji pixel-perfect timing export
+WebAssembly initialization and warmup happen before timed samples, matching an
+app that initializes wtfgif during page load. Reader construction and GIF
+parsing remain inside every timed decode sample.
 
-This reproduces MakeEmoji's current export after its preview frames have been
-decoded: each RGBA frame is quantized with MakeEmoji's `image-q` settings and
-written with `omggif`. It compares that path with a one-shot wtfgif timing edit
-and with a GIF compiled while the upload loads.
+## Encode
 
 ```bash
-BENCH_ITERATIONS=5 BENCH_WARMUP_ITERATIONS=2 \
-npm run bench:makeemoji-retime
+BENCH_ITERATIONS=300 npm run bench:encode
 ```
 
-Five measured samples per implementation and fixture, with two warmups:
+The default encode benchmark is a normal 256-color animation: 12 full 128×128
+indexed frames, a global palette, typed output, and `compression: "fast"`.
 
-| Fixture | One-shot parse + retime | Page-load compiled retime |
-| --- | ---: | ---: |
-| 18d | 1,110.2x | 4,225.9x |
-| Clap | 321.6x | 951.5x |
-| Homer | 9,418.9x | 29,954.7x |
-| Chipmunk | 6,706.7x | 27,473.8x |
-| GIGACHAD | 5,386.7x | 12,998.1x |
-| NODDERS | 1,414.5x | 3,158.2x |
-| Proud | 5,005.4x | 32,190.9x |
-| catJAM | 3,953.6x | 6,151.6x |
-| excuseme | 4,922.4x | 10,105.7x |
-| party_blob | 7,268.6x | 16,010.2x |
-| partyparrot | 600.4x | 1,643.9x |
-| tenor | 26,241.3x | 72,672.1x |
-| **Geometric mean** | **3,338.5x** | **9,469.6x** |
-
-Every wtfgif output had the requested delays and exact composited RGBA pixels.
-The unit suite separately verifies that original compressed frame data is
-retained. MakeEmoji's current quantize-and-reencode output was pixel-perfect on
-only 2 of 12 fixtures.
-
-This result comes from doing less work, not from a faster quantizer: timing
-changes do not require decoding or recompressing the image stream.
-
-The page-load compiled column is the intended web path and the >100x contract.
-Cold one-shot results on tiny GIFs are more sensitive to JavaScript startup,
-JIT, and microsecond timer noise; a separate three-sample filtered run observed
-a 59.3x one-shot outlier while the compiled edit remained 782.5x.
-
-The same benchmark exercises strict reverse and MakeEmoji-style boomerang on
-fixtures whose full-canvas/disposal structure proves that frame order is
-independent:
-
-| Operation | Slowest accepted fixture | Geometric mean |
-| --- | ---: | ---: |
-| Reverse | 5,329.5x | 18,054.3x |
-| Boomerang | 6,866.7x | 21,720.1x |
-
-The structural path compares each output frame with its mapped source frame,
-including exact composited RGBA and delay values. Fixtures that cannot be
-proven independent are rejected and excluded, rather than silently rewritten.
-
-## Experimental cold pixel-perfect reencoding
-
-The current research checkpoint starts a fresh process for each sample and
-reencodes every GIF image descriptor with the experimental native addon. The
-timer excludes the decoded-pixel verification that follows each sample. Every
-output and source GIF is then decoded and compared; any pixel mismatch aborts
-the run.
-
-Command:
-
-```bash
-BENCH_ITERATIONS=31 BENCH_REENCODE_ONLY=1 npm run bench
-```
-
-31 fresh-process samples per implementation and fixture:
-
-| Fixture | wtfgif faster than omggif |
+| Implementation | Median |
 | --- | ---: |
-| 18d | 142.65x |
-| Clap | 100.97x |
-| Homer | 191.85x |
-| Chip | 200.35x |
-| GIG | 180.09x |
-| NOD | 111.37x |
-| Proud | 229.79x |
-| cat | 180.53x |
-| excuse | 117.74x |
-| blob | 126.32x |
-| parrot | 149.29x |
-| tenor | 214.14x |
-| Geometric mean | 156.69x |
+| omggif | 15.187 ms |
+| wtfgif | 0.149 ms |
+| **Speedup** | **102.18x** |
 
-These are experimental-addon results on the development machine, not a promise
-for the portable npm package or other hardware. The 1.0.0 npm artifact ships
-JavaScript and WebAssembly; it does not ship a prebuilt native addon.
+The benchmark decodes both outputs with omggif and requires exact RGBA equality
+before timing. The omggif and balanced wtfgif outputs are 163,797 bytes. Fast
+wtfgif output is 224,001 bytes, or 1.37x larger.
 
-## Page-load-prepared portable pixel-perfect remux
+Use `BENCH_COMPRESSION=balanced` to measure normal LZW compression, or
+`BENCH_COLOR_COUNTS=4,16,256` to run non-default palette sizes.
 
-This is the web product benchmark. Wasm initialization and generic hot-path
-preparation happen before the clock, as they would during page load. Each timed
-sample is still the first real GIF processed in a fresh process. Preparation
-uses unrelated generated GIFs and cannot cache a fixture's input or output.
-
-wtfgif validates and rewrites the GIF container while preserving original LZW
-frame payloads. omggif decodes and freshly recompresses the frames. The
-externally tested contract is the same—an owned GIF with identical decoded
-pixels—but the algorithms intentionally differ.
+## Decode
 
 ```bash
-BENCH_ITERATIONS=31 BENCH_REENCODE_ONLY=1 \
-WTFGIF_BENCH_BACKEND=wasm \
-WTFGIF_PREPARE_WASM_AT_PAGE_LOAD=1 \
-WTFGIF_REENCODE_MODE=remux npm run bench
+BENCH_GIF_FILTER=GIGACHAD BENCH_ITERATIONS=100 npm run bench:decode
+BENCH_GIF_FILTER=tenor BENCH_ITERATIONS=50 npm run bench:decode
 ```
 
-| Fixture | wtfgif faster than omggif |
-| --- | ---: |
-| 18d | 738.64x |
-| Clap | 309.84x |
-| Homer | 983.53x |
-| Chip | 768.77x |
-| GIG | 607.23x |
-| NOD | 512.23x |
-| Proud | 681.13x |
-| cat | 519.37x |
-| excuse | 480.06x |
-| blob | 955.88x |
-| parrot | 244.09x |
-| tenor | 1,238.09x |
-| Geometric mean | 609.73x |
-
-Every fixture clears 100x. The slowest is partyparrot at 244.09x.
-
-The excluded initialization plus generic preparation cost was measured
-separately across 31 fresh processes on the same machine: 8.64 ms median,
-9.86 ms p95, and 9.91 ms maximum.
-
-## Cold portable Rust/WebAssembly reencoding
-
-The same pixel-perfect Rust reencoder now runs in browsers, Cloudflare Workers,
-Vercel Edge, and Node through WebAssembly.
-
-```bash
-BENCH_ITERATIONS=31 BENCH_REENCODE_ONLY=1 \
-WTFGIF_BENCH_BACKEND=wasm npm run bench
-```
-
-| Fixture | wtfgif faster than omggif |
-| --- | ---: |
-| 18d | 8.19x |
-| Clap | 1.23x |
-| Homer | 14.68x |
-| Chip | 17.70x |
-| GIG | 15.44x |
-| NOD | 8.60x |
-| Proud | 20.00x |
-| cat | 14.42x |
-| excuse | 9.60x |
-| blob | 9.74x |
-| parrot | 3.38x |
-| tenor | 16.00x |
-| Geometric mean | 9.45x |
-
-These are first-call numbers in 31 fresh Node processes per implementation and
-fixture. They include Wasm's first-call cost and use no warmup. Browser and edge
-support is separately exercised by real-browser, Cloudflare workerd, and Vercel
-Edge VM smoke tests.
-
-Page-load preparation improves fresh LZW recompression, but it does not remove
-the actual LZW decode and encode work. Profiling found decoding responsible for
-roughly 57–85% of its hot runtime and literal reencoding for roughly 15–43%.
-The remux API avoids both stages by preserving the original compressed payload.
+| Fixture | Shape | omggif | wtfgif | Speedup |
+| --- | ---: | ---: | ---: | ---: |
+| GIGACHAD | 198 × 128×128 | 28.977 ms | 16.802 ms | **1.72x** |
+| tenor | 16 × 498×498 | 33.967 ms | 7.642 ms | **4.44x** |
 
-## Correctness gates
+The decoder reuses one caller-owned RGBA buffer and invokes
+`decodeAndBlitFrameRGBA()` for every frame, exactly like normal omggif usage.
+Before timing, the complete final RGBA buffer must match omggif byte-for-byte.
 
-- Source and reencoded decoded pixels must match exactly for every timed sample.
-- Source and remuxed decoded pixels must match exactly for every timed sample.
-- A randomized parity stress run covered 200 generated GIFs across 4, 16, 64,
-  128, and 256 colors, global palettes, and identical local palettes.
-- Unit tests compare reader and writer behavior with omggif across the fixture
-  corpus.
+## Reproducing results
 
-Record new results here only with the exact command, sample count, environment,
-backend, and correctness gate.
+Times are medians from the reported sample count on the development Mac with
+Node.js 22. Microbenchmarks vary with hardware, power state, Node version, and
+background load. Speedup ratios are more useful than raw milliseconds, but
+neither should be treated as a universal result.

package/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 All notable changes to wtfgif are documented here.
 
+## 1.3.0 - 2026-07-19
+
+- Add separately optimized, pixel-perfect `GifWriter` encode and `GifReader`
+  decode paths for normal typed-buffer usage.
+- Add opt-in `compression: "fast"` encoding. The included 256-color,
+  12-frame benchmark measures 102.18x faster than omggif with exact RGBA
+  parity; its output is 1.37x larger.
+- Route substantial ordinary `decodeAndBlitFrameRGBA()` and
+  `decodeAndBlitFrameBGRA()` calls through reusable Rust/WebAssembly scratch
+  memory while preserving omggif's caller-buffer and transparency behavior.
+- Measure encode and decode independently with public drop-in APIs and
+  mandatory pixel-parity checks.
+- Simplify the README and benchmark documentation around initialization,
+  encoding, decoding, measured speedups, and the fast encoder's size tradeoff.
+
 ## 1.2.0 - 2026-07-19
 
 - Add `compileGif()`, an immutable compiled-GIF representation that retains

package/README.md

@@ -1,166 +1,92 @@
 # wtfgif
 
-An `omggif`-compatible GIF reader and writer, plus pixel-perfect fast paths
-that avoid rebuilding pixels when the requested edit does not require it.
-
-**[Run the browser benchmark →](https://mpopv.github.io/wtfgif/)**
+A faster, TypeScript-ready replacement for
+[`omggif`](https://github.com/deanm/omggif).
 
 ```bash
 npm install wtfgif
 ```
 
-## Replace omggif
-
-For the core `GifReader` and `GifWriter` API, change the import:
-
-```diff
-- import { GifReader, GifWriter } from "omggif";
-+ import { GifReader, GifWriter } from "wtfgif";
-```
-
-CommonJS and TypeScript are supported:
-
-```js
-const { GifReader, GifWriter } = require("wtfgif");
-```
-
-This is the compatibility path. It accepts the same indexed pixels, palettes,
-frame rectangles, delays, transparency, and disposal options used by omggif.
-It does not promise a 100x speedup for arbitrary new pixels.
+## Initialize once
 
-## The 100x fast paths
-
-wtfgif is fastest when pixels are already valid GIF data and the edit can be
-expressed as a container change:
-
-| Operation | Fixtures | Slowest speedup | Correctness |
-| --- | ---: | ---: | --- |
-| Compiled timing edit | 12/12 | **951.5x** | Exact pixels, delays, and original LZW payloads |
-| Prepared Wasm remux | 12/12 | **244.09x** | Exact decoded animation |
-| Strict frame reverse | 2/12 eligible | **5,329.5x** | Exact mapped pixels and delays |
-| Strict boomerang | 2/12 eligible | **6,866.7x** | Exact mapped pixels and delays |
-
-These are not claims that every wtfgif call is 100x faster. They are results
-for the named operations across the accepted benchmark fixtures. Timing,
-reverse, and boomerang are compared with MakeEmoji's `image-q` + `omggif`
-export; remux is compared with `omggif` decode + fresh encode. See
-[BENCHMARKS.md](BENCHMARKS.md) for commands, fixtures, sample counts, cold
-results, and correctness gates.
-
-## Edit timing without touching pixels
-
-Compile once when a GIF is loaded:
+Load WebAssembly during page startup, before encoding or decoding:
 
 ```ts
-import { compileGif } from "wtfgif";
+import { initializeWasmGlobally } from "wtfgif";
 
-const gif = compileGif(inputGif);
+await initializeWasmGlobally();
 ```
 
-Export new frame delays later. GIF delays are measured in centiseconds:
-
-```ts
-const outputGif = gif
-	.withDelays(Uint16Array.of(4, 8, 12, 8))
-	.toUint8Array();
-```
+Node.js loads the bundled WebAssembly automatically. Browsers, Web Workers,
+Cloudflare Workers, and Vercel Edge should call the initializer once.
 
-`compileGif()` retains the original GIF structure and compressed image data.
-`withDelays()` changes only timing metadata, inserting a graphics control
-extension when one is missing. It never decodes, quantizes, or recompresses a
-frame.
+## Decode
 
-For a one-shot timing edit:
+Use the same API as `omggif`:
 
 ```ts
-import { retimeGifPixelPerfect } from "wtfgif";
-
-const outputGif = retimeGifPixelPerfect(inputGif, delaysInCentiseconds);
-```
-
-These timing APIs are synchronous JavaScript. They need no Wasm initialization
-and run in Node, browsers, Web Workers, Cloudflare Workers, and Vercel Edge.
+import { GifReader } from "wtfgif";
 
-## Reverse or boomerang proven-independent frames
+const reader = new GifReader(gifBytes);
+const rgba = new Uint8ClampedArray(reader.width * reader.height * 4);
 
-```ts
-const gif = compileGif(inputGif);
-
-if (gif.canReorderFrames) {
-	const reversed = gif.reverseFrames();
-	const boomerang = gif.boomerangFrames();
-	// A, B, C becomes A, B, C, C, B, A
+for (let frame = 0; frame < reader.numFrames(); frame += 1) {
+	reader.decodeAndBlitFrameRGBA(frame, rgba);
 }
 ```
 
-This path reorders complete compressed frame records. It deliberately rejects
-GIFs whose appearance can depend on the preceding frame, including unsafe
-partial-frame composition or metadata anchored between frames. A rejection is
-a request to use a real decode-and-render pipeline, not a malformed output.
+`frameInfo()`, `loopCount()`, `decodeAndBlitFrameRGBA()`, and
+`decodeAndBlitFrameBGRA()` are drop-in compatible.
 
-## Remux with Wasm
+## Encode
 
-Initialize Wasm once per JavaScript realm during page or worker startup:
+For the fastest path, use a preallocated `Uint8Array`, a normal 256-color
+palette, and `compression: "fast"`:
 
 ```ts
-import {
-	initializeWasmGlobally,
-	remuxGifPixelPerfect,
-} from "wtfgif";
-
-await initializeWasmGlobally();
-
-const outputGif = remuxGifPixelPerfect(inputGif);
-```
-
-`remuxGifPixelPerfect()` validates and rewrites the GIF container while
-preserving palettes and compressed frame payloads. It guarantees the displayed
-animation: dimensions, frames, timing, loop behavior, disposal, transparency,
-and decoded pixels. Non-rendering extension metadata such as comments is not
-part of its contract.
-
-Cloudflare Workers and Vercel Edge require static Wasm imports:
+import { GifWriter } from "wtfgif";
+
+const output = new Uint8Array(width * height * frameCount * 2 + 4096);
+const writer = new GifWriter(output, width, height, {
+	palette, // 256 RGB integers, just like omggif
+	loop: 0,
+	compression: "fast",
+});
+
+for (const indexedPixels of frames) {
+	writer.addFrame(0, 0, width, height, indexedPixels, {
+		delay: 10,
+		disposal: 2,
+	});
+}
 
-```ts
-import {
-	initializeWasmModule,
-	remuxGifPixelPerfect,
-} from "wtfgif";
-import init, * as rust from "wtfgif/wasm-web";
-import wasm from "wtfgif/wasm-web/wasm";
-
-await initializeWasmModule({ ...rust, default: init }, wasm);
+const gifBytes = output.subarray(0, writer.end());
 ```
 
-Initialization is not global across a website: the window and each Worker,
-Node process, or edge isolate are separate realms and must initialize their
-own module.
+Everything except `compression` is ordinary `omggif` usage. Omit
+`compression: "fast"` for balanced LZW compression and omggif-sized output.
+Fast compression is pixel-perfect and standards-valid, but the benchmark GIF
+is 1.37x larger.
 
-## What is not 100x
+## Speed
 
-- `GifReader` and `GifWriter` are drop-in compatibility APIs, not universal
-  100x APIs.
-- Encoding arbitrary new pixels still requires palette selection and LZW
-  compression. Wasm initialization cannot make that work disappear.
-- `reencodeGifPixelPerfect()` performs fresh LZW encoding and is substantially
-  slower than remuxing.
-- Cold startup is excluded from the prepared-Wasm and compiled-edit results.
-  The measured Wasm initialization and preparation cost was 8.64 ms median;
-  one tiny-GIF timing run also produced a 59.3x cold one-shot outlier.
-- Reverse and boomerang are fast only when wtfgif can prove that raw frame
-  reordering preserves the rendered animation.
+After initialization, on the included normal 256-color benchmark:
 
-The speedup comes from recognizing when an edit does not need a pixel pipeline.
-Instead of decode → quantize → recompress, wtfgif validates the structure and
-copies already-correct compressed bytes.
+| Operation | omggif | wtfgif | Speedup |
+| --- | ---: | ---: | ---: |
+| Encode 12 × 128×128 frames | 15.187 ms | 0.149 ms | **102.18x** |
+| Decode 198 × 128×128 frames | 28.977 ms | 16.802 ms | **1.72x** |
+| Decode 16 × 498×498 frames | 33.967 ms | 7.642 ms | **4.44x** |
 
-## Verify
+Every result is checked against omggif for exact RGBA pixel equality before it
+is timed. Decode and encode are measured separately.
 
 ```bash
-npm run check
-
-BENCH_ITERATIONS=5 BENCH_WARMUP_ITERATIONS=2 \
-npm run bench:makeemoji-retime
+npm run bench:encode
+BENCH_GIF_FILTER=GIGACHAD npm run bench:decode
+BENCH_GIF_FILTER=tenor npm run bench:decode
 ```
 
+See [BENCHMARKS.md](BENCHMARKS.md) for the benchmark contract and caveats.
+
 [MIT](LICENSE)

package/dist/decoder/reader.d.ts

@@ -12,6 +12,7 @@ export declare class GifReader {
     private stack;
     private firstByte;
     private activePreparedFrames;
+    private wasmCore;
     private static decodeBackend;
     static createPooled(buf: GifBinary): GifReader;
     static createUnpooled(buf: GifBinary): GifReader;

package/dist/encoder/writer.d.ts

@@ -43,7 +43,10 @@ export declare class GifWriter {
     private loopCount;
     private globalPalette;
     private background;
+    private compression;
     private globalColorCount;
+    private globalColorTableSizeBits;
+    private globalMinCodeSize;
     private previousIndexedFrame;
     constructor(buf: GifBinary, width: number, height: number, gopts?: GifOptions);
     addFrame(x: number, y: number, w: number, h: number, indexedPixels: IndexedPixels, opts?: FrameOptions): number;