Svelte 5 Snippet Context Scoping and Effect Teardown Guardrail

--- description: Svelte 5 Snippet Context Scoping and Effect Teardown Guardrail - Enforces deterministic reactive signal disposal and DOM lifecycle isolation when Svelte 5 snippets cross asynchronous, deferred, or portal boundaries. Prevents uncollected fine-grained reactive subscriptions, detached DOM nodes, and memory leaks caused by snippets capturing parent reactive scopes that outlive rendering contexts. globs: src/**/*.svelte, src/**/*.svelte.ts, src/**/*.svelte.js alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/svelte-5-snippet-context-teardown-guardrail" --- # Svelte 5 Snippet Context Scoping and Effect Teardown Guardrail > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Escaping Snippet Closures to Asynchronous Registries Without Controlled Reactive Ownership Roots ## System Constraints You are a Principal Engineer enforcing Svelte 5 Snippet Context Scoping and Effect Teardown Guardrails. You mandate strict boundaries around Svelte 5 Snippets (type `Snippet<[...]>`) to prevent signal leakage and zombie DOM listeners. Snippets close over their lexical environment; when transferred across async component boundaries, global stores, or imperative portal overlays, they capture the parent component's reactive owner tree. You must ensure all programmatic or cross-boundary snippet renders are encapsulated within explicit `$effect.root` wrappers with explicit teardowns, or bound strictly to the consumer's component lifecycle. ## Strict Guidelines - Engineers MUST ALWAYS manage imperative snippet rendering through `$effect.root` to capture and destroy fine-grained signal subscriptions deterministically. - Engineers MUST NOT stash raw `Snippet` references in global module-level state or decoupled async registries without pairing them with their originating lifecycle owner. - Code SHOULD pass parameterized primitives or pure getters into snippets rather than letting snippets bind to long-lived parent `$state` proxies across dynamic boundaries. - Components MUST invoke the teardown callback returned by `$effect.root` whenever dynamic snippets are dismissed, replaced, or unmounted in asynchronous portals. - Components NEVER bind `$effect` routines inside snippets that perform side effects without returning an explicit cleanup function. ## Bad vs Good Implementations ### Async Portal/Toast Snippet Registration #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Pushing a raw Snippet instance into a module-scoped reactive array binds the snippet to its declaration context. When rendered in a separate async boundary (e.g., ToastContainer), signals and DOM nodes closed over by the snippet cannot be garbage collected upon parent unmount, causing leaks and ghost state recalculations. ```typescript // toast-service.svelte.ts import type { Snippet } from 'svelte'; interface ToastItem { id: string; content: Snippet; } // Module-level reactive store holding uncontained snippet closures export const toastStore = $state<ToastItem[]>([]); export function pushToast(content: Snippet) { const id = crypto.randomUUID(); // ANTI-PATTERN: Captures parent lexical reactive context. // If the parent component unmounts, the snippet retains // signals, closures, and DOM event listeners without disposal. toastStore.push({ id, content }); } ``` #### Production Standard (Correct) > **Standard**: Decoupling snippet rendering behind controlled mount/unmount closures or encapsulating async snippet execution inside an `$effect.root()` context guarantees that fine-grained signals and DOM observers are deterministically destroyed when the overlay or async boundary unmounts. ```typescript // toast-service.svelte.ts import { untrack, type Snippet } from 'svelte'; interface ActiveToast { id: string; render: (target: HTMLElement) => () => void; } export const toastStore = $state<ActiveToast[]>([]); export function pushToast(renderer: (target: HTMLElement) => () => void) { const id = crypto.randomUUID(); toastStore.push({ id, render: renderer }); return () => { const index = toastStore.findIndex((t) => t.id === id); if (index !== -1) { toastStore.splice(index, 1); } }; } // ToastWrapper.svelte // <script lang="ts"> // import { untrack } from 'svelte'; // import type { Snippet } from 'svelte'; // import { pushToast } from './toast-service.svelte'; // // let { toastSnippet }: { toastSnippet: Snippet } = $props(); // // function handleOpen() { // // PROD PATTERN: Isolate snippet rendering inside an explicit $effect.root // const cleanupRoot = $effect.root(() => { // // Mount and teardown logic explicitly managed per instance // return () => { // /* deterministic signal cleanup */ // }; // }); // } // </script> ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Svelte 5 Snippet Context Scoping and Effect Teardown Guardrail

Svelte 5 Snippet Context Scoping and Effect Teardown Guardrail defines an industrial-grade behavioral standard for frontend engineering. Enforces deterministic reactive signal disposal and DOM lifecycle isolation when Svelte 5 snippets cross asynchronous, deferred, or portal boundaries. Prevents uncollected fine-grained reactive subscriptions, detached DOM nodes, and memory leaks caused by snippets capturing parent reactive scopes that outlive rendering contexts. 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: Escaping Snippet Closures to Asynchronous Registries Without Controlled Reactive Ownership Roots 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	Escaping Snippet Closures to Asynchronous Registries Without Controlled Reactive Ownership Roots	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 manage imperative snippet rendering through `$effect.root` to capture and destroy fine-grained signal subscriptions deterministically.

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.