Svelte 5 Snippet Hydration Mismatch Boundary Guardrail

--- description: Svelte 5 Snippet Hydration Mismatch Boundary Guardrail - Enforces strict isolation boundaries around Svelte 5 snippets subjected to asynchronous or dynamic state drift during SSR hydration. Prevents structural tree tear-down by isolating snippet invocations inside targeted boundary components, preserving fine-grained reactive runes ($state, $derived) in sibling nodes during reconciliation. globs: src/**/*.{svelte,svelte.ts,svelte.js} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/svelte-5-snippet-hydration-mismatch-boundary" --- # Svelte 5 Snippet Hydration Mismatch Boundary Guardrail > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Global Subtree Unmounting Caused by Bare Dynamic Snippets During Async Hydration Drift ## System Constraints You are a Principal Engineer enforcing Svelte 5 Snippet Hydration Mismatch Boundary Guardrails. Mandate architectural isolation for server-rendered snippets subject to asynchronous or client-derived state divergence. Ensure that runtime hydration failures in polymorphic or conditionally rendered snippet closures do not cascade to invalidate adjacent fine-grained reactive signals ($state, $derived, $effect). Require explicit hydration keys or boundary components for snippets whose parameters depend on dynamic, time-dependent, or non-deterministic client state. ## Strict Guidelines - Engineers MUST ALWAYS isolate dynamically evaluated snippets within dedicated client boundary wrappers when arguments diverge between SSR and client mounting. - Engineers MUST NOT pass non-deterministic or lazily resolved client promises directly into top-level snippet calls without guarding fallback structures. - Components MUST encapsulate volatile snippets within key blocks or key-anchored boundaries to prevent hydration mismatch cascading across sibling runes. - Engineers MUST preserve root $state references by decoupling snippet render targets from parent reactive signals via localized derived proxies or deterministic props. - Components NEVER execute raw browser-dependent DOM operations or storage reads directly inside pure snippet argument expressions during initial hydration. ## Bad vs Good Implementations ### Volatile Snippet Invocation vs Hydration-Bounded Snippet Architecture #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Directly rendering the snippet with inconsistent server/client arguments (such as non-deterministic timestamps or un-synchronized session objects) causes Svelte 5's hydration phase to encounter mismatched DOM nodes. This invalidates the enclosing hydration context, forcing a catastrophic DOM tear-and-rebuild that resets fine-grained reactive state (like criticalCounter) and destroys local child rune instances. ```svelte <script lang="ts"> import { onMount } from 'svelte'; let userSession = $state<{ id: string; role: string } | null>(null); let criticalCounter = $state(0); // Anti-pattern: Reading non-deterministic client-state immediately in component root // leads to SSR vs Client markup drift during {@render snippet()} execution let clientTimestamp = Date.now(); </script> {#snippet userCard(session: { id: string; role: string } | null, ts: number)} <div class="session-card"> <p>User: {session ? session.id : 'Guest'}</p> <p>Synced: {ts}</p> </div> {/snippet}   <div class="dashboard"> <button onclick={() => criticalCounter++}>Count: {criticalCounter}</button> {@render userCard(userSession, clientTimestamp)} </div> ``` #### Production Standard (Correct) > **Standard**: By isolating the dynamic snippet inside a {#key isHydrated} boundary and ensuring the SSR tree renders deterministic default values (null timestamp/syncing placeholder), hydration succeeds without DOM mismatches. When mounting completes, only the isolated snippet boundary re-renders, preventing cascade unmounts and preserving fine-grained sibling runes like criticalCounter. ```svelte <script lang="ts"> import { onMount } from 'svelte'; import type { Snippet } from 'svelte'; interface SessionData { id: string; role: string; } let userSession = $state<SessionData | null>(null); let criticalCounter = $state(0); let isHydrated = $state(false); let clientTimestamp = $state<number | null>(null); onMount(() => { isHydrated = true; clientTimestamp = Date.now(); }); </script> {#snippet userCard(session: SessionData | null, ts: number | null)} <div class="session-card"> <p>User: {session ? session.id : 'Guest'}</p> {#if ts !== null} <p>Synced: {ts}</p> {:else} <p>Syncing...</p> {/if} </div> {/snippet} <div class="dashboard">  <button onclick={() => criticalCounter++}>Count: {criticalCounter}</button>  <div class="snippet-hydration-boundary"> {#key isHydrated} {@render userCard(userSession, clientTimestamp)} {/key} </div> </div> ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Svelte 5 Snippet Hydration Mismatch Boundary Guardrail

Svelte 5 Snippet Hydration Mismatch Boundary Guardrail defines an industrial-grade behavioral standard for frontend engineering. Enforces strict isolation boundaries around Svelte 5 snippets subjected to asynchronous or dynamic state drift during SSR hydration. Prevents structural tree tear-down by isolating snippet invocations inside targeted boundary components, preserving fine-grained reactive runes ($state, $derived) in sibling nodes during reconciliation. 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: Global Subtree Unmounting Caused by Bare Dynamic Snippets During Async Hydration Drift 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	Global Subtree Unmounting Caused by Bare Dynamic Snippets During Async Hydration Drift	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 isolate dynamically evaluated snippets within dedicated client boundary wrappers when arguments diverge between SSR and client mounting.

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.