Svelte 5 Runes Reactive Isolation & Deep Proxy Trap Guardrails

--- description: Svelte 5 Runes Reactive Isolation & Deep Proxy Trap Guardrails - Enforces strict fine-grained reactivity boundaries in Svelte 5 by preventing deep proxy leaks into external systems and eliminating destructuring-induced reactive loss. Guarantees memory safety and deterministic rendering through explicit $state.raw usage for heavy/external references and $state.snapshot for boundary handoffs. globs: **/*.svelte, **/*.svelte.ts, **/*.svelte.js alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/svelte-5-runes-reactive-isolation-proxy-traps" --- # Svelte 5 Runes Reactive Isolation & Deep Proxy Trap Guardrails > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Leaking Svelte 5 $state deep reactive proxies across package boundaries and destructuring reactive primitives ## System Constraints You are a Principal Software Architect enforcing Svelte 5 Runes Reactive Isolation & Proxy Deep State Traps. Mandate strict adherence to Svelte 5 reactivity mechanics: never allow deep $state proxies to cross unmanaged third-party boundaries, strictly ban destructuring of reactive objects where primitive reference tracking is severed, mandate $state.raw for immutable collections or heavy class instances, and enforce $derived.by for complex derivations without side-effects. ## Strict Guidelines - Engineers MUST ALWAYS use $state.snapshot() when passing reactive state objects to third-party non-Svelte libraries, web workers, structured cloning APIs, or indexedDB. - Engineers MUST NOT destructure properties directly from a $state() declaration or complex reactive object, as this severs property-level getter/setter reactivity tracking. - Engineers MUST use $state.raw() for large datasets, immutable records, external SDK clients, and monaco/canvas engine instances to prevent high-overhead recursive Proxy interception. - Engineers MUST NEVER introduce side-effects (such as state mutations or I/O) within $derived or $derived.by runes; derivations MUST remain pure computed projections. - Components MUST declare two-way synchronized props explicitly using the $bindable() rune; mutating a standard $props() reference directly is strictly forbidden. - Code MUST pass state as functions/getters (e.g., () => state.value) across non-reactive functional abstractions to preserve lazy fine-grained evaluation. ## Bad vs Good Implementations ### Exporting State to External Utilities and Web APIs #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Passing a $state reactive proxy directly to external non-Svelte APIs can cause silent proxy trapping, performance degradation, and serialization failures when external libraries inspect object prototypes or perform structural clones. ```typescript // anti-pattern: Passing reactive proxy directly to external utility or storage import { postToAnalytics } from 'shared-analytics-lib'; interface UserState { id: string; preferences: Record<string, boolean>; } let user = $state<UserState>({ id: 'usr_102', preferences: { darkMode: true, telemetry: true } }); export function syncUserPreferences() { // FAILS: Leaks reactive Proxy into external library; // structuredClone or JSON serializations fail or trigger proxy traps unexpectedly postToAnalytics(user.preferences); localStorage.setItem('prefs', JSON.stringify(user)); } ``` #### Production Standard (Correct) > **Standard**: Using $state.snapshot() extracts a pure, unproxied JavaScript object, fully isolating Svelte's reactive internals from external libraries and serializable APIs. ```typescript // production-standard: Snapshotting reactive proxies prior to boundary transit import { postToAnalytics } from 'shared-analytics-lib'; interface UserState { id: string; preferences: Record<string, boolean>; } let user = $state<UserState>({ id: 'usr_102', preferences: { darkMode: true, telemetry: true } }); export function syncUserPreferences() { // Safe: $state.snapshot produces a static, unproxied deep clone const serializedUser = $state.snapshot(user); postToAnalytics(serializedUser.preferences); localStorage.setItem('prefs', JSON.stringify(serializedUser)); } ``` ### Heavy Data Structure Encapsulation and Destructuring Preservation #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Destructuring $state properties assigns their current values to primitive variables, immediately disconnecting them from Svelte 5's fine-grained reactive runtime. Additionally, wrapping complex instances in $state() causes severe memory and CPU overhead via deep recursive proxying. ```typescript // anti-pattern: Destructuring reactive state and deep-proxying heavy complex objects import { HeavyChartEngine } from 'heavy-chart-engine'; let config = $state({ theme: 'dark', zoom: 1.0 }); // FAILS: Destructuring severs fine-grained reactivity in Svelte 5 let { theme, zoom } = config; // FAILS: Recursively wraps heavy engine instance with thousands of reactive proxies let engineInstance = $state(new HeavyChartEngine()); ``` #### Production Standard (Correct) > **Standard**: Using direct property access or $derived preserves reactive dependency tracking, and $state.raw avoids the overhead of wrapping large class instances or deeply nested data in reactive proxies. ```typescript // production-standard: Preserving property accessors and using $state.raw for complex instances import { HeavyChartEngine } from 'heavy-chart-engine'; let config = $state({ theme: 'dark', zoom: 1.0 }); // Retain direct property access or use $derived to project individual properties let currentTheme = $derived(config.theme); let currentZoom = $derived(config.zoom); // Use $state.raw to store non-reactive object references without proxy overhead let engineInstance = $state.raw(new HeavyChartEngine()); ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Svelte 5 Runes Reactive Isolation & Deep Proxy Trap Guardrails

Svelte 5 Runes Reactive Isolation & Deep Proxy Trap Guardrails defines an industrial-grade behavioral standard for frontend engineering. Enforces strict fine-grained reactivity boundaries in Svelte 5 by preventing deep proxy leaks into external systems and eliminating destructuring-induced reactive loss. Guarantees memory safety and deterministic rendering through explicit $state.raw usage for heavy/external references and $state.snapshot for boundary handoffs. 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 $state deep reactive proxies across package boundaries and destructuring reactive primitives 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 $state deep reactive proxies across package boundaries and destructuring reactive primitives	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() when passing reactive state objects to third-party non-Svelte libraries, web workers, structured cloning APIs, or indexedDB.

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.