CSS View Transitions L2 Cross-Document Prerender Isolation Standard

--- description: CSS View Transitions L2 Cross-Document Prerender Isolation Standard - Prevents GPU surface buffer leaks, render-tree thrashing, and snapshot race conditions during Speculation Rules-driven multi-page navigations. Enforces explicit gating of pseudo-element capture states (`view-transition-name`) behind the `document.prerendering` lifecycle and requires deterministic resource release on aborted prerenders. globs: src/**/*.{ts,tsx,css,scss} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/css-view-transitions-l2-prerender-isolation" --- # CSS View Transitions L2 Cross-Document Prerender Isolation Standard > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Unconditional Static View-Transition Snapshot Binding During Speculative Prerender Lifecycles ## System Constraints You are a Principal Software Architect enforcing the CSS View Transitions Level 2 Cross-Document Prerender Isolation Standard. You must prevent render-tree thrashing and snapshot memory leaks by ensuring dynamic pseudo-element capture states are never initialized inside unactivated speculative documents. All cross-document view transition references must defer snapshot generation until document activation and bind clean teardown logic on pageswap/pagereveal lifecycles. ## Strict Guidelines - Engineers MUST ALWAYS gate dynamic `view-transition-name` assignments behind `!document.prerendering` or defer assignment until the `prerenderingchange` event resolves. - Engineers MUST NOT declare static, non-isolated `view-transition-name` properties in global stylesheets on components subject to speculative pre-rendering. - Components MUST unbind active transition names and purge transition snapshot wrappers if navigation is aborted or during `pagehide` / `freeze` lifecycles. - Code SHOULD utilize the `pageswap` and `pagereveal` events exclusively to map cross-document view-transition states rather than component mounting lifecycles. - Services MUST enforce explicit memory caps on captured DOM element dimensions to prevent backing-store texture allocation spikes when rendering speculatively in the background. ## Bad vs Good Implementations ### Unsafe Prerender View Transition Binding vs. Prerender-Isolated Transition State Controller #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Assigning `viewTransitionName` during speculative prerender phases allocates GPU textures and locks DOM subtrees into capture groups before activation. If the user navigates elsewhere, the speculative document is discarded, causing GPU texture thrashing and memory retention. ```typescript import React, { useEffect } from 'react'; interface CardProps { id: string; title: string; } // ANTI-PATTERN: Assigns view-transition-name during initial render. // If the page is speculatively prerendered via Speculation Rules API, // the browser allocates GPU snapshot textures for hidden render-trees. // If the user never navigates, these surface buffers leak until garbage collected. export const SpeculativeCard: React.FC<CardProps> = ({ id, title }) => { return ( <div style={{ viewTransitionName: `card-element-${id}`, contain: 'layout' }} className="card-container" > <h2>{title}</h2> </div> ); }; ``` #### Production Standard (Correct) > **Standard**: Production invariant compliant implementation ensuring memory safety, deterministic execution, and zero runtime hallucination. ```typescript import React, { useEffect, useState } from 'react'; interface CardProps { id: string; title: string; } export const SpeculativeCard: React.FC<CardProps> = ({ id, title }) => { const [canCapture, setCanCapture] = useState<boolean>(() => { if (typeof document === 'undefined') return false; // Verify document is not in a background prerendering state return !('prerendering' in document && (document as any).prerendering); }); useEffect(() => { if (typeof document === 'undefined') return; const doc = document as Document & { prerendering?: boolean }; // If currently prerendering, defer transition snapshot identity until activation if (doc.prerendering) { const onPrerenderChange = (): void => { setCanCapture(true); }; doc.addEventListener('prerenderingchange', onPrerenderChange, { once: true }); return () => { doc.removeEventListener('prerenderingchange', onPrerenderChange); }; } // Handle teardown on aborted cross-document transitions const onPageSwap = (event: Event): void => { const swapEvent = event as PageSwapEvent; if (!swapEvent.viewTransition) { setCanCapture(false); } }; window.addEventListener('pageswap', onPageSwap); return () => { window.removeEventListener('pageswap', onPageSwap); setCanCapture(false); }; }, []); return ( <div style={{ viewTransitionName: canCapture ? `card-element-${id}` : 'none', contain: canCapture ? 'layout paint' : 'none' }} className="card-container" > <h2>{title}</h2> </div> ); }; ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: CSS View Transitions L2 Cross-Document Prerender Isolation Standard

CSS View Transitions L2 Cross-Document Prerender Isolation Standard defines an industrial-grade behavioral standard for frontend engineering. Prevents GPU surface buffer leaks, render-tree thrashing, and snapshot race conditions during Speculation Rules-driven multi-page navigations. Enforces explicit gating of pseudo-element capture states (`view-transition-name`) behind the `document.prerendering` lifecycle and requires deterministic resource release on aborted prerenders. 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: Unconditional Static View-Transition Snapshot Binding During Speculative Prerender Lifecycles 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	Unconditional Static View-Transition Snapshot Binding During Speculative Prerender Lifecycles	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 gate dynamic `view-transition-name` assignments behind `!document.prerendering` or defer assignment until the `prerenderingchange` event resolves.

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.