Svelte 5 $state.raw Proxy Bypass Standard for High-Throughput Streams

--- description: Svelte 5 $state.raw Proxy Bypass Standard for High-Throughput Streams - Enforces the mandatory use of Svelte 5's $state.raw() rune for large external state trees, high-frequency streaming collections, and immutable third-party data structures. Prevents catastrophic garbage collection thrashing and main-thread freezing caused by deep recursive proxy wrapping on high-volume incoming payloads. globs: src/**/*.{svelte,svelte.ts,svelte.js,ts} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/svelte-5-raw-state-proxy-bypass-standard" --- # Svelte 5 $state.raw Proxy Bypass Standard for High-Throughput Streams > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Wrapping Large or Streaming Data Payloads in Deeply Reactive Svelte 5 $state() Proxies ## System Constraints You are a Principal Software Architect enforcing performance guardrails in Svelte 5 applications. You mandate that any external data structures, high-frequency stream buffers (WebSocket, SSE, WebRTC), large tabular payloads, and complex third-party library models (Three.js, Leaflet, Chart.js) MUST bypass Svelte 5's deep recursive proxy engine by utilizing `$state.raw()`. Ensure engineers mutate such states via top-level reference reassignment rather than in-place deep property manipulation. ## Strict Guidelines - Engineers MUST ALWAYS declare external streaming buffers, WebSocket payloads, and large datasets (>500 items or deeply nested structures) with `$state.raw()` instead of `$state()`. - Engineers MUST NOT allow high-frequency data ingests (e.g., telemetry, market data, ticks >10Hz) to pass through standard `$state()` recursive proxy wrappers. - Code SHOULD trigger reactive updates on `$state.raw()` structures via reference reassignment (e.g., `ticks = [...ticks, newTick]` or `payload = { ...nextPayload }`), ensuring fine-grained control over change propagation. - Services MUST encapsulate bulk mutation operations off the main thread or behind immutable updates to prevent repeated frame drops during reactive invalidation. - Components NEVER deep-mutate properties inside a `$state.raw()` variable directly, as Svelte 5 explicitly will not track internal mutations on raw reactive targets. ## Bad vs Good Implementations ### Real-Time WebSocket Stream Buffer Ingestion #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Using $state() for high-volume streaming data forces Svelte 5 to recursively wrap every array entry and nested property in reactive proxies. Under continuous streaming, this results in excessive heap allocations, CPU-bound proxy graph traversals, and catastrophic garbage collection pauses. ```typescript import { untrack } from 'svelte'; interface MarketTick { id: string; symbol: string; price: number; depth: { bids: [number, number][]; asks: [number, number][] }; } // ANTI-PATTERN: Standard $state recursively wraps every nested object and array // in a Proxy. At 60-120 ticks/sec, this triggers extreme GC thrashing and frame drops. let orderBook = $state<Record<string, MarketTick>>({}); export function handleTick(tick: MarketTick) { orderBook[tick.symbol] = tick; } ``` #### Production Standard (Correct) > **Standard**: Declaring the order book with $state.raw() prevents Svelte 5 from traversing nested arrays and objects to create proxies. Reactivity is retained at zero proxy overhead, cleanly invalidating downstream dependencies solely when the root reference is reassigned. ```typescript interface MarketTick { id: string; symbol: string; price: number; depth: { bids: [number, number][]; asks: [number, number][] }; } // PRODUCTION INVARIANT: $state.raw bypasses deep proxying entirely. // Reactivity only triggers when the top-level reference changes. let orderBook = $state.raw<Record<string, MarketTick>>({}); export function handleTick(tick: MarketTick) { // Invariant-compliant immutable reference update orderBook = { ...orderBook, [tick.symbol]: tick }; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Svelte 5 $state.raw Proxy Bypass Standard for High-Throughput Streams

Svelte 5 $state.raw Proxy Bypass Standard for High-Throughput Streams defines an industrial-grade behavioral standard for frontend engineering. Enforces the mandatory use of Svelte 5's $state.raw() rune for large external state trees, high-frequency streaming collections, and immutable third-party data structures. Prevents catastrophic garbage collection thrashing and main-thread freezing caused by deep recursive proxy wrapping on high-volume incoming payloads. 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: Wrapping Large or Streaming Data Payloads in Deeply Reactive Svelte 5 $state() Proxies 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	Wrapping Large or Streaming Data Payloads in Deeply Reactive Svelte 5 $state() Proxies	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 declare external streaming buffers, WebSocket payloads, and large datasets (>500 items or deeply nested structures) with `$state.raw()` instead of `$state()`.

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.