From 0470c9abe46c52b55eb034ef6e0f981338c8191e Mon Sep 17 00:00:00 2001
From: Todd Schiller <todd.schiller@gmail.com>
Date: Sun, 7 Jun 2026 15:12:39 -0400
Subject: [PATCH] Fix: cover open declarative shadow DOM via setHTMLUnsafe
 (#203)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Addresses audit item #4 (open variant). `<template shadowrootmode="open">`
materialized post-parse via `Element.setHTMLUnsafe` or
`ShadowRoot.setHTMLUnsafe` bypassed both the `attachShadow` patch and the
subtree-watcher's "host was just inserted" path — the receiver is already
in the tree and only its descendants mutate, so a host that gains a
shadow this way was invisible to every shadow-piercing rule. The
extension now wraps both `setHTMLUnsafe` variants in
`installShadowRootHook` and walks the receiver afterward so any new open
DSD shadow lands in the registry and fans out to subscribers.

Closed DSD inherits the same opt-out contract as imperative closed
shadows; the main-world probe sketched in `closed-shadow-root-annotate`
is captured as future work.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 demo-site/src/components/ShadowDomEmbed.tsx   |  73 +++++++-
 docs/src/content/docs/rules.md                |  42 +++--
 extension/src/__test-mocks__/jsdom-extras.ts  | 174 ++++++++++++++++++
 .../__tests__/shadow-roots.property.test.ts   | 116 ++++++++++++
 .../src/lib/__tests__/shadow-roots.test.ts    | 111 +++++++++++
 .../src/lib/__tests__/subtree-watcher.test.ts |  37 ++++
 extension/src/lib/shadow-roots.ts             |  68 +++++++
 .../src/rules/closed-shadow-root-annotate.ts  |  10 +-
 8 files changed, 611 insertions(+), 20 deletions(-)

diff --git a/demo-site/src/components/ShadowDomEmbed.tsx b/demo-site/src/components/ShadowDomEmbed.tsx
index 1bb9fef..1706b5c 100644
--- a/demo-site/src/components/ShadowDomEmbed.tsx
+++ b/demo-site/src/components/ShadowDomEmbed.tsx
@@ -21,7 +21,14 @@ import { INJECTIONS } from "../data/injection-fixtures";
 // class only matches via the EasyList generic CSS sheet, which now
 // adopts into open shadow roots so the hide applies here too.
 //
-// A second host below mounts a custom element with a CLOSED shadow root
+// A third host hydrates via `Element.setHTMLUnsafe` with a
+// `<template shadowrootmode="open">` payload — the declarative shadow
+// DOM path. The HTML parser materializes the shadow without ever going
+// through `attachShadow`, so the extension's `setHTMLUnsafe` patch is
+// the only thing that gets the shadow into the registry; without it
+// the injection paragraph here would be passed through to the agent.
+//
+// A fourth host mounts a custom element with a CLOSED shadow root
 // to exercise `closed-shadow-root-annotate`. By spec the rules cannot
 // see inside; the heuristic only confirms it's there.
 
@@ -47,6 +54,7 @@ if (typeof customElements !== "undefined" && !customElements.get(CLOSED_TAG)) {
 
 export default function ShadowDomEmbed() {
   const hostRef = useRef<HTMLDivElement>(null);
+  const dsdHostRef = useRef<HTMLDivElement>(null);
   const closedHostRef = useRef<HTMLDivElement>(null);
 
   useEffect(() => {
@@ -100,6 +108,56 @@ export default function ShadowDomEmbed() {
     };
   }, []);
 
+  useEffect(() => {
+    const host = dsdHostRef.current;
+    if (!host || host.shadowRoot) {
+      return;
+    }
+    // Declarative shadow DOM: the parser materializes the shadow when
+    // it encounters `<template shadowrootmode>` as a child of the
+    // receiver during `setHTMLUnsafe`. No `attachShadow` call is made.
+    // Without the extension's `setHTMLUnsafe` patch the new shadow is
+    // invisible to every shadow-piercing rule.
+    //
+    // `setHTMLUnsafe` is in TypeScript's lib.dom.d.ts but the browser
+    // matrix for "Baseline 2024" — feature-detect rather than rely on
+    // a tooling assumption.
+    if (typeof host.setHTMLUnsafe !== "function") {
+      return;
+    }
+    const escapedInjection = INJECTIONS.PRODUCT_DETAIL_HIDDEN_SYSTEM.replaceAll(
+      "<",
+      "&lt;",
+    ).replaceAll(">", "&gt;");
+    host.setHTMLUnsafe(
+      `<template shadowrootmode="open">
+        <style>
+          .dsd-card {
+            padding: 6px 10px;
+            border: 1px solid #0f766e;
+            background: #f0fdfa;
+            color: #134e4a;
+            font: 13px system-ui;
+            border-radius: 4px;
+          }
+          .dsd-injection {
+            margin: 8px 0 0;
+            padding: 6px 10px;
+            border: 1px solid #b91c1c;
+            background: #fef2f2;
+            color: #7f1d1d;
+            font: 13px system-ui;
+          }
+        </style>
+        <div class="dsd-card">SSR-style widget hydrated via declarative shadow DOM.</div>
+        <p class="dsd-injection">${escapedInjection}</p>
+      </template>`,
+    );
+    return () => {
+      host.shadowRoot?.replaceChildren();
+    };
+  }, []);
+
   useEffect(() => {
     const host = closedHostRef.current;
     if (!host || host.querySelector(CLOSED_TAG)) {
@@ -135,6 +193,19 @@ export default function ShadowDomEmbed() {
         ref={hostRef}
         className="shadow-host mt-3 rounded border border-dashed border-slate-300 p-3"
       />
+      <p className="mt-4 text-sm text-stone-700">
+        The host below hydrates via <code>Element.setHTMLUnsafe</code> with a{" "}
+        <code>&lt;template shadowrootmode="open"&gt;</code> payload — the
+        declarative shadow DOM path used by SSR component frameworks. The HTML
+        parser attaches the shadow without ever calling{" "}
+        <code>attachShadow</code>; without the extension's{" "}
+        <code>setHTMLUnsafe</code> patch the injection paragraph inside this
+        shadow would slip past every shadow-piercing rule.
+      </p>
+      <div
+        ref={dsdHostRef}
+        className="dsd-shadow-host mt-3 rounded border border-dashed border-slate-300 p-3"
+      />
       <p className="mt-4 text-sm text-stone-700">
         The widget below mounts inside a <em>closed</em> shadow root. ABS cannot
         reach inside by spec — every rule passes its contents through untouched.
diff --git a/docs/src/content/docs/rules.md b/docs/src/content/docs/rules.md
index 06e4cea..f2a6ef1 100644
--- a/docs/src/content/docs/rules.md
+++ b/docs/src/content/docs/rules.md
@@ -27,20 +27,29 @@ Numbered citations like [[1]](#ref-greshake-2023) link to the
 ## Coverage scope
 
 All rules run against the page's light DOM and any **open shadow roots** the
-page builds via `element.attachShadow({ mode: "open" })`. That covers the way
-most chat widgets, consent banners, ad SDKs, and custom elements ship UI today —
-the host element lives in the light tree, the rendered content lives one
-boundary inside.
-
-**Closed shadow roots** (`{ mode: "closed" }`) are not reached. The Web
-Components spec makes closed mode opt-out of all external JavaScript access —
-`host.shadowRoot` is `null`, `document.adoptedStyleSheets` and
-`MutationObserver` do not cross the boundary, and no supported API undoes that.
-Any content a page renders inside a closed shadow root — whether ads, chat
-widgets, hidden text, or prompt-injection payloads — is invisible to every rule
-and will be passed through to the agent untouched. Closed shadow roots are
-uncommon outside browser UA shadows and a handful of hardened embeds, but they
-are a known gap. The optional
+page builds, regardless of which attachment path created the shadow:
+
+- Imperative attachment — `element.attachShadow({ mode: "open" })`. Covers the
+  way most chat widgets, consent banners, ad SDKs, and custom elements ship UI
+  today.
+- Declarative shadow DOM at parse time — `<template shadowrootmode="open">` in
+  the initial HTML. The browser materializes the shadow before the content
+  script runs; the extension's startup walk finds it.
+- Declarative shadow DOM post-parse — `Element.setHTMLUnsafe` and
+  `ShadowRoot.setHTMLUnsafe`, the modern hydration path used by SSR-style
+  component frameworks. The extension wraps both so a host that gains a shadow
+  via this path is added to the registry.
+
+**Closed shadow roots** (`{ mode: "closed" }`) are not reached, regardless of
+how they were attached (imperative, parse-time DSD with
+`shadowrootmode="closed"`, or any other path). The Web Components spec makes
+closed mode opt-out of all external JavaScript access — `host.shadowRoot` is
+`null`, `document.adoptedStyleSheets` and `MutationObserver` do not cross the
+boundary, and no supported API undoes that. Any content a page renders inside a
+closed shadow root — whether ads, chat widgets, hidden text, or prompt-injection
+payloads — is invisible to every rule and will be passed through to the agent
+untouched. Closed shadow roots are uncommon outside browser UA shadows and a
+handful of hardened embeds, but they are a known gap. The optional
 [Flag Closed Shadow Roots](#flag-closed-shadow-roots-experimental) rule can
 heuristically warn the agent at read-time when this gap is in use.
 
@@ -483,9 +492,10 @@ JavaScript. The rule looks for the structural shape strongly correlated with
 in `customElements`) with no light-DOM children, no `host.shadowRoot`, and a
 non-zero rendered box. Built-in elements with UA shadow roots (`<input>`,
 `<details>`, `<video>`) are filtered out for free — their tag names contain no
-hyphen. Declarative shadow DOM (`<template shadowrootmode="closed">`) is
+hyphen. Declarative shadow DOM with `shadowrootmode="closed"` is
 indistinguishable from imperative closed shadows after parsing and is not
-separately surfaced.
+separately surfaced; the open variant of declarative shadow DOM is covered by
+the regular open-shadow plumbing described in [Coverage scope](#coverage-scope).
 
 The landmark says "may contain content ABS cannot see," not "this is definitely
 a closed shadow root" — a custom element that renders via canvas, WebGL, or
diff --git a/extension/src/__test-mocks__/jsdom-extras.ts b/extension/src/__test-mocks__/jsdom-extras.ts
index 2d0a339..a50f668 100644
--- a/extension/src/__test-mocks__/jsdom-extras.ts
+++ b/extension/src/__test-mocks__/jsdom-extras.ts
@@ -95,3 +95,177 @@ if (!("adoptedStyleSheets" in Document.prototype)) {
 if (!("adoptedStyleSheets" in ShadowRoot.prototype)) {
   defineAdoptedStyleSheets(ShadowRoot.prototype);
 }
+
+// setHTMLUnsafe / declarative shadow DOM — Baseline 2024, present in the
+// Chrome MV3 versions we target. jsdom 26 hasn't shipped it. The
+// production code in `shadow-roots.ts` patches both Element and
+// ShadowRoot variants; tests need the underlying method on the prototype
+// so the patch has something to wrap and so callers (test fixtures,
+// integration tests) can drive the DSD path.
+//
+// This polyfill emulates only the surface our tests exercise:
+//
+//   - Parse the HTML into a throwaway staging element with `innerHTML`.
+//     innerHTML preserves `<template>` elements and stashes their
+//     children in `template.content` — exactly the shape the parser
+//     uses ahead of DSD lifting.
+//   - For top-level `<template shadowrootmode="open"|"closed">` (parent
+//     is the staging element), `attachShadow` on the **receiver** in
+//     the requested mode and move the template content into the new
+//     shadow root.
+//   - For nested `<template shadowrootmode>` (parent is some other
+//     element in the parsed tree), `attachShadow` on the parent
+//     element and move the template content into its new shadow root.
+//   - Both passes recurse into `template.content` first so DSD inside
+//     DSD is materialized child-first.
+//   - The remaining (non-template, non-shadow) staging children
+//     replace the receiver's children.
+//
+// Limitations vs. the real parser:
+//   - `shadowrootdelegatesfocus`, `shadowrootclonable`, and
+//     `shadowrootserializable` attributes are ignored — none of our
+//     tests assert on those.
+//   - A duplicate top-level DSD template of the same mode is dropped
+//     (the real parser handles the second one as ordinary fragment
+//     content, but our tests never produce duplicates).
+//
+// Note on test-environment interaction: the polyfill calls
+// `attachShadow` to materialize DSD shadows. `attachShadow` is itself
+// patched by the production code under test, so in tests the registry
+// also fills via the attachShadow path. This is fine — the production
+// `setHTMLUnsafe` trampoline's `discoverShadowRootsIn` call is
+// idempotent against the registry. In real browsers the parser
+// materializes DSD without going through `attachShadow`, which is the
+// gap the trampoline closes.
+//
+// Gated on the absence of the native method so a future jsdom upgrade
+// that ships DSD natively will use the engine implementation.
+interface SetHTMLUnsafeCapable {
+  setHTMLUnsafe?: (this: Element | ShadowRoot, html: string) => void;
+}
+
+function attachDSDShadow(host: Element, template: HTMLTemplateElement): void {
+  const mode = template.getAttribute("shadowrootmode");
+  if (mode !== "open" && mode !== "closed") {
+    template.remove();
+    return;
+  }
+  // Recurse into the template's content first so any nested DSD is
+  // lifted before the outer shadow swallows the subtree.
+  liftNestedDSD(template.content);
+  let shadow: ShadowRoot;
+  try {
+    shadow = host.attachShadow({ mode });
+  } catch {
+    // Host already has a shadow root attached. Fall back to it when
+    // accessible (open mode) and otherwise drop the template content —
+    // matches the spec's "ignore duplicate" outcome for closed.
+    const existing = host.shadowRoot;
+    if (!existing) {
+      template.remove();
+      return;
+    }
+    shadow = existing;
+  }
+  shadow.append(template.content);
+  template.remove();
+}
+
+function liftNestedDSD(root: ParentNode): void {
+  // Walk the document tree under `root` (NOT into `template.content`,
+  // which is its own off-tree fragment — attachDSDShadow handles those
+  // by recursing explicitly).
+  const stack: ParentNode[] = [root];
+  const templates: HTMLTemplateElement[] = [];
+  while (stack.length > 0) {
+    const node = stack.pop();
+    if (!node) {
+      continue;
+    }
+    for (const child of node.children) {
+      if (
+        child instanceof HTMLTemplateElement &&
+        child.hasAttribute("shadowrootmode")
+      ) {
+        templates.push(child);
+        // Do not descend through the template — its children live in
+        // `.content`, which `attachDSDShadow` walks separately.
+        continue;
+      }
+      stack.push(child);
+    }
+  }
+  for (const template of templates) {
+    const parent = template.parentElement;
+    if (parent) {
+      attachDSDShadow(parent, template);
+    } else {
+      template.remove();
+    }
+  }
+}
+
+function polyfilledSetHTMLUnsafe(
+  this: Element | ShadowRoot,
+  html: string,
+): void {
+  const ownerDocument = this.ownerDocument;
+  const staging = ownerDocument.createElement("div");
+  staging.innerHTML = html;
+
+  // Top-level DSD templates (direct children of staging) attach shadows
+  // on the receiver, not on staging. ShadowRoot receivers can't host a
+  // shadow of their own — drop those templates' DSD intent but keep
+  // their content as ordinary children.
+  //
+  // Collect templates in one pass before mutating; iterating an
+  // HTMLCollection while removing its members skips siblings.
+  const topLevelTemplates: HTMLTemplateElement[] = [];
+  for (const child of staging.children) {
+    if (
+      child instanceof HTMLTemplateElement &&
+      child.hasAttribute("shadowrootmode")
+    ) {
+      topLevelTemplates.push(child);
+    }
+  }
+  for (const child of topLevelTemplates) {
+    if (this instanceof Element) {
+      attachDSDShadow(this, child);
+    } else {
+      // ShadowRoot receiver — flatten the template's content into the
+      // staging so downstream copy moves it into the shadow root.
+      liftNestedDSD(child.content);
+      child.replaceWith(child.content);
+    }
+  }
+
+  // Descendant DSD templates attach on their immediate parents.
+  liftNestedDSD(staging);
+
+  // Replace the receiver's children with the processed staging contents.
+  while (this.firstChild) {
+    this.firstChild.remove();
+  }
+  while (staging.firstChild) {
+    this.append(staging.firstChild);
+  }
+}
+
+const elementProtoForSet = Element.prototype as SetHTMLUnsafeCapable;
+if (typeof elementProtoForSet.setHTMLUnsafe !== "function") {
+  Object.defineProperty(Element.prototype, "setHTMLUnsafe", {
+    configurable: true,
+    writable: true,
+    value: polyfilledSetHTMLUnsafe,
+  });
+}
+
+const shadowProtoForSet = ShadowRoot.prototype as SetHTMLUnsafeCapable;
+if (typeof shadowProtoForSet.setHTMLUnsafe !== "function") {
+  Object.defineProperty(ShadowRoot.prototype, "setHTMLUnsafe", {
+    configurable: true,
+    writable: true,
+    value: polyfilledSetHTMLUnsafe,
+  });
+}
diff --git a/extension/src/lib/__tests__/shadow-roots.property.test.ts b/extension/src/lib/__tests__/shadow-roots.property.test.ts
index 99b3639..fcf4eb7 100644
--- a/extension/src/lib/__tests__/shadow-roots.property.test.ts
+++ b/extension/src/lib/__tests__/shadow-roots.property.test.ts
@@ -343,6 +343,122 @@ describe("discoverShadowRootsIn — set-idempotence", () => {
   });
 });
 
+// -----------------------------------------------------------------------
+// Invariant 3a: setHTMLUnsafe DSD lifting registers every open root
+// -----------------------------------------------------------------------
+
+// Each spec describes one element in a flat hosting tree. The tree is
+// serialized to a `<template shadowrootmode>`-bearing HTML string, and
+// `setHTMLUnsafe` is called on a single receiver in the document. After
+// the call, every open declarative shadow should be in the registry and
+// every closed declarative shadow should be absent.
+interface DSDNode {
+  // null = no DSD on this element, otherwise the mode of the template
+  // hosted as a direct child of this element.
+  shadow: ShadowMode;
+}
+
+interface DSDTree {
+  size: number;
+  parents: readonly number[];
+  specs: readonly DSDNode[];
+}
+
+const dsdNodeArb: fc.Arbitrary<DSDNode> = fc.record({
+  shadow: shadowModeArb,
+});
+
+const dsdTreeArb: fc.Arbitrary<DSDTree> = fc
+  .integer({ min: 1, max: 8 })
+  .chain((size) => {
+    const specsArb = fc.array(dsdNodeArb, {
+      minLength: size,
+      maxLength: size,
+    });
+    if (size === 1) {
+      return specsArb.map((specs) => ({ size, parents: [], specs }));
+    }
+    const parentArbs = Array.from({ length: size - 1 }, (_, index) =>
+      fc.integer({ min: 0, max: index }),
+    );
+    return fc
+      .tuple(fc.tuple(...parentArbs), specsArb)
+      .map(([parents, specs]) => ({ size, parents, specs }));
+  });
+
+// Serialize a tree to an HTML string with one element per node, indexed
+// for later querySelector lookup, and a `<template shadowrootmode>` as
+// the first child of every shadow-bearing node.
+function serializeDSDTree(tree: DSDTree): string {
+  const { size, parents, specs } = tree;
+  // Build children-by-parent index so we can recurse in document order.
+  const childrenByParent = new Map<number, number[]>();
+  for (let i = 1; i < size; i++) {
+    const parent = parents[i - 1] as number;
+    const list = childrenByParent.get(parent) ?? [];
+    list.push(i);
+    childrenByParent.set(parent, list);
+  }
+  function emit(nodeIndex: number): string {
+    const spec = specs[nodeIndex] as DSDNode;
+    const children = childrenByParent.get(nodeIndex) ?? [];
+    const tag = `node-${nodeIndex}`;
+    let inner = "";
+    if (spec.shadow !== null) {
+      inner += `<template shadowrootmode="${spec.shadow}">shadow content for ${nodeIndex}</template>`;
+    }
+    for (const childIndex of children) {
+      inner += emit(childIndex);
+    }
+    return `<${tag} data-index="${nodeIndex}">${inner}</${tag}>`;
+  }
+  return emit(0);
+}
+
+describe("setHTMLUnsafe — open DSD registration property", () => {
+  it("registers exactly the open declarative shadows in the parsed HTML", () => {
+    fc.assert(
+      fc.property(dsdTreeArb, (tree) => {
+        document.body.innerHTML = "";
+        __resetShadowRootsForTesting();
+        installShadowRootHook();
+
+        const receiver = document.createElement("div");
+        document.body.append(receiver);
+        receiver.setHTMLUnsafe(serializeDSDTree(tree));
+
+        // For each spec with shadow !== null we expect a corresponding
+        // host element of tag `node-<index>` to exist and either have
+        // an open shadow (registered) or a closed shadow (host.shadowRoot
+        // returns null — and the tracker should not contain anything
+        // attributable to it).
+        const expectedOpen = new Set<ShadowRoot>();
+        let expectedClosedCount = 0;
+        for (let i = 0; i < tree.size; i++) {
+          const spec = tree.specs[i] as DSDNode;
+          const host = receiver.querySelector(`node-${i}`);
+          expect(host).not.toBeNull();
+          if (spec.shadow === "open") {
+            expect(host?.shadowRoot).not.toBeNull();
+            expectedOpen.add(host?.shadowRoot as ShadowRoot);
+          } else if (spec.shadow === "closed") {
+            expect(host?.shadowRoot).toBeNull();
+            expectedClosedCount += 1;
+          } else {
+            expect(host?.shadowRoot).toBeNull();
+          }
+        }
+
+        const tracked = new Set(getOpenShadowRoots());
+        expect(tracked).toEqual(expectedOpen);
+        expect(tracked.size + expectedClosedCount).toBe(
+          tree.specs.filter((s) => s.shadow !== null).length,
+        );
+      }),
+    );
+  });
+});
+
 // -----------------------------------------------------------------------
 // Invariant 3: dispatch coverage on randomized nested shadow forests
 // -----------------------------------------------------------------------
diff --git a/extension/src/lib/__tests__/shadow-roots.test.ts b/extension/src/lib/__tests__/shadow-roots.test.ts
index e6c421c..25a667a 100644
--- a/extension/src/lib/__tests__/shadow-roots.test.ts
+++ b/extension/src/lib/__tests__/shadow-roots.test.ts
@@ -138,3 +138,114 @@ describe("discoverShadowRootsIn", () => {
     expect(getOpenShadowRoots().has(root)).toBe(true);
   });
 });
+
+describe("setHTMLUnsafe — declarative shadow DOM", () => {
+  // The HTML parser materializes `<template shadowrootmode>` into a
+  // real shadow root on the parent without ever invoking
+  // `attachShadow`. `Element.setHTMLUnsafe` is the post-parse opt-in
+  // that re-enables the same path. Without the patch in
+  // `installShadowRootHook`, a page that hydrates via setHTMLUnsafe
+  // could ship content in an open shadow without registering with the
+  // tracker — every shadow-piercing rule would miss it.
+
+  it("registers an open root materialized via setHTMLUnsafe on a connected host", () => {
+    const host = document.createElement("div");
+    document.body.append(host);
+
+    host.setHTMLUnsafe(
+      '<template shadowrootmode="open"><span class="hidden-content">message</span></template>',
+    );
+
+    expect(host.shadowRoot).not.toBeNull();
+    expect(host.shadowRoot?.mode).toBe("open");
+    expect(getOpenShadowRoots().has(host.shadowRoot as ShadowRoot)).toBe(true);
+  });
+
+  it("does not register a closed declarative shadow", () => {
+    const host = document.createElement("div");
+    document.body.append(host);
+
+    host.setHTMLUnsafe(
+      '<template shadowrootmode="closed"><span>closed payload</span></template>',
+    );
+
+    // Closed roots are opt-out — `host.shadowRoot` is null and the
+    // tracker should respect that even when the carrier was DSD
+    // rather than imperative attachShadow.
+    expect(host.shadowRoot).toBeNull();
+    expect(getOpenShadowRoots().size).toBe(0);
+  });
+
+  it("registers a nested DSD open shadow attached to a descendant host", () => {
+    const wrapper = document.createElement("div");
+    document.body.append(wrapper);
+
+    // The DSD template is inside a descendant of the receiver, not at
+    // the top level — the parser attaches the shadow on the
+    // descendant host, not on the receiver.
+    wrapper.setHTMLUnsafe(
+      '<div class="wrapper"><section class="nested-host"><template shadowrootmode="open"><p>nested</p></template></section></div>',
+    );
+
+    const nested = wrapper.querySelector(".nested-host");
+    expect(nested?.shadowRoot).not.toBeNull();
+    expect(getOpenShadowRoots().has(nested?.shadowRoot as ShadowRoot)).toBe(
+      true,
+    );
+  });
+
+  it("notifies subscribers exactly once per registered DSD shadow", () => {
+    const listener = jest.fn();
+    const unsubscribe = subscribeShadowRootAttached(listener);
+
+    const host = document.createElement("div");
+    document.body.append(host);
+    host.setHTMLUnsafe(
+      '<template shadowrootmode="open"><span>x</span></template>',
+    );
+
+    // The host's shadow should fire the listener exactly once even
+    // though both the attachShadow patch (via the polyfill's lift
+    // path) and the setHTMLUnsafe trampoline's discoverShadowRootsIn
+    // walk see the same root. registerShadowRoot is idempotent against
+    // the registry.
+    expect(listener).toHaveBeenCalledTimes(1);
+    expect(listener).toHaveBeenCalledWith(host.shadowRoot);
+    unsubscribe();
+  });
+
+  it("registers DSD shadows nested inside a ShadowRoot.setHTMLUnsafe call", () => {
+    const host = document.createElement("div");
+    const root = host.attachShadow({ mode: "open" });
+    document.body.append(host);
+
+    root.setHTMLUnsafe(
+      '<section><inner-host><template shadowrootmode="open"><span>deep</span></template></inner-host></section>',
+    );
+
+    const inner = root.querySelector("inner-host");
+    expect(inner?.shadowRoot).not.toBeNull();
+    expect(getOpenShadowRoots().has(inner?.shadowRoot as ShadowRoot)).toBe(
+      true,
+    );
+  });
+
+  it("is safe to call setHTMLUnsafe repeatedly without double-registering", () => {
+    const host = document.createElement("div");
+    document.body.append(host);
+
+    host.setHTMLUnsafe(
+      '<template shadowrootmode="open"><span>first</span></template>',
+    );
+    const firstRoot = host.shadowRoot;
+    expect(firstRoot).not.toBeNull();
+
+    // Second call: the receiver already has a shadow. Spec-wise the
+    // duplicate template is dropped; either way the registry should
+    // still contain exactly the one root.
+    host.setHTMLUnsafe("<div>plain replacement content</div>");
+
+    expect(getOpenShadowRoots().size).toBe(1);
+    expect(getOpenShadowRoots().has(firstRoot as ShadowRoot)).toBe(true);
+  });
+});
diff --git a/extension/src/lib/__tests__/subtree-watcher.test.ts b/extension/src/lib/__tests__/subtree-watcher.test.ts
index 5e8f689..dafe385 100644
--- a/extension/src/lib/__tests__/subtree-watcher.test.ts
+++ b/extension/src/lib/__tests__/subtree-watcher.test.ts
@@ -1749,5 +1749,42 @@ describe("createSubtreeWatcher", () => {
       setTimeoutSpy.mockRestore();
       watcher.stop();
     });
+
+    it("dispatches children of an open DSD shadow materialized via setHTMLUnsafe", async () => {
+      // Declarative shadow DOM (`<template shadowrootmode="open">`)
+      // attached via Element.setHTMLUnsafe on a connected host bypasses
+      // both `attachShadow` and the "host was just inserted"
+      // MutationObserver path — the receiver is already in the tree;
+      // only its descendants mutate, and the shadow it gains is invisible
+      // to a vanilla observer. The setHTMLUnsafe patch in shadow-roots
+      // closes the gap by walking the receiver afterward and registering
+      // the new open root with the existing subscribeShadowRootAttached
+      // fanout.
+      const host = document.createElement("div");
+      document.body.append(host);
+
+      const onSubtrees = jest.fn();
+      const watcher = createSubtreeWatcher({ onSubtrees });
+      watcher.start(document.body);
+
+      await flushMutations();
+      jest.advanceTimersByTime(THROTTLE_MS);
+      onSubtrees.mockClear();
+
+      host.setHTMLUnsafe(
+        '<template shadowrootmode="open"><section id="dsd-inner">payload</section></template>',
+      );
+
+      await flushMutations();
+      jest.advanceTimersByTime(THROTTLE_MS);
+
+      const allRoots = (onSubtrees.mock.calls as Array<[Element[]]>).flatMap(
+        (call) => call[0],
+      );
+      const dsdInner = host.shadowRoot?.querySelector("#dsd-inner");
+      expect(dsdInner).not.toBeNull();
+      expect(allRoots).toContain(dsdInner);
+      watcher.stop();
+    });
   });
 });
diff --git a/extension/src/lib/shadow-roots.ts b/extension/src/lib/shadow-roots.ts
index ec1f274..6e1f555 100644
--- a/extension/src/lib/shadow-roots.ts
+++ b/extension/src/lib/shadow-roots.ts
@@ -16,6 +16,18 @@
 // page parsing have already happened by the time we install the hook. Callers
 // pair `installShadowRootHook()` with `discoverShadowRootsIn(document.body)`
 // at startup to catch those.
+//
+// Declarative shadow DOM (`<template shadowrootmode="open">`) is consumed by
+// the HTML parser without invoking `attachShadow`. Initial-parse DSD shadows
+// are caught by the startup walk because by document_idle the parser has
+// already materialized them and `host.shadowRoot` returns the open root. The
+// remaining post-parse opt-in surface — `Element.prototype.setHTMLUnsafe` and
+// `ShadowRoot.prototype.setHTMLUnsafe` — bypasses both `attachShadow` and the
+// subtree-watcher's "host was just inserted" path (the receiver is already
+// in the tree; only its children mutate). Those two methods are patched here
+// to walk the receiver after the call so any newly-materialized open shadow
+// is registered. Closed DSD is invisible by the same spec contract as
+// imperative closed shadows.
 
 const HOOK_INSTALLED = Symbol.for("abs.shadowRootHookInstalled");
 
@@ -46,6 +58,62 @@ export function installShadowRootHook(): void {
     }
     return root;
   };
+
+  patchSetHTMLUnsafe();
+}
+
+// `setHTMLUnsafe` is the only post-parse opt-in path that honors declarative
+// shadow DOM templates. Plain `innerHTML` drops them by spec. Patching both
+// the Element and ShadowRoot variants covers the case where the receiver is
+// itself already in the document: the page calls `host.setHTMLUnsafe(html)`,
+// the parser attaches a shadow root on the receiver without ever invoking
+// `attachShadow`, and the subtree-watcher's "host was just inserted" path
+// never fires — the receiver's host record is unchanged, only its descendants
+// mutated. The trampoline walks the receiver after the call so any new open
+// shadow shows up in the registry and fans out to subscribers.
+//
+// `Document.parseHTMLUnsafe` returns a detached `Document`; any path that
+// grafts its contents into the live tree goes through `appendChild` (which
+// trips the subtree-watcher's discovery walk on the host) or another
+// `setHTMLUnsafe`, so it does not need its own patch.
+function patchSetHTMLUnsafe(): void {
+  interface ElementSetHTMLUnsafeCapable {
+    setHTMLUnsafe?: (this: Element, html: string) => void;
+  }
+  interface ShadowSetHTMLUnsafeCapable {
+    setHTMLUnsafe?: (this: ShadowRoot, html: string) => void;
+  }
+
+  const elementProto = Element.prototype as ElementSetHTMLUnsafeCapable;
+  const originalElementSet = elementProto.setHTMLUnsafe;
+  if (typeof originalElementSet === "function") {
+    elementProto.setHTMLUnsafe = function patched(
+      this: Element,
+      html: string,
+    ): void {
+      originalElementSet.call(this, html);
+      // The receiver itself may have gained a shadow root (when the
+      // top-level fragment is a `<template shadowrootmode>`), and any
+      // descendant element may have gained one too — walk the whole
+      // subtree from the receiver.
+      discoverShadowRootsIn(this);
+    };
+  }
+
+  const shadowProto = ShadowRoot.prototype as ShadowSetHTMLUnsafeCapable;
+  const originalShadowSet = shadowProto.setHTMLUnsafe;
+  if (typeof originalShadowSet === "function") {
+    shadowProto.setHTMLUnsafe = function patched(
+      this: ShadowRoot,
+      html: string,
+    ): void {
+      originalShadowSet.call(this, html);
+      // A shadow root cannot itself receive another shadow — only its
+      // element descendants can. Walk from the shadow root so nested
+      // DSD inside the new content is registered.
+      discoverShadowRootsIn(this);
+    };
+  }
 }
 
 function registerShadowRoot(root: ShadowRoot): void {
diff --git a/extension/src/rules/closed-shadow-root-annotate.ts b/extension/src/rules/closed-shadow-root-annotate.ts
index d660754..2efa534 100644
--- a/extension/src/rules/closed-shadow-root-annotate.ts
+++ b/extension/src/rules/closed-shadow-root-annotate.ts
@@ -43,11 +43,15 @@
 // content ABS cannot see," not "this is definitely a closed shadow root."
 //
 // Known false negatives:
-//   - Declarative shadow DOM (`<template shadowrootmode="closed">`) — the
-//     template is consumed during HTML parsing, never goes through
+//   - Declarative shadow DOM with `shadowrootmode="closed"` — the template
+//     is consumed during HTML parsing, never goes through
 //     `Element.prototype.attachShadow`, and the materialized closed root
 //     is indistinguishable from "no shadow" the same as imperative
-//     closed shadows.
+//     closed shadows. The open variant of declarative shadow DOM is
+//     covered by the regular open-shadow plumbing — initial-parse roots
+//     are walked at content-script startup, and the `setHTMLUnsafe`
+//     patch in `shadow-roots.ts` registers any open shadow materialized
+//     post-parse.
 //   - Closed shadows on non-custom elements (e.g., a page that attaches a
 //     closed shadow to a `<div>`). Rare in practice — closed mode is
 //     almost always paired with the custom element pattern — and a