Declarative shadow DOM: <template shadowrootmode> is parsed as an inert template, nothing inside renders

[luis-serrano-l]

Version: blitz-dom / blitz-html 0.3.0-beta.2 (crates.io), rendered headless through HtmlDocument::from_html + blitz_paint::paint_scene with anyrender_vello_cpu.

<template shadowrootmode="open"> is parsed as an inert template (html_sink.rs: get_template_contents has a // TODO: implement templates properly), so a page that relies on declarative shadow DOM renders nothing from the template and shows its light-DOM children unslotted.

Repro

<!doctype html>
<body>
  <template shadowrootmode="open">
    <h1>Shadow heading</h1>
    <slot name="a"><p>placeholder for a</p></slot>
  </template>
  <div slot="a">Slotted content</div>
</body>

Expected (Chrome 111+, Firefox 123+, Safari 16.4+): <body> gets an open shadow root; "Shadow heading" renders, and "Slotted content" renders in place of the placeholder.

Actual: nothing from the template is rendered. query_selector("h1") finds no node with a layout box; "Slotted content" renders as an ordinary block.

Context

I hit this using Blitz as the render engine for a zero-JS server-side component library's test suite, where out-of-order streaming ships the page inside a DSD root on <body> and appends <div slot=…> chunks later in the byte stream. Every other page in that suite renders fine through Blitz.

#889 / #892 add shadow trees and slots but explicitly leave the declarative parser path out ("Not in this PR"). This issue is to track that remaining piece: html5ever's TreeSink::get_template_contents + the shadowrootmode attribute attaching a shadow root to the template's parent, with the template's children moved into it.

[yinnho]

We hit this same gap in our html5ever-based engine and shipped the parse-side fix today — a few implementation notes, since the machinery you need is already in the html5ever version you're on.

Blitz pins html5ever 0.39.0, and 0.39's tree builder carries the complete declarative-shadow arm: on a <template shadowrootmode=open|closed> start tag it inserts the template as a foreign element and calls TreeSink::attach_declarative_shadow(shadow_host, template, attrs); returning false falls back to a plain inert template (spec step 8.1.1), which is exactly the behavior in this report. So the core fix is implementing that sink method in html_sink.rs — the trait default just returns failure. One prerequisite per the TODO marker in the report: get_template_contents needs to return a real contents fragment first, or even the fallback has nowhere to hold the children.

For what it's worth, we're on an older html5ever where the declarative arm is an earlier, incomplete skeleton (the success path never routed children into the shadow root, and a "close" typo meant closed mode was never detected — both since fixed in 0.39). So we took a route that may be useful on 0.39 too: opt out via allow_declarative_shadow_roots() -> false, let the template parse completely normally (children properly contained in template_contents), then a single post-parse walk converts each template[shadowrootmode] — attach its contents fragment to the parent as a shadow root, remove the template shell. Invalid mode values and already-shadowed hosts stay inert for free, nested declarative templates inside shadow content come out of the same walk, and innerHTML fragments get it automatically since they share the parse entry points.

One non-obvious bit if your DOM layer is JS-reflecting: our shadowRoot property was backed by a wrapper cache that only attachShadow populated, so parse-created roots read as null until the getter learned to consult the tree when the cache is cold. Easy to miss because everything else (rendering, slotted layout) keys off the host→root edge and just works.

(Engine in question: aginxbrowser — diting, the HTML/CSS/layout core.)

[luis-serrano-l]

Thanks, that matches what I see in the sources. For anyone picking this up, the current state:

• html5ever 0.39.0 (what blitz-dom pins on both beta.2 and main) already does the parser side:
  should_attach_declarative_shadow checks shadowrootmode=open|closed and
  TreeSink::allow_declarative_shadow_roots, inserts the template on the open-element stack
  only (never into the tree), calls TreeSink::attach_declarative_shadow(host, template, attrs),
  and on false falls back to an inert template (spec step 8.1.1). blitz-html does not
  override the default, so it always gets the fallback.
• After a successful attach, the tree builder keeps routing the template's children through
  get_template_contents(template) (tree_builder/mod.rs ~line 428). So the sink does not need
  to move nodes afterwards; it only has to make that call return the shadow root.
• On main, get_template_contents is already real (DocumentMutator::template_contents), so
  the prerequisite from the report is done. What is missing is the shadow root itself, which
  Shadow DOM: shadow trees, slots and scoped styles #892 adds (DocumentMutator::attach_shadow(host_id, mode)) while explicitly leaving
  <template shadowrootmode> out.

So once #892 lands, the whole fix should be one sink method in html_sink.rs, roughly:

fn attach_declarative_shadow(&self, host: &NodeId, template: &NodeId, attrs: &[Attribute]) -> bool {
    let mode = match attrs.iter().find(|a| a.name.local == local_name!("shadowrootmode")).map(|a| &*a.value) {
        Some("open") => ShadowRootMode::Open,
        Some("closed") => ShadowRootMode::Closed,
        _ => return false,
    };
    let mut mutr = self.mutr();
    let root = mutr.attach_shadow(*host, mode);          // returns the existing root if already shadowed
    mutr.set_template_contents(*template, root);           // so the parser's children land in the shadow root
    true
}

plus a small set_template_contents on the mutator (the field is private) and, if
attach_shadow returning an existing root should count as "already a shadow host", a false
return in that case so the template stays inert as the spec requires. The post-parse walk is a
good fallback for older html5ever, but on 0.39 the tree builder already does that work.

[yinnho]

Sketch looks right against what we ship, with one spec nit: an already-shadowed host must take the inert fallback. The spec's attach steps say "if shadow host's shadow root is non-null, return failure" — so attach_shadow returning the existing root shouldn't flow into set_template_contents(template, existing_root), or the template's children land in a root the author created separately. Easiest shape: check the host's shadow edge first and return false — the fallback then gives you the normal contents fragment, which is where an inert template's children belong anyway. That may fall out of DocumentMutator::attach_shadow's semantics already; just flagging it since the sketch comment ("returns the existing root if already shadowed") reads as if the success path continues.

One note from our equivalent batch: the already-shadowed and invalid-mode inert cases are exactly where our post-parse walk needed explicit guards, so they're worth pin tests: two templates targeting the same host, shadowrootmode="CLOSED" (case), shadowrootmode="". The invalid-mode values your _ => return false covers; the two-templates-one-host case is the sketch-level nit above.

And to close the loop on my earlier comment: the shadowRoot reflection gotcha only bites engines with a JS-visible property backed by a wrapper cache — moot for blitz-dom.