perf(vendor): let the browser decompress x2t.wasm

[chaxus]

What

The x2t module ships brotli-compressed as x2t.wasm.br, and every host declares Content-Encoding: br for it. The browser decodes it at the network layer, so instantiateStreaming compiles the module straight off the response and nothing in our code decompresses anything.

	before	after
on the wire	9,483,006 B (zopfli gzip)	6,898,179 B (brotli -q 11)
decompressed by	DecompressionStream('gzip') in JS	the browser, at the network layer
loader	fetch → sniff magic bytes → rebuild stream → inflate → instantiate	fetch → instantiate

2.58 MB off the largest single download in the app, and ~100 lines gone from the two loaders that had to stay in step with each other (x2t_helper.js and packages/converter): sniffAndRebuild in both, the gzip branch of prepareWasmBinary in both, and the DecompressionStream capability check.

Idea taken from a third-party local-first Office site (see #219), verified against their production deployment before starting.

The part that took the time

wrangler pages dev — what e2e-pages runs — re-compresses responses and overwrites Content-Encoding with its own result. A pre-encoded asset then arrives double-encoded, and no browser API can decode brotli to recover. The suite went red on ran: false; x2t never instantiated.

name              Accept-Encoding   response
x2t.wasm          br                Content-Encoding: br,   body = br(br(wasm))
x2t.wasm          (none)            Content-Encoding: br,   body = br(br(wasm))
x2t.wasm          identity          no Content-Encoding,    body = br(wasm)      <- ours dropped, not merged
x2t.wasm.br + CT  br                Content-Encoding: gzip, body = gzip(br(wasm))
x2t-probe.bin     br                Content-Encoding: br,   body = br(wasm)      ✓

--compatibility-flags brotli_content_encoding makes no difference. What wrangler does respect is its own compressibility rule: it leaves application/octet-stream alone, and that is what an unrecognised extension gets.

So two things are load-bearing and neither looks it: the .br extension, and the absence of a Content-Type rule for that path in _headers. Adding Content-Type: application/wasm there is enough to make wrangler compress it again (row 4 — that is how this was first written). Both are documented in _headers next to the rule. The loader labels the response application/wasm itself, so nothing depends on the host typing it.

Verified

environment	how	result
vite preview (test:e2e)	vite.config.ts middleware	full 160-spec suite green
wrangler pages dev (e2e-pages)	public/_headers	green after the rename
static-web-server (e2e-docker)	sws.toml twin rule	passes through untouched, header preserved
real Cloudflare Pages	public/_headers	preview-smoke on this PR

What stays

The instantiateWasm hook — no longer decompressing, but still carrying the fetch retry (the CF 500 of 2026-08-20) and the two-way failure reporting the open-failure guard needs. The buffered fallback stays too, now four lines.

After a vendor upgrade

brotli -q 11 -c x2t.wasm > x2t.wasm.br

vendor-contract pins the sha256 of the decompressed module (unchanged by this migration — 7db02f5c…, which is how we know the recompression is lossless) and bounds the compressed size.

Reverse validation (convention 5): removing the Content-Encoding line from _headers turns the new hosting-contract case red.

🤖 Generated with Claude Code

https://claude.ai/code/session_01MKNHFQ1kek1cHeqhbH37Pk

[cloudflare-workers-and-pages]

Deploying document with    Cloudflare Pages

Latest commit:	757a129
Status:	✅  Deploy successful!
Preview URL:	https://15888a8c.document-7hm.pages.dev
Branch Preview URL:	https://perf-wasm-content-encoding.document-7hm.pages.dev

View logs