refactor: improve closeElement comment and add conditional shadow DOM test

Co-authored-by: NullVoxPopuli <[email protected]>
Agent-Logs-Url: https://github.com/emberjs/ember.js/sessions/e70854e9-f877-4c7d-81b1-ac34ddb3b3f9

Author: Copilot

packages/@glimmer-workspace/integration-tests/lib/suites/shadow-dom.ts

@@ -210,4 +210,40 @@ export class ShadowDOMSuite extends RenderTest {
       'same shadow root instance reused (not recreated)'
     );
   }
+
+  @test
+  'conditional <template shadowrootmode="open"> inside a host element attaches shadow root when rendered'() {
+    if (typeof document === 'undefined' || !('attachShadow' in document.createElement('div'))) {
+      this.assert.ok(true, 'Shadow DOM not supported, skipping');
+      return;
+    }
+
+    this.render(
+      '<div class="host">{{#if this.useShadow}}<template shadowrootmode="open"><p>shadow content</p></template>{{else}}<div>regular content</div>{{/if}}</div>',
+      { useShadow: true }
+    );
+
+    const rootEl = castToBrowser(this.element, 'HTML');
+    const host = rootEl.querySelector('.host') as HTMLElement | null;
+
+    this.assert.ok(host !== null, 'host element exists');
+    this.assert.ok(host?.shadowRoot !== null, 'shadow root is attached when useShadow=true');
+    this.assert.strictEqual(
+      host?.shadowRoot?.querySelector('p')?.textContent,
+      'shadow content',
+      'shadow content renders in shadow root'
+    );
+
+    // Switch to regular content branch
+    this.rerender({ useShadow: false });
+    // The shadow root persists on the host element (platform behavior)
+    // but the <div> regular content is rendered into the shadow root's slot
+    // (since the shadow root owns the rendering for the host).
+    // The important assertion is that no <template> element ended up in the DOM.
+    this.assert.strictEqual(
+      host?.querySelector('template'),
+      null,
+      '<template> element is not present in the DOM'
+    );
+  }
 }

packages/@glimmer/runtime/lib/vm/element-builder.ts

@@ -296,18 +296,27 @@ export class NewTreeBuilder implements TreeBuilder {
   }
 
   closeElement(): Nullable<ModifierInstance[]> {
-    // Check if we are closing a shadow DOM section. Shadow roots (and document
-    // fragments) have nodeType 11 (DOCUMENT_FRAGMENT_NODE), whereas regular
-    // elements have nodeType 1 (ELEMENT_NODE).
-    //
-    // When we detect a shadow root as the current element, we need to pop the
-    // block we pushed in flushElement (instead of using willCloseElement which
-    // decrements the parent block's nesting counter).
-    //
-    // Note: this.element is typed as SimpleElement (nodeType 1), but at runtime
-    // it may be a ShadowRoot (nodeType 11) that was stored during flushElement's
-    // shadow DOM handling. We use an explicit nodeType check to detect this case.
     if (isShadowRootOrDocumentFragment(this.element)) {
+      // A ShadowRoot (or DocumentFragment) is used as the rendering target for
+      // declarative shadow DOM (`<template shadowrootmode="...">`) and
+      // `{{#in-element}}` calls.
+      //
+      // Unlike a regular element, a shadow root:
+      //  1. Has nodeType 11 (DOCUMENT_FRAGMENT_NODE) instead of 1 (ELEMENT_NODE)
+      //  2. Must always be attached to a host element — it cannot exist as a
+      //     free-standing node — so its content must not be tracked in the
+      //     parent block's bounds (the host element is the visible boundary).
+      //
+      // Because of (2), `flushElement` pushed an extra *remote* block (isRemote=true)
+      // for the shadow root content so that its nodes are excluded from the
+      // enclosing block's first/last node tracking. We must pop that extra
+      // block here rather than calling `willCloseElement()`, which would
+      // incorrectly decrement the parent block's element-nesting counter.
+      //
+      // Note: `this.element` is typed as SimpleElement (nodeType 1), but at
+      // runtime it may hold a ShadowRoot (nodeType 11) placed there during
+      // `flushElement`'s shadow DOM handling. The explicit nodeType check in
+      // `isShadowRootOrDocumentFragment` detects this case.
       this.popBlock();
       this.popElement();
       return this.popModifiers();