Svelte 5 $state.raw Proxy Bypass for High-Frequency Telemetry Invariant

--- description: Svelte 5 $state.raw Proxy Bypass for High-Frequency Telemetry Invariant - Enforces shallow reactivity via $state.raw for streaming telemetry, WebSockets, WebRTC streams, and high-throughput real-time dashboards in Svelte 5. Bypasses recursive reactive proxy allocation on dense arrays and nested objects to eliminate GC thrashing and microtask queue saturation. Guarantees 60fps rendering budgets by treating streaming updates as atomic buffer replacements or coupled with animation-frame throttling. 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-state-raw-high-frequency-telemetry" --- # Svelte 5 $state.raw Proxy Bypass for High-Frequency Telemetry Invariant > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Deep Reactive Proxy Trapping of High-Throughput Streaming Datasets Causing GC Stalls and Frame Dropping ## System Constraints You are a Principal Engineer enforcing Svelte 5 $state.raw Proxy Bypass for High-Frequency Telemetry Invariant. Mandate invariants that prevent using standard `$state()` or `$state([])` for streaming payloads, time-series data, canvas feeds, or WebSocket buffers arriving at >10Hz. Deep reactive proxies traverse every nested property and generate significant allocation pressure. You must enforce `$state.raw()` paired with reference re-assignment, ring buffers, or requestAnimationFrame batching. ## Strict Guidelines - Engineers MUST ALWAYS declare telemetry buffers, WebSocket payloads, time-series series arrays, and high-frequency stream states (>10 updates/sec) using `$state.raw()` instead of `$state()`. - Engineers MUST NOT mutate inner fields of objects wrapped in `$state.raw()`; updates must be applied by replacing the top-level reference (e.g., `telemetry = nextBuffer`) or by calling canvas/DOM render routines directly. - Engineers MUST NOT rely on deep mutation triggers (such as `push()`, `splice()`, or in-place object property assignments) when using `$state.raw()`, as raw state relies strictly on reference equality (`===`) checks. - Code SHOULD buffer high-frequency network messages off the main reactivity cycle using a non-reactive TypedArray or RingBuffer, flushing to `$state.raw` on `requestAnimationFrame` boundaries. - Components NEVER instantiate recursive `$derived` trees or granular Svelte 5 each-block key bindings over high-churn deep objects; downstream views must consume sliced primitives or render through WebGL/Canvas. ## Bad vs Good Implementations ### High-Frequency WebSocket Telemetry Ingestion #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Using `$state([])` wraps incoming streaming objects into deep reactive Proxies. At high ingestion rates (e.g., 60-120Hz), GC churn triggers micro-stutters and frame drops across the application. ```typescript import { untrack } from 'svelte'; interface MetricPacket { timestamp: number; values: number[]; metadata: { sensorId: string; status: string }; } // ANTI-PATTERN: Standard $state recursively wraps every packet, array, and nested object in a Reactive Proxy. // Receiving 60 packets/sec creates thousands of Proxy allocations per second, degrading the V8 garbage collector. export class TelemetryStore { data = $state<MetricPacket[]>([]); constructor(socket: WebSocket) { socket.onmessage = (event: MessageEvent) => { const packet: MetricPacket = JSON.parse(event.data); // Deep mutation triggers deep traversal and memory churn this.data.push(packet); if (this.data.length > 1000) { this.data.shift(); } }; } } ``` #### Production Standard (Correct) > **Standard**: Using `$state.raw` eliminates proxy instantiation. Batching via `requestAnimationFrame` and performing atomic reference assignment reduces reactivity triggers to maximum display refresh rate while preventing GC degradation. ```typescript interface MetricPacket { timestamp: number; values: number[]; metadata: { sensorId: string; status: string }; } // PRODUCTION FIX: $state.raw avoids proxy wrapping entirely. // We accumulate incoming packets in a plain array and commit via RAF to keep reactivity cost minimal. export class TelemetryStore { data = $state.raw<readonly MetricPacket[]>([]); private buffer: MetricPacket[] = []; private rafHandle: number | null = null; constructor(socket: WebSocket) { socket.onmessage = (event: MessageEvent) => { const packet: MetricPacket = JSON.parse(event.data); this.buffer.push(packet); if (this.buffer.length > 1000) { this.buffer.shift(); } this.scheduleFlush(); }; } private scheduleFlush(): void { if (this.rafHandle !== null) return; this.rafHandle = requestAnimationFrame(() => { // Atomic reference assignment triggers shallow reactivity without proxy overhead this.data = [...this.buffer]; this.rafHandle = null; }); } destroy(): void { if (this.rafHandle !== null) { cancelAnimationFrame(this.rafHandle); } } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Svelte 5 $state.raw Proxy Bypass for High-Frequency Telemetry Invariant

Svelte 5 $state.raw Proxy Bypass for High-Frequency Telemetry Invariant defines an industrial-grade behavioral standard for frontend engineering. Enforces shallow reactivity via $state.raw for streaming telemetry, WebSockets, WebRTC streams, and high-throughput real-time dashboards in Svelte 5. Bypasses recursive reactive proxy allocation on dense arrays and nested objects to eliminate GC thrashing and microtask queue saturation. Guarantees 60fps rendering budgets by treating streaming updates as atomic buffer replacements or coupled with animation-frame throttling. 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: Deep Reactive Proxy Trapping of High-Throughput Streaming Datasets Causing GC Stalls and Frame Dropping 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	Deep Reactive Proxy Trapping of High-Throughput Streaming Datasets Causing GC Stalls and Frame Dropping	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 telemetry buffers, WebSocket payloads, time-series series arrays, and high-frequency stream states (>10 updates/sec) using `$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.