npm - @harness-engineering/cli - Versions diffs - 1.23.2 → 1.24.1 - Mend

@harness-engineering/cli 1.23.2 → 1.24.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (5716) hide show

package/dist/agents/skills/claude-code/perf-critical-rendering-path/SKILL.md ADDED Viewed

@@ -0,0 +1,167 @@
+# Critical Rendering Path
+> Understand and optimize the browser's 5-stage pixel pipeline — Parse HTML to DOM, Parse CSS to CSSOM, Render Tree construction, Layout, Paint and Composite — to minimize time-to-first-paint and eliminate render-blocking bottlenecks.
+## When to Use
+- A page shows a blank white screen for more than 1 second before any content appears
+- Lighthouse flags "Eliminate render-blocking resources" as a performance opportunity
+- Time to First Paint or First Contentful Paint exceeds 1.8 seconds on mobile
+- The DevTools Network waterfall shows CSS or JS files blocking the initial render
+- You need to decide between inlining critical CSS versus loading external stylesheets
+- A page loads many resources in the `<head>` and you need to determine which are render-blocking
+- Server response includes large HTML documents that could benefit from streaming/chunked delivery
+- You are implementing a performance budget and need to understand critical path length, bytes, and resource count
+- A Single Page Application shows delayed first paint due to JavaScript-dependent rendering
+- Core Web Vitals field data shows LCP regression correlated with render-blocking resource changes
+## Instructions
+1. **Map the critical rendering path.** Open Chrome DevTools Performance panel with CPU throttling set to 4x slowdown. Record a page load. Identify these 5 stages in the flame chart:
+   - **Parse HTML to DOM** — the HTML parser tokenizes and constructs the DOM tree incrementally
+   - **Parse CSS to CSSOM** — CSS is parsed into the CSS Object Model; this is render-blocking by default
+   - **Render Tree** — the browser combines DOM and CSSOM, excluding invisible nodes (`display: none`, `<head>`)
+   - **Layout** — the browser computes exact position and size of every visible element in pixels
+   - **Paint and Composite** — the browser fills pixels and composites layers to the screen
+2. **Identify render-blocking resources.** In DevTools Network panel, filter by "Render-blocking" or look for CSS `<link>` tags and synchronous `<script>` tags in the `<head>`. Every render-blocking resource adds its download and parse time to time-to-first-paint.
+3. **Measure the three critical path metrics:**
+   - **Critical path length** — the number of roundtrips required to fetch all critical resources (minimum is 1 for the HTML document itself)
+   - **Critical bytes** — total bytes of all render-blocking resources
+   - **Critical resources** — count of resources that block first render
+4. **Inline critical CSS.** Extract the CSS required for above-the-fold content (tools: Critical, Critters, PurgeCSS) and inline it in a `<style>` tag in `<head>`. Keep inlined CSS under 14KB — this matches TCP's initial congestion window (10 segments x ~1,460 bytes), meaning it arrives in the first network roundtrip.
+   ```html
+   <head>
+     <style>
+       /* Critical CSS — only above-the-fold styles, under 14KB */
+       .hero {
+         display: flex;
+         min-height: 60vh;
+       }
+       .nav {
+         position: sticky;
+         top: 0;
+         background: #fff;
+       }
+     </style>
+     <link
+       rel="preload"
+       href="/styles/main.css"
+       as="style"
+       onload="this.onload=null;this.rel='stylesheet'"
+     />
+     <noscript><link rel="stylesheet" href="/styles/main.css" /></noscript>
+   </head>
+   ```
+5. **Eliminate parser-blocking scripts.** Add `defer` or `async` to every `<script>` tag that does not need to run before first paint. Use `defer` for scripts that depend on DOM order; use `async` for independent scripts like analytics.
+   ```html
+   <!-- Parser-blocking (bad) — blocks HTML parsing until downloaded and executed -->
+   <script src="/app.js"></script>
+   <!-- Deferred (good) — downloads in parallel, executes after HTML parsing completes -->
+   <script src="/app.js" defer></script>
+   <!-- Async (good for independent scripts) — downloads in parallel, executes when ready -->
+   <script src="/analytics.js" async></script>
+   ```
+6. **Use media queries on non-critical CSS.** A print stylesheet should not block rendering on screen:
+   ```html
+   <!-- Render-blocking for all media (bad) -->
+   <link rel="stylesheet" href="/print.css" />
+   <!-- Only blocks rendering when printing (good) -->
+   <link rel="stylesheet" href="/print.css" media="print" />
+   ```
+7. **Enable streaming HTML.** Configure the server to flush the `<head>` section immediately (including critical CSS and preload hints) before the backend finishes generating the `<body>`. This allows the browser to start fetching critical resources while the server is still processing.
+## Details
+### The Pixel Pipeline in Depth
+The browser processes each frame through five stages, and each stage depends on the output of the previous one:
+1. **DOM Construction** — The HTML parser reads bytes, decodes characters, tokenizes tags, and builds nodes into the Document Object Model. This is incremental — the browser can start constructing the DOM before the entire HTML document arrives.
+2. **CSSOM Construction** — CSS is not incremental. The browser must fully parse all CSS before it can compute styles, because later rules can override earlier ones (the cascade). This is why CSS is render-blocking: the browser will not paint until the CSSOM is complete.
+3. **Render Tree** — Combines DOM and CSSOM. Walks the DOM, finds matching CSSOM rules for each visible node, and produces a tree of visible elements with computed styles. Elements with `display: none` are excluded entirely. Elements with `visibility: hidden` are included (they occupy space).
+4. **Layout (Reflow)** — Converts the render tree's relative units (%, em, vh) into absolute pixel positions. Computes exact box geometry for every element. This is computationally expensive for deep DOM trees.
+5. **Paint and Composite** — Rasterizes each layer into pixels, then composites layers together respecting z-order, transforms, and opacity. GPU-accelerated compositing handles `transform` and `opacity` changes without repaint.
+### Worked Example: Google.com First Paint Optimization
+Google.com achieves first paint in under 1 second on 3G networks. The technique: the entire critical CSS (~4KB) is inlined in the `<head>`, and the HTML payload for the search page is under 14KB total. This means the complete above-the-fold content arrives in the first TCP roundtrip (initial congestion window = 10 TCP segments = ~14KB). No additional network roundtrips are needed before the browser can construct DOM, CSSOM, render tree, and paint. External CSS and JavaScript are loaded with `defer` or dynamically injected after first paint.
+### Worked Example: Shopify Storefront CRP Optimization
+Shopify reduced their critical rendering path from 8 critical resources to 3 by auditing their storefront themes. The original CRP included 4 external CSS files and 4 synchronous JS files in `<head>`. They inlined critical CSS (6KB), deferred all JavaScript, and combined remaining CSS into one file loaded with `media="print"` and swapped to `media="all"` on load. The result: Start Render improved by 50% (from 3.2s to 1.6s on 3G) because the critical path length dropped from 4 roundtrips to 1.
+### Anti-Patterns
+**Render-blocking CSS without media queries.** Loading `print.css` without `media="print"` forces the browser to download and parse it before rendering anything on screen. Every CSS `<link>` in `<head>` without a specific media query blocks rendering for all media types.
+**Synchronous scripts in `<head>` without `defer` or `async`.** A `<script src="...">` tag without attributes blocks HTML parsing entirely — the parser stops, downloads the script, executes it, then resumes parsing. This can add seconds to first paint if the script is large or on a slow connection.
+**Over-inlining CSS.** Inlining the entire CSS framework (200KB+ of Tailwind or Bootstrap) defeats the purpose. Inlined CSS cannot be cached separately, so users re-download it on every page navigation. Inline only the critical above-the-fold CSS; load the rest asynchronously.
+**Invisible text during font loading.** Using `font-display: block` (the default for many font services) makes text invisible until the web font downloads. On slow connections, users see a blank content area for 1-3 seconds. Use `font-display: swap` or `font-display: optional` to show fallback text immediately.
+### Resource Priority and Discovery
+The browser assigns fetch priority to resources based on their type and position:
+- CSS `<link>` in `<head>` — Highest priority, render-blocking
+- Synchronous `<script>` in `<head>` — High priority, parser-blocking
+- `<script defer>` — Low priority during parse, executes in order after DOMContentLoaded
+- `<script async>` — High priority download, executes immediately when ready (out of order)
+- `<img>` above the fold — High priority (browsers use heuristics to detect viewport position)
+- `<img>` below the fold — Low priority
+- `<link rel="preload">` — High priority early fetch without blocking render
+Use `fetchpriority="high"` to boost critical images (hero images, LCP candidates) and `fetchpriority="low"` to deprioritize below-the-fold resources that the browser might otherwise fetch eagerly.
+### Measuring CRP Metrics in Code
+```javascript
+// Measure critical path timing with Navigation Timing API
+const timing = performance.getEntriesByType('navigation')[0];
+const ttfb = timing.responseStart - timing.requestStart;
+const domParsing = timing.domInteractive - timing.responseStart;
+const cssBlocking = timing.domContentLoadedEventStart - timing.domInteractive;
+console.log(`TTFB: ${ttfb}ms, DOM parsing: ${domParsing}ms, CSS blocking: ${cssBlocking}ms`);
+```
+## Source
+- Google Web Fundamentals: Critical Rendering Path — https://web.dev/articles/critical-rendering-path
+- Ilya Grigorik, "High Performance Browser Networking" (O'Reilly)
+- W3C Navigation Timing Level 2 — https://www.w3.org/TR/navigation-timing-2/
+- HTTP Archive Web Almanac, Performance chapter
+## Process
+1. Read the instructions and examples in this document.
+2. Apply the patterns to your implementation, adapting to your specific context.
+3. Verify your implementation against the details and edge cases listed above.
+## Harness Integration
+- **Type:** knowledge — this skill is a reference document, not a procedural workflow.
+- **No tools or state** — consumed as context by other skills and agents.
+## Success Criteria
+- The patterns described in this document are applied correctly in the implementation.
+- Edge cases and anti-patterns listed in this document are avoided.
+- Critical rendering path is measured before and after optimization with specific metrics.
+- Render-blocking resources are identified and addressed with appropriate strategies.

package/dist/agents/skills/claude-code/perf-critical-rendering-path/skill.yaml ADDED Viewed

@@ -0,0 +1,39 @@
+name: perf-critical-rendering-path
+version: '1.0.0'
+description: Browser rendering pipeline — Parse, Style, Layout, Paint, Composite stages and optimization strategies
+stability: static
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths: []
+related_skills:
+  - perf-dom-parsing
+  - perf-style-calculation
+  - perf-layout-reflow
+  - perf-paint-compositing
+  - perf-largest-contentful-paint
+  - css-performance-patterns
+stack_signals: []
+keywords:
+  - critical rendering path
+  - rendering pipeline
+  - render blocking
+  - CSSOM
+  - DOM construction
+  - first paint
+  - pixel pipeline
+  - browser rendering
+metadata:
+  author: community
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/claude-code/perf-cumulative-layout-shift/SKILL.md ADDED Viewed

@@ -0,0 +1,180 @@
+# Cumulative Layout Shift (CLS)
+> Measure and prevent unexpected layout shifts — elements visually moving after being rendered — by reserving space for dynamic content, handling font loading, setting explicit dimensions, and understanding the CLS scoring formula.
+## When to Use
+- CrUX or Lighthouse reports CLS exceeding 0.1 at the 75th percentile
+- Users report "the page jumped" or complain about accidentally clicking the wrong element
+- Images, ads, or embeds load and push surrounding content down
+- Web fonts load and cause text to reflow (FOUT — Flash of Unstyled Text)
+- Dynamically injected content (banners, notifications, cookie consent) pushes existing content
+- You need to understand the CLS scoring formula (impact fraction \* distance fraction)
+- A/B testing scripts inject content above the fold after initial render
+- `content-visibility: auto` needs `contain-intrinsic-size` to avoid shifts
+- Late-loading CSS changes element sizes after initial render
+- Infinite scroll or lazy-loaded content sections cause shifts on insertion
+## Instructions
+1. **Understand what CLS measures.** CLS quantifies how much visible content shifts unexpectedly during the page lifespan. It uses a session window approach: shifts are grouped into sessions (max 5 seconds, with 1-second gaps between shifts), and the largest session's total score is the CLS value.
+2. **Understand the scoring formula.** Each layout shift gets a score: `impact fraction * distance fraction`.
+   - **Impact fraction** — the percentage of the viewport area affected by the shift. If an element occupies 25% of the viewport and shifts, pushing another 25% of content, the impact fraction is 0.5 (50% of viewport was affected).
+   - **Distance fraction** — the greatest distance any element moved, as a fraction of the viewport dimension. If an element moved 100px in a 900px viewport, distance fraction is 0.11.
+   - Example: impact 0.5 \* distance 0.11 = shift score 0.055.
+3. **Always set explicit dimensions on images and videos:**
+   ```html
+   <!-- BAD — no dimensions, browser cannot reserve space -->
+   <img src="/photo.jpg" alt="Photo" />
+   <!-- GOOD — browser reserves exact space before image loads -->
+   <img src="/photo.jpg" alt="Photo" width="800" height="600" />
+   <!-- GOOD — CSS aspect-ratio for responsive images -->
+   <img src="/photo.jpg" alt="Photo" style="width: 100%; aspect-ratio: 4/3;" />
+   ```
+4. **Reserve space for ad slots and embeds:**
+   ```css
+   .ad-container {
+     min-height: 250px; /* IAB standard medium rectangle height */
+     aspect-ratio: 300/250; /* Or use fixed dimensions if known */
+     background: #f0f0f0; /* Visual placeholder while loading */
+   }
+   ```
+5. **Handle web font loading to prevent text reflow:**
+   ```css
+   /* Option 1: font-display: optional — no swap, no shift */
+   @font-face {
+     font-family: 'CustomFont';
+     src: url('/font.woff2') format('woff2');
+     font-display: optional; /* Uses fallback permanently if font loads too slowly */
+   }
+   /* Option 2: Match fallback metrics to web font metrics */
+   @font-face {
+     font-family: 'CustomFont Fallback';
+     src: local('Arial');
+     ascent-override: 90%;
+     descent-override: 22%;
+     line-gap-override: 0%;
+     size-adjust: 105%;
+   }
+   ```
+6. **Use `contain-intrinsic-size` with `content-visibility: auto`:**
+   ```css
+   .section {
+     content-visibility: auto;
+     contain-intrinsic-size: 0 500px; /* Estimated height when hidden */
+   }
+   ```
+7. **Inject dynamic content below the fold or in reserved space.** Never insert banners, notifications, or consent dialogs above existing visible content:
+   ```javascript
+   // BAD — inserts banner at top, pushes everything down
+   document.body.prepend(bannerElement);
+   // GOOD — uses a pre-reserved slot
+   document.querySelector('.banner-slot').appendChild(bannerElement);
+   // Where .banner-slot has min-height: 60px pre-set in CSS
+   ```
+8. **Measure CLS with the Performance API:**
+   ```javascript
+   let clsValue = 0;
+   let sessionValue = 0;
+   let sessionEntries = [];
+   const observer = new PerformanceObserver((list) => {
+     for (const entry of list.getEntries()) {
+       if (!entry.hadRecentInput) {
+         // Ignore user-initiated shifts
+         sessionEntries.push(entry);
+         sessionValue += entry.value;
+         clsValue = Math.max(clsValue, sessionValue);
+       }
+     }
+   });
+   observer.observe({ type: 'layout-shift', buffered: true });
+   ```
+## Details
+### CLS Thresholds
+| Rating            | CLS (p75) | User experience              |
+| ----------------- | --------- | ---------------------------- |
+| Good              | <= 0.1    | Content is stable            |
+| Needs improvement | <= 0.25   | Occasional noticeable shifts |
+| Poor              | > 0.25    | Frequent, disruptive shifts  |
+### What Counts as "Expected"
+A layout shift is excluded from CLS if it occurs within 500ms of a discrete user input (click, tap, keypress). Scroll is not a discrete input — shifts during scroll still count. Hover is not a discrete input. This means:
+- Clicking a button that reveals a dropdown: expected (not counted)
+- An image loading during scroll that pushes text: unexpected (counted)
+- A font swap causing text reflow during page load: unexpected (counted)
+### Worked Example: Yahoo! Japan News CLS Elimination
+Yahoo! Japan News reduced CLS from 0.3 to 0.02. The primary source was ad containers with no reserved height. When ads loaded (100-500ms after page render), the 250px-tall ad pushed the article content 200px down the viewport. With the article visible in ~50% of the viewport and shifting 200px in a 900px viewport:
+- Impact fraction: 0.75 (ad area + shifted article area)
+- Distance fraction: 0.22 (200px / 900px)
+- Shift score: 0.165 per ad load
+Fix: Added `min-height: 250px` and `aspect-ratio: 300/250` to all ad containers. Combined with `aspect-ratio` on all editorial images (`width` and `height` attributes), CLS dropped to 0.02.
+### Worked Example: Smashing Magazine Font CLS
+Smashing Magazine eliminated font-swap CLS by using `font-display: optional` combined with font metric overrides. Their web font had significantly different metrics than the system fallback (Arial): the web font was 8% wider with different ascent and descent values. On swap, every line of text reflowed, shifting content throughout the page.
+Fix: Used CSS `@font-face` metric overrides (`ascent-override: 92%`, `descent-override: 24%`, `line-gap-override: 0%`, `size-adjust: 107%`) to match the fallback font metrics to within 2% of the web font. Text reflow on font swap became imperceptible, and CLS from font loading dropped from 0.08 to 0.001.
+### Anti-Patterns
+**Images and videos without `width`/`height` attributes.** Without explicit dimensions, the browser reserves 0px height for the image. When the image loads, it pushes all content below it. Modern browsers use `width`/`height` to calculate `aspect-ratio` automatically.
+**Injecting banners or notifications above existing content.** Cookie consent banners, promotional banners, or error notifications inserted at the top of the page push the entire viewport down. Use overlay/modal patterns, or reserve space in advance.
+**Web fonts with `font-display: swap` and large metric differences.** `font-display: swap` shows fallback text immediately, then swaps to the web font. If the web font has different metrics (width, height, spacing), text reflows on swap. Use `font-display: optional` (no swap if font loads slowly) or metric overrides to minimize the difference.
+**Dynamically loading content that changes height of above-the-fold sections.** A/B testing scripts that modify above-the-fold content after initial render cause shifts. Load A/B test decisions server-side or inline the decision in the HTML to avoid post-render modifications.
+**CSS that loads late and changes element sizes.** Non-critical CSS loaded asynchronously may contain rules that change element dimensions from their default values. This causes shifts when the stylesheet arrives and styles are recalculated. Ensure all above-the-fold element dimensions are defined in critical CSS.
+## Source
+- web.dev CLS documentation — https://web.dev/articles/cls
+- Layout Instability API specification — https://wicg.github.io/layout-instability/
+- Chrome CrUX methodology — https://developers.google.com/web/tools/chrome-user-experience-report
+- "Optimize Cumulative Layout Shift" — https://web.dev/articles/optimize-cls
+## Process
+1. Read the instructions and examples in this document.
+2. Apply the patterns to your implementation, adapting to your specific context.
+3. Verify your implementation against the details and edge cases listed above.
+## Harness Integration
+- **Type:** knowledge — this skill is a reference document, not a procedural workflow.
+- **No tools or state** — consumed as context by other skills and agents.
+## Success Criteria
+- The patterns described in this document are applied correctly in the implementation.
+- Edge cases and anti-patterns listed in this document are avoided.
+- CLS is measured using the Layout Instability API and stays below 0.1 at p75.
+- All images, videos, and dynamic content containers have explicit dimensions or reserved space.

package/dist/agents/skills/claude-code/perf-cumulative-layout-shift/skill.yaml ADDED Viewed

@@ -0,0 +1,40 @@
+name: perf-cumulative-layout-shift
+version: '1.0.0'
+description: CLS measurement — layout shift sources, impact/distance fractions, prevention strategies
+stability: static
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths: []
+related_skills:
+  - perf-layout-reflow
+  - perf-paint-compositing
+  - perf-largest-contentful-paint
+  - perf-interaction-to-next-paint
+  - perf-performance-api
+  - css-performance-patterns
+stack_signals: []
+keywords:
+  - CLS
+  - cumulative layout shift
+  - Core Web Vitals
+  - layout shift
+  - aspect ratio
+  - content-visibility
+  - font loading
+  - image dimensions
+  - dynamic content
+metadata:
+  author: community
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/claude-code/perf-dom-parsing/SKILL.md ADDED Viewed

@@ -0,0 +1,153 @@
+# DOM Parsing
+> Understand the HTML5 parsing algorithm — tokenization, tree construction, speculative parsing, and the preload scanner — to minimize parser-blocking delays and accelerate DOM construction.
+## When to Use
+- DOMContentLoaded fires significantly later than expected relative to HTML size
+- DevTools shows long "Parse HTML" blocks in the Performance timeline
+- The page uses `document.write()` to inject scripts or content dynamically
+- Scripts in the `<head>` are blocking the parser and delaying resource discovery
+- You are deciding between `defer`, `async`, or module scripts for loading strategy
+- The page has a DOM tree exceeding 1,500 nodes and you need to understand the performance implications
+- Server-side rendering flushes large HTML payloads and you want to optimize chunked delivery
+- You see "A Parser-blocking, cross site script" warnings in Chrome DevTools
+- The preload scanner is failing to discover critical resources before the parser reaches them
+- `DOMContentLoaded` and `load` event timings differ significantly and you need to understand why
+## Instructions
+1. **Understand the HTML5 parsing pipeline.** The parser operates in four stages: byte stream decoding (charset detection), tokenization (converting characters into tokens: start tags, end tags, character data, comments), tree construction (building the DOM tree from tokens following the HTML5 algorithm's insertion modes), and script execution (when a `<script>` tag is encountered without `defer`/`async`).
+2. **Identify parser-blocking resources.** A classic `<script src="...">` tag without `defer` or `async` halts the HTML parser completely. The parser must wait for the script to download and execute before it can continue building the DOM. This is because scripts can call `document.write()` which modifies the token stream.
+   ```html
+   <!-- Parser-blocking: parser stops, downloads, executes, then resumes -->
+   <script src="/heavy-library.js"></script>
+   <!-- Non-parser-blocking: parser continues, script executes after parsing -->
+   <script src="/heavy-library.js" defer></script>
+   <!-- Module scripts are deferred by default -->
+   <script type="module" src="/app.js"></script>
+   ```
+3. **Leverage the preload scanner.** When the main parser is blocked on a script, browsers run a secondary "preload scanner" (also called speculative parser) that scans ahead in the raw HTML to discover resources like images, stylesheets, and other scripts. It then initiates fetches for those resources in parallel. The preload scanner typically improves page load times by 20% or more (per Chrome team measurements).
+4. **Avoid defeating the preload scanner.** The preload scanner can only find resources visible in the raw HTML. Resources loaded via JavaScript, CSS `background-image`, or `document.write()` are invisible to it.
+   ```javascript
+   // BAD: invisible to preload scanner — discovered only when JS executes
+   const img = new Image();
+   img.src = '/hero.jpg';
+   // GOOD: visible to preload scanner in raw HTML
+   // <link rel="preload" href="/hero.jpg" as="image">
+   ```
+5. **Use streaming HTML delivery.** Flush the `<head>` and initial content as soon as possible:
+   ```javascript
+   // Express.js streaming example
+   app.get('/', (req, res) => {
+     res.setHeader('Content-Type', 'text/html');
+     res.write(`<!DOCTYPE html><html><head>
+       <link rel="stylesheet" href="/critical.css">
+       <link rel="preload" href="/hero.jpg" as="image">
+     </head><body><div id="root">`);
+     // Continue processing while browser fetches resources
+     const data = await fetchData();
+     res.write(renderContent(data));
+     res.end('</div></body></html>');
+   });
+   ```
+6. **Measure DOM parsing performance.** Use the Navigation Timing API to isolate parsing time:
+   ```javascript
+   const nav = performance.getEntriesByType('navigation')[0];
+   const parsingTime = nav.domInteractive - nav.responseEnd;
+   const domContentLoaded = nav.domContentLoadedEventEnd - nav.domContentLoadedEventStart;
+   console.log(`DOM parsing: ${parsingTime}ms, DOMContentLoaded handler: ${domContentLoaded}ms`);
+   ```
+## Details
+### Tokenizer and Tree Construction
+The HTML5 tokenizer is a state machine with 80+ states. It processes the character stream and emits tokens: DOCTYPE, start tag, end tag, comment, character, and end-of-file. The tree construction stage consumes these tokens and builds the DOM tree according to the HTML5 specification's precise rules for handling malformed markup (foster parenting, adoption agency algorithm, implicit tag closing).
+Key performance insight: the tokenizer is fast (linear in input size), but tree construction can be expensive when the DOM tree is deep. Each node insertion requires walking up the tree to find the correct insertion point. Browsers optimize this with stack-based insertion mode tracking, but pathologically deep nesting (>1,500 levels) degrades performance.
+### Speculative Parsing Architecture
+When the main parser blocks on a synchronous script, the speculative parser takes over. It does not build a DOM tree. Instead, it scans the raw byte stream for URLs in known attributes (`href`, `src`, `poster`, `srcset`) and queues them for download. This happens on a separate thread in most modern browsers.
+The speculative parser has limitations: it cannot parse JavaScript, evaluate CSS `url()` values, or follow redirects in meta refresh tags. It also cannot discover resources that depend on the execution of earlier scripts.
+### Worked Example: Chrome Preload Scanner Impact
+The Chrome team measured the impact of the preload scanner across 10,000 popular sites. On average, disabling the preload scanner increased page load time by 20%. On sites with many synchronous scripts in the `<head>`, the impact was even larger — up to 50% slower. The scanner discovers an average of 7 resources per page before the main parser reaches them, saving one or more network roundtrips.
+### Worked Example: eBay Streaming HTML Architecture
+eBay implemented streaming HTML where the server flushes the `<head>` section (containing critical CSS links and preload hints) within 100ms, before backend data fetching completes. The body content streams as data becomes available. This architecture reduced time-to-first-byte for visual content from 800ms to 100ms. The browser begins fetching CSS and fonts while the server is still querying databases and assembling page content.
+### Anti-Patterns
+**`document.write()` for script injection.** `document.write()` inserts content directly into the parser's token stream, which forces the parser to restart tokenization. On 2G connections, Chrome intervenes and blocks `document.write()`-injected cross-origin scripts entirely because the delay is too severe. Use `document.createElement('script')` and `appendChild` instead.
+**Excessive DOM depth.** DOM trees deeper than 1,500 nodes cause quadratic increases in style recalculation cost. Each CSS selector match requires walking up the ancestor chain. Trees with more than 32 levels of nesting also trigger browser-specific performance cliffs in layout computation.
+**Parser-blocking scripts in `<head>` without `defer`/`async`.** Every synchronous script in `<head>` adds download time plus execution time to the critical path before the browser can start rendering. A chain of 5 synchronous scripts, each taking 200ms to download, adds 1 second of sequential blocking even if the preload scanner discovers them early.
+**Injecting large HTML via `innerHTML`.** Setting `innerHTML` bypasses incremental parsing. The browser must parse the entire HTML string at once, construct the subtree, and insert it. For large fragments (>10KB of HTML), this creates a noticeable jank spike. Use `insertAdjacentHTML` for incremental insertions or `DocumentFragment` for batch DOM construction.
+### DOMContentLoaded vs load Event
+`DOMContentLoaded` fires when the HTML document is fully parsed and all deferred scripts have executed, but external resources like images, stylesheets loaded asynchronously, and subframes may still be loading. The `load` event fires only when all dependent resources are fully loaded.
+Key timing relationships:
+- `responseEnd` — HTML bytes fully received
+- `domInteractive` — HTML parsing complete, DOM tree built
+- `domContentLoadedEventStart` — deferred scripts executed, ready for DOM manipulation
+- `loadEventStart` — all resources loaded (images, stylesheets, subframes)
+The gap between `domInteractive` and `domContentLoadedEventStart` represents deferred script execution time. A large gap indicates heavy deferred JavaScript that should be code-split or lazy-loaded.
+### DOM Size Budget
+For optimal performance, target these DOM complexity budgets:
+- Total DOM elements: fewer than 1,500 (Google Lighthouse warns at 800, flags at 1,400)
+- Maximum DOM depth: fewer than 32 levels
+- Maximum child elements per parent: fewer than 60
+Each additional DOM node increases memory usage by approximately 0.5-1KB and adds incremental cost to style recalculation, layout, and garbage collection.
+## Source
+- HTML Living Standard, Section 13: Parsing — https://html.spec.whatwg.org/multipage/parsing.html
+- Chrome Preload Scanner documentation — https://web.dev/articles/preload-scanner
+- WebKit Blog: Speculative Parsing — https://webkit.org/blog/
+- "High Performance Browser Networking" by Ilya Grigorik (O'Reilly)
+## Process
+1. Read the instructions and examples in this document.
+2. Apply the patterns to your implementation, adapting to your specific context.
+3. Verify your implementation against the details and edge cases listed above.
+## Harness Integration
+- **Type:** knowledge — this skill is a reference document, not a procedural workflow.
+- **No tools or state** — consumed as context by other skills and agents.
+## Success Criteria
+- The patterns described in this document are applied correctly in the implementation.
+- Edge cases and anti-patterns listed in this document are avoided.
+- DOM parsing time is measured before and after optimization using Navigation Timing API.
+- Parser-blocking resources are eliminated or appropriately deferred.

package/dist/agents/skills/claude-code/perf-dom-parsing/skill.yaml ADDED Viewed

@@ -0,0 +1,36 @@
+name: perf-dom-parsing
+version: '1.0.0'
+description: HTML parsing — tokenization, tree construction, speculative parsing, parser-blocking scripts
+stability: static
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths: []
+related_skills:
+  - perf-critical-rendering-path
+  - perf-style-calculation
+  - perf-largest-contentful-paint
+stack_signals: []
+keywords:
+  - HTML parser
+  - tokenization
+  - tree construction
+  - speculative parsing
+  - preload scanner
+  - parser blocking
+  - document.write
+  - DOMContentLoaded
+metadata:
+  author: community
+state:
+  persistent: false
+  files: []
+depends_on: []