From 519f4ecec8c72d4a57583346d1d948b89e05342f Mon Sep 17 00:00:00 2001
From: Pierre Le Fevre <hello@pierrelf.com>
Date: Thu, 4 Jun 2026 21:47:34 +0200
Subject: [PATCH] html/style/dom: render declarative shadow DOM (isu issue 348)

Recognise <template shadowrootmode="open|closed"> (and the legacy
shadowroot attribute) in the tree builder and attach the template
contents as a shadow root on the host element instead of inserting an
inert <template> into the light tree.

- dom: Document gains host->root / root->host shadow maps plus
  attach_shadow_root / shadow_root / shadow_host. The shadow fragment is
  detached from the light tree (children(host) never returns it).
- html: <template> with shadowrootmode/shadowroot attaches a shadow
  root and directs subsequent insertions into the shadow fragment; the
  matching </template> pops it. Ordinary <template> is unchanged.
- style: resolve_node walks an element's shadow tree as its rendered
  children, styled by the outer stylesheet plus the shadow's own <style>
  rules; the shadow stylesheet's :host rules cascade onto the host.
- e2e dom_dump descends into shadow roots (#shadow-root marker).

The blocket.se finn-topbar header lives in a declarative shadow root;
it now lays out and its "Logga in" link is clickable. Adds a regression
probe (assert_link_at [data-automation-id=profile-link] /auth/login) to
blocket.se.we and unit tests across dom/html/style. The scenario keeps
its screenshot xfail (parity gap tracked by isu issue 331).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 .isu/issues.json                            |   2 +-
 crates/dom/src/lib.rs                       |  61 ++++++++++
 crates/e2e/scenarios/real-web/blocket.se.we |   5 +
 crates/e2e/src/dom_dump.rs                  |  11 ++
 crates/html/src/tree_builder.rs             | 106 ++++++++++++++++++
 crates/style/src/computed.rs                | 117 +++++++++++++++++---
 crates/style/src/matching.rs                |  66 +++++++++++
 7 files changed, 352 insertions(+), 16 deletions(-)

diff --git a/.isu/issues.json b/.isu/issues.json
index d5059ae..7ead1f1 100644
--- a/.isu/issues.json
+++ b/.isu/issues.json
@@ -4254,7 +4254,7 @@
       ],
       "assigned": [],
       "author": "piefev",
-      "state": "open",
+      "state": "closed",
       "created_at": "2026-06-04T19:05:09Z"
     }
   ]
diff --git a/crates/dom/src/lib.rs b/crates/dom/src/lib.rs
index 762c77d..4b18770 100644
--- a/crates/dom/src/lib.rs
+++ b/crates/dom/src/lib.rs
@@ -128,6 +128,13 @@ pub struct Document {
     /// Decoded RGBA8 pixel data for `<img>` elements, keyed by NodeId.
     /// Populated by the resource loader after image decoding.
     image_buffers: HashMap<NodeId, (Vec<u8>, u32, u32)>,
+    /// Shadow roots keyed by host element. The value is a `DocumentFragment`
+    /// node that holds the shadow tree; it is *not* a light-DOM child of the
+    /// host (so `children()` never returns it), but its own children carry a
+    /// parent pointer back to it for tree walks within the shadow tree.
+    shadow_roots: HashMap<NodeId, NodeId>,
+    /// Reverse map: shadow-root fragment -> host element.
+    shadow_hosts: HashMap<NodeId, NodeId>,
 }
 
 impl fmt::Debug for Document {
@@ -165,9 +172,38 @@ impl Document {
             canvas_sizes: HashMap::new(),
             canvas_contexts: CanvasContextStore::new(),
             image_buffers: HashMap::new(),
+            shadow_roots: HashMap::new(),
+            shadow_hosts: HashMap::new(),
         }
     }
 
+    /// Attach a shadow root to `host` and return the shadow-root fragment node.
+    ///
+    /// The fragment is created detached from the light tree: it is recorded in
+    /// the host→root and root→host maps but never appended as a light-DOM
+    /// child, so `children(host)` does not return it. Content parsed into the
+    /// shadow tree is appended to this fragment. If `host` already has a shadow
+    /// root, the existing one is returned unchanged.
+    pub fn attach_shadow_root(&mut self, host: NodeId) -> NodeId {
+        if let Some(&existing) = self.shadow_roots.get(&host) {
+            return existing;
+        }
+        let root = self.create_document_fragment();
+        self.shadow_roots.insert(host, root);
+        self.shadow_hosts.insert(root, host);
+        root
+    }
+
+    /// Returns the shadow-root fragment attached to `host`, if any.
+    pub fn shadow_root(&self, host: NodeId) -> Option<NodeId> {
+        self.shadow_roots.get(&host).copied()
+    }
+
+    /// Returns the host element of a shadow-root fragment, if `node` is one.
+    pub fn shadow_host(&self, node: NodeId) -> Option<NodeId> {
+        self.shadow_hosts.get(&node).copied()
+    }
+
     /// Returns the root document node ID.
     pub fn root(&self) -> NodeId {
         self.root
@@ -2557,4 +2593,29 @@ mod tests {
         assert!(entries.contains(&(c1, (100, 50))));
         assert!(entries.contains(&(c2, (200, 100))));
     }
+
+    #[test]
+    fn attach_shadow_root_maps_host_and_root() {
+        let mut doc = Document::new();
+        let host = doc.create_element("my-bar");
+        doc.append_child(doc.root(), host);
+
+        assert!(doc.shadow_root(host).is_none());
+        let root = doc.attach_shadow_root(host);
+        assert_eq!(doc.shadow_root(host), Some(root));
+        assert_eq!(doc.shadow_host(root), Some(host));
+        assert!(matches!(doc.node_data(root), NodeData::DocumentFragment));
+
+        // The shadow root is not a light-DOM child of the host.
+        assert_eq!(doc.children(host).count(), 0);
+
+        // Content appended to the shadow root is not visible as a host child.
+        let p = doc.create_element("p");
+        doc.append_child(root, p);
+        assert_eq!(doc.children(host).count(), 0);
+        assert_eq!(doc.children(root).next(), Some(p));
+
+        // Re-attaching returns the same root.
+        assert_eq!(doc.attach_shadow_root(host), root);
+    }
 }
diff --git a/crates/e2e/scenarios/real-web/blocket.se.we b/crates/e2e/scenarios/real-web/blocket.se.we
index 1fba656..50f362e 100644
--- a/crates/e2e/scenarios/real-web/blocket.se.we
+++ b/crates/e2e/scenarios/real-web/blocket.se.we
@@ -60,6 +60,11 @@ assert_link_at a[href="/23744090"] /23744090
 # flex-shrink crushed the category-nav wrapper and the listing-card grid
 # overlapped it, stealing this click).
 assert_link_at [id=first-market-link] /recommerce/forsale/search
+# A native click on the fixed-header "Logga in" link resolves to the login URL
+# (regression guard for isu issue 348 — the finn-topbar header lives in a
+# declarative shadow root; before declarative shadow DOM was rendered the header
+# collapsed to a 0x0 box at the document origin and this link was unclickable).
+assert_link_at [data-automation-id=profile-link] /auth/login
 assert_screenshot_matches real-web/blocket.se/desktop.png blocket.se.desktop.chromium.expected.png
 
 viewport 390 844
diff --git a/crates/e2e/src/dom_dump.rs b/crates/e2e/src/dom_dump.rs
index eee5ea6..524ef5c 100644
--- a/crates/e2e/src/dom_dump.rs
+++ b/crates/e2e/src/dom_dump.rs
@@ -36,6 +36,17 @@ fn walk(doc: &Document, node: NodeId, depth: usize, out: &mut String) {
                 }
             }
             out.push_str(">\n");
+            // Descend into a declarative shadow root, if present, so shadow
+            // content appears in the dump (it is not a light-DOM child).
+            if let Some(root) = doc.shadow_root(node) {
+                for _ in 0..depth + 1 {
+                    out.push_str("  ");
+                }
+                out.push_str("#shadow-root\n");
+                for child in doc.children(root) {
+                    walk(doc, child, depth + 2, out);
+                }
+            }
         }
         NodeData::Text { data } => {
             let trimmed = data.trim();
diff --git a/crates/html/src/tree_builder.rs b/crates/html/src/tree_builder.rs
index 5d1e8a2..b7a0dd5 100644
--- a/crates/html/src/tree_builder.rs
+++ b/crates/html/src/tree_builder.rs
@@ -549,6 +549,9 @@ impl TreeBuilder {
                 self.insert_node(elem);
                 // Don't push void elements onto the stack.
             }
+            Token::StartTag { ref name, .. } if name == "template" => {
+                self.handle_template_start(&token);
+            }
             Token::StartTag { .. } => {
                 // Generic start tag: create element and push onto stack.
                 let elem = self.create_element_from_token(&token);
@@ -636,6 +639,20 @@ impl TreeBuilder {
                     }
                 }
             }
+            Token::EndTag { ref name } if name == "template" => {
+                // If a declarative-shadow-root fragment is open, pop down to and
+                // including it. Otherwise fall back to generic end-tag handling
+                // for an ordinary `<template>` element.
+                if let Some(pos) = self
+                    .open_elements
+                    .iter()
+                    .rposition(|&id| self.document.shadow_host(id).is_some())
+                {
+                    self.open_elements.truncate(pos);
+                } else {
+                    self.handle_any_other_end_tag(name);
+                }
+            }
             Token::EndTag { ref name } => {
                 // Generic end tag: walk back through open elements.
                 self.handle_any_other_end_tag(name);
@@ -646,6 +663,45 @@ impl TreeBuilder {
         }
     }
 
+    /// Handle a `<template>` start tag.
+    ///
+    /// A `<template>` carrying `shadowrootmode="open|closed"` (or the legacy
+    /// `shadowroot="open|closed"`) is a *declarative shadow root*: instead of
+    /// inserting a `<template>` element into the light tree, attach a shadow
+    /// root to the current (host) element and direct subsequent insertions into
+    /// the shadow fragment. Any other `<template>` is inserted as an ordinary
+    /// element.
+    fn handle_template_start(&mut self, token: &Token) {
+        let shadow_mode = if let Token::StartTag { attributes, .. } = token {
+            attributes
+                .iter()
+                .find(|(n, _)| n == "shadowrootmode" || n == "shadowroot")
+                .map(|(_, v)| v.trim().to_ascii_lowercase())
+                .filter(|v| v == "open" || v == "closed")
+        } else {
+            None
+        };
+
+        if shadow_mode.is_some() {
+            if let Some(&host) = self.open_elements.last() {
+                if self.document.tag_name(host).is_some()
+                    && self.document.shadow_root(host).is_none()
+                {
+                    let root = self.document.attach_shadow_root(host);
+                    // Subsequent inserts target the shadow fragment; the
+                    // matching </template> pops it back off the stack.
+                    self.open_elements.push(root);
+                    return;
+                }
+            }
+        }
+
+        // Ordinary <template>: behave like a generic element.
+        let elem = self.create_element_from_token(token);
+        self.insert_node(elem);
+        self.open_elements.push(elem);
+    }
+
     /// Handle tokens inside a `<select>` element (InSelect insertion mode).
     fn handle_in_select(&mut self, token: Token) {
         match token {
@@ -1985,4 +2041,54 @@ mod tests {
         // The lowercased form must not be what's stored.
         assert_eq!(doc.get_attribute(svg, "viewbox"), None);
     }
+
+    /// Helper: depth-first search for the first element with the given tag.
+    fn find_tag(doc: &Document, node: NodeId, tag: &str) -> Option<NodeId> {
+        if doc.tag_name(node) == Some(tag) {
+            return Some(node);
+        }
+        doc.children(node).find_map(|c| find_tag(doc, c, tag))
+    }
+
+    #[test]
+    fn declarative_shadow_root_attaches_to_host() {
+        let doc = parse_html(
+            "<body><my-bar><template shadowrootmode=\"open\">\
+             <header><a href=\"/login\">Logga in</a></header>\
+             </template></my-bar></body>",
+        );
+        let host = find_tag(&doc, doc.root(), "my-bar").expect("host element");
+
+        // The <template> is NOT a light-DOM child of the host.
+        assert!(child_tags(&doc, host).is_empty());
+
+        // A shadow root is attached and carries the template content.
+        let root = doc.shadow_root(host).expect("shadow root attached");
+        assert_eq!(doc.shadow_host(root), Some(host));
+        let header = doc.children(root).next().expect("shadow content");
+        assert_eq!(doc.tag_name(header), Some("header"));
+        let anchor = doc.children(header).next().expect("anchor");
+        assert_eq!(doc.tag_name(anchor), Some("a"));
+        assert_eq!(doc.get_attribute(anchor, "href"), Some("/login"));
+    }
+
+    #[test]
+    fn plain_template_stays_in_light_tree() {
+        let doc = parse_html("<body><div><template><span>x</span></template></div></body>");
+        let div = find_tag(&doc, doc.root(), "div").expect("div");
+        // An ordinary <template> (no shadowrootmode) is a normal element child,
+        // and gets no shadow root.
+        assert_eq!(child_tags(&doc, div), vec!["template"]);
+        assert!(doc.shadow_root(div).is_none());
+    }
+
+    #[test]
+    fn legacy_shadowroot_attribute_attaches_shadow_root() {
+        let doc = parse_html(
+            "<body><my-bar><template shadowroot=\"open\"><p>hi</p></template></my-bar></body>",
+        );
+        let host = find_tag(&doc, doc.root(), "my-bar").expect("host element");
+        assert!(doc.shadow_root(host).is_some());
+        assert!(child_tags(&doc, host).is_empty());
+    }
 }
diff --git a/crates/style/src/computed.rs b/crates/style/src/computed.rs
index cfd143e..5c76c71 100644
--- a/crates/style/src/computed.rs
+++ b/crates/style/src/computed.rs
@@ -3161,29 +3161,67 @@ fn resolve_node(
             let matched_rules = collect_matching_rules(doc, node, stylesheet, media_ctx);
             let inline_style_attr = doc.get_attribute(node, "style").map(|s| s.to_owned());
 
-            let key = StyleCacheKey {
-                matched_rules_hash: hash_matched_rules(&matched_rules),
-                inline_style_hash: hash_inline_style(inline_style_attr.as_deref()),
-                parent_style_id,
-            };
-
-            // Step 2: Check cache before running the cascade.
-            let (style, style_id) = if let Some((cached, id)) = cache.entries.get(&key) {
-                cache.hits += 1;
-                (cached.clone(), *id)
-            } else {
-                cache.misses += 1;
+            // Declarative shadow DOM: an element hosting a shadow root carries a
+            // scoped stylesheet (the shadow tree's own `<style>` elements) whose
+            // `:host` rules style this host and whose other rules style the
+            // shadow tree. Collect it once here.
+            let shadow_root = doc.shadow_root(node);
+            let shadow_sheet = shadow_root.map(|root| {
+                let mut sheets = Vec::new();
+                collect_style_elements(doc, root, &mut sheets);
+                let mut merged = Stylesheet { rules: Vec::new() };
+                for s in sheets {
+                    merged.rules.extend(s.rules);
+                }
+                merged
+            });
+
+            // Step 2: Compute the cascaded style.
+            let (style, style_id) = if let Some(ref ss) = shadow_sheet {
+                // Shadow host: merge the shadow stylesheet's `:host` rules into
+                // the host's matched rules and cascade directly (cache-bypassed;
+                // hosts are rare, so the extra work is negligible).
+                let host_rules = crate::matching::collect_host_rules(ss, media_ctx, 1_000_000);
+                let mut combined: Vec<crate::matching::MatchedRule<'_>> = matched_rules;
+                combined.extend(host_rules);
+                combined.sort_by(|a, b| {
+                    a.specificity
+                        .cmp(&b.specificity)
+                        .then(a.source_order.cmp(&b.source_order))
+                });
                 let inline_decls = parse_inline_style_from_attr(inline_style_attr.as_deref());
                 let style = compute_style_for_element_with_inputs(
-                    &matched_rules,
+                    &combined,
                     &inline_decls,
                     parent_style,
                     viewport,
                 );
                 let id = cache.next_id;
                 cache.next_id += 1;
-                cache.entries.insert(key, (style.clone(), id));
                 (style, id)
+            } else {
+                let key = StyleCacheKey {
+                    matched_rules_hash: hash_matched_rules(&matched_rules),
+                    inline_style_hash: hash_inline_style(inline_style_attr.as_deref()),
+                    parent_style_id,
+                };
+                if let Some((cached, id)) = cache.entries.get(&key) {
+                    cache.hits += 1;
+                    (cached.clone(), *id)
+                } else {
+                    cache.misses += 1;
+                    let inline_decls = parse_inline_style_from_attr(inline_style_attr.as_deref());
+                    let style = compute_style_for_element_with_inputs(
+                        &matched_rules,
+                        &inline_decls,
+                        parent_style,
+                        viewport,
+                    );
+                    let id = cache.next_id;
+                    cache.next_id += 1;
+                    cache.entries.insert(key, (style.clone(), id));
+                    (style, id)
+                }
             };
 
             if style.display == Display::None {
@@ -3196,7 +3234,26 @@ fn resolve_node(
                 tag_name == "svg" && namespace.as_deref() == Some("http://www.w3.org/2000/svg");
 
             let mut children = Vec::new();
-            if !is_svg_root {
+            if let Some(root) = shadow_root {
+                // Resolve the shadow tree as this host's rendered children. The
+                // shadow tree is styled by the outer stylesheet plus the shadow
+                // tree's own `<style>` rules. (Full inward style encapsulation —
+                // preventing outer author rules from reaching the shadow tree —
+                // is not yet modelled.)
+                let mut scoped = Stylesheet {
+                    rules: stylesheet.rules.clone(),
+                };
+                if let Some(ref ss) = shadow_sheet {
+                    scoped.rules.extend(ss.rules.iter().cloned());
+                }
+                for child in doc.children(root) {
+                    if let Some(styled) = resolve_node(
+                        doc, child, &scoped, &style, style_id, viewport, media_ctx, cache,
+                    ) {
+                        children.push(styled);
+                    }
+                }
+            } else if !is_svg_root {
                 for child in doc.children(node) {
                     if let Some(styled) = resolve_node(
                         doc, child, stylesheet, &style, style_id, viewport, media_ctx, cache,
@@ -5412,4 +5469,34 @@ mod tests {
         assert_eq!(span_a_node.style.color, Color::rgb(255, 0, 0));
         assert_eq!(span_b_node.style.color, Color::rgb(0, 0, 255));
     }
+
+    fn find_styled<'a>(doc: &Document, sn: &'a StyledNode, tag: &str) -> Option<&'a StyledNode> {
+        if doc.tag_name(sn.node) == Some(tag) {
+            return Some(sn);
+        }
+        sn.children.iter().find_map(|c| find_styled(doc, c, tag))
+    }
+
+    #[test]
+    fn declarative_shadow_dom_host_and_scoped_styles() {
+        let doc = we_html::parse_html(
+            "<body><my-bar><template shadowrootmode=\"open\">\
+             <style>:host{display:block;height:40px} .box{position:fixed}</style>\
+             <header class=\"box\">x</header>\
+             </template></my-bar></body>",
+        );
+        let (result, _) = resolve_with_cache(&doc, "", (800.0, 600.0));
+        let root = result.unwrap();
+
+        // `:host` from the shadow stylesheet styles the host element.
+        let host = find_styled(&doc, &root, "my-bar").expect("host styled node");
+        assert_eq!(host.style.display, Display::Block);
+
+        // The shadow tree is the host's rendered children; the `<style>`
+        // element is display:none (UA) and drops out, leaving the <header>.
+        let header = find_styled(&doc, host, "header").expect("shadow header styled");
+        // The shadow-scoped `.box { position: fixed }` rule applies inside the
+        // shadow tree.
+        assert_eq!(header.style.position, Position::Fixed);
+    }
 }
diff --git a/crates/style/src/matching.rs b/crates/style/src/matching.rs
index 7cb231d..b351556 100644
--- a/crates/style/src/matching.rs
+++ b/crates/style/src/matching.rs
@@ -373,6 +373,72 @@ pub fn collect_matching_rules<'a>(
     matched
 }
 
+/// Collect rules from a shadow-root stylesheet whose key selector is the
+/// `:host` pseudo-class, which targets the shadow *host* element rather than
+/// any node inside the shadow tree. `:host` never matches a regular element
+/// during ordinary selector matching (see [`matches_pseudo_class`]), so these
+/// rules are gathered separately and merged into the host's matched rules.
+///
+/// `base_order` source-orders the returned rules after the host's light-tree
+/// author rules so they cascade later at equal specificity.
+pub fn collect_host_rules<'a>(
+    stylesheet: &'a Stylesheet,
+    media_ctx: &MediaContext,
+    base_order: usize,
+) -> Vec<MatchedRule<'a>> {
+    let mut matched = Vec::new();
+    let mut order = base_order;
+    collect_host_from_rules(&stylesheet.rules, &mut matched, &mut order, media_ctx);
+    matched
+}
+
+fn collect_host_from_rules<'a>(
+    rules: &'a [Rule],
+    matched: &mut Vec<MatchedRule<'a>>,
+    order: &mut usize,
+    media_ctx: &MediaContext,
+) {
+    for rule in rules {
+        match rule {
+            Rule::Style(style_rule) => {
+                let current_order = *order;
+                *order += 1;
+                for selector in &style_rule.selectors.selectors {
+                    if selector_is_host(selector) {
+                        matched.push(MatchedRule {
+                            rule: style_rule,
+                            // `:host` counts as a single pseudo-class.
+                            specificity: Specificity::new(0, 1, 0),
+                            source_order: current_order,
+                        });
+                        break;
+                    }
+                }
+            }
+            Rule::Media(media_rule) if media_rule.queries.evaluate(media_ctx) => {
+                collect_host_from_rules(&media_rule.rules, matched, order, media_ctx);
+            }
+            _ => {}
+        }
+    }
+}
+
+/// True if `selector` is a bare `:host` selector (a single compound whose only
+/// simple selector is the `host` pseudo-class).
+fn selector_is_host(selector: &Selector) -> bool {
+    let mut compounds = selector.components.iter().filter_map(|c| match c {
+        SelectorComponent::Compound(cs) => Some(cs),
+        _ => None,
+    });
+    match (compounds.next(), compounds.next()) {
+        (Some(c), None) => {
+            c.simple.len() == 1
+                && matches!(&c.simple[0], SimpleSelector::PseudoClass(p) if p == "host")
+        }
+        _ => false,
+    }
+}
+
 fn collect_from_rules<'a>(
     doc: &Document,
     node: NodeId,
-- 
2.51.2