@jgamaraalv/ts-dev-kit 2.2.0 → 3.0.0

package/skills/core-web-vitals/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: core-web-vitals
+description: "Core Web Vitals reference for measuring, diagnosing, and improving LCP, INP, and CLS. Use when: (1) auditing page performance against Google's thresholds, (2) implementing the web-vitals JS library for field monitoring, (3) diagnosing slow LCP, high INP, or layout shifts, (4) choosing between field and lab measurement tools, (5) optimizing specific metrics with the Chrome team's top recommendations, (6) explaining what each metric measures to non-technical stakeholders, or (7) generating a visual CWV report from metric values or a Lighthouse JSON file."
+allowed-tools: Bash(python3 *)
+---
+
+# Core Web Vitals
+
+The three stable Core Web Vitals, each measured at the **75th percentile** of
+real page loads (segmented by mobile and desktop):
+
+| Metric | Measures | Good | Needs Improvement | Poor |
+|--------|----------|------|-------------------|------|
+| **LCP** — Largest Contentful Paint | Loading | ≤ 2.5 s | 2.5–4.0 s | > 4.0 s |
+| **INP** — Interaction to Next Paint | Interactivity | ≤ 200 ms | 200–500 ms | > 500 ms |
+| **CLS** — Cumulative Layout Shift | Visual stability | ≤ 0.1 | 0.1–0.25 | > 0.25 |
+
+A page **passes** Core Web Vitals only if all three metrics meet "Good" at the 75th percentile.
+
+## Quick setup: measure all three in the field
+
+```bash
+npm install web-vitals
+```
+
+```js
+import { onCLS, onINP, onLCP } from 'web-vitals';
+
+function sendToAnalytics(metric) {
+  const body = JSON.stringify(metric);
+  (navigator.sendBeacon && navigator.sendBeacon('/analytics', body)) ||
+    fetch('/analytics', { body, method: 'POST', keepalive: true });
+}
+
+onCLS(sendToAnalytics);
+onINP(sendToAnalytics);
+onLCP(sendToAnalytics);
+```
+
+Each callback receives `{ name, value, rating, delta, id, navigationType }`.
+`rating` is `"good"`, `"needs-improvement"`, or `"poor"`.
+
+> The `web-vitals` library handles bfcache restores, prerendered pages, iframe
+> aggregation, and other edge cases that raw PerformanceObserver does not.
+
+## Tools matrix
+
+| Tool | Type | LCP | INP | CLS | Notes |
+|------|------|-----|-----|-----|-------|
+| Chrome User Experience Report (CrUX) | Field | ✓ | ✓ | ✓ | 28-day rolling window of real users |
+| PageSpeed Insights | Field + Lab | ✓ | ✓ | ✓ | Field = CrUX data; Lab = Lighthouse |
+| Search Console CWV report | Field | ✓ | ✓ | ✓ | Groups URLs by template |
+| Chrome DevTools Performance panel | Field + Lab | ✓ | ✓ | ✓ | Local profiling, interaction tracing |
+| Lighthouse | Lab | ✓ | TBT* | ✓ | CI integration; INP → use TBT as proxy |
+
+*Lighthouse uses **Total Blocking Time (TBT)** as a lab proxy for INP. TBT
+correlates with INP but does not replace field measurement.
+
+## Supporting metrics (non-Core but diagnostic)
+
+- **FCP** (First Contentful Paint) — diagnoses render-blocking resources upstream of LCP
+- **TTFB** (Time to First Byte) — server response time; directly affects LCP
+- **TBT** (Total Blocking Time) — lab proxy for INP; identifies long tasks
+
+## When to read reference files
+
+| Reference | Read when… |
+|-----------|-----------|
+| [references/lcp.md](references/lcp.md) | LCP > 2.5 s, diagnosing slow image/text load, preload/CDN questions |
+| [references/inp.md](references/inp.md) | INP > 200 ms, slow click/key/tap response, long task investigations |
+| [references/cls.md](references/cls.md) | CLS > 0.1, elements jumping on scroll or load, font/image shift |
+| [references/tools.md](references/tools.md) | Setting up monitoring, using DevTools/Lighthouse/PSI, top-9 optimization checklist |
+
+## Generate a visual report
+
+When the user provides metric values or a Lighthouse JSON file, generate an interactive HTML report and open it in the browser:
+
+```bash
+# From manual values
+python3 ~/.claude/skills/core-web-vitals/scripts/visualize.py \
+  --lcp 2.1 --inp 180 --cls 0.05 \
+  --url https://example.com
+
+# From a Lighthouse JSON output
+python3 ~/.claude/skills/core-web-vitals/scripts/visualize.py \
+  --lighthouse lighthouse-report.json
+
+# Custom output path, no auto-open
+python3 ~/.claude/skills/core-web-vitals/scripts/visualize.py \
+  --lcp 3.8 --inp 420 --cls 0.12 \
+  --output cwv-report.html --no-open
+```
+
+The script (`scripts/visualize.py`) requires only Python 3 stdlib — no packages to install.
+It outputs a self-contained HTML file with color-coded metric cards, a visual progress bar showing where each value falls on the Good/Needs Improvement/Poor scale, and an overall PASS/FAIL/NEEDS IMPROVEMENT verdict.
+
+## Metric lifecycle
+
+Metrics progress through: **Experimental → Pending → Stable**.
+All three current Core Web Vitals (LCP, CLS, INP) are **Stable**.
+INP replaced FID (First Input Delay) in March 2024.
+Changes to stable metrics follow an annual cadence with advance notice.

package/skills/core-web-vitals/references/cls.md

@@ -0,0 +1,154 @@
+# CLS — Cumulative Layout Shift
+
+**Good:** ≤ 0.1 | **Needs improvement:** 0.1–0.25 | **Poor:** > 0.25
+(measured at the 75th percentile of field loads)
+
+CLS measures the largest burst of layout shift scores across the entire page
+lifecycle. A layout shift occurs when a visible element changes its start
+position from one rendered frame to the next.
+
+## How the CLS score is calculated
+
+```
+layout shift score = impact fraction × distance fraction
+
+impact fraction = combined area of unstable elements (before + after)
+                  ─────────────────────────────────────────────────
+                  total viewport area
+
+distance fraction = greatest distance any unstable element moved
+                    ──────────────────────────────────────────────
+                    largest viewport dimension (width or height)
+```
+
+Shifts are grouped into **session windows** (max 5 s, max 1 s gap between
+shifts). CLS = the session window with the highest cumulative score.
+
+**Example:** element moves from top 25% to top 50% of viewport →
+- impact fraction ≈ 0.75 (covers 75% of viewport across both positions)
+- distance fraction = 0.25 (moved 25% of viewport height)
+- layout shift score = 0.75 × 0.25 = **0.1875**
+
+## Expected vs. unexpected layout shifts
+
+Only **unexpected** shifts count toward CLS. User-initiated shifts are excluded:
+- Clicking a button that expands content ✓ (expected)
+- Content jumping after an ad loads without reserved space ✗ (unexpected)
+- A banner appearing after page load without reserved space ✗ (unexpected)
+
+Shifts within 500 ms of a user interaction do not count.
+Animations and transitions using CSS `transform` do not cause layout shifts —
+they run off the main thread and do not trigger layout recalculation.
+
+## Common causes and fixes
+
+### Images and videos without dimensions
+Images load asynchronously; without explicit dimensions, the browser doesn't
+know how much space to reserve.
+
+```html
+<!-- Bad: no dimensions, causes layout shift when image loads -->
+<img src="/hero.jpg" alt="hero">
+
+<!-- Good: explicit width/height let browser reserve space -->
+<img src="/hero.jpg" alt="hero" width="1200" height="600">
+
+<!-- Also good for responsive images -->
+<img src="/hero.jpg" alt="hero" width="1200" height="600"
+     style="width: 100%; height: auto;">
+```
+
+The `aspect-ratio` CSS property is a modern alternative:
+```css
+img { aspect-ratio: 16 / 9; width: 100%; }
+```
+
+### Ads, embeds, and iframes without reserved space
+Always define a minimum height for ad slots and dynamic embed containers:
+```css
+.ad-slot { min-height: 250px; }
+.video-embed { aspect-ratio: 16 / 9; }
+```
+
+### Dynamically injected content above existing content
+Avoid inserting banners, cookie notices, or promotional elements above existing
+page content after load. If necessary, reserve the space in the layout before
+content loads, or insert below the fold.
+
+### Web fonts causing FOUT/FOIT shifts
+Flash of Unstyled Text (FOUT) can cause layout shifts if the fallback font
+has different metrics than the loaded font.
+
+```css
+/* Preferred: font-display: optional never shows fallback, eliminates shift */
+@font-face {
+  font-family: 'MyFont';
+  src: url('/fonts/myfont.woff2') format('woff2');
+  font-display: optional;
+}
+```
+
+Use the `size-adjust`, `ascent-override`, `descent-override`, and
+`line-gap-override` descriptors to match fallback font metrics:
+```css
+@font-face {
+  font-family: 'MyFont-fallback';
+  src: local('Arial');
+  size-adjust: 104%;
+  ascent-override: 90%;
+}
+```
+
+### Animations that trigger layout (not using transform)
+CSS properties that trigger layout recalculation cause shifts:
+- **Avoid:** `top`, `left`, `right`, `bottom`, `margin`, `padding`, `width`, `height`
+- **Use instead:** `transform: translate()`, `transform: scale()`, `opacity`
+
+```css
+/* Bad: triggers layout */
+.slide-in { transition: margin-left 0.3s ease; }
+
+/* Good: compositor-only, no layout shift */
+.slide-in { transition: transform 0.3s ease; transform: translateX(0); }
+.slide-in.hidden { transform: translateX(-100%); }
+```
+
+## bfcache eligibility improves CLS
+
+Pages restored from the back/forward cache (bfcache) don't reload resources,
+which eliminates many common layout shifts. Ensure your pages are bfcache
+eligible:
+- Avoid `unload` event listeners
+- Don't use `Cache-Control: no-store` unnecessarily
+- Close open `IndexedDB` transactions before navigating away
+- Avoid `window.opener` references
+
+Check bfcache eligibility in Chrome DevTools: Application → Back/forward cache.
+
+## Measure CLS in JavaScript
+
+```js
+let clsValue = 0;
+let clsEntries = [];
+
+new PerformanceObserver((list) => {
+  for (const entry of list.getEntries()) {
+    if (!entry.hadRecentInput) {
+      clsValue += entry.value;
+      clsEntries.push(entry);
+    }
+  }
+}).observe({ type: 'layout-shift', buffered: true });
+```
+
+Prefer `onCLS()` from the `web-vitals` library — it correctly implements
+session windowing and excludes user-initiated shifts.
+
+## Key nuances
+
+- CLS is measured for the entire page lifecycle, including after user interaction
+- `layout-shift` entries from iframes are not visible in the parent frame's
+  raw API — the web-vitals library does not cover this gap either
+- CLS is 0 for pages with no layout shifts (even with heavy JS)
+- Adding new DOM elements that push existing elements down = layout shift
+  only if it changes the **start position** of existing visible elements

package/skills/core-web-vitals/references/inp.md

@@ -0,0 +1,140 @@
+# INP — Interaction to Next Paint
+
+**Good:** ≤ 200 ms | **Needs improvement:** 200–500 ms | **Poor:** > 500 ms
+(measured at the 75th percentile of field loads)
+
+INP replaced FID (First Input Delay) as a Core Web Vital in March 2024.
+Unlike FID (only measured the first interaction's input delay), INP measures
+**all interactions** on the page — clicks, taps, and key presses — and reports
+the worst one observed.
+
+## What makes up an interaction?
+
+Each interaction has three phases:
+
+```
+[user gesture]
+     │
+     ▼
+┌─────────────────┐
+│  Input delay    │  Time before event handlers start (blocked by other tasks)
+└────────┬────────┘
+         │
+         ▼
+┌─────────────────┐
+│ Processing time │  Time to run event handlers (JS execution)
+└────────┬────────┘
+         │
+         ▼
+┌─────────────────┐
+│Presentation     │  Time to render the next frame (layout, paint, composite)
+│delay            │
+└─────────────────┘
+         │
+         ▼
+  [visual feedback]
+```
+
+INP = input delay + processing time + presentation delay
+
+Only clicks, taps, and key presses count. Hover and scroll do not.
+No INP value is reported if the user never interacts with the page.
+
+## Common causes of high INP
+
+### Long input delay (main thread is busy)
+- Long tasks (> 50 ms) scheduled during or just before the interaction
+- Timer callbacks (`setInterval`, `setTimeout`) running too frequently
+- Third-party scripts blocking the main thread
+
+**Fix: yield to the main thread between tasks**
+
+```js
+// Instead of doing everything synchronously:
+function handleClick() {
+  doHeavyWork();   // blocks interaction handling
+  updateUI();
+}
+
+// Yield after each chunk using scheduler.yield() (Chrome 129+)
+async function handleClick() {
+  doFirstChunk();
+  await scheduler.yield();  // gives browser a chance to handle interactions
+  doSecondChunk();
+  await scheduler.yield();
+  updateUI();
+}
+
+// Fallback for older browsers
+function yieldToMain() {
+  return new Promise(resolve => setTimeout(resolve, 0));
+}
+```
+
+### Heavy event handler processing time
+- Running too much synchronous JS inside `onclick`/`onkeydown` handlers
+- Triggering expensive recalculations (style, layout) inside handlers
+
+**Fix: defer non-essential work**
+
+```js
+element.addEventListener('click', async (event) => {
+  // Do only what's needed for the immediate visual update
+  updateButtonState(event.target);
+
+  // Defer expensive analytics/processing until after the frame paints
+  await scheduler.yield();
+  sendAnalytics(event);
+  prefetchRelatedContent();
+});
+```
+
+### Large rendering updates (presentation delay)
+- Re-rendering a large DOM subtree unnecessarily
+- Causing style recalculation on many elements
+- JavaScript animations that force layout (reading `offsetWidth`, `getBoundingClientRect`)
+  then writing styles in a loop
+
+**Fix: minimize DOM size and avoid layout thrashing**
+
+```js
+// Layout thrashing (bad) — forces synchronous layout each iteration
+elements.forEach(el => {
+  const height = el.offsetHeight;  // forces layout
+  el.style.height = height * 2 + 'px';  // invalidates layout
+});
+
+// Batch reads then writes (good)
+const heights = elements.map(el => el.offsetHeight);  // one layout
+elements.forEach((el, i) => { el.style.height = heights[i] * 2 + 'px'; });
+```
+
+## Avoid unnecessary JavaScript
+
+- Code-split aggressively — defer JS not needed for initial interaction
+- Remove unused polyfills and libraries
+- Avoid loading third-party scripts that add long tasks during user sessions
+
+## Measure INP in JavaScript (raw API)
+
+```js
+new PerformanceObserver((list) => {
+  for (const entry of list.getEntries()) {
+    if (entry.interactionId) {
+      console.log('Interaction:', entry.name, entry.duration, 'ms');
+    }
+  }
+}).observe({ type: 'event', buffered: true, durationThreshold: 16 });
+```
+
+Prefer `onINP()` from the `web-vitals` library — it correctly aggregates all
+interactions, selects the worst, and handles attribution.
+
+## Key nuances
+
+- INP is the **worst interaction** observed (excluding statistical outliers at
+  very high page load counts to reduce noise from accidental interactions)
+- If a page has ≤ 50 interactions, INP = worst interaction
+- If a page has > 50 interactions, the 98th percentile interaction is used
+- Animations triggered by JS do not count as interactions
+- INP is not measurable in lab tools (Lighthouse uses TBT as a proxy)

package/skills/core-web-vitals/references/lcp.md

@@ -0,0 +1,89 @@
+# LCP — Largest Contentful Paint
+
+**Good:** ≤ 2.5 s | **Needs improvement:** 2.5–4.0 s | **Poor:** > 4.0 s
+(measured at the 75th percentile of field loads)
+
+## What qualifies as the LCP element?
+
+Only these element types are considered:
+- `<img>` elements (including `<image>` inside SVG)
+- `<video>` elements (poster image only)
+- Block-level elements with a CSS `background-image` loaded via `url()`
+- Block-level text elements (`<p>`, `<h1>`, etc.)
+
+Elements excluded from LCP consideration: full-viewport background images,
+`opacity: 0` elements, placeholder images, elements the browser heuristically
+considers non-contentful.
+
+LCP is the *last* candidate emitted before user interaction or page hide —
+the browser continuously updates the candidate as larger elements paint.
+
+## LCP timing breakdown
+
+LCP time = TTFB + resource load delay + resource load time + element render time
+
+1. **TTFB** — time until first byte of HTML arrives
+2. **Resource load delay** — time from TTFB until the LCP resource starts downloading
+3. **Resource load time** — how long the resource takes to download
+4. **Element render time** — time from download complete to paint on screen
+
+Diagnosing which phase dominates tells you what to fix.
+
+## Common causes and fixes
+
+### Slow TTFB (phase 1)
+- Use a CDN geographically close to users
+- Enable server-side caching, edge caching, or stale-while-revalidate
+- Reduce database query time / server processing time
+- Target: TTFB ≤ 800 ms
+
+### LCP image not discoverable (phase 2)
+- **Don't** hide the LCP image behind `data-src`, JS lazy-loading, or CSS
+  `background-image` in a stylesheet — the preload scanner can't find it
+- **Do** use `<img src="...">` or `<img srcset="...">` in the HTML source
+- **Do** use `<link rel="preload" as="image" href="...">` if the image must
+  come from CSS/JS
+- **Do** prefer SSR/SSG over CSR — CSR blocks image discovery behind JS execution
+- Remove `loading="lazy"` from the LCP image; lazy-loading delays it
+
+### LCP image deprioritized (phase 2)
+```html
+<!-- Add fetchpriority="high" to your LCP image -->
+<img src="/hero.jpg" fetchpriority="high" alt="..." width="1200" height="600">
+
+<!-- Or on the preload link -->
+<link rel="preload" as="image" href="/hero.jpg" fetchpriority="high">
+```
+
+### Slow resource download (phase 3)
+- Compress images (use WebP or AVIF; target < 200 KB for hero images)
+- Use `srcset` + `sizes` to serve appropriately sized images per viewport
+- Serve from a CDN with HTTP/2 or HTTP/3
+- Defer non-critical resources to reduce bandwidth contention
+
+### Render delay (phase 4)
+- Minimize render-blocking scripts and stylesheets in `<head>`
+- Avoid long tasks on the main thread that block painting
+- If using a web font for LCP text: `font-display: optional` or preload the font
+
+## JavaScript API (raw, without web-vitals library)
+
+```js
+new PerformanceObserver((list) => {
+  const entries = list.getEntries();
+  const last = entries[entries.length - 1];
+  console.log('LCP candidate:', last.startTime, last.element);
+}).observe({ type: 'largest-contentful-paint', buffered: true });
+```
+
+Prefer `onLCP()` from the `web-vitals` library — it handles bfcache restores,
+prerendered page activation, and iframe aggregation automatically.
+
+## Key nuances
+
+- LCP from bfcache restores counts as a new page visit — measure it
+- Images inside cross-origin iframes contribute to LCP but are not observable
+  from the parent frame via the raw API (web-vitals library handles this)
+- For prerendered pages, measure LCP from `activationStart`, not navigation start
+- The largest element is determined by rendered size in the viewport, not
+  intrinsic dimensions

package/skills/core-web-vitals/references/tools.md

@@ -0,0 +1,112 @@
+# CWV Tools & Top Optimization Checklist
+
+## Field tools (real user data)
+
+### Chrome User Experience Report (CrUX)
+- 28-day rolling window of anonymized Chrome user data
+- Aggregated by origin and URL-pattern (template level)
+- Requires sufficient traffic (threshold: ~100 qualifying visits/28 days)
+- Access via: BigQuery, PageSpeed Insights API, CrUX API, Search Console
+
+### PageSpeed Insights (PSI)
+- URL: https://pagespeed.web.dev/
+- Shows CrUX field data (if available) + Lighthouse lab audit in one view
+- API available for programmatic access:
+  ```
+  https://www.googleapis.com/pagespeedonline/v5/runPagespeed?url=<URL>&strategy=mobile
+  ```
+
+### Search Console — Core Web Vitals report
+- Groups pages by URL template (not individual URLs)
+- Shows "Good", "Needs improvement", "Poor" counts with 28-day CrUX data
+- Best for finding which page groups have systematic CWV issues
+
+## Lab tools (simulated/local)
+
+### Lighthouse (Chrome DevTools / CLI / CI)
+```bash
+npm install -g lighthouse
+lighthouse https://example.com --output html --output-path ./report.html
+```
+- Use `--throttling-method=simulate` for reproducible scores
+- INP not measured in Lighthouse — use TBT (Total Blocking Time) as proxy
+- Run in incognito to avoid extension interference
+
+### Chrome DevTools Performance panel
+- Record interactions to identify long tasks and INP attribution
+- Performance Insights panel: shows LCP, CLS, INP with timeline markers
+- Rendering panel → "Layout Shift Regions" highlights shifting elements in real time
+
+### web-vitals Chrome extension
+- Badge shows live LCP, INP, CLS values as you browse
+- Console logs detailed attribution data
+- Useful for quick spot-checks without instrumenting analytics
+
+## Top 9 optimizations (Chrome team recommendations)
+
+### INP
+1. **Yield often to break up long tasks** — Use `scheduler.yield()` or
+   `setTimeout(0)` to give the browser opportunities between work chunks.
+   Any JS task > 50 ms becomes a "long task" that blocks interaction handling.
+
+2. **Avoid unnecessary JavaScript** — Code-split, defer non-critical JS, remove
+   unused polyfills. Less JS = fewer long tasks = better INP.
+
+3. **Avoid large rendering updates** — Minimize DOM size, batch DOM writes,
+   use `requestAnimationFrame` for visual updates, avoid layout thrashing
+   (interleaved reads/writes of layout properties).
+
+### LCP
+4. **Make the LCP resource discoverable from HTML source and prioritized** —
+   Use `<img src>` or `<img srcset>` (not `data-src`). Add `fetchpriority="high"`
+   to the LCP image or its `<link rel="preload">`. Remove `loading="lazy"` from LCP.
+
+5. **Aim for instant navigations** — Implement the View Transitions API for
+   client-side navigations. Use speculation rules for prerendering next pages:
+   ```html
+   <script type="speculationrules">
+   { "prerender": [{ "where": { "href_matches": "/products/*" } }] }
+   </script>
+   ```
+   Use `rel="prefetch"` for likely next navigations.
+
+6. **Use a CDN to optimize TTFB** — Serve HTML from an edge CDN geographically
+   close to users. Edge compute (e.g., Cloudflare Workers, Vercel Edge) can
+   stream HTML early while fetching dynamic data in parallel.
+   Target TTFB ≤ 800 ms.
+
+### CLS
+7. **Set explicit sizes on content loaded from the page** — Add `width` and
+   `height` attributes to all `<img>` and `<video>` elements. Use CSS
+   `aspect-ratio` for responsive containers. Reserve space for ads and embeds
+   with `min-height`.
+
+8. **Ensure pages are eligible for bfcache** — Avoid `unload` listeners,
+   `Cache-Control: no-store`, and unclosed `IndexedDB` transactions.
+   bfcache restores eliminate load-time layout shifts entirely.
+
+9. **Avoid layout-inducing CSS animations/transitions** — Animate only
+   `transform` and `opacity`. These run on the compositor thread and do not
+   cause layout shifts. Never animate `top`, `left`, `margin`, `width`, etc.
+
+## Measuring in CI/CD
+
+```js
+// Example: assert LCP in Playwright test
+import { onLCP } from 'web-vitals';
+
+test('LCP is under 2.5s', async ({ page }) => {
+  await page.goto('/');
+  const lcp = await page.evaluate(() => new Promise(resolve => {
+    onLCP(metric => resolve(metric.value), { reportAllChanges: false });
+  }));
+  expect(lcp).toBeLessThan(2500);
+});
+```
+
+For automated CWV regression testing use Lighthouse CI:
+```bash
+npm install -g @lhci/cli
+lhci autorun --collect.url=https://staging.example.com \
+  --assert.assertions.largest-contentful-paint=["warn", {"maxNumericValue": 2500}]
+```