Stream HTML into element or ShadowRoot by noamr · Pull Request #12758 · whatwg/html

noamr · 2026-08-04T19:09:46Z

Add streaming HTML insertion methods to Element, ShadowRoot, and ChildNode

Introduce safe and unsafe streaming HTML parsing and insertion methods:

Element & ShadowRoot: streamHTML(), streamHTMLUnsafe(), streamAppendHTML(), streamAppendHTMLUnsafe(), streamPrependHTML(), and streamPrependHTMLUnsafe()
ChildNode: streamBeforeHTML(), streamBeforeHTMLUnsafe(), streamAfterHTML(), streamAfterHTMLUnsafe(), streamReplaceWithHTML(), and streamReplaceWithHTMLUnsafe()
This allows developers to parse and stream HTML directly into specific positions of the DOM tree using WritableStream.

The HTML fragment parser is divided into two:

Preparing the fragment parser (create an inert document with a proper element stack)
Using that parser to parse into a DocumentFragment

The preparation algorithm is used when streaming, by creating a new fragment parser, and then the stream is routed to feed that parser.

When parsing, the "insertion target redirection map" is configured to reroute insertions intended for the root to go directly into the stream's target element, instead of going into the DocumentFragment.

A special sanitizer mitigation is in place to avoid these removed elements from incurring side effects, by creating them in an inert document if they are about to be removed.

"Scripting mode" has been refactored so that the streaming fragment parser can execute scripts. Instead of relying on the fragment/inert/normal scripting mode, the parser receives a "target document" which is assigned to the script as an "intended document" and checked at preparation time. It is set to the dummy inert document for inert fragment parsing, and to the context document when runScripts is true.

The "fragment case" variants of the parser now check the parser's context element explicitly, rather than relying on
an implicit "this was created by the HTML fragment parser".

Closes #2142

At least two implementers are interested (and none opposed):
- Chrome
- Gecko (HTML streaming & revamped DOM parsing mozilla/standards-positions#1370)
Tests are written and can be reviewed and commented upon at:
- Un-tentative streamHTML tests web-platform-tests/wpt#61748
Implementation bugs are filed:
- Chromium: Implemented
- WebKit: https://bugs.webkit.org/show_bug.cgi?id=315741
- Gecko: https://bugzilla.mozilla.org/show_bug.cgi?id=2043150
Corresponding HTML AAM & ARIA in HTML issues & PRs: N/A
MDN issue is filed: Will be done as part of Blink shipping
The top of this comment includes a [clear commit message

(https://github.com/whatwg/meta/blob/main/COMMITTING.md) to use.

(See WHATWG Working Mode: Changes for more details.)

💥 Error: Wattsi server error 💥

PR Preview failed to build. (Last tried on Aug 28, 2026, 2:28 PM UTC).

More

PR Preview relies on a number of web services to run. There seems to be an issue with the following one:

🚨 Wattsi Server - Wattsi Server is the web service used to build the WHATWG HTML spec.

🔗 Related URL

Error output:

      <!DOCTYPE html>
      <html>
      <head>
          <meta name="viewport" content="width=device-width, initial-scale=1">
          <meta name="robots" content="noindex">
          <style>body,html{height:100%;margin:0}body{display:flex;align-items:center;justify-content:center;flex-direction:column;-webkit-font-smoothing:antialiased;text-rendering:optimizeLegibility}p{text-align:center;font-family:-apple-system,BlinkMacSystemFont,Segoe UI,Roboto,Oxygen,Ubuntu,Cantarell,Fira Sans,Droid Sans,Helvetica Neue,sans-serif;color:#000;font-size:14px;margin-top:-50px}p.code{font-size:24px;font-weight:500;border-bottom:1px solid #e0e1e2;padding:0 20px 15px}p.text{margin:0}a,a:visited{color:#aaa}</style>
      </head>
      <body>
      <p class="code">
        Error code: 503      </p>
      <p class="text">
        Well, This is unexpected. An Error has occurred, and we are working to fix the problem! We will be up and running shortly. Try refreshing the page or try again in a few minutes.
      </p>
        <div style="display:none;">
          <h1>
    upstream_reset_before_response_started{connection_termination} (503 UC)      </h1>
          <p data-translate="connection_timed_out">App Platform failed to forward this request to the application.</p>
      </div>
      </body>
      </html>

This seems to be an issue with the Wattsi Server service. PR Preview doesn't manage this service and so has no control over it. If you've identified an issue with it, you can report the issue to the maintainers of Wattsi Server directly. Please be courteous. Thank you!

If you don't have enough information above to solve the error by yourself or if the issue doesn't seem related to Wattsi Server, you can file an issue with PR Preview.

See whatwg/html#12758 Note that tests that assert how this works with <template for> are still tentative as that PR is still not landed.

zcorpan

LGTM % spaces

… context element

… script

…ext in fragment parser initialization

…ote on parser context element

… allows attribute

noamr mentioned this pull request Aug 5, 2026

Un-tentative streamHTML tests web-platform-tests/wpt#61748

Open

noamr changed the title ~~Add streaming HTML insertion methods~~ Streaming HTML insertion methods Aug 5, 2026

noamr changed the title ~~Streaming HTML insertion methods~~ Stream HTML into element or ShadowRoot Aug 5, 2026

noamr force-pushed the noamr/stream-html branch from df24ea2 to e416732 Compare August 5, 2026 09:32

noamr closed this Aug 5, 2026

noamr reopened this Aug 5, 2026

zcorpan mentioned this pull request Aug 5, 2026

Integrate fragment parser options with trusted types #12583

Open

5 tasks

noamr force-pushed the noamr/stream-html branch from e416732 to 5106e9d Compare August 6, 2026 16:23

noamr force-pushed the noamr/stream-html branch from deb55bb to e97c374 Compare August 6, 2026 19:46

noamr force-pushed the noamr/stream-html branch from d5a18a7 to b19b385 Compare August 7, 2026 20:17

zcorpan reviewed Aug 11, 2026

View reviewed changes

Comment thread source

Comment thread source Outdated

Comment thread source Outdated

Comment thread source Outdated

noamr force-pushed the noamr/stream-html branch from d87ab8d to 4880d38 Compare August 11, 2026 15:49

noamr force-pushed the noamr/stream-html branch from 2de75ec to ce9f49b Compare August 11, 2026 20:18

noamr added a commit to web-platform-tests/wpt that referenced this pull request Aug 12, 2026

Un-tentative streamHTML tests

5478eb6

See whatwg/html#12758 Note that tests that assert how this works with <template for> are still tentative as that PR is still not landed.

zcorpan approved these changes Aug 12, 2026

View reviewed changes

Comment thread source Outdated

Comment thread source Outdated

noamr force-pushed the noamr/stream-html branch from 421aa3f to 043dcdf Compare August 12, 2026 13:02

noamr force-pushed the noamr/stream-html branch from 043dcdf to 286c499 Compare August 12, 2026 13:25

noamr force-pushed the noamr/stream-html branch from 286c499 to 146266b Compare August 12, 2026 16:08

zcorpan mentioned this pull request Aug 14, 2026

Sanitize while parsing #12756

Open

5 tasks

noamr force-pushed the noamr/stream-html branch from 146266b to 6e5c251 Compare August 14, 2026 08:56

noamr closed this Aug 14, 2026

noamr reopened this Aug 14, 2026

noamr force-pushed the noamr/stream-html branch from 8376fee to 82e9336 Compare August 28, 2026 12:34

noamr force-pushed the noamr/stream-html branch 3 times, most recently from 8b318d5 to 2a95737 Compare August 28, 2026 14:27

noamr force-pushed the noamr/stream-html branch from 2a95737 to 67cae0b Compare September 1, 2026 15:11

noamr force-pushed the noamr/stream-html branch 2 times, most recently from b3835c2 to a7f0a86 Compare September 1, 2026 17:07

noamr force-pushed the noamr/stream-html branch from a7f0a86 to 9b016ad Compare September 1, 2026 20:38

noamr force-pushed the noamr/stream-html branch from 9b016ad to b61ef7d Compare September 1, 2026 20:44

noamr force-pushed the noamr/stream-html branch from b61ef7d to 8ae6011 Compare September 2, 2026 10:26

noamr force-pushed the noamr/stream-html branch from 8ae6011 to f4db75c Compare September 2, 2026 14:58

tunetheweb mentioned this pull request Sep 4, 2026

Add HTML setters features web-platform-dx/web-features#4318

Open

zcorpan approved these changes Sep 4, 2026

View reviewed changes

noamr added 9 commits September 4, 2026 16:56

HTML streaming methods and editorial review cleanup

cd7ab03

Editorial and stylistic fixes for HTML streaming methods and fragment…

99675ad

… context element

stream HTML: throw NotSupportedError when safe is true and context is…

c487961

… script

Editorial: wrap streaming method dfns and assert safe non-script cont…

eded23d

…ext in fragment parser initialization

specfmt

b09c414

Editorial: Refine streaming domintros, fix stray character, and add n…

7da75db

…ote on parser context element

Refine note about defer scripts

acff8c6

Refine the context element algo

1c42ad1

Remove stale remove javascript navigation URLs arguments to sanitizer…

92af766

… allows attribute

Navigation Menu

Uh oh!

Stream HTML into element or ShadowRoot - #12758

Stream HTML into element or ShadowRoot#12758
noamr wants to merge 9 commits into
noamr/streaming-sanitizerfrom
noamr/stream-html

noamr commented Aug 4, 2026 •

edited by pr-preview Bot

Loading

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

zcorpan left a comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

noamr commented Aug 4, 2026 • edited by pr-preview Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

💥 Error: Wattsi server error 💥

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

zcorpan left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Milestone

Development

Uh oh!

2 participants

noamr commented Aug 4, 2026 •

edited by pr-preview Bot

Loading