// Web Performance & Core Web Vitals — concept page for /concepts/web-perf-core-vitals. // Google CWV (2024-2026): LCP < 2.5s, INP < 200ms (replaced FID 2024), CLS < 0.1. // p75 of real users (CrUX) is ranking signal. Tools: Lighthouse, PageSpeed Insights, RUM. // Runtime: browser sandbox. Globals: TopologyBuilder, FlowBuilder. No import/export. const topology = new TopologyBuilder(true); // === User device === const userGroup = topology.createGroup('user', { label: 'User device (Chrome, slow 4G, mid-tier CPU)', x: 60, y: 60, }); userGroup .addProcess({ id: 'browser', label: 'Browser main thread', icon: 'browser', state: 'running', capacity: { maxRps: 60, replicas: 1 }, decisions: [ { id: 'ADR-001', title: 'Performance budget enforcement в CI как hard gate, не как dashboard', status: 'accepted', context: 'Команда ловит perf regression через 2-4 недели после деплоя — когда CrUX показывает p75 LCP > 2.5s и Search Console шлёт alert о падении ranking. К этому моменту виновата не одна PR, а 5-10 мелких изменений: новый analytics SDK +30KB, hero image PNG вместо AVIF, useEffect блокирующий hydration, sync localStorage в render. Постфактум разбираться дорого: blame git history, A/B бенчмаркать revert, переубеждать продукт что "новый виджет engagement +1.5% но LCP +400ms". Lighthouse score в PR описании никто не читает; "performance dashboard" в Grafana становится noise через месяц. Нужен механизм который ОСТАНАВЛИВАЕТ regression в момент введения, не через 4 недели.', decision: 'Performance budget = hard CI gate, fail PR при превышении. Конкретные budgets (Lighthouse CI / size-limit / bundlewatch): JS bundle initial route < 170KB gzipped (Lighthouse baseline для INP/LCP на 4G + mid-CPU), CSS < 30KB, images on landing < 500KB total, web fonts < 100KB total. Lab metrics: Lighthouse LCP < 2.5s, TBT < 200ms (proxy для INP в lab — INP не измеряется в Lighthouse), CLS < 0.1, score >= 90 на mobile. Реализация: treosh/lighthouse-ci-action в GitHub Actions, lhci autorun против preview deploy, baseline в lhci-server / отдельный JSON committed в репо. Бюджет per-route (homepage strict, deep nested менее), не глобальный — иначе heavy /admin тянет вниз lightweight /. Override механизм: PR label perf-budget-override требует approve от perf-owner + новый budget commit (zero hidden regressions, всё в git history). Тренд-tracking parallel: CrUX field data в weekly ops review (lab catches majority, CrUX ловит то что lab не видит — slow CPU users, slow networks). Анти-паттерн: budget = warn в Slack — за 2 недели игнор-эффект, regression проходит. Анти-паттерн: budget на gzipped, но dependency tree приходит uncompressed CDN — измеряй в network tab, не в build artifact. Анти-паттерн: один budget на весь app — заставит heavy admin route снижать landing budget. Trade-off: иногда нужно legitimately превысить (новый product feature) — процесс через explicit override + новый budget, не silent allow.', date: '2026-05-14', }, { id: 'ADR-002', title: 'Когда оптимизировать INP через web worker vs scheduler.postTask vs useTransition', status: 'accepted', context: 'INP < 200ms — самая жёсткая из CWV: измеряет worst interaction за всю сессию (не average!), включая slow 3rd-party scripts, garbage collection pauses, long event handlers. Типичные виновники: heavy state recompute на input change, sync filtering 10K-item list, JSON.parse гигантского payload в click handler, hydration trampling по интерактивности. Три инструмента для разруливания main thread, и команды путают, когда какой: useTransition (React-concurrent), scheduler.postTask (raw Web API), Web Worker (offload в другой thread). Выбор не по вкусу — определяется природой работы.', decision: 'Decision tree: (1) Если работа — это React state update который вызывает много re-renders (filter list, sort table, search-as-you-type, change theme, recalc derived state), используй useTransition. Render продолжает быть на main thread, но React помечает update как non-urgent, прерывает на user input, рендерит progressive. Cost: 0 — это часть React 18+. Лимит: помогает когда bottleneck = React reconciliation, не помогает если bottleneck = твой код в reducer/computation. (2) Если работа — это short-but-non-React задача, которую можно отложить на idle (analytics flush, prefetch, background work), используй scheduler.postTask с priority background или requestIdleCallback. Cost: 0 — native API. Лимит: всё ещё main thread, мешает если задача > 50ms. (3) Если работа — это CPU-heavy compute (JSON.parse 5MB, image decode, regex over big text, crypto, ML inference, fuzzy search index, markdown parsing для editor), уноси в Web Worker. Main thread остаётся отзывчивым полностью. Cost: communication overhead postMessage (~1-5ms), structured clone для больших объектов; около 100 строк кода и build setup (Vite/Webpack worker plugin). Лимит: нельзя обращаться к DOM, нельзя SharedArrayBuffer без COOP/COEP. Pattern: combine — useTransition для UX-плавности re-render + Web Worker для heavy compute, postTask для background flushing analytics. Анти-паттерн: useTransition обёрнутый вокруг fetch — не помогает (fetch уже async), маскирует bug. Анти-паттерн: всё в Web Worker по дефолту — overhead postMessage > выигрыш для маленьких задач (<20ms). Анти-паттерн: оптимизирую INP через debounce — debounce помогает уменьшить ЧАСТОТУ работы, но единичная interaction всё ещё медленная если handler heavy. Измеряй: Chrome DevTools Performance Long Tasks lane показывает реальных виновников; web-vitals.js attribution build (onINP с attribution: true) в production даёт component-level breakdown.', date: '2026-05-14', }, { id: 'ADR-003', title: 'CLS bulletproofing: explicit dimensions для всех visual elements vs CSS aspect-ratio vs реактивный resize', status: 'accepted', context: 'CLS — единственная CWV которая измеряется не за один моментный замер, а CUMULATIVE — суммирует все unexpected layout shifts за session window (5 sec, max 5 sec gap). Один поздно-загруженный image без width/height легко даёт CLS=0.4 (poor) на мобильнике с slow network. Виновники по убыванию частоты: (1) img без width/height — пустое место 0x0, потом 600x400 = jump на 400px; (2) web font swap — fallback Helvetica и custom Inter с разной x-height сдвигает все блоки; (3) ad slots / cookie banner / GDPR overlay появляющиеся через 2с после load; (4) skeleton loaders с неправильной высотой; (5) async-loaded карточки внизу feed which push existing content; (6) third-party widgets (chat, social embed). Каждый из этих pattern имеет proper fix, но fix-by-fix не масштабируется — нужна system-level discipline.', decision: 'Layered defense: (1) Lint-rule banning img без width/height ИЛИ aspect-ratio (eslint-plugin-jsx-a11y has alt-text; для dimensions custom rule или eslint-plugin-react/jsx-no-img-without-dimensions). Для responsive images используй aspect-ratio: 16/9 в CSS + width: 100% — браузер резервирует место по соотношению до загрузки. Для Next.js / Astro / similar — встроенные Image компоненты делают это автоматически и являются default. (2) Fonts: всегда font-display: swap + size-adjust / ascent-override / descent-override для metric matching с fallback (использовать tool как fontaine или next/font который автоматически генерирует local fallback с правильными metrics — CLS для font load = 0). Альтернатива дорогая: font-display: optional (если font не загрузился за 100ms — не показываем), но рискуешь FOUT навсегда. (3) Reserve space для всего что появится async: ad slots — min-height: 250px placeholder, cookie banner — render at SSR с visibility: hidden + flip на client (или fixed-position overlay который НЕ влияет на normal flow), skeleton loader — точная высота итогового content. (4) Late-mounted components: transform translateY -100% (не affects layout) вместо display none -> block. (5) Measurement в production: web-vitals.js onCLS с attribution: true даёт largestShiftTarget — DOM selector виновника. Логируй в Sentry/RUM с DOM selector — instant root cause. Trade-off: aspect-ratio CSS не работает в IE11 (мы не support), но 100% Chrome/Safari/FF; explicit width/height attributes работают везде но требуют знать dimensions заранее (для UGC images приходится store metadata в БД). Анти-паттерн: min-height: 100vh на main — маскирует CLS но создаёт visible empty space. Анти-паттерн: animate height with transition — animated layout shifts не считаются в CLS, но это hack, реальный UX всё ещё плохой. Анти-паттерн: измерять CLS только в Lighthouse — lab CLS measures одну загрузку, real CrUX CLS — за всю session, может быть 5x хуже из-за scroll-triggered content.', date: '2026-05-14', }, ], }) .addProcess({ id: 'main-thread', label: 'JS event loop', icon: 'cpu', state: 'running' }) .addProcess({ id: 'worker', label: 'Web Worker (heavy compute)', icon: 'cpu', state: 'running' }) .autoResize(); // === Network / Edge === const edgeGroup = topology.createGroup('edge', { label: 'Edge / CDN (Cloudflare, Vercel, Fastly)', x: 720, y: 60, }); edgeGroup .addProcess({ id: 'cdn', label: 'CDN cache (HTML, AVIF, JS)', icon: 'cloud', state: 'running', capacity: { maxRps: 100000, replicas: 1 } }) .addProcess({ id: 'edge-fn', label: 'Edge function (SSR/RSC)', icon: 'lambda', state: 'running' }) .autoResize(); // === Origin === const originGroup = topology.createGroup('origin', { label: 'Origin (slow path on cache miss)', x: 720, y: 380, }); originGroup .addProcess({ id: 'ssr', label: 'Node SSR / Next.js server', icon: 'server', state: 'running' }) .addProcess({ id: 'api', label: 'API', icon: 'api', state: 'running' }) .addProcess({ id: 'db', label: 'Postgres', icon: 'database', state: 'running' }) .autoResize(); // === Telemetry: RUM + lab === const telemetryGroup = topology.createGroup('telemetry', { label: 'Telemetry: RUM (real users) + Lab (Lighthouse CI)', x: 60, y: 520, }); telemetryGroup .addProcess({ id: 'rum', label: 'web-vitals.js beacon', icon: 'chart', state: 'running' }) .addProcess({ id: 'rum-store', label: 'Sentry / Vercel Speed Insights', icon: 'storage', state: 'running' }) .addProcess({ id: 'crux', label: 'CrUX (Chrome p75, ranking signal)', icon: 'chart', state: 'running' }) .addProcess({ id: 'lhci', label: 'Lighthouse CI (PR gate)', icon: 'shield', state: 'running' }) .autoResize(); // === Edges: physical connections === topology.connect('browser', 'cdn', { type: 'tcp', label: 'HTTPS' }); topology.connect('cdn', 'edge-fn', { type: 'tcp', label: 'cache miss' }); topology.connect('edge-fn', 'ssr', { type: 'tcp', label: 'fallback' }); topology.connect('ssr', 'api', { type: 'tcp', label: 'data fetch' }); topology.connect('api', 'db', { type: 'tcp', label: 'SQL' }); topology.connect('browser', 'main-thread', { type: 'tcp', label: 'JS exec' }); topology.connect('main-thread', 'worker', { type: 'tcp', label: 'postMessage' }); topology.connect('browser', 'rum', { type: 'tcp', label: 'beacon' }); topology.connect('rum', 'rum-store', { type: 'tcp', label: 'POST /vitals' }); topology.connect('browser', 'crux', { type: 'tcp', label: 'Chrome telemetry' }); topology.connect('lhci', 'cdn', { type: 'tcp', label: 'audit preview' }); await topology.apply(); const flow = new FlowBuilder(); // ============================================================ // Scenario 1: Bad LCP (4.2s) — render-blocking + huge hero // ============================================================ flow .scenario('bad-lcp', 'Bad LCP — 4.2s (poor): render-blocking CSS + 800KB hero JPEG', 'Классический LCP failure: CSS блокирует render, hero image не preloaded, без modern format') .from('browser').showMessage('[NAV] User clicks link, navigates to /landing') .from('browser').to('cdn').showMessage('[GET /] Request HTML') .from('cdn').to('browser').showMessage('[200] HTML returned, TTFB=120ms') .from('browser').showMessage('[PARSE] Browser parses HTML, finds link rel=stylesheet') .from('browser').to('cdn').showError('[BLOCK] GET /styles.css — 200KB render-blocking') .from('cdn').to('browser').showError('[CSS] 350ms download + parse — render frozen until done') .from('browser').showMessage('[FCP=720ms] First text paints — but no hero yet') .from('browser').showMessage('[DISCOVER] HTML parser finds img src=/hero.jpg only after CSS') .from('browser').to('cdn').showError('[GET hero.jpg] 800KB JPEG, no fetchpriority hint') .from('cdn').to('browser').showError('[SLOW] 3.5s download on 4G, default priority Low') .flashError('browser') .from('browser').showError('[LCP=4.2s] POOR — Search Console alert, ranking penalty') .from('browser').to('rum').showError('[BEACON] web-vitals.js sends LCP=4200, element=img.hero') .from('rum').to('rum-store').showMessage('[STORE] Sentry collects, p75 over 28d > 2.5s') .from('browser').showMessage('[ROOT CAUSE] No preload, no AVIF, render-blocking CSS, no fetchpriority') .from('browser').showMessage('[FIX PLAN] inline critical CSS + link rel=preload as=image fetchpriority=high + AVIF'); // ============================================================ // Scenario 2: Optimized LCP (1.6s) — preload + AVIF + critical CSS // ============================================================ flow .scenario('optimized-lcp', 'Optimized LCP — 1.6s (good): preload hero + AVIF + inlined critical CSS', 'Same page after fixes: hero discovered immediately, modern format, no render block') .from('browser').showMessage('[NAV] Same /landing route, after optimizations') .from('browser').to('cdn').showMessage('[GET /] Request HTML') .from('cdn').to('edge-fn').showMessage('[103 EARLY HINTS] Link header: hero.avif rel=preload as=image') .from('edge-fn').to('browser').showMessage('[103] Browser starts hero preload BEFORE HTML body arrives') .from('browser').to('cdn').showMessage('[GET hero.avif] fetchpriority=high, parallel with HTML') .from('cdn').to('browser').showMessage('[200] HTML, TTFB=80ms (edge cache hit)') .from('browser').showMessage('[INLINE CRITICAL CSS] style tag in head, no blocking external') .from('browser').showMessage('[FCP=380ms] Text paints immediately') .from('cdn').to('browser').showMessage('[hero.avif] 60KB AVIF (vs 800KB JPEG = 13x smaller)') .from('browser').showMessage('[LCP=1.6s] GOOD — hero painted, well under 2.5s') .from('browser').to('rum').showMessage('[BEACON] LCP=1600, element=img.hero') .from('rum').to('rum-store').showMessage('[STORE] p75 trends down, CrUX in green') .from('crux').showMessage('[RANKING] Google CrUX 28d p75 < 2.5s — no penalty') .from('browser').showMessage('[KEY TACTICS] preload + AVIF + critical CSS + Early Hints + edge cache'); // ============================================================ // Scenario 3: CLS spike (0.4) — image without dimensions // ============================================================ flow .scenario('cls-spike', 'CLS spike — 0.4 (poor): image without width/height + late web font + cookie banner', 'Three layout shifts compound: image jump + font swap reflow + GDPR banner') .from('browser').to('cdn').showMessage('[GET /] HTML loads') .from('cdn').to('browser').showMessage('[HTML] img src=/photo.jpg WITHOUT width/height') .from('browser').showMessage('[LAYOUT 1] Browser reserves 0x0 for image (unknown dimensions)') .from('browser').showMessage('[FCP=500ms] Text rendered, but image slot is empty 0x0') .from('cdn').to('browser').showMessage('[CSS] Custom font Inter requested') .from('browser').showMessage('[FALLBACK] Helvetica shown immediately') .from('cdn').to('browser').showMessage('[FONT] Inter loads after 800ms') .flashError('browser') .from('browser').showError('[SHIFT 1] Font swap: Inter wider than Helvetica, every line reflows, score=0.08') .from('cdn').to('browser').showMessage('[IMG] photo.jpg loads at 1.2s, real size 800x600') .flashError('browser') .from('browser').showError('[SHIFT 2] Image expands 0x0 -> 800x600, pushes 600px down, score=0.25') .from('browser').to('rum').showMessage('[3rd-party] GDPR cookie banner script loads at 2s') .flashError('browser') .from('browser').showError('[SHIFT 3] Cookie banner inserted at top, pushes everything 80px down, score=0.07') .from('browser').showError('[CLS=0.40] POOR (sum of shifts in 5s window) — ranking signal degraded') .from('browser').to('rum').showError('[BEACON] CLS=0.4, attribution: largestShiftTarget=img.photo') .from('browser').showMessage('[FIX 1] img width=800 height=600 OR aspect-ratio CSS') .from('browser').showMessage('[FIX 2] next/font OR fontaine — generate local fallback with metric overrides') .from('browser').showMessage('[FIX 3] GDPR banner = fixed-position overlay, not in normal flow') .from('browser').showMessage('[RESULT after fixes] CLS=0.02, all green'); // ============================================================ // Scenario 4: Bad INP (380ms) — long task blocks main thread // ============================================================ flow .scenario('bad-inp', 'Bad INP — 380ms (poor): heavy click handler blocks main thread', 'Filter 10K-item list synchronously in click handler — blocks paint until done') .from('browser').showMessage('[USER] Clicks filter chip Show Active Only') .from('browser').to('main-thread').showMessage('[EVENT] click handler fires') .from('main-thread').showError('[LONG TASK] sync filter over 10K items + setState -> re-render 10K rows') .flashError('main-thread') .from('main-thread').showError('[BLOCK] Main thread blocked 350ms — no paint, no input response') .from('main-thread').to('browser').showError('[PAINT] Finally paints filtered list') .from('browser').showError('[INP=380ms] POOR — user perceives lag, abandoned 12% more') .from('browser').to('rum').showError('[BEACON] onINP attribution: longAnimationFrame, scriptDuration=320ms') .from('rum').to('rum-store').showMessage('[STORE] Sentry shows worst-case INP per session') .from('browser').showMessage('[ANALYSIS] Bottleneck = React reconciliation + heavy compute in handler') .from('browser').showMessage('[FIX 1] useTransition: mark filter-state-update as non-urgent -> React yields to input') .from('browser').showMessage('[FIX 2] Virtualize list (react-window) — render 20 visible rows, not 10K') .from('browser').showMessage('[FIX 3] If pure compute heavy -> offload to Web Worker (postMessage)'); // ============================================================ // Scenario 5: Good INP (90ms) — useTransition + virtualization // ============================================================ flow .scenario('good-inp', 'Good INP — 90ms: useTransition + virtualization keep main thread responsive', 'Same interaction after fix: input painted immediately, results stream in') .from('browser').showMessage('[USER] Clicks same filter chip') .from('browser').to('main-thread').showMessage('[EVENT] click handler fires') .from('main-thread').showMessage('[startTransition] mark setState as non-urgent') .from('main-thread').to('browser').showMessage('[PAINT 60ms] Chip visually pressed, ripple animation runs') .from('browser').showMessage('[INP=90ms] GOOD — user sees immediate response') .from('main-thread').showMessage('[YIELD] React time-slices reconciliation, yields to input every ~5ms') .from('main-thread').showMessage('[VIRTUALIZE] react-window renders only 20 visible rows, not 10K') .from('main-thread').to('browser').showMessage('[PAINT 180ms] Filtered list visible, smooth scroll') .from('browser').to('rum').showMessage('[BEACON] INP=90, all green') .from('browser').showMessage('[BONUS] If we had pure compute (e.g. fuzzy search index 50MB) -> Web Worker') .from('main-thread').to('worker').showMessage('[postMessage] type=search, query=active') .from('worker').showMessage('[OFFLOAD] heavy work runs in worker thread, main stays free') .from('worker').to('main-thread').showMessage('[postMessage] results returned') .from('main-thread').to('browser').showMessage('[PAINT] results render, main thread never blocked'); // ============================================================ // Scenario 6: CI perf budget enforcement — block bad PR // ============================================================ flow .scenario('ci-budget', 'CI perf budget gate — block PR before regression hits production', 'Lighthouse CI runs on every PR preview deploy, fails build if budget exceeded') .from('lhci').showMessage('[PR #4521] dev pushes feat: rich-text editor on landing') .from('lhci').to('cdn').showMessage('[AUDIT] Lighthouse CI runs against preview deploy URL') .from('cdn').to('lhci').showMessage('[METRICS] LCP=2.8s, CLS=0.05, TBT=240ms, JS=240KB gz') .from('lhci').showError('[BUDGET CHECK] LCP 2.8s > 2.5s budget, JS 240KB > 170KB budget') .flashError('lhci') .from('lhci').showError('[FAIL] CI red, PR blocked, comment auto-posted with diff') .from('lhci').showMessage('[DEV ACTION] dev investigates: editor SDK 70KB added to landing bundle') .from('lhci').showMessage('[FIX] dynamic import — editor loaded only on /editor route, not landing') .from('lhci').to('cdn').showMessage('[RE-AUDIT] LCP=1.7s, JS=165KB gz') .from('lhci').showMessage('[PASS] PR mergeable') .from('lhci').showMessage('[PHILOSOPHY] Hard gate at PR > soft dashboard 4 weeks later') .from('lhci').showMessage('[OVERRIDE] Label perf-budget-override + perf-owner approve + new budget commit') .from('lhci').showMessage('[PARALLEL] CrUX field data reviewed weekly — catches what lab misses') .from('crux').showMessage('[FIELD] CrUX p75 = ranking signal, lab is proxy'); return flow;