Declarative Shadow DOM SSR Hydration Boundary Isolation Standard

--- description: Declarative Shadow DOM SSR Hydration Boundary Isolation Standard - Enforces strict Declarative Shadow DOM (DSD) boundaries for server-rendered web components and micro-frontends to eliminate Cumulative Layout Shift (CLS) and DOMException conflicts during client hydration. Mandates the use of standardized template attributes and non-destructive shadow root adoption before client scripts execute. globs: src/**/*.{ts,tsx,js,jsx}, server/**/*.{ts,tsx,js,jsx}, packages/**/src/**/*.{ts,tsx,js,jsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/declarative-shadow-dom-ssr-hydration-boundary-standard" --- # Declarative Shadow DOM SSR Hydration Boundary Isolation Standard > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Imperative attachShadow Overwrites and Missing shadowrootmode Fallbacks Causing FOUC and Hydration Crashes ## System Constraints You are a Principal Software Architect enforcing Declarative Shadow DOM (DSD) SSR Hydration standards across distributed micro-frontend architectures. You must prevent hydration mismatches, layout shifts, and runtime DOMExceptions by ensuring all server-side components emit standard <template shadowrootmode="open"> payloads, and client custom element definitions non-destructively adopt existing shadow roots rather than calling attachShadow unconditionally. ## Strict Guidelines - Components MUST emit server-side templates with 'shadowrootmode="open"' (and never deprecated 'shadowroot="open"') along with explicit layout dimension constraints to prevent Cumulative Layout Shift. - Engineers MUST NOT unconditionally execute 'this.attachShadow({ mode: 'open' })' in connectedCallback or constructors without first checking if 'this.shadowRoot' already exists from SSR. - Client hydration logic MUST adopt existing DOM child nodes of the pre-rendered shadow root rather than overwriting 'shadowRoot.innerHTML', preserving event listener attachment points and input state. - Micro-frontend hosts MUST include a polyfill script or inline cross-browser DSD parser before rendering blocking resources in browsers lacking native Declarative Shadow DOM support. - Styles encapsulated within a Declarative Shadow DOM template MUST be injected via inline '<style>' elements or adopted CSSStyleSheet objects marked with critical containment tokens to isolate cascade bleeding. ## Bad vs Good Implementations ### Adopting Existing Declarative Shadow DOM in Custom Element Hydration #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Calling attachShadow on an element that was pre-rendered using Declarative Shadow DOM throws an 'InvalidStateError: Shadow root cannot be created on a host which already hosts a shadow tree' DOMException, breaking client-side execution. ```typescript class UserProfileWidget extends HTMLElement { connectedCallback() { // Anti-pattern: Unconditionally calling attachShadow throws DOMException if DSD is present, // or wiping innerHTML causes severe layout shifts and destroys server-rendered DOM nodes. const shadow = this.attachShadow({ mode: 'open' }); shadow.innerHTML = ` <style>:host { display: block; }</style> <div class="profile">Loading...</div> `; this.bindEvents(); } private bindEvents() {} } ``` #### Production Standard (Correct) > **Standard**: Checks 'this.shadowRoot' first to preserve the SSR-rendered tree, preventing DOMException, avoiding layout shifts, and selectively binding event listeners to pre-existing DOM elements. ```typescript class UserProfileWidget extends HTMLElement { private shadow!: ShadowRoot; connectedCallback() { // Invariant: Non-destructively adopt existing shadowRoot created via DSD SSR this.shadow = this.shadowRoot ?? this.attachShadow({ mode: 'open' }); if (this.shadow.childElementCount > 0) { // Hydration path: Nodes already rendered by SSR; attach listeners without re-rendering markup this.hydrateExistingNodes(this.shadow); } else { // Client-only fallback path if SSR template was omitted this.renderFallbackMarkup(this.shadow); } this.bindEvents(this.shadow); } private hydrateExistingNodes(root: ShadowRoot): void { // Bind dynamic state to SSR elements directly } private renderFallbackMarkup(root: ShadowRoot): void { root.innerHTML = `<style>:host { display: block; min-height: 48px; }</style><div class="profile"></div>`; } private bindEvents(root: ShadowRoot): void {} } ``` ### Server-Side Rendering of Declarative Shadow DOM Boundary #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Without the Declarative Shadow DOM template tag, child content is treated as light DOM slots, rendering without style isolation and causing flash of unstyled content (FOUC) when custom element definitions register. ```typescript export function renderMicroFrontend(userId: string): string { // Anti-pattern: Missing shadowrootmode or using legacy non-standard shadowroot attribute // Allows CSS to leak and delays shadow tree creation until client JS evaluates. return ` <user-profile-widget data-user-id="${userId}"> <div class="profile-inner"> <span>User ${userId}</span> </div> </user-profile-widget> `; } ``` #### Production Standard (Correct) > **Standard**: Emits standard '<template shadowrootmode="open">' with encapsulated containment styling, allowing the browser engine to immediately construct the shadow tree upon HTML parsing prior to JS bundle execution. ```typescript export function renderMicroFrontend(userId: string): string { // Invariant: Standard shadowrootmode="open" isolates styling and geometry before client JS executes return ` <user-profile-widget data-user-id="${userId}"> <template shadowrootmode="open"> <style> :host { display: block; contain: content; min-height: 48px; } .profile-inner { font-family: var(--ds-font-sans, sans-serif); } </style> <div class="profile-inner"> <span>User ${userId}</span> </div> </template> </user-profile-widget> `; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Declarative Shadow DOM SSR Hydration Boundary Isolation Standard

Declarative Shadow DOM SSR Hydration Boundary Isolation Standard defines an industrial-grade behavioral standard for frontend engineering. Enforces strict Declarative Shadow DOM (DSD) boundaries for server-rendered web components and micro-frontends to eliminate Cumulative Layout Shift (CLS) and DOMException conflicts during client hydration. Mandates the use of standardized template attributes and non-destructive shadow root adoption before client scripts execute. Modern software architectures require strict adherence to deterministic patterns to guarantee high availability, maintainability, and zero security vulnerabilities.

Framework Paradigm Shift & Drift MechanicsLLMs are trained on millions of open-source repositories containing outdated code, legacy idioms, and unpatched antipatterns. When coding assistants generate implementations for this stack, they default to common statistical tokens: Imperative attachShadow Overwrites and Missing shadowrootmode Fallbacks Causing FOUC and Hydration Crashes Without an explicit system instruction file, developers spend hours debugging silent failures.

Failure Modes & Production Blast Radius

Hazard Analysis: What Breaks Without This Rule

The following failure modes have been cataloged from hundreds of hours of production code reviews where AI assistants produced non-compliant implementations:

Failure Mode	AI Symptom (The Anti-Pattern)	Severity	Production Impact & Remedy
AI Hallucination & Deprecation Drift	Imperative attachShadow Overwrites and Missing shadowrootmode Fallbacks Causing FOUC and Hydration Crashes	Critical	Violating this industrial standard introduces regression bugs, security risks, and unexpected runtime failures in production. Enforce explicit behavioral system directives across all AI coding assistants in your repository.
Silent Architecture Inconsistency	AI assistants produce mixed paradigms across files, creating fragmented codebase conventions.	Medium	Increases cognitive load during code reviews and leads to maintenance debt across engineering teams. Pin project conventions in .cursor/rules, CLAUDE.md, and AGENTS.md so all team agents follow identical guardrails.

Architectural Directives in Detail

Step-by-Step Production Directives

Each rule constraint below is injected into the AI agent's system prompt to establish deterministic boundaries:

Components MUST emit server-side templates with 'shadowrootmode="open"' (and never deprecated 'shadowroot="open"') along with explicit layout dimension constraints to prevent Cumulative Layout Shift.

Rationale:AI models frequently generate unconstrained code here because statistical language distributions lack project-specific architectural context. Mandating this directive ensures that generated code adheres to verified industrial production requirements.