Svelte 5 Runes Universal Reactive Proxy Sandboxing & Memory Boundary Isolation

--- description: Svelte 5 Runes Universal Reactive Proxy Sandboxing & Memory Boundary Isolation - Enforces strict boundary encapsulation when passing Svelte 5 `$state` deep proxies across asynchronous boundaries like Web Workers, XState machines, or IndexedDB storage engines. Prevents silent proxy detachment, prototype serialization corruption, and unbounded memory leaks by requiring explicit structured cloning via `$state.snapshot()` and raw proxy sandboxing. globs: src/**/*.{svelte,svelte.ts,svelte.js,ts,js} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/svelte5-runes-proxy-sandboxing" --- # Svelte 5 Runes Universal Reactive Proxy Sandboxing & Memory Boundary Isolation > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Leaking Svelte 5 $state Proxies Directly into PostMessage, Structured Clone, or External Finite State Machine Contexts ## System Constraints You are a Principal Software Architect enforcing Svelte 5 reactive proxy sandboxing and boundary hygiene. Svelte 5 uses deep Proxy instances for `$state(...)`. When these proxies interact with Web Workers via `postMessage()`, `structuredClone()`, or external state engines (e.g., XState, Redux, RxJS), engines either throw `DataCloneError`, drop reactive prototype traps silently, or retain persistent uncollected closure references causing memory leaks. You must strictly mandate `$state.snapshot()` for all outbound serialization and enforce bidirectional decoupling invariants. ## Strict Guidelines - Engineers MUST ALWAYS invoke `$state.snapshot(proxy)` when passing reactive state across thread boundaries (`worker.postMessage`) or non-Svelte third-party stores. - Engineers MUST NOT pass raw `$state` or `$state.raw` objects directly into browser structured clone algorithms or WebSockets without explicit sanitization. - Engineers MUST NEVER mutate inbound external state directly on the root reference inside an untracked worker callback; apply updates through atomic `$state` reassignment or targeted reactive property mutation. - Code SHOULD use `$state.raw` for large, immutable data payloads (e.g., ArrayBuffers, 3D meshes, high-frequency telemetry streams) to bypass Proxy overhead and prevent multi-gigabyte memory amplification. - Services MUST implement explicit lifecycle disposal (`onDestroy` or `$effect` teardown returns) to detach worker event listeners holding closures over reactive proxies. - Components NEVER expose internal rune reactive graph references to external state machines; pass immutable read snapshots and receive state via decoupled messages or subscriptions. ## Bad vs Good Implementations ### Dispatching Reactive Runes to a Web Worker Boundary #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Passing `this.session` directly exposes Svelte 5's internal `ReactiveProxy` to `postMessage()`. In modern runtimes, structured cloning either throws a `DOMException (DataCloneError)` on Proxy traps or strips getters/setters, detaching reactive synchronization and leaking proxy tracking nodes in memory. ```typescript import { workerPool } from './worker-pool'; interface SessionState { userId: string; metrics: number[]; } // ANTI-PATTERN: Passing reactive proxy directly causes DataCloneError or proxy detachment export class TelemetryService { session = $state<SessionState>({ userId: 'usr_1029', metrics: [1.2, 4.5, 9.8] }); syncWithWorker(): void { // Directly passing deep proxy reference triggers structured clone failure // or causes detached proxy traps when mutated inside worker callbacks workerPool.postMessage({ type: 'SYNC_TELEMETRY', payload: this.session }); } } ``` #### Production Standard (Correct) > **Standard**: `$state.snapshot(...)` recursively unpacks the Svelte 5 Proxy graph into a pristine, plain JavaScript object. This guarantees safe zero-leak serialization across the structured clone boundary without prototype pollution or runtime DOM exceptions. ```typescript import { workerPool } from './worker-pool'; interface SessionState { userId: string; metrics: number[]; } export class TelemetryService { session = $state<SessionState>({ userId: 'usr_1029', metrics: [1.2, 4.5, 9.8] }); syncWithWorker(): void { // INVARIANT: Take an immutable, non-proxied snapshot prior to boundary crossing const serializablePayload: SessionState = $state.snapshot(this.session); workerPool.postMessage({ type: 'SYNC_TELEMETRY', payload: serializablePayload }); } handleWorkerResponse(updatedMetrics: number[]): void { // Apply updates back to the reactive boundary deterministically this.session.metrics = updatedMetrics; } } ``` ### Decoupling External State Machine Subscriptions from Svelte 5 Runes #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Placing non-reactive state engines (like an XState actor) inside deep `$state` wraps the machine's internal symbols and emitters into Svelte proxies, triggering infinite loops or prototype invalidation during machine event transitions. ```typescript import { createActor } from 'xstate'; import { pipelineMachine } from './pipeline.machine'; export class Orchestrator { // ANTI-PATTERN: Storing actor ref directly inside deep reactive state triggers recursive proxying state = $state({ actor: createActor(pipelineMachine), context: {} }); init(): void { this.state.actor.subscribe((snapshot) => { // Mutating nested proxy with raw machine state links internal XState context to Svelte proxy tree this.state.context = snapshot.context; }); this.state.actor.start(); } } ``` #### Production Standard (Correct) > **Standard**: Using `$state.raw` prevents Svelte from recursively proxying the external state machine. Assigning a deep-cloned context ensures Svelte's reactive graph is completely isolated from the machine's internal state cycles. ```typescript import { createActor, type ActorRefFrom } from 'xstate'; import { pipelineMachine } from './pipeline.machine'; export class Orchestrator { // INVARIANT: Use $state.raw to store the non-reactive actor instance actor = $state.raw<ActorRefFrom<typeof pipelineMachine> | null>(null); context = $state<Record<string, unknown>>({}); init(): () => void { const actorInstance = createActor(pipelineMachine); this.actor = actorInstance; const sub = actorInstance.subscribe((snapshot) => { // Explicitly detach and freeze external context before assigning to runes this.context = structuredClone(snapshot.context); }); actorInstance.start(); // Invariant: Always return teardown to prevent uncollected closures return () => { sub.unsubscribe(); actorInstance.stop(); this.actor = null; }; } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Svelte 5 Runes Universal Reactive Proxy Sandboxing & Memory Boundary Isolation

Svelte 5 Runes Universal Reactive Proxy Sandboxing & Memory Boundary Isolation defines an industrial-grade behavioral standard for frontend engineering. Enforces strict boundary encapsulation when passing Svelte 5 `$state` deep proxies across asynchronous boundaries like Web Workers, XState machines, or IndexedDB storage engines. Prevents silent proxy detachment, prototype serialization corruption, and unbounded memory leaks by requiring explicit structured cloning via `$state.snapshot()` and raw proxy sandboxing. 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 Proxies Directly into PostMessage, Structured Clone, or External Finite State Machine Contexts 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 Proxies Directly into PostMessage, Structured Clone, or External Finite State Machine Contexts	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 `$state.snapshot(proxy)` when passing reactive state across thread boundaries (`worker.postMessage`) or non-Svelte third-party stores.

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.