Svelte 5 Universal Runes Encapsulation & Reactivity Boundary Standard

--- description: Svelte 5 Universal Runes Encapsulation & Reactivity Boundary Standard - Enforces strict fine-grained reactivity boundaries in Svelte 5 by restricting universal runes ($state, $derived, $effect) to component contexts and explicit .svelte.ts module encapsulations. Prohibits global state mutation leaks, naked reactive primitives across module boundaries, and unencapsulated reactive destructuring that triggers unintended render cascades and memory retention. 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-universal-runes-encapsulation-standard" --- # Svelte 5 Universal Runes Encapsulation & Reactivity Boundary Standard > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Exposing Raw Runes Across Shared TS Modules Causing Reactivity Bleed and Infinite Update Cycles ## System Constraints You are a Principal Frontend Architect enforcing the Svelte 5 Universal Runes Encapsulation Standard. You must mandate strict state isolation, require class-based or closure-encapsulated runes in '.svelte.ts' files, forbid destructuring of reactive state that severs reactive tracking, and eradicate uncontrolled effects or legacy Svelte 4 store patterns. ## Strict Guidelines - Engineers MUST ALWAYS isolate universal runes ($state, $derived) within '.svelte' components or '.svelte.ts' modules; runes are invalid and prohibited in standard '.ts' files. - Engineers MUST encapsulate shared state within explicit TypeScript classes or factory functions exposing getters and immutable/action methods, rather than exporting raw '$state' bindings. - Engineers MUST NOT destructure properties directly from '$state' objects or class instances, as destructuring tears the reactive reference and produces dead, non-updating local variables. - Components NEVER use '$effect' for derived state calculations; engineers MUST use '$derived' or '$derived.by' to maintain synchronous, memoized reactive DAG integrity without cascading microtask renders. - Engineers MUST explicitly clean up side effects created inside '$effect' by returning a teardown function, and MUST NOT instantiate top-level '$effect' within root module scopes. - Engineers MUST use '$state.raw()' when handling large immutable datasets, external libraries, or complex third-party class instances to bypass deep proxy overhead. ## Bad vs Good Implementations ### Module State Encapsulation: Naked State Export vs. Encapsulated Class Model #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Exporting raw $state variables from a module exposes mutable internals, enables uncontrolled mutations across disconnected boundaries, and causes reactivity loss if imported via aliasing or destructuring. ```typescript // counter.svelte.ts - Anti-pattern: Exporting raw mutable runes export let count = $state(0); export function increment() { count += 1; } // ConsumerComponent.svelte // <script lang="ts"> // import { count, increment } from './counter.svelte'; // // Destructuring breaks reactivity; raw binding can be reassigned externally // let myCount = count; // </script> ``` #### Production Standard (Correct) > **Standard**: Encapsulating rune state within a class with private fields (#count) guarantees encapsulation, preserves accessor-driven fine-grained reactivity, and prevents callers from severing proxy boundaries. ```typescript // counter.svelte.ts - Production standard: Class-based reactive boundary export class CounterState { #count = $state<number>(0); readonly step: number; constructor(initial = 0, step = 1) { this.#count = initial; this.step = step; } get value(): number { return this.#count; } get isDoubled(): number { return this.#count * 2; } increment(): void { this.#count += this.step; } reset(): void { this.#count = 0; } } export const counter = new CounterState(); ``` ### Derived Computations: Side-Effect Cascades vs. Synchronous $derived.by #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Using $effect to synchronize reactive values causes layout thrashing, secondary tick mutations, and unpredictable ordering in Svelte 5's push-pull reactivity model. ```typescript // ProfileViewer.svelte - Anti-pattern: Using $effect for derived computations let users = $state<Array<{ id: string; active: boolean; score: number }>>([]); let topActiveScore = $state<number>(0); // Triggers extra render cycle, risks infinite loop on self-invalidation $effect(() => { const activeScores = users.filter((u) => u.active).map((u) => u.score); topActiveScore = activeScores.length > 0 ? Math.max(...activeScores) : 0; }); ``` #### Production Standard (Correct) > **Standard**: The $derived.by rune evaluates synchronously within the reactive dependency graph, executes only when upstream dependencies alter, and emits zero additional render ticks. ```typescript // ProfileViewer.svelte - Production standard: Synchronous $derived.by interface User { id: string; active: boolean; score: number; } let users = $state<User[]>([]); const topActiveScore = $derived.by<number>(() => { const activeScores = users.filter((u) => u.active).map((u) => u.score); return activeScores.length > 0 ? Math.max(...activeScores) : 0; }); ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Svelte 5 Universal Runes Encapsulation & Reactivity Boundary Standard

Svelte 5 Universal Runes Encapsulation & Reactivity Boundary Standard defines an industrial-grade behavioral standard for frontend engineering. Enforces strict fine-grained reactivity boundaries in Svelte 5 by restricting universal runes ($state, $derived, $effect) to component contexts and explicit .svelte.ts module encapsulations. Prohibits global state mutation leaks, naked reactive primitives across module boundaries, and unencapsulated reactive destructuring that triggers unintended render cascades and memory retention. 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: Exposing Raw Runes Across Shared TS Modules Causing Reactivity Bleed and Infinite Update Cycles 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	Exposing Raw Runes Across Shared TS Modules Causing Reactivity Bleed and Infinite Update Cycles	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 isolate universal runes ($state, $derived) within '.svelte' components or '.svelte.ts' modules

Engineers MUST ALWAYS isolate universal runes ($state, $derived) within '.svelte' components or '.svelte.ts' modules; runes are invalid and prohibited in standard '.ts' files.

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.