Svelte 5 Runes Cross-Worker State Synchronization & Proxy Isolation Standard

Q: How does adopting this rule prevent AI hallucinations?

This rule explicitly declares what the AI must avoid (Direct Serialization of Svelte 5 Reactive Proxies and Unsynchronized Worker Mutability Leading to DataCloneError and State Tearing) and prescribes verified positive examples. Grounding the LLM with negative and positive pairs eliminates guesswork.

Q: Which AI coding environments are supported?

This specification is multi-platform compatible: Cursor (.cursor/rules/*.mdc & .cursorrules), Anthropic Claude Code (CLAUDE.md), Windsurf (.windsurfrules), Codex / Cline (AGENTS.md), and GitHub Copilot (.github/copilot-instructions.md).

Q: Can I combine this rule with other technology stacks?

Yes. Use the Interactive Stack Builder or download an Agent Pack to merge this rule with other frontend, backend, database, security, and DevOps rules without syntax collision.

Svelte 5 Runes Cross-Worker State Synchronization & Proxy Isolation Standard

--- description: Svelte 5 Runes Cross-Worker State Synchronization & Proxy Isolation Standard - Enforces deterministic state boundaries between Svelte 5 Runes reactivity and Web Worker thread pools. Guarantees that deeply reactive proxies created by $state() are snapshot-sanitized prior to postMessage serialization, preventing runtime DataCloneError exceptions, thread-boundary proxy leakage, and reactive graph tearing. 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/svelte-5-runes-cross-worker-proxy-invariant" --- # Svelte 5 Runes Cross-Worker State Synchronization & Proxy Isolation Standard > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Direct Serialization of Svelte 5 Reactive Proxies and Unsynchronized Worker Mutability Leading to DataCloneError and State Tearing ## System Constraints You are a Principal Software Architect enforcing Svelte 5 Runes Cross-Worker Proxy Invariants. Svelte 5 introduces fine-grained reactive signals wrapped in transparent ECMAScript Proxies via `$state()`. These proxies are non-transferable across thread boundaries and fail structured cloning algorithms (`DataCloneError`). You must mandate strict snapshot decoupling via `$state.snapshot()` at postMessage exit boundaries and enforce single-writer transactional state application on return boundaries to prevent state tearing. ## Strict Guidelines - Engineers MUST ALWAYS invoke `$state.snapshot()` on reactive state structures before passing them to `worker.postMessage()` or `MessagePort.postMessage()`. - Engineers MUST NOT transmit raw `$state()` or `$state.raw()` proxy references across worker threads, as the browser Structured Clone Algorithm will reject proxy traps with a DOMException DataCloneError. - Worker event listeners on the main thread MUST apply worker response payloads transactionally in a single synchronous tick rather than via piecewise mutations to prevent intermediate reactive state tears in `$derived` graphs. - Code SHOULD enforce message envelope typing with monotonic sequence counters (`seqId`) or generation tokens to drop out-of-order worker responses that conflict with newer local `$state` mutations. - Services interacting with high-throughput workers MUST utilize `$state.raw()` for bulk worker state buffers when deep fine-grained reactivity inside the ingested data structure is not required, avoiding unnecessary proxy wrapping overhead. ## Bad vs Good Implementations ### Cross-Worker State Dispatch and Ingestion #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Directly passing `this.state.items` (which is a Svelte 5 reactive Proxy) into `postMessage` causes a browser DataCloneError. Updating the array elements incrementally upon message receipt produces micro-render state tearing in dependent `$derived` runes and effects. ```typescript import { workerInstance } from './worker-client'; interface TaskState { items: string[]; status: 'idle' | 'processing'; } // ANTI-PATTERN: Reactive proxy sent directly over thread boundary // and updated piecewise upon return, risking DataCloneError & state tears. export class StateManager { state = $state<TaskState>({ items: ['alpha', 'beta'], status: 'idle' }); runWorkerTask() { this.state.status = 'processing'; // CRITICAL BUG: Passing reactive proxy to postMessage triggers DataCloneError workerInstance.postMessage({ items: this.state.items }); } handleWorkerMessage(e: MessageEvent<{ items: string[] }>) { // ANTI-PATTERN: Piecewise mutation causes intermediate derived graph recalculations this.state.items.length = 0; for (const item of e.data.items) { this.state.items.push(item); } this.state.status = 'idle'; } } ``` #### Production Standard (Correct) > **Standard**: Calling `$state.snapshot()` strips all Svelte 5 signal proxy wrappers, producing a plain, immutable object that guarantees safe structured cloning. The response is handled atomically with monotonic sequence ordering, preventing race conditions and partial-update reactive tears. ```typescript import { workerInstance } from './worker-client'; interface TaskState { items: readonly string[]; status: 'idle' | 'processing'; lastSyncSeq: number; } interface WorkerEnvelope { seqId: number; items: string[]; } export class StateManager { #seq = 0; // Maintain state predictability using typed, discrete snapshots state = $state<TaskState>({ items: ['alpha', 'beta'], status: 'idle', lastSyncSeq: 0 }); runWorkerTask(): void { const currentSeq = ++this.#seq; this.state.status = 'processing'; // INVARIANT: Unwrap proxy tree using $state.snapshot before structured clone const plainPayload = $state.snapshot(this.state.items); const message: WorkerEnvelope = { seqId: currentSeq, items: plainPayload }; workerInstance.postMessage(message); } handleWorkerMessage(e: MessageEvent<WorkerEnvelope>): void { const { seqId, items } = e.data; // INVARIANT: Discard stale out-of-order execution threads if (seqId < this.state.lastSyncSeq) { return; } // INVARIANT: Atomic transaction eliminates intermediate reactive tears this.state = { items: Object.freeze([...items]), status: 'idle', lastSyncSeq: seqId }; } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Svelte 5 Runes Cross-Worker State Synchronization & Proxy Isolation Standard

Svelte 5 Runes Cross-Worker State Synchronization & Proxy Isolation Standard defines an industrial-grade behavioral standard for frontend engineering. Enforces deterministic state boundaries between Svelte 5 Runes reactivity and Web Worker thread pools. Guarantees that deeply reactive proxies created by $state() are snapshot-sanitized prior to postMessage serialization, preventing runtime DataCloneError exceptions, thread-boundary proxy leakage, and reactive graph tearing. 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: Direct Serialization of Svelte 5 Reactive Proxies and Unsynchronized Worker Mutability Leading to DataCloneError and State 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	Direct Serialization of Svelte 5 Reactive Proxies and Unsynchronized Worker Mutability Leading to DataCloneError and State 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 invoke `$state.snapshot()` on reactive state structures before passing them to `worker.postMessage()` or `MessagePort.postMessage()`.

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.