Svelte 5 Runes Fine-Grained Reactive Context Isolation Invariant

--- description: Svelte 5 Runes Fine-Grained Reactive Context Isolation Invariant - Enforces strict lifecycle-bound encapsulation for Svelte 5 runes ($state, $effect, $derived) within micro-frontend architectures and component hierarchies. Prevents memory leaks caused by module-level signal subscriptions and cross-boundary graph pollution where external event cascades trigger untracked reactive evaluation in unmounted sub-trees. 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-runes-reactive-context-isolation" --- # Svelte 5 Runes Fine-Grained Reactive Context Isolation Invariant > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Module-Scoped Signal Retention and Unbounded Cross-Boundary Reactive Graph Pollution ## System Constraints You are a Principal Software Architect enforcing Svelte 5 Runes Fine-Grained Reactive Context Isolation Invariants. Svelte 5 relies on an underlying signal graph where reactive state dependencies ($state, $derived) subscribe to the active effect context ($effect). In high-throughput enterprise micro-frontends (MFEs) and dynamic boundary contexts, engineers frequently leak references by establishing module-scoped reactive singletons, failing to clean up manual `$effect.root` scopes, or allowing foreign MFE consumers to retain direct signal references across lifecycle teardowns. You MUST enforce deterministic signal encapsulation using `getContext`/`setContext` patterns, explicit `$effect.root()` teardowns, boundary-safe untracked reads, and sealed reactive stores. ## Strict Guidelines - Engineers MUST NEVER export raw, mutable `$state` signals directly from module roots across federated boundaries or micro-frontend bridge interfaces. - Engineers MUST instantiate shared reactive domain state exclusively via factory classes injected through Svelte's `setContext` and consumed via `getContext` to ensure state is strictly bound to the component subtree lifecycle. - Engineers MUST explicitly invoke the cleanup disposer returned by `$effect.root()` whenever running reactive computations outside of an active Svelte component tree (e.g., custom event buses, external MFE bridges, or headless orchestration layers). - Engineers MUST wrap foreign or cross-boundary signal reads in `untrack()` when executing internal local side-effects that should not re-trigger on foreign state mutations. - Engineers MUST NOT leak reactive proxy wrappers to vanilla JavaScript micro-frontend boundaries; any state exposed across window-level or web-component APIs MUST be marshaled as deep-cloned plain objects or read-only non-reactive snapshots. - Components NEVER capture persistent event listeners inside an `$effect` without returning an explicit teardown function or utilizing an `AbortController` linked to the component destruction phase. ## Bad vs Good Implementations ### Module-Level Signal Leak vs. Context-Scoped Reactive Boundary #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Exporting $state at module scope binds all consumer component effect nodes to a persistent global signal graph. When micro-frontends mount and unmount dynamically, stale effect subscribers remain retained in the module-level signal's subscriber list, causing unbounded memory leaks and ghost effect runs. ```typescript // shared-user-state.svelte.ts // ANTI-PATTERN: Module-scoped rune creates a permanent signal node across all MFE lifecycles export const globalUserState = $state({ profile: null as any, activeSessionId: '' }); // Any component importing this directly will pin subscriber nodes indefinitely, // preventing garbage collection when an MFE container unmounts or switches tenants. ``` #### Production Standard (Correct) > **Standard**: Encapsulating $state inside a class provisioned via setContext/getContext guarantees that the reactive signal graph is strictly tied to the component lifecycle. When the parent component or micro-frontend unmounts, the context and its signal subscriber trees are systematically released for garbage collection. ```typescript // user-state-context.svelte.ts import { getContext, setContext } from 'svelte'; const USER_STATE_KEY = Symbol('USER_STATE_KEY'); export class IsolatedUserState { #profile = $state<Record<string, unknown> | null>(null); #activeSessionId = $state<string>(''); constructor(initialSessionId: string) { this.#activeSessionId = initialSessionId; } get profile() { return this.#profile; } get activeSessionId() { return this.#activeSessionId; } setProfile(data: Record<string, unknown>) { this.#profile = data; } } export function initUserState(initialSessionId: string): IsolatedUserState { return setContext(USER_STATE_KEY, new IsolatedUserState(initialSessionId)); } export function useUserState(): IsolatedUserState { const context = getContext<IsolatedUserState>(USER_STATE_KEY); if (!context) { throw new Error('useUserState must be consumed within a valid boundary context.'); } return context; } ``` ### Headless Signal Orchestration via Disposed $effect.root #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Calling $effect outside an active component creation context either fails at runtime or attaches to an untracked parent graph. Without $effect.root, reactive listeners cannot be manually disconnected, leaking memory and running after foreign bridge termination. ```typescript // bridge-subscriber.ts // ANTI-PATTERN: Spawning raw effects in external headless adapters without root isolation export function bridgeExternalStore(externalBus: any, stateStore: any) { $effect(() => { // Compiler runtime error outside component, or dangling signal subscription inside run context externalBus.send(stateStore.activeSessionId); }); } ``` #### Production Standard (Correct) > **Standard**: Using $effect.root provides an isolated reactive boundary with an explicit cleanup handle. Reading external side-effects with untrack() ensures downstream updates do not circularly reinvoke the reactive graph, and returning the dispose function enables deterministic lifecycle teardown upon unmounting. ```typescript // bridge-subscriber.ts import { untrack } from 'svelte'; export interface BridgeHandle { dispose: () => void; } export function bridgeExternalStore( externalBus: { send: (payload: string) => void }, stateStore: { activeSessionId: string } ): BridgeHandle { const cleanup = $effect.root(() => { $effect(() => { // Explicitly track only intended signals, read bridge properties cleanly const sessionId = stateStore.activeSessionId; untrack(() => { externalBus.send(sessionId); }); }); }); return { dispose: () => { cleanup(); } }; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Svelte 5 Runes Fine-Grained Reactive Context Isolation Invariant

Svelte 5 Runes Fine-Grained Reactive Context Isolation Invariant defines an industrial-grade behavioral standard for frontend engineering. Enforces strict lifecycle-bound encapsulation for Svelte 5 runes ($state, $effect, $derived) within micro-frontend architectures and component hierarchies. Prevents memory leaks caused by module-level signal subscriptions and cross-boundary graph pollution where external event cascades trigger untracked reactive evaluation in unmounted sub-trees. 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: Module-Scoped Signal Retention and Unbounded Cross-Boundary Reactive Graph Pollution 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	Module-Scoped Signal Retention and Unbounded Cross-Boundary Reactive Graph Pollution	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 NEVER export raw, mutable `$state` signals directly from module roots across federated boundaries or micro-frontend bridge interfaces.

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.