feat: compiler-based declarative shadow DOM support via ShadowRoot wire opcode

Copilot · NullVoxPopuli · Copilot · commit 0fd2b32fa06c · 2026-03-24T16:31:52.000Z
Co-authored-by: NullVoxPopuli <199018+NullVoxPopuli@users.noreply.github.com> Agent-Logs-Url: https://github.com/emberjs/ember.js/sessions/c72c698a-f4d5-4118-b66f-d9641f62c001
diff --git a/packages/@glimmer/compiler/lib/passes/1-normalization/visitors/statements.ts b/packages/@glimmer/compiler/lib/passes/1-normalization/visitors/statements.ts
@@ -86,6 +86,32 @@ class NormalizationStatements {
   }
 
   SimpleElement(element: ASTv2.SimpleElement, state: NormalizationState): Result<mir.Statement> {
+    // Detect declarative shadow DOM: <template shadowrootmode="open|closed">
+    // When Glimmer builds the DOM via createElement rather than parsing HTML, the browser's native
+    // declarative shadow DOM processing never fires. We handle it explicitly with a dedicated opcode.
+    if (element.tag.chars === 'template') {
+      const shadowrootmodeAttr = element.attrs.find(
+        (attr): attr is ASTv2.HtmlAttr =>
+          attr.type === 'HtmlAttr' && attr.name.chars === 'shadowrootmode'
+      );
+
+      if (shadowrootmodeAttr && ASTv2.isLiteral(shadowrootmodeAttr.value, 'string')) {
+        const mode = shadowrootmodeAttr.value.value as string;
+
+        if (mode === 'open' || mode === 'closed') {
+          return this.visitList(element.body, state).mapOk(
+            (body) =>
+              new mir.DeclarativeShadowRoot({
+                loc: element.loc,
+                guid: state.generateUniqueCursor(),
+                mode,
+                body: body.toArray(),
+              })
+          );
+        }
+      }
+    }
+
     return new ClassifiedElement(
       element,
       new ClassifiedSimpleElement(element.tag, element, hasDynamicFeatures(element)),
diff --git a/packages/@glimmer/compiler/lib/passes/1-normalization/visitors/strict-mode.ts b/packages/@glimmer/compiler/lib/passes/1-normalization/visitors/strict-mode.ts
@@ -100,6 +100,9 @@ export default class StrictModeValidationPass {
 
       case 'InvokeComponent':
         return this.InvokeComponent(statement);
+
+      case 'DeclarativeShadowRoot':
+        return this.DeclarativeShadowRoot(statement);
     }
   }
 
@@ -268,6 +271,10 @@ export default class StrictModeValidationPass {
     return this.ElementParameters(statement.params).andThen(() => this.Statements(statement.body));
   }
 
+  DeclarativeShadowRoot(statement: mir.DeclarativeShadowRoot): Result<null> {
+    return this.Statements(statement.body);
+  }
+
   InvokeBlock(statement: mir.InvokeBlock): Result<null> {
     return this.Expression(statement.head, statement.head, COMPONENT_RESOLUTION)
       .andThen(() => this.Args(statement.args))
diff --git a/packages/@glimmer/compiler/lib/passes/2-encoding/content.ts b/packages/@glimmer/compiler/lib/passes/2-encoding/content.ts
@@ -69,6 +69,8 @@ export class ContentEncoder {
         return this.Component(stmt);
       case 'SimpleElement':
         return this.SimpleElement(stmt);
+      case 'DeclarativeShadowRoot':
+        return this.DeclarativeShadowRoot(stmt);
       case 'InElement':
         return this.InElement(stmt);
       case 'InvokeBlock':
@@ -137,6 +139,14 @@ export class ContentEncoder {
     ]);
   }
 
+  DeclarativeShadowRoot({
+    guid,
+    mode,
+    body,
+  }: mir.DeclarativeShadowRoot): WireFormat.Statements.ShadowRoot {
+    return [SexpOpcodes.ShadowRoot, [CONTENT.list(body), []], guid, mode];
+  }
+
   Component({ tag, params, args, blocks }: mir.Component): WireFormat.Statements.Component {
     let wireTag = EXPR.expr(tag);
     let wirePositional = CONTENT.ElementParameters(params);
diff --git a/packages/@glimmer/compiler/lib/passes/2-encoding/mir.ts b/packages/@glimmer/compiler/lib/passes/2-encoding/mir.ts
@@ -120,6 +120,12 @@ export class SimpleElement extends node('SimpleElement').fields<{
   dynamicFeatures: boolean;
 }>() {}
 
+export class DeclarativeShadowRoot extends node('DeclarativeShadowRoot').fields<{
+  guid: string;
+  mode: string;
+  body: Statement[];
+}>() {}
+
 export class ElementParameters extends node('ElementParameters').fields<{
   body: AnyOptionalList<ElementParameter>;
 }>() {}
@@ -214,6 +220,7 @@ export type Statement =
   | AppendTextNode
   | Component
   | SimpleElement
+  | DeclarativeShadowRoot
   | InvokeBlock
   | AppendComment
   | If
diff --git a/packages/@glimmer/compiler/lib/wire-format-debug.ts b/packages/@glimmer/compiler/lib/wire-format-debug.ts
@@ -56,6 +56,9 @@ export default class WireFormatDebugger {
             opcode[3] ? this.formatOpcode(opcode[3]) : undefined,
           ];
 
+        case Op.ShadowRoot:
+          return ['shadow-root', opcode[3], opcode[2]];
+
         case Op.OpenElement:
           return ['open-element', inflateTagName(opcode[1])];
 
diff --git a/packages/@glimmer/constants/lib/syscall-ops.ts b/packages/@glimmer/constants/lib/syscall-ops.ts
@@ -58,6 +58,7 @@ import type {
   VmNot,
   VmOp,
   VmOpenDynamicElement,
+  VmAttachShadowRoot,
   VmOpenElement,
   VmPop,
   VmPopArgs,
@@ -187,7 +188,8 @@ export const VM_IF_INLINE_OP = 109 satisfies VmIfInline;
 export const VM_NOT_OP = 110 satisfies VmNot;
 export const VM_GET_DYNAMIC_VAR_OP = 111 satisfies VmGetDynamicVar;
 export const VM_LOG_OP = 112 satisfies VmLog;
-export const VM_SYSCALL_SIZE = 113 satisfies VmSize;
+export const VM_ATTACH_SHADOW_ROOT_OP = 113 satisfies VmAttachShadowRoot;
+export const VM_SYSCALL_SIZE = 114 satisfies VmSize;
 
 export function isOp(value: number): value is VmOp {
   return value >= 16;
diff --git a/packages/@glimmer/interfaces/lib/compile/wire-format/api.d.ts b/packages/@glimmer/interfaces/lib/compile/wire-format/api.d.ts
@@ -47,6 +47,7 @@ import type {
   UndefinedOpcode,
   WithDynamicVarsOpcode,
   YieldOpcode,
+  ShadowRootOpcode,
 } from './opcodes.js';
 
 export type * from './opcodes.js';
@@ -300,6 +301,13 @@ export namespace Statements {
     blocks: Blocks | null,
   ];
 
+  export type ShadowRoot = [
+    op: ShadowRootOpcode,
+    block: SerializedInlineBlock,
+    guid: string,
+    mode: string,
+  ];
+
   /**
    * A Handlebars statement
    */
@@ -325,7 +333,8 @@ export namespace Statements {
     | Each
     | Let
     | WithDynamicVars
-    | InvokeComponent;
+    | InvokeComponent
+    | ShadowRoot;
 
   export type Attribute =
     | StaticAttr
diff --git a/packages/@glimmer/interfaces/lib/compile/wire-format/opcodes.d.ts b/packages/@glimmer/interfaces/lib/compile/wire-format/opcodes.d.ts
@@ -64,6 +64,7 @@ export type NotOpcode = 51;
 export type IfInlineOpcode = 52;
 export type GetDynamicVarOpcode = 53;
 export type LogOpcode = 54;
+export type ShadowRootOpcode = 55;
 
 export type GetStartOpcode = GetSymbolOpcode;
 export type GetEndOpcode = GetFreeAsComponentHeadOpcode;
diff --git a/packages/@glimmer/interfaces/lib/vm-opcodes.d.ts b/packages/@glimmer/interfaces/lib/vm-opcodes.d.ts
@@ -111,7 +111,8 @@ export type VmIfInline = 109;
 export type VmNot = 110;
 export type VmGetDynamicVar = 111;
 export type VmLog = 112;
-export type VmSize = 113;
+export type VmAttachShadowRoot = 113;
+export type VmSize = 114;
 
 export type VmOp =
   | VmHelper
@@ -206,6 +207,7 @@ export type VmOp =
   | VmIfInline
   | VmNot
   | VmGetDynamicVar
-  | VmLog;
+  | VmLog
+  | VmAttachShadowRoot;
 
 export type SomeVmOp = VmOp | VmMachineOp;
diff --git a/packages/@glimmer/opcode-compiler/lib/syntax/statements.ts b/packages/@glimmer/opcode-compiler/lib/syntax/statements.ts
@@ -6,6 +6,7 @@ import type {
   WireFormat,
 } from '@glimmer/interfaces';
 import {
+  VM_ATTACH_SHADOW_ROOT_OP,
   VM_CLOSE_ELEMENT_OP,
   VM_COMMENT_OP,
   VM_COMPONENT_ATTR_OP,
@@ -291,6 +292,33 @@ STATEMENTS.add(SexpOpcodes.InElement, (op, [, block, guid, destination, insertBe
   );
 });
 
+STATEMENTS.add(SexpOpcodes.ShadowRoot, (op, [, block, guid, mode]) => {
+  // Push guid and insertBefore (always undefined for shadow roots) onto the stack,
+  // then call VM_ATTACH_SHADOW_ROOT_OP which attaches a shadow root to the current
+  // parent element and pushes a reference to it. Use ReplayableIf so that the whole
+  // sequence is re-evaluated on update and so that SSR (where attachShadow is unavailable)
+  // gracefully falls through without rendering into a shadow root.
+  ReplayableIf(
+    op,
+
+    () => {
+      expr(op, guid);
+      PushPrimitiveReference(op, undefined); // insertBefore
+      PushPrimitiveReference(op, mode); // 'open' | 'closed'
+      op(VM_ATTACH_SHADOW_ROOT_OP);
+      op(VM_DUP_OP, $sp, 0);
+
+      return 4;
+    },
+
+    () => {
+      op(VM_PUSH_REMOTE_ELEMENT_OP);
+      InvokeStaticBlock(op, block);
+      op(VM_POP_REMOTE_ELEMENT_OP);
+    }
+  );
+});
+
 STATEMENTS.add(SexpOpcodes.If, (op, [, condition, block, inverse]) =>
   ReplayableIf(
     op,
diff --git a/packages/@glimmer/runtime/lib/compiled/opcodes/dom.ts b/packages/@glimmer/runtime/lib/compiled/opcodes/dom.ts
@@ -15,6 +15,7 @@ import type { Reference } from '@glimmer/reference';
 import type { Revision, Tag } from '@glimmer/validator';
 import {
   CURRIED_MODIFIER,
+  VM_ATTACH_SHADOW_ROOT_OP,
   VM_CLOSE_ELEMENT_OP,
   VM_COMMENT_OP,
   VM_DYNAMIC_ATTR_OP,
@@ -41,7 +42,7 @@ import {
 import { debugToString, expect } from '@glimmer/debug-util';
 import { associateDestroyableChild, destroy, registerDestructor } from '@glimmer/destroyable';
 import { getInternalModifierManager } from '@glimmer/manager';
-import { createComputeRef, isConstRef, valueForRef } from '@glimmer/reference';
+import { createComputeRef, createConstRef, isConstRef, valueForRef } from '@glimmer/reference';
 import { isIndexable } from '@glimmer/util';
 import { consumeTag, CURRENT_TAG, validateTag, valueForTag } from '@glimmer/validator';
 import { $t0 } from '@glimmer/vm';
@@ -126,6 +127,57 @@ APPEND_OPCODES.add(VM_POP_REMOTE_ELEMENT_OP, (vm) => {
   }
 });
 
+/**
+ * VM_ATTACH_SHADOW_ROOT_OP — declarative shadow DOM support.
+ *
+ * Pops the shadow root mode ('open' | 'closed') from the stack, then attaches
+ * a shadow root to the current parent element and pushes a const reference to
+ * it. The caller (via VM_PUSH_REMOTE_ELEMENT_OP) then uses that reference as
+ * the remote rendering target for the shadow root's children.
+ *
+ * Stack in (top → bottom):  mode, insertBefore, guid
+ * Stack out (top → bottom): shadowRoot ref, insertBefore, guid
+ *
+ * If the environment does not support shadow DOM (e.g. SSR with simple-dom),
+ * a null reference is pushed so that the surrounding ReplayableIf falls
+ * through without rendering any children.
+ */
+APPEND_OPCODES.add(VM_ATTACH_SHADOW_ROOT_OP, (vm) => {
+  const modeRef = check(vm.stack.pop(), CheckReference);
+  const mode = check(valueForRef(modeRef), CheckString) as ShadowRootMode;
+
+  // Get the current parent element from the element builder.
+  const rawParent = vm.tree().element as unknown as Element;
+
+  // Gracefully degrade in SSR/simple-dom environments that lack shadow DOM.
+  if (typeof rawParent.attachShadow !== 'function') {
+    vm.stack.push(createConstRef(null, false));
+    return;
+  }
+
+  // If an open shadow root already exists on this element (which happens when
+  // a component whose root is <template shadowrootmode="open"> re-renders into
+  // the same host element), reuse it after clearing its children.
+  let shadowRoot: ShadowRoot;
+  const existingShadowRoot = rawParent.shadowRoot;
+
+  if (existingShadowRoot) {
+    existingShadowRoot.replaceChildren();
+    shadowRoot = existingShadowRoot;
+  } else {
+    try {
+      shadowRoot = rawParent.attachShadow({ mode });
+    } catch {
+      // attachShadow can throw if the element already has a closed shadow root
+      // or is not a valid shadow host. Fall back gracefully.
+      vm.stack.push(createConstRef(null, false));
+      return;
+    }
+  }
+
+  vm.stack.push(createConstRef(shadowRoot as unknown as SimpleElement, false));
+});
+
 APPEND_OPCODES.add(VM_FLUSH_ELEMENT_OP, (vm) => {
   let operations = check(vm.fetchValue($t0), CheckOperations);
   let modifiers: Nullable<ModifierInstance[]> = null;
diff --git a/packages/@glimmer/runtime/lib/vm/element-builder.ts b/packages/@glimmer/runtime/lib/vm/element-builder.ts
diff --git a/packages/@glimmer/wire-format/lib/opcodes.ts b/packages/@glimmer/wire-format/lib/opcodes.ts

Original file line number	Diff line number	Diff line change
`@@ -100,6 +100,9 @@ export default class StrictModeValidationPass {`
`100`	`100`
`101`	`101`	`case 'InvokeComponent':`
`102`	`102`	`return this.InvokeComponent(statement);`
	`103`	`+`
	`104`	`+ case 'DeclarativeShadowRoot':`
	`105`	`+ return this.DeclarativeShadowRoot(statement);`
`103`	`106`	`}`
`104`	`107`	`}`
`105`	`108`
`@@ -268,6 +271,10 @@ export default class StrictModeValidationPass {`
`268`	`271`	`return this.ElementParameters(statement.params).andThen(() => this.Statements(statement.body));`
`269`	`272`	`}`
`270`	`273`
	`274`	`+ DeclarativeShadowRoot(statement: mir.DeclarativeShadowRoot): Result<null> {`
	`275`	`+ return this.Statements(statement.body);`
	`276`	`+ }`
	`277`	`+`
`271`	`278`	`InvokeBlock(statement: mir.InvokeBlock): Result<null> {`
`272`	`279`	`return this.Expression(statement.head, statement.head, COMPONENT_RESOLUTION)`
`273`	`280`	`.andThen(() => this.Args(statement.args))`