feat(runtime): HTMLRewriter (lol-html binding)

[colinhacks]

Adds a Cloudflare-Workers-shape HTMLRewriter global, backed by a WebAssembly build of lol-html (Cloudflare's own streaming HTML rewriter). Code written against the Workers — or Bun — HTMLRewriter API ports over unchanged, including async handlers.

const res = new HTMLRewriter()
  .on("a[href]", {
    async element(el) {
      if (!(await isAllowed(el.getAttribute("href")))) el.remove();
    },
  })
  .transform(await fetch("https://example.com"));

Architecture — WASM + Asyncify (one engine, all platforms)

The engine is lol-html compiled to WebAssembly with Binaryen's Asyncify pass, vendored prebuilt under runtime/html-rewriter-engine/ (the BSD-3 html-rewriter-wasm build — html_rewriter.js + asyncify.js + a 908KB html_rewriter_bg.wasm, with the upstream license retained). Asyncify is what enables full async-handler support: when a handler returns a Promise, the WASM stack is unwound, the Promise awaited, then the stack rewound and the transform continues — the same mechanism Cloudflare and Bun use.

Chosen over a native napi binding (the earlier revision of this PR) because:

• One portable .wasm for every platform — no per-platform native prebuilds, no 8-platform cross-build concern for this feature.
• Async handlers work on stock Node — a native binding can't await a Promise from inside lol-html's synchronous callback without owning the event loop (workerd uses kj fibers, Bun its own loop); Asyncify solves it in pure WASM.
• The native path's entire unsafe + re-entrancy-guard surface is gone.

Path decision: vendor CF's proven prebuilt build rather than build our own lol-html→WASM+Asyncify (which needs a patched wasm-pack fork + a specific binaryen). The prebuilt artifact is proven, BSD-3, and maintainable.

API

• new HTMLRewriter().on(selector, handlers).onDocument(handlers).transform(response), fluent + chainable, Cloudflare-exact transform(Response) → Response. A non-Response input throws a TypeError.
• Element/Text/Comment/Doctype/EndTag/DocumentEnd surface (getAttribute/setAttribute/before/after/prepend/append/replace/remove/removeAndKeepContent/setInnerContent/onEndTag, text get/set, etc.). Insertion is text-escaped by default; { html: true } inserts raw HTML.
• Handlers may be sync or async — a Promise return is awaited mid-transform.
• Installed as a lazy, non-enumerable globalThis.HTMLRewriter from the preload (feature-detected, bows out if a native global exists). Absent under --node / NODE_COMPAT (compat mode skips preload injection). Engine + .wasm load lazily on first transform.
• Invalid selectors throw at .on(). The output stream's cancel frees the engine + releases the source reader (no leak on early abort).

No companion npm package

HTMLRewriter is a standard API injected as the built-in global — zero lock-in without a separate package, and non-nub users already have packages like html-rewriter-wasm. Built-in global only.

Verification (local, macOS arm64)

• cargo clippy --all-targets --all-features -- -D warnings, cargo fmt --check — clean.
• cargo test -p nub-core --lib (feature-matrix invariants) — 285 pass.
• cargo test -p nub-cli --test html_rewriter — 3 pass (full API surface, async handlers awaited mid-transform, streaming + header carry-over, non-Response throw, invalid-selector throw, --node/NODE_COMPAT absence), through the real nub binary.
• e2e: sync rewrite, async handler (element + document-end) awaited mid-transform, streaming, and output-stream cancel — all verified.
• nub-native builds + clippy-clean without lol_html.

Refs html-rewriter

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
nub	Ready	Preview, Comment	Jun 24, 2026 5:33am

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[pullfrog]

Important

The rewritable-unit mutator methods are typed as chainable (returning the unit) but the native binding returns undefined, so chained calls throw at runtime — which contradicts the PR's "ports over unchanged" claim.

Reviewed changes — initial review of a Cloudflare-Workers-shape HTMLRewriter global backed by a first-party napi-rs binding to lol-html 3.0.0 in the nub-native addon.

• Native lol-html binding — crates/nub-native/src/html_rewriter.rs exposes a low-level HtmlRewriterEngine plus JS-facing Element/EndTag/TextChunk/Comment/Doctype/DocumentEnd wrappers, using the lol-html-js-api lifetime-erasure pattern (NativeRefWrap + poison-on-drop Anchor) over synchronous single-threaded dispatch.
• Fluent JS wrapper — runtime/html-rewriter.mjs layers the chainable .on()/.onDocument()/.transform() surface on top, with transform(Response) streaming via ReadableStream and a transform(string) eager convenience form; the engine is resolved lazily + memoized.
• Preload wiring — preload.cjs installs a non-enumerable lazy getter (fast tier + worker threads) and preload.mjs installs eagerly threading the floor createRequire (compat tier), mirroring the Worker lazy-global precedent.
• Types + docs + tests — ambient HTMLRewriter declarations in npm/nub-types/index.d.ts, a feature_matrix.rs entry, a docs page, and an integration test driving two fixtures through the built nub binary (full surface, --node/NODE_COMPAT absence).

The lifetime-erasure + poison-cell soundness argument holds (synchronous, single-threaded dispatch; the anchor poisons on return), the tier split is correct, and the additive contract (non-enumerable, feature-detected, absent under compat mode) is covered by tests. The one substantive issue is the typed-but-not-implemented chaining; the rest are minor.

  ^{｜ Fix all ➔ ｜ Fix 👍s ➔ ｜ View workflow run ｜ Using Claude Opus ｜ 𝕏}

[pullfrog]

ℹ️ No new issues in the engine, stream, or type changes — one garbled comment in the new test fixture.

Reviewed changes — the incremental delta since the prior pullfrog review (d672914): a per-instance re-entrancy guard on the native engine, a stream-cancel path on transform, and the removal of the transform(string) ergonomic to match Cloudflare exactly.

• Re-entrancy guard on HtmlRewriterEngine — added an active flag + ActiveGuard RAII + enter(), acquired by write/end, so a handler that re-enters the same instance throws cleanly instead of aliasing &mut into lol-html. Cross-instance re-entrancy stays allowed; covered by the new reentrancy.mjs fixture and integration test.
• Stream cancel on transform — the output ReadableStream now cancels and releases the source reader and drops the engine on consumer abort, with engine/reader hoisted to outer scope and nulled in the start finally, preventing a source-body-lock and engine leak.
• CF-exact transform — dropped the transform(string) Bun-style form; transform now accepts only a Response and throws a TypeError otherwise. The .d.ts overload, the "Rewriting a string" docs section, and the concatChunks helper were removed, and rewrite.mjs was rewritten to wrap strings in a Response.

The guard's RAII clear-on-unwind is correct, the cancel path is sound, and the API narrowing is consistent across the binding, .d.ts, docs, and fixtures.

  ^{｜ Fix all ➔ ｜ Fix 👍s ➔ ｜ View workflow run ｜ Using Claude Opus ｜ 𝕏}

[pullfrog]

ℹ️ No critical issues — the WASM pivot is clean and the prior .d.ts threads are genuinely resolved by it. One stale doc-comment in the touched test file.

Reviewed changes — the incremental delta since the prior pullfrog review (33b3240): commit 28a05d4 replaces the native napi lol-html binding with a vendored prebuilt WASM build of lol-html (Binaryen Asyncify), adding full async-handler support.

• Pivoted the engine to WASM + Asyncify — vendored the BSD-3 html-rewriter-wasm dist (html_rewriter.js, asyncify.js, ~908KB html_rewriter_bg.wasm, LICENSE) under runtime/html-rewriter-engine/, deleting the 847-line native binding and the lol_html dependency.
• Added async-handler support — the wrapper's write()/end() are now awaited; a handler returning a Promise is awaited mid-transform via Asyncify stack unwind/rewind, dropping the old sync-only guard and throw-on-Promise path.
• Rewrote runtime/html-rewriter.mjs as a thin fluent wrapper over the WASM engine — lazy memoized engine resolution, eager selector validation via a freed probe engine, a streaming transform with a cancel path freeing the engine and releasing the source reader.
• Resolved the prior chaining + iterator threads structurally — the vendored engine's element mutators all return this and get attributes() returns a real iterator, so the chainable .d.ts types and the IterableIterator<[string, string]> declaration now match runtime.
• Updated the surrounding surface — ambient types (handlers return void | Promise<void>), the docs page (async supported, WASM mechanism), the feature_matrix row, and the integration test (now asserts async handlers are awaited mid-transform).

The pivot is internally consistent — chaining, the iterator shape, the streaming/cancel lifecycle, and the lazy non-enumerable global install all check out against the vendored engine, and the BSD-3 license is retained.

One prior thread remains open and was not addressed by 28a05d4: the garbled runtime/preload.mjs comment (…the createRequire in before installing, missing a verb). It is left open rather than re-raised here.

  ^{｜ Fix all ➔ ｜ Fix 👍s ➔ ｜ View workflow run ｜ Using Claude Opus ｜ 𝕏}

[pullfrog]

✅ No new issues found.

Reviewed changes — the incremental delta since the prior pullfrog review (28a05d4): commit bfee36b fixes two engine-leak paths sharing one root cause — a rejected or cancelled-mid-suspend async handler left the suspended Rust frame holding its wasm-bindgen borrow, so engine.free() threw and the WASM engine leaked.

• Patched the Asyncify wrap() to rewind on rejection — runtime/html-rewriter-engine/asyncify.js now also start_rewinds when the handler promise rejects (so the suspended frame returns and drops its borrow), swallows the secondary error the re-run re-throws, settles a possible re-suspend, then re-throws the ORIGINAL rejection. Marked NUB PATCH in-file with provenance in the engine LICENSE for re-vendoring.
• Made consumer cancel resolve cleanly mid-suspend — runtime/html-rewriter.mjs adds a cancelled flag and a non-throwing safeFree(); on a cancel during an in-flight async handler the held borrow is tolerated and the engine is freed when the suspended write resumes via start()'s finally{cleanup()}. The read loop, enqueue, end(), and controller.error are all cancelled-gated so nothing touches a torn-down stream.
• Added three regression fixtures + tests — async-reject.mjs (original error propagates + a fresh transform recovers), cancel.mjs (plain and cancel-mid-suspend both resolve), and leak-loop.mjs (RSS stays bounded over 3000 rejecting/cancelled cycles).
• Refreshed the stale test-file module doc — crates/nub-cli/tests/html_rewriter.rs header now names the vendored WASM engine and drops the make addon / nub-native.node prerequisite (the prior review thread, now resolved).

The reject-rewind logic is sound: the original handler error always wins (the swallowed re-throw and re-suspend handling are correctly gated on rejected !== null), and safeFree()'s retry-on-resume frees the engine on every reject/cancel path with no leak and no hang. The cancelled-gating is consistent across the source-read loop, sink, terminate, and error paths.

  ^{｜ View workflow run ｜ Using Claude Opus ｜ 𝕏}

[pullfrog]

✅ No new issues found.

Reviewed changes — the incremental delta since the prior pullfrog review (bfee36b): commit 4a19550 fixes a residual engine leak the previous cancel fix introduced — on a consumer cancel mid-suspend, calling free() from cancel() swallowed the held-borrow throw but left a wrapper whose pointer was already zeroed, orphaning a live Rust object.

• Removed safeFree() from the stream cancel() path — runtime/html-rewriter.mjs now defers ALL engine freeing to start()'s finally{cleanup()}. wasm-bindgen's __destroy_into_raw() zeroes the wrapper ptr before the throwing wasm free, so a free() from cancel() mid-suspend left a truthy engine with ptr=0; the later cleanup() then freed a null pointer (no-op) and the live Rust object leaked (~20KB each, OOB crash by ~1000 cycles). Freeing only after the suspended write resumes and the borrow releases frees exactly once.
• Rewrote the leak fixture into a pure cancel-mid-suspend reclamation loop — tests/fixtures/html-rewriter/leak-loop.mjs now warms up 300 cycles, then asserts RSS stays flat (< 20MB delta) over a 2000-cycle measure window and that the loop reaches its markers without an OOB crash.
• Updated the integration test — crates/nub-cli/tests/html_rewriter.rs renames the test to cancel_mid_suspend_reclaims_the_engine and asserts the new CANCEL_MIDSUSPEND_NO_CRASH / CANCEL_MIDSUSPEND_FLAT markers.

Traced sound against the vendored engine: html_rewriter.js:573-583 confirms __destroy_into_raw sets ptr=0 before the throwing wasm.__wbg_*_free, so the double-free orphan the fix avoids is real. The cancel-without-in-flight-handler path remains correct (the cancelled reader resolves done, the read loop breaks, and finally{cleanup()} frees the still-referenced engine).

  ^{｜ View workflow run ｜ Using Claude Opus ｜ 𝕏}