Svelte 5 Runes Shadow DOM Hydration and Micro-Frontend Memory Boundary

--- description: Svelte 5 Runes Shadow DOM Hydration and Micro-Frontend Memory Boundary - Enforces strict lifecycle boundaries and reactive runtime isolation when mounting Svelte 5 Custom Elements within Shadow DOM boundaries. Prevents cross-micro-frontend reactive context leakage, orphaned Rune signal graph subscriptions, and dual-tree DOM reconciliation conflicts between host and guest runtimes. globs: src/**/*.svelte, src/**/*.wc.ts, src/**/elements/**/*.ts, src/**/micro-frontends/**/*.ts alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/svelte5-runes-shadow-dom-hydration-boundary-standard" --- # Svelte 5 Runes Shadow DOM Hydration and Micro-Frontend Memory Boundary > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Leaking Svelte 5 Signal Graphs and Orphaned Effect Roots across Unmanaged Custom Element Shadow Roots ## System Constraints You are a Principal Software Architect enforcing the Svelte 5 Runes Shadow DOM Hydration Boundary Standard. Svelte 5 introduces fine-grained reactive primitives ($state, $effect, $derived) driven by signals. When compiling components to Custom Elements (<svelte:options customElement=.../>) or manually mounting them inside Shadow Roots via `mount()` or `hydrate()`, runtime boundaries must guarantee zero signal-graph leaks across custom element lifecycles. You must enforce explicit effect root tearing (`unmount()`), prevent cross-boundary direct signal sharing, enforce isolated event bridging through composed CustomEvents, and ensure server-rendered Declarative Shadow DOM (DSD) trees pass strict node hydration checks without DOM desynchronization. ## Strict Guidelines - Engineers MUST ALWAYS invoke Svelte 5 `unmount()` inside the Custom Element's `disconnectedCallback()` to destroy the internal Rune effect tree and cancel all active signals. - Engineers MUST NOT pass raw Svelte 5 reactive proxy objects ($state) across Custom Element boundaries; all inputs must be normalized via primitive attributes, serializable properties, or encapsulated getter/setter bridges. - Custom Element wrappers MUST explicitly define `shadow: 'open'` and configure styles using adoptedStyleSheets to isolate CSSOM recalculations from parent reactive invalidation cycles. - Components rendered into existing Declarative Shadow DOM (DSD) MUST use `hydrate()` with exact boundary matching instead of `mount()` to prevent memory-ballooning DOM recreation and duplicated listeners. - Micro-frontend custom elements NEVER register shared global stores or module-level Rune singletons across independent shadow root boundaries without an explicit scoped Context API or Event Target bridge. - Engineers MUST wrap all external DOM MutationObservers and host resize listeners inside Svelte 5 `$effect()` cleanup closures or the web component's `disconnectedCallback()` to guarantee zero memory retention upon unmount. ## Bad vs Good Implementations ### Custom Element Micro-Frontend Lifecycle & Shadow Root Hydration #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Failing to mount inside a Shadow Root leaks internal styling and DOM queries to the host document. Omitting `unmount()` in `disconnectedCallback()` permanently retains the Svelte 5 component instance and its internal signal reactivity tree, creating a severe memory leak across SPA navigation cycles. ```typescript import { mount } from 'svelte'; import Widget from './Widget.svelte'; export class MicroFrontendWidget extends HTMLElement { private app: any; connectedCallback() { // Anti-pattern: mounting without shadow boundary isolation, // leaking DOM queries and styles into global document tree. this.app = mount(Widget, { target: this, props: { user: (window as any).globalUserState } }); } disconnectedCallback() { // Anti-pattern: omitting unmount(), causing active Svelte 5 $effect // and Rune signal graphs to remain active in memory indefinitely. } } customElements.define('mf-widget', MicroFrontendWidget); ``` #### Production Standard (Correct) > **Standard**: The component is mounted strictly within an encapsulated ShadowRoot, preventing CSS contamination and DOM bleed. In `disconnectedCallback()`, `unmount()` tears down the entire Svelte 5 Rune signal root, completely releasing memory and halting reactive listeners. ```typescript import { mount, unmount } from 'svelte'; import Widget from './Widget.svelte'; export interface WidgetProps { userId: string; theme?: 'light' | 'dark'; } export class MicroFrontendWidget extends HTMLElement { private componentInstance: Record<string, unknown> | null = null; private shadow: ShadowRoot; constructor() { super(); this.shadow = this.attachShadow({ mode: 'open' }); } connectedCallback(): void { if (this.componentInstance) return; const userId = this.getAttribute('user-id') ?? ''; const theme = (this.getAttribute('theme') as 'light' | 'dark') ?? 'light'; // Invariant: Mount inside dedicated ShadowRoot; isolate signal graph this.componentInstance = mount(Widget, { target: this.shadow, props: { userId, theme } }); } disconnectedCallback(): void { if (this.componentInstance) { // Invariant: Unmount completely destroys Rune root effect scope unmount(this.componentInstance); this.componentInstance = null; } } attributeChangedCallback(name: string, _oldValue: string | null, newValue: string | null): void { // Bound updates must re-synchronize cleanly without leaking proxy references if (this.componentInstance && name === 'theme') { (this.componentInstance as any).theme = newValue ?? 'light'; } } static get observedAttributes(): string[] { return ['user-id', 'theme']; } } customElements.define('mf-widget', MicroFrontendWidget); ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Svelte 5 Runes Shadow DOM Hydration and Micro-Frontend Memory Boundary

Svelte 5 Runes Shadow DOM Hydration and Micro-Frontend Memory Boundary defines an industrial-grade behavioral standard for frontend engineering. Enforces strict lifecycle boundaries and reactive runtime isolation when mounting Svelte 5 Custom Elements within Shadow DOM boundaries. Prevents cross-micro-frontend reactive context leakage, orphaned Rune signal graph subscriptions, and dual-tree DOM reconciliation conflicts between host and guest runtimes. 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: Leaking Svelte 5 Signal Graphs and Orphaned Effect Roots across Unmanaged Custom Element Shadow Roots 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	Leaking Svelte 5 Signal Graphs and Orphaned Effect Roots across Unmanaged Custom Element Shadow Roots	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 invoke Svelte 5 `unmount()` inside the Custom Element's `disconnectedCallback()` to destroy the internal Rune effect tree and cancel all active signals.

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.