Svelte 5 Runes Reactive Proxy Serialization Guardrail

Enforces explicit dereferencing and snapshotting of Svelte 5 rune reactive proxies before passing data across Web Worker message ports, BroadcastChannels, or SSR-to-client hydration state boundaries. Deeply reactive state generated via $state() wraps structures in JavaScript Proxies that fail structured clone algorithms or retain hidden component lifecycle bindings, causing cross-boundary memory leaks and silent mutation tracking failures. Production systems must mandate explicit $state.snapshot() extraction and structured schema-validated transfer.

--- description: Svelte 5 Runes Reactive Proxy Serialization Guardrail - Enforces explicit dereferencing and snapshotting of Svelte 5 rune reactive proxies before passing data across Web Worker message ports, BroadcastChannels, or SSR-to-client hydration state boundaries. Deeply reactive state generated via $state() wraps structures in JavaScript Proxies that fail structured clone algorithms or retain hidden component lifecycle bindings, causing cross-boundary memory leaks and silent mutation tracking failures. Production systems must mandate explicit $state.snapshot() extraction and structured schema-validated transfer. 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-reactive-proxy-serialization-guardrail" --- # Svelte 5 Runes Reactive Proxy Serialization Guardrail > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Passing $state Reactive Proxies Across Structured Clone Boundaries Causing Clone Failures and State Retainment ## System Constraints You are a Principal Engineer enforcing Svelte 5 Runes Reactive Proxy Serialization Guardrail. Mandate invariants regarding Svelte 5 reactivity boundaries, specifically $state() proxy stripping across serialization contexts (Web Workers, IndexedDB, postMessage, and SSR hydration transfer). Ensure code never passes active $state proxies to structured clone APIs, never mutates deserialized Worker payloads directly back into rune graphs without re-proxying, and explicitly leverages $state.snapshot() or immutable cloning before thread or boundary transit. ## Strict Guidelines - Engineers MUST ALWAYS invoke $state.snapshot(target) before passing reactive $state structures to postMessage, Worker boundaries, IndexedDB, or localStorage. - Engineers MUST NOT pass raw reactive $state() proxies directly into worker.postMessage() or window.postMessage(), as structured cloning either throws DataCloneError or silently detaches reactivity graphs leaving zombie references. - Code MUST deeply validate and re-initialize incoming serialized payloads from Web Workers using schema parsers before assigning back into $state rune properties. - Services MUST ensure SSR-injected initial page state (e.g., event.locals data passed to SvelteKit load functions) is clean POJO data without un-serializable references or lingering reactive traps. - Components NEVER store active Web Worker instances or Transferable objects inside $state runes, but must instead manage worker instances via non-reactive lexical scope or $state.raw when reactivity wrapper overhead or proxying would cause memory leaks. ## Bad vs Good Implementations ### Dispatching Reactive Runes State to a Web Worker Boundary #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Passing this.state.blocks directly causes structured clone algorithms to encounter reactive proxy wrappers. Depending on the runtime engine, this either causes an outright DataCloneError or retains memory references across thread queues, preventing garbage collection and breaking Svelte 5 fine-grained dependency tracking. ```typescript import { workerPool } from './worker-pool'; interface DocumentState { id: string; blocks: Array<{ id: string; content: string; version: number }>; cursor: number; } // ANTI-PATTERN: Passing reactive proxy directly to structured clone / postMessage export class DocumentController { state = $state<DocumentState>({ id: 'doc-1', blocks: [{ id: 'b-1', content: 'Initial', version: 1 }], cursor: 0 }); syncWithWorker(): void { // Fails in strict structuredClone environments or passes reactive traps, // retaining active references and leaking GC boundaries across tasks. workerPool.postMessage({ type: 'INDEX_BLOCKS', payload: this.state.blocks }); } } ``` #### Production Standard (Correct) > **Standard**: Using $state.snapshot() extracts a static, non-reactive JavaScript deep copy of the proxy, ensuring zero proxy overhead, safe structured cloning across worker boundaries, and immune to cross-thread memory retention. ```typescript import { workerPool } from './worker-pool'; interface Block { id: string; content: string; version: number; } interface DocumentState { id: string; blocks: Block[]; cursor: number; } export class DocumentController { state = $state<DocumentState>({ id: 'doc-1', blocks: [{ id: 'b-1', content: 'Initial', version: 1 }], cursor: 0 }); syncWithWorker(): void { // CORRECT: Strip reactive proxies into a pristine, plain JS snapshot before boundary transit const rawBlocks = $state.snapshot(this.state.blocks); workerPool.postMessage({ type: 'INDEX_BLOCKS', payload: rawBlocks }); } } ``` ### Ingesting Worker Payloads and SSR State Hydration into Svelte 5 Runes #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Storing DOM/Worker platform instances inside $state triggers unnecessary reactive proxy wrapping on platform classes and causes memory leaks. Furthermore, directly assigning unverified worker event.data bypasses type safety and lifecycle guarantees. ```typescript // ANTI-PATTERN: Directly merging arbitrary worker response into $state without validation // and managing WebWorker instance inside reactive state export class WorkerOrchestrator { // Anti-pattern: Storing complex non-serializable instances in reactive state workerState = $state<{ worker: Worker | null; data: Record<string, unknown>; }>({ worker: null, data: {} }); init(): void { this.workerState.worker = new Worker(new URL('./compute.worker.ts', import.meta.url), { type: 'module' }); this.workerState.worker.onmessage = (event: MessageEvent) => { // Directly assigning raw deserialized payload back without validation this.workerState.data = event.data; }; } } ``` #### Production Standard (Correct) > **Standard**: Platform objects like Worker instances are safely kept outside the Svelte reactive graph in private fields (#worker), preventing reactive interception. Incoming deserialized worker payloads are rigorously parsed with Zod before mutating rune state. ```typescript import { z } from 'zod'; const WorkerResponseSchema = z.object({ resultId: z.string(), computedMetrics: z.record(z.string(), z.number()) }); type WorkerResponse = z.infer<typeof WorkerResponseSchema>; export class WorkerOrchestrator { // CORRECT: Non-reactive platform instance managed lexically or via non-reactive property #worker: Worker | null = null; // Only store actual display/domain reactive data in runes state = $state<{ data: WorkerResponse | null; isProcessing: boolean; }>({ data: null, isProcessing: false }); init(): void { this.#worker = new Worker(new URL('./compute.worker.ts', import.meta.url), { type: 'module' }); this.#worker.onmessage = (event: MessageEvent) => { const parsed = WorkerResponseSchema.safeParse(event.data); if (!parsed.success) { console.error('Worker contract violation:', parsed.error); return; } // Safe assignment into Svelte 5 rune graph this.state.data = parsed.data; this.state.isProcessing = false; }; } destroy(): void { this.#worker?.terminate(); this.#worker = null; } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Svelte 5 Runes Reactive Proxy Serialization Guardrail

Svelte 5 Runes Reactive Proxy Serialization Guardrail defines an industrial-grade behavioral standard for frontend engineering. Enforces explicit dereferencing and snapshotting of Svelte 5 rune reactive proxies before passing data across Web Worker message ports, BroadcastChannels, or SSR-to-client hydration state boundaries. Deeply reactive state generated via $state() wraps structures in JavaScript Proxies that fail structured clone algorithms or retain hidden component lifecycle bindings, causing cross-boundary memory leaks and silent mutation tracking failures. Production systems must mandate explicit $state.snapshot() extraction and structured schema-validated transfer. 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: Passing $state Reactive Proxies Across Structured Clone Boundaries Causing Clone Failures and State Retainment 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	Passing $state Reactive Proxies Across Structured Clone Boundaries Causing Clone Failures and State Retainment	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(target) before passing reactive $state structures to postMessage, Worker boundaries, IndexedDB, or localStorage.

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.