Declarative Shadow DOM Hydration Boundary & Isolation Standard

--- description: Declarative Shadow DOM Hydration Boundary & Isolation Standard - Enforces deterministic, non-destructive streaming hydration for Web Components utilizing Declarative Shadow DOM (DSD) across heterogeneous micro-frontends. Eliminates runtime DOMExceptions caused by redundant shadow root attachment, prevents Flash of Unstyled Content (FOUC) during chunked SSR streaming, and prevents memory leaks from detached event boundaries in nested framework islands. globs: src/**/*.{ts,tsx,js,jsx}, packages/**/*.{ts,tsx,js,jsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/dsd-hydration-boundary-streaming-isolation" --- # Declarative Shadow DOM Hydration Boundary & Isolation Standard > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Destructive Re-Attachment of Existing Declarative Shadow Roots and InnerHTML Hydration Wipeouts ## System Constraints You are a Principal Software Architect enforcing production-grade Web Components Declarative Shadow DOM (DSD) standards. You must ensure all custom element hydration routines check for pre-existing declarative shadow roots, preserve SSR DOM structures during streaming, isolate framework-specific lifecycles (React, Vue, Svelte, Lit), and eliminate flash of unstyled content (FOUC) through atomic stylesheet adoption. ## Strict Guidelines - Engineers MUST ALWAYS query and preserve `this.shadowRoot` before invoking `this.attachShadow()`; calling `attachShadow()` unconditionally on a DSD-rendered component throws an unrecoverable DOMException. - Engineers MUST NOT overwrite `shadowRoot.innerHTML` or clear shadow children during client-side hydration; hydration must non-destructively bind listeners and reconcile existing DOM nodes. - Components NEVER execute imperative slot re-assignment or DOM mutation until streaming completes and all nested hydration boundaries emit a resolved boundary event. - Services MUST compile SSR output using the standard `<template shadowrootmode="open">` specification and avoid legacy `shadowroot` attributes. - Code SHOULD adopt shared CSS via constructable stylesheets (`shadowRoot.adoptedStyleSheets`) upon hydration to prevent duplicating static CSS text nodes inside the shadow root. ## Bad vs Good Implementations ### DSD Custom Element Hydration and Style Adoption #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Calling `attachShadow()` on a host that already contains a Declarative Shadow Root generated by the server causes a fatal JavaScript DOMException. Overwriting `shadow.innerHTML` causes a visual Flash of Unstyled Content (FOUC) and unmounts any nested micro-frontend islands streaming within slotted or internal DOM boundaries. ```typescript import { LitElement, html } from 'lit'; export class MicroFrontendContainer extends HTMLElement { connectedCallback() { // ANTI-PATTERN: Throws DOMException if already rendered via DSD streaming SSR. // Re-creating the shadow root destroys SSR DOM nodes and wipes nested framework state. const shadow = this.attachShadow({ mode: 'open' }); shadow.innerHTML = ` <style>:host { display: block; min-height: 100px; }</style> <div class="mfe-root"> <slot></slot> </div> `; this.bindEvents(shadow); } private bindEvents(root: ShadowRoot) { root.addEventListener('click', () => console.log('clicked')); } } customElements.define('mfe-container', MicroFrontendContainer); ``` #### Production Standard (Correct) > **Standard**: Safely acquires `this.shadowRoot` without throwing a DOMException when DSD is present, preserves server-streamed internal DOM structures, applies constructable stylesheets deterministically, and implements clean hydration guards with leak-free teardown. ```typescript const sheet = new CSSStyleSheet(); sheet.replaceSync(':host { display: block; min-height: 100px; }'); export class MicroFrontendContainer extends HTMLElement { private isHydrated = false; connectedCallback() { // PRODUCTION FIX: Resolve existing declarative shadow root or create fallback for CSR let root = this.shadowRoot; if (!root) { root = this.attachShadow({ mode: 'open' }); root.innerHTML = '<div class="mfe-root"><slot></slot></div>'; } // Prevent duplicate hydration passes in streaming chunk boundaries if (this.isHydrated) return; this.isHydrated = true; // Efficiently adopt styles without causing FOUC or DOM duplication if (root.adoptedStyleSheets.length === 0) { root.adoptedStyleSheets = [sheet]; } this.hydrateSubtree(root); } private hydrateSubtree(root: ShadowRoot): void { const trigger = root.querySelector('.mfe-root'); if (trigger) { trigger.addEventListener('click', this.handleClick, { passive: true }); } } private handleClick = (event: Event): void => { this.dispatchEvent(new CustomEvent('mfe-select', { bubbles: true, composed: true })); }; disconnectedCallback() { const trigger = this.shadowRoot?.querySelector('.mfe-root'); trigger?.removeEventListener('click', this.handleClick); this.isHydrated = false; } } if (!customElements.get('mfe-container')) { customElements.define('mfe-container', MicroFrontendContainer); } ```

Architectural Specification & Invariant Rationale

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

Declarative Shadow DOM Hydration Boundary & Isolation Standard defines an industrial-grade behavioral standard for frontend engineering. Enforces deterministic, non-destructive streaming hydration for Web Components utilizing Declarative Shadow DOM (DSD) across heterogeneous micro-frontends. Eliminates runtime DOMExceptions caused by redundant shadow root attachment, prevents Flash of Unstyled Content (FOUC) during chunked SSR streaming, and prevents memory leaks from detached event boundaries in nested framework islands. 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: Destructive Re-Attachment of Existing Declarative Shadow Roots and InnerHTML Hydration Wipeouts 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	Destructive Re-Attachment of Existing Declarative Shadow Roots and InnerHTML Hydration Wipeouts	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:

Engineers MUST ALWAYS query and preserve `this.shadowRoot` before invoking `this.attachShadow()`

Engineers MUST ALWAYS query and preserve `this.shadowRoot` before invoking `this.attachShadow()`; calling `attachShadow()` unconditionally on a DSD-rendered component throws an unrecoverable DOMException.

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.