Core Web Vitals (INP, LCP, CLS) & Main Thread Yielding Standard

Q: How does adopting this rule prevent AI hallucinations?

This rule explicitly declares what the AI must avoid (AI executes large data transformation loops synchronously in event handlers, blocking the main thread and resulting in catastrophic INP failures (>500ms).) and prescribes verified positive examples. Grounding the LLM with negative and positive pairs eliminates guesswork.

--- description: Core Web Vitals (INP, LCP, CLS) & Main Thread Yielding Standard - Production performance engineering standard for modern web applications. Mandates Interaction to Next Paint (INP) < 200ms using scheduler.yield() chunking, explicit layout dimensions preventing Cumulative Layout Shift (CLS), and priority resource loading (fetchpriority='high'). globs: **/*.tsx, **/*.jsx, **/*.vue, **/*.ts alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/core-web-vitals-inp-lcp-optimization" --- # Core Web Vitals (INP, LCP, CLS) & Main Thread Yielding Standard > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: AI executes large data transformation loops synchronously in event handlers, blocking the main thread and resulting in catastrophic INP failures (>500ms). ## System Constraints You are a Web Performance and Core Web Vitals Specialist. When writing UI interactions or data rendering, you must guarantee INP < 200ms, LCP < 2.5s, and CLS < 0.1. Never execute heavy loops synchronously inside click or input handlers. Yield control back to the browser using scheduler.yield() or requestAnimationFrame. ## Strict Guidelines - Break long tasks (>50ms) into discrete micro-chunks using scheduler.yield() or setTimeout fallback to let the browser process user input and render frames. - Never update React state synchronously for hundreds of DOM elements in a single event loop tick; use useTransition or startTransition for non-urgent updates. - Always specify explicit width and height or aspect-ratio on all images, videos, and dynamic embeds to eliminate Cumulative Layout Shift (CLS). - Prioritize Above-the-Fold Largest Contentful Paint (LCP) images with priority={true} (Next.js) or fetchpriority='high' and decoding='async'. - Avoid layout thrashing by separating DOM reads (e.g. offsetHeight) from DOM writes (e.g. style.height) across animation frames. ## Bad vs Good Implementations ### Breaking Long Iteration Tasks with scheduler.yield() for Sub-200ms INP #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Executing a monolithic filter loop blocks the main thread for over 250ms. User input events cannot be dispatched, resulting in an INP penalty that drops Google Lighthouse and SEO ranking into the poor bracket. ```typescript // FATAL: Synchronously processing 10,000 records inside user search filter function onFilterChange(query: string, rawItems: Item[]) { // BLOCKS MAIN THREAD: 250ms of CPU locking prevents click dispatch and typing const filtered = rawItems.filter(item => heavyRegexMatch(item, query)); updateDOMList(filtered); } ``` #### Production Standard (Correct) > **Standard**: Implements cooperative multi-tasking with scheduler.yield(). The iteration pauses every 16ms, allowing the browser engine to flush paints and handle incoming user events, ensuring INP remains under 50ms. ```typescript // Cross-browser cooperative task yielding async function yieldToMain(): Promise<void> { if ('scheduler' in window && 'yield' in (window as any).scheduler) { return await (window as any).scheduler.yield(); } return new Promise(resolve => setTimeout(resolve, 0)); } async function processItemsChunked(query: string, rawItems: Item[], onProgress: (items: Item[]) => void) { const result: Item[] = []; let lastYieldTime = performance.now(); for (let i = 0; i < rawItems.length; i++) { if (heavyRegexMatch(rawItems[i], query)) { result.push(rawItems[i]); } // Yield every 16ms to allow browser to paint at 60 FPS if (performance.now() - lastYieldTime > 16) { await yieldToMain(); lastYieldTime = performance.now(); } } onProgress(result); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Core Web Vitals (INP, LCP, CLS) & Main Thread Yielding Standard

Core Web Vitals (INP, LCP, CLS) & Main Thread Yielding Standard defines an industrial-grade behavioral standard for frontend engineering. Production performance engineering standard for modern web applications. Mandates Interaction to Next Paint (INP) < 200ms using scheduler.yield() chunking, explicit layout dimensions preventing Cumulative Layout Shift (CLS), and priority resource loading (fetchpriority='high'). 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: AI executes large data transformation loops synchronously in event handlers, blocking the main thread and resulting in catastrophic INP failures (>500ms). 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	AI executes large data transformation loops synchronously in event handlers, blocking the main thread and resulting in catastrophic INP failures (>500ms).	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:

Break long tasks (>50ms) into discrete micro-chunks using scheduler.yield() or setTimeout fallback to let the browser process user input and render frames.

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.