Svelte 5 Runes Fine-Grained Reactive State & Deep Mutation Isolation

--- description: Svelte 5 Runes Fine-Grained Reactive State & Deep Mutation Isolation - Enforces strict isolation boundaries around Svelte 5 $state proxies to eliminate microfrontend state tearing, infinite cyclic re-render loops, and untracked cross-boundary mutations. Requires explicit read/write separation via $state.snapshot, strict $state.raw for external payload exchanges, and mandatory untrack() encapsulation in effects. globs: src/**/*.{svelte,svelte.ts,ts} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/svelte-5-runes-mutation-isolation-boundaries" --- # Svelte 5 Runes Fine-Grained Reactive State & Deep Mutation Isolation > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Leaking Deep $state Proxies Across Boundaries and Triggering Cascading Reactive Loops via Implicit Effect Reads ## System Constraints You are a Principal Engineer enforcing Svelte 5 Runes Fine-Grained Reactive State & Deep Mutation Isolation. Mandate invariants that prevent infinite reactive loops, race-driven state tearing across microfrontends, and deep proxy leaks across component boundaries. Enforce $state.raw, $state.snapshot, and untrack() strictly where isolation is required. ## Strict Guidelines - Engineers MUST ALWAYS use $state.snapshot(proxy) or structuredClone() when emitting state over CustomEvent, window message buses, or cross-microfrontend boundaries to prevent leaking mutating proxies. - Engineers MUST NOT read reactive proxy dependencies inside an $effect when performing mutations that touch the same dependency tree, unless wrapped in untrack(). - Code SHOULD prefer $state.raw for external, immutable, or large third-party data structures to prevent unnecessary deep proxy wrapping and memory overhead. - Services MUST encapsulate reactive state within dedicated domain classes or module closures using the .svelte.ts extension, exposing only readonly getters or immutable projections. - Components NEVER directly mutate reactive objects received via props from parent microfrontends; all upstream changes must dispatch explicit actions or callback contracts. ## Bad vs Good Implementations ### Preventing Reactive Proxy Leaks and Cascading Effect Loops #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Emitting this.cart.items leaks a reactive Proxy object to other microfrontends, allowing external unmonitored mutations. Inside syncRemote, reading this.cart.items within an $effect that pushes to this.cart.items triggers an infinite synchronous re-run loop and state tearing. ```typescript // Microfrontend communication leaking deep reactive proxy import { untrack } from 'svelte'; class MicrofrontendCartStore { cart = $state({ items: [] as Array<{ id: string; qty: number }> }); constructor() { $effect(() => { // BAD: Reading cart.items creates a dependency on cart.items mutations // BAD: Emitting raw $state proxy across window boundary causes state tearing window.dispatchEvent(new CustomEvent('mfe:cart-updated', { detail: this.cart.items })); }); } syncRemote(item: { id: string; qty: number }) { $effect(() => { // BAD: Implicit dependency cycle: reads cart.items and mutates it inside $effect const exists = this.cart.items.find(i => i.id === item.id); if (!exists) { this.cart.items.push(item); } }); } } ``` #### Production Standard (Correct) > **Standard**: The store encapsulates #cart using private fields, emits non-reactive snapshots via $state.snapshot() over the event bus, and uses untrack() to read the current array state without establishing a feedback loop inside effects. ```typescript // Isolated state boundaries with $state.snapshot and untrack import { untrack } from 'svelte'; export class MicrofrontendCartStore { #cart = $state({ items: [] as Array<{ id: string; qty: number }> }); constructor() { $effect(() => { // Track only item length changes; snapshot payload to strip reactive proxies const count = this.#cart.items.length; const payload = untrack(() => $state.snapshot(this.#cart.items)); window.dispatchEvent(new CustomEvent('mfe:cart-updated', { detail: { count, items: payload } })); }); } get items(): readonly { id: string; qty: number }[] { return this.#cart.items; } syncRemote(item: { id: string; qty: number }): void { // GOOD: Explicit mutation method outside effect, or untracked read const exists = untrack(() => this.#cart.items.some(i => i.id === item.id)); if (!exists) { this.#cart.items.push(Object.freeze({ ...item })); } } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Svelte 5 Runes Fine-Grained Reactive State & Deep Mutation Isolation

Svelte 5 Runes Fine-Grained Reactive State & Deep Mutation Isolation defines an industrial-grade behavioral standard for frontend engineering. Enforces strict isolation boundaries around Svelte 5 $state proxies to eliminate microfrontend state tearing, infinite cyclic re-render loops, and untracked cross-boundary mutations. Requires explicit read/write separation via $state.snapshot, strict $state.raw for external payload exchanges, and mandatory untrack() encapsulation in effects. 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 Deep $state Proxies Across Boundaries and Triggering Cascading Reactive Loops via Implicit Effect Reads 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 Deep $state Proxies Across Boundaries and Triggering Cascading Reactive Loops via Implicit Effect Reads	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 use $state.snapshot(proxy) or structuredClone() when emitting state over CustomEvent, window message buses, or cross-microfrontend boundaries to prevent leaking mutating proxies.

Engineers MUST ALWAYS use $state.snapshot(proxy) or structuredClone() when emitting state over CustomEvent, window message buses, or cross-microfrontend boundaries to prevent leaking mutating proxies.

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.