Svelte 5 Runes Async Hydration Boundary Guardrail

--- description: Svelte 5 Runes Async Hydration Boundary Guardrail - Enforces strict isolation of asynchronous microtask execution from Svelte 5 synchronous signal tracking to prevent reactive graph tearing. In Svelte 5, the active reactive tracking context ($effect, $derived) is synchronously bound and detaches across await points and microtask queues. This rule prevents orphaned signals, missed invalidations, and DOM hydration mismatches between SSR streaming chunks and client signal graphs. globs: src/**/*.{svelte,svelte.ts,svelte.js,ts} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/svelte-5-runes-async-hydration-boundary" --- # Svelte 5 Runes Async Hydration Boundary Guardrail > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Microtask Suspension Within Runes Tracking Context Causing Hydration Graph Tearing ## System Constraints You are a Principal Engineer enforcing Svelte 5 Runes Async Hydration Boundary Guardrails. Mandate that asynchronous microtasks must never tear Svelte 5 fine-grained reactive contexts ($derived, $effect, $state). Enforce clean synchronous dependency collection, strict separation of async dispatch via untrack or explicit controller patterns, and prevention of hydration race conditions during SSR streaming. ## Strict Guidelines - Engineers MUST ALWAYS capture all reactive dependencies synchronously at the top of an $effect before any asynchronous microtask or await expression. - Engineers MUST NOT read dynamic $state runes after an await boundary inside an $effect expecting reactive tracking, as Svelte 5 tracking contexts do not survive microtask suspension. - Engineers MUST wrap asynchronous state mutations initiated inside tracking scopes with untrack() to prevent uncoordinated downstream reaction scheduling during DOM hydration. - Components NEVER execute raw async IIFEs directly inside $effect without cleanup handlers and abortable signal controllers to avoid streaming SSR / client hydration race conditions. - Code MUST isolate SSR streaming promises through SvelteKit page data load mechanisms or explicit suspense boundaries rather than unmanaged top-level client signal mutations. ## Bad vs Good Implementations ### Async State Mutation Inside $effect Tracking Scope #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: In Svelte 5, reactive tracking is strictly synchronous. The async IIFE detaches tracking at the first 'await', so dependencies accessed later are ignored. Mutating 'profile' across microtask boundaries without proper cancellation or isolation races against the client hydration of SSR streamed HTML. ```typescript import { onMount } from 'svelte'; let userId = $state('user-1'); let profile = $state<Record<string, unknown> | null>(null); // ANTI-PATTERN: Async microtasks inside $effect cause reactive graph tearing. // The tracking context is lost after 'await', while setting profile here can race // against SSR streaming hydration nodes and leave stale/broken dependencies. $effect(() => { (async () => { const response = await fetch(`/api/users/${userId}`); profile = await response.json(); // Graph tearing: untracked dependency resolution })(); }); ``` #### Production Standard (Correct) > **Standard**: Dependencies are registered synchronously at the top of the $effect. The actual asynchronous execution is insulated within untrack() and protected by an AbortController returned in the cleanup function, guaranteeing no hydration graph tearing or state corruption across SSR stream phases. ```typescript import { untrack } from 'svelte'; let userId = $state('user-1'); let profile = $state<Record<string, unknown> | null>(null); // PRODUCTION FIX: Explicit synchronous capture, abort controller cleanup, // and untracked asynchronous execution boundary. $effect(() => { const currentId = userId; // Synchronously register reactive dependency const controller = new AbortController(); untrack(() => { fetch(`/api/users/${currentId}`, { signal: controller.signal }) .then((res) => { if (!res.ok) throw new Error('Fetch failed'); return res.json(); }) .then((data) => { profile = data; }) .catch((err) => { if (err.name !== 'AbortError') { console.error('Hydration safe error boundary:', err); } }); }); return () => { controller.abort(); }; }); ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Svelte 5 Runes Async Hydration Boundary Guardrail

Svelte 5 Runes Async Hydration Boundary Guardrail defines an industrial-grade behavioral standard for frontend engineering. Enforces strict isolation of asynchronous microtask execution from Svelte 5 synchronous signal tracking to prevent reactive graph tearing. In Svelte 5, the active reactive tracking context ($effect, $derived) is synchronously bound and detaches across await points and microtask queues. This rule prevents orphaned signals, missed invalidations, and DOM hydration mismatches between SSR streaming chunks and client signal graphs. 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: Microtask Suspension Within Runes Tracking Context Causing Hydration Graph Tearing 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	Microtask Suspension Within Runes Tracking Context Causing Hydration Graph Tearing	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 capture all reactive dependencies synchronously at the top of an $effect before any asynchronous microtask or await expression.

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.