npm - @harness-engineering/cli - Versions diffs - 1.24.0 → 1.24.3 - Mend

@harness-engineering/cli 1.24.0 → 1.24.3

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 (3869) hide show

package/dist/agents/skills/cursor/perf-font-loading/SKILL.md ADDED Viewed

@@ -0,0 +1,222 @@
+# Font Loading
+> Master web font loading optimization — font-display strategies for FOIT/FOUT control, Unicode range subsetting, variable fonts for multi-weight reduction, WOFF2 compression, preloading critical fonts, self-hosting versus CDN delivery, and the Font Loading API for programmatic control.
+## When to Use
+- Text is invisible for 1-3 seconds while web fonts download (Flash of Invisible Text)
+- Text shifts or reflows when web fonts replace system fonts (Flash of Unstyled Text)
+- Lighthouse flags "Ensure text remains visible during webfont load"
+- Multiple font weights/styles are loaded but only 2-3 are used on most pages
+- Google Fonts or other third-party font CDNs add extra DNS lookups and connections
+- Font files are large (>50KB per weight) because they include unused character ranges
+- CLS is caused by font swap changing text dimensions after initial render
+- A design system uses 6+ font weights that could be consolidated with a variable font
+- Font loading blocks LCP because the LCP element contains custom-font text
+- Users on slow connections see significant delay before text renders
+## Instructions
+1. **Set font-display for every @font-face rule.** This controls browser behavior while the font downloads:
+   ```css
+   @font-face {
+     font-family: 'Inter';
+     src: url('/fonts/inter-var.woff2') format('woff2');
+     font-weight: 100 900;
+     font-display: swap; /* show fallback immediately, swap when loaded */
+   }
+   ```
+   ```
+   font-display value | Behavior
+   -------------------|--------------------------------------------------
+   swap               | Show fallback immediately, swap to web font when ready
+   optional           | Show fallback; use web font only if it loads very quickly (~100ms)
+   fallback           | Brief invisible period (~100ms), then fallback, then swap
+   block              | Invisible text for up to 3s, then fallback (DEFAULT — avoid this)
+   auto               | Browser decides (usually same as block)
+   ```
+   Use `swap` for body text where readability matters most. Use `optional` for non-critical decorative fonts where layout stability matters more than exact typography.
+2. **Preload critical fonts.** The browser does not discover font files until it parses CSS. Preloading eliminates this delay:
+   ```html
+   <head>
+     <!-- Preload the primary font used for body text -->
+     <link rel="preload" href="/fonts/inter-var.woff2" as="font" type="font/woff2" crossorigin />
+     <!-- crossorigin is REQUIRED even for same-origin fonts -->
+   </head>
+   ```
+   Only preload 1-2 fonts that are used above the fold. Preloading too many fonts competes with other critical resources.
+3. **Subset fonts to reduce file size.** Remove unused character ranges to dramatically reduce font size:
+   ```bash
+   # Using pyftsubset (from fonttools)
+   pip install fonttools brotli
+   # Latin subset only (covers English and most Western European languages)
+   pyftsubset Inter-Regular.ttf \
+     --output-file=inter-latin.woff2 \
+     --flavor=woff2 \
+     --layout-features='kern,liga,calt' \
+     --unicodes='U+0000-00FF,U+0131,U+0152-0153,U+02BB-02BC,U+02C6,U+02DA,U+02DC,U+0300-0301,U+0304,U+0308,U+0329,U+2000-206F,U+2074,U+20AC,U+2122,U+2191,U+2193,U+2212,U+2215,U+FEFF,U+FFFD'
+   ```
+   ```css
+   /* Declare Unicode ranges for subset loading */
+   @font-face {
+     font-family: 'Inter';
+     src: url('/fonts/inter-latin.woff2') format('woff2');
+     unicode-range:
+       U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA, U+02DC, U+2000-206F, U+20AC;
+     font-display: swap;
+   }
+   @font-face {
+     font-family: 'Inter';
+     src: url('/fonts/inter-cyrillic.woff2') format('woff2');
+     unicode-range: U+0400-045F, U+0490-0491, U+04B0-04B1, U+2116;
+     font-display: swap;
+   }
+   /* Browser only downloads the subset(s) needed for the page content */
+   ```
+4. **Use variable fonts to eliminate multiple files.** A single variable font file replaces 6-12 static weight files:
+   ```css
+   /* One file covers all weights from 100 to 900 */
+   @font-face {
+     font-family: 'Inter';
+     src: url('/fonts/Inter-Variable.woff2') format('woff2-variations');
+     font-weight: 100 900;
+     font-style: normal;
+     font-display: swap;
+   }
+   /* Use any weight without additional file downloads */
+   h1 {
+     font-weight: 750;
+   } /* not limited to 700 or 800 */
+   body {
+     font-weight: 400;
+   }
+   .bold {
+     font-weight: 650;
+   }
+   ```
+   ```
+   Comparison for Inter with 4 weights (400, 500, 600, 700):
+   Static files: 4 x ~25KB = ~100KB
+   Variable font: 1 x ~50KB = ~50KB (50% smaller)
+   ```
+5. **Minimize layout shift from font swap.** Match the fallback font metrics to the web font:
+   ```css
+   /* Size-adjusted fallback to match Inter metrics */
+   @font-face {
+     font-family: 'Inter Fallback';
+     src: local('Arial');
+     size-adjust: 107.64%;
+     ascent-override: 90.49%;
+     descent-override: 22.56%;
+     line-gap-override: 0%;
+   }
+   body {
+     font-family: 'Inter', 'Inter Fallback', system-ui, sans-serif;
+   }
+   ```
+   ```bash
+   # Generate metric overrides automatically
+   npx @capsizecss/metrics Inter
+   # Or use: https://screenspan.net/fallback
+   ```
+6. **Self-host fonts instead of using Google Fonts CDN.** Self-hosting eliminates third-party DNS lookups and connection overhead, enables HTTP cache partition benefits, and gives full control over caching:
+   ```bash
+   # Download Google Fonts for self-hosting
+   npx google-fonts-helper download -f Inter -s latin -w 400,500,600,700
+   # Or use: https://gwfh.mranftl.com/fonts (google-webfonts-helper)
+   ```
+7. **Use the Font Loading API for fine-grained control.** Programmatically manage font loading when CSS alone is insufficient:
+   ```javascript
+   // Load fonts programmatically with timeout
+   async function loadFonts() {
+     const font = new FontFace('Inter', 'url(/fonts/inter-var.woff2)', {
+       weight: '100 900',
+       display: 'swap',
+     });
+     try {
+       const loaded = await Promise.race([
+         font.load(),
+         new Promise((_, reject) => setTimeout(() => reject(new Error('Font timeout')), 3000)),
+       ]);
+       document.fonts.add(loaded);
+       document.documentElement.classList.add('fonts-loaded');
+     } catch {
+       document.documentElement.classList.add('fonts-failed');
+     }
+   }
+   ```
+## Details
+### WOFF2 Compression
+WOFF2 uses Brotli compression and achieves 30-50% smaller files than WOFF. All modern browsers support WOFF2. There is no reason to serve WOFF, TTF, or EOT to modern browsers. A typical font file: TTF ~150KB, WOFF ~90KB, WOFF2 ~50KB. Always convert to WOFF2 and provide only WOFF2 in @font-face src unless supporting IE11 (which requires WOFF).
+### Worked Example: GitHub Font Optimization
+GitHub uses a single variable weight Inter font file (WOFF2, ~50KB) self-hosted on their CDN. They preload it with `<link rel="preload" as="font" type="font/woff2" crossorigin>` and use `font-display: swap` with a size-adjusted system font fallback. The fallback uses `size-adjust` and `ascent-override` to match Inter's metrics within 1%, virtually eliminating visible reflow on font swap. Combined with Latin subsetting, their font loading adds zero render-blocking time and <5 CLS points from the swap.
+### Worked Example: Stripe Documentation
+Stripe's documentation site uses a two-stage font loading strategy. Stage 1 loads the regular weight (used for body text) with preload and `font-display: swap`. Stage 2 loads bold and italic variants on `requestIdleCallback` after the page is interactive. The CSS classes `fonts-stage-1` and `fonts-stage-2` are added to the document element, allowing the design system to progressively enhance typography. This ensures body text renders within 100ms while non-critical weights load in the background without competing for bandwidth.
+### Anti-Patterns
+**Preloading too many fonts.** Preloading 4+ font files competes with critical CSS, JavaScript, and LCP images for bandwidth. Preload only the 1-2 fonts used in above-the-fold body text.
+**Using font-display: block on body text.** This causes up to 3 seconds of invisible text (FOIT) on slow connections. Use `swap` for body text so content is immediately readable. Reserve `block` only for icon fonts where showing the wrong character would be confusing.
+**Loading all weights when only 2 are used.** If the page uses regular (400) and bold (700), loading light (300), medium (500), semi-bold (600), and extra-bold (800) wastes bandwidth. Audit which weights are actually used and load only those.
+**Not specifying crossorigin on font preload.** Font requests are always CORS anonymous requests. Without the `crossorigin` attribute on `<link rel="preload">`, the preloaded font and the CSS-requested font are treated as different requests, causing a double download.
+## Source
+- web.dev: Best practices for fonts — https://web.dev/articles/font-best-practices
+- MDN: font-display — https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/font-display
+- Variable Fonts guide — https://web.dev/articles/variable-fonts
+- Font Loading API — https://developer.mozilla.org/en-US/docs/Web/API/CSS_Font_Loading_API
+## 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
+- All @font-face rules include an explicit font-display value (swap or optional).
+- Critical fonts (1-2 max) are preloaded with correct crossorigin attribute.
+- Font files are WOFF2 format and subsetted to used Unicode ranges.
+- Variable fonts replace multiple static weight files where applicable.
+- Fallback fonts use metric overrides (size-adjust, ascent-override) to minimize CLS.

package/dist/agents/skills/cursor/perf-font-loading/skill.yaml ADDED Viewed

@@ -0,0 +1,39 @@
+name: perf-font-loading
+version: '1.0.0'
+description: Font loading — font-display strategies, subsetting, variable fonts, FOIT/FOUT mitigation, and preloading critical fonts
+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-largest-contentful-paint
+  - perf-cumulative-layout-shift
+  - perf-resource-hints
+  - css-performance-patterns
+stack_signals: []
+keywords:
+  - font-display
+  - font loading
+  - FOIT
+  - FOUT
+  - font subsetting
+  - variable fonts
+  - woff2
+  - preload font
+  - web fonts
+metadata:
+  author: community
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/cursor/perf-garbage-collection/SKILL.md ADDED Viewed

@@ -0,0 +1,192 @@
+# Garbage Collection
+> Understand V8's generational garbage collector — young generation Scavenge, old generation Mark-Sweep-Compact, incremental and concurrent marking — to minimize GC pauses and reduce allocation pressure in performance-critical code.
+## When to Use
+- Chrome DevTools Performance panel shows yellow "GC" blocks causing frame drops or long pauses
+- The application has a high allocation rate (>10MB/s) causing frequent minor GC pauses
+- Major GC pauses (>50ms) interrupt animations or user interactions
+- Node.js `--trace-gc` output shows frequent or long GC events under load
+- You are building a real-time application (trading dashboard, game, audio processor) where GC pauses are unacceptable
+- Object pooling or allocation reduction could improve throughput
+- The V8 heap grows unboundedly and you suspect objects are surviving to old generation unnecessarily
+- `performance.measureUserAgentSpecificMemory()` or `performance.memory` shows high heap usage
+- Animation code creates new objects every frame (60 allocations/second per object type)
+- A Node.js server experiences latency spikes correlated with GC pauses
+## Instructions
+1. **Understand the generational hypothesis.** Most objects die young — they are allocated, used briefly, and become garbage. V8 exploits this by dividing the heap into generations:
+   - **Young generation (new space)** — small (1-8MB), collected frequently with fast Scavenge algorithm
+   - **Old generation (old space)** — larger (up to GB), collected less frequently with Mark-Sweep-Compact
+2. **Understand Scavenge (minor GC).** The young generation uses a semi-space copying collector:
+   - Two equally-sized semi-spaces: "from-space" and "to-space"
+   - Allocation happens in from-space
+   - When from-space is full, live objects are copied to to-space (dead objects are simply abandoned)
+   - The spaces swap roles
+   - Objects that survive 2 Scavenge cycles are promoted to old generation
+   - Pause time: 1-5ms (proportional to number of live objects, not dead ones)
+3. **Understand Mark-Sweep-Compact (major GC).** The old generation uses a tracing collector:
+   - **Mark** — trace from GC roots (global object, stack, handles), mark reachable objects
+   - **Sweep** — reclaim memory of unmarked objects, add to free lists
+   - **Compact** — (optional) move surviving objects together to reduce fragmentation
+   - Pause time: 10-100ms+ for large heaps (proportional to number of live objects)
+4. **Reduce allocation pressure in hot paths.** Every allocation eventually triggers GC. In code that runs 60 times per second (animation loops) or thousands of times per second (request handlers), minimize allocations:
+   ```javascript
+   // BAD — creates new object every frame (60 objects/second, all become garbage)
+   function animate() {
+     const position = { x: calcX(), y: calcY() };
+     applyPosition(position);
+     requestAnimationFrame(animate);
+   }
+   // GOOD — reuse object, zero allocations per frame
+   const position = { x: 0, y: 0 };
+   function animate() {
+     position.x = calcX();
+     position.y = calcY();
+     applyPosition(position);
+     requestAnimationFrame(animate);
+   }
+   ```
+5. **Implement object pooling for frequently created/destroyed objects:**
+   ```javascript
+   class ParticlePool {
+     constructor(size) {
+       this.pool = Array.from({ length: size }, () => ({
+         x: 0,
+         y: 0,
+         vx: 0,
+         vy: 0,
+         active: false,
+       }));
+       this.nextFree = 0;
+     }
+     acquire() {
+       const obj = this.pool[this.nextFree];
+       obj.active = true;
+       this.nextFree = (this.nextFree + 1) % this.pool.length;
+       return obj;
+     }
+     release(obj) {
+       obj.active = false;
+       obj.x = obj.y = obj.vx = obj.vy = 0;
+     }
+   }
+   ```
+6. **Monitor GC in Node.js with `--trace-gc`:**
+   ```bash
+   # Shows every GC event with type, duration, and heap sizes
+   node --trace-gc server.js
+   # Output example:
+   # [12345:0x1234]   100 ms: Scavenge 4.2 (8.0) -> 2.1 (8.0) MB, 1.3 / 0.0 ms
+   # [12345:0x1234]  5000 ms: Mark-sweep 45.2 (64.0) -> 32.1 (64.0) MB, 85.3 / 0.0 ms
+   ```
+7. **Use `performance.measureUserAgentSpecificMemory()` for browser heap measurement:**
+   ```javascript
+   // Requires cross-origin isolation headers
+   if (performance.measureUserAgentSpecificMemory) {
+     const result = await performance.measureUserAgentSpecificMemory();
+     console.log('Total JS heap:', result.bytes);
+     for (const breakdown of result.breakdown) {
+       console.log(breakdown.types, breakdown.bytes);
+     }
+   }
+   ```
+## Details
+### V8 Heap Spaces
+V8 divides the heap into several spaces:
+- **New space** (young generation) — 1-8MB, two semi-spaces. Objects start here.
+- **Old space** — objects promoted from new space after surviving 2 GCs
+- **Large object space** — objects larger than the semi-space maximum (~512KB) go directly here
+- **Code space** — JIT-compiled code (machine code)
+- **Map space** — hidden classes (V8's internal type system)
+### Orinoco: V8's Modern GC
+V8's garbage collector (Orinoco) uses three strategies to reduce pause times:
+1. **Incremental marking** — breaks the Mark phase into small steps (1-5ms each) interleaved with JavaScript execution. Instead of one 100ms mark phase, runs 20 steps of 5ms.
+2. **Concurrent marking** — runs marking on background threads while JavaScript executes on the main thread. The main thread only pauses briefly for the final "remark" step.
+3. **Parallel Scavenge** — uses multiple threads for the young generation copy, reducing Scavenge pause from 3ms to <1ms.
+### Worked Example: Trading Dashboard Allocation Pressure
+A real-time trading dashboard received WebSocket price updates at 100 messages/second. Each message handler created a new price tick object: `{ symbol, price, timestamp, change }`. At 100 objects/second, allocation rate was 50MB/s. This triggered Scavenge every 100ms and major GC every 10 seconds (200ms pause).
+Fix: implemented object pooling with a ring buffer of 1,000 pre-allocated tick objects. When a new tick arrives, the oldest inactive tick is recycled. Allocation rate dropped from 50MB/s to 2MB/s (only new strings for symbol names). Scavenge frequency dropped to every 4 seconds, and major GC pauses dropped from 200ms to <5ms because the old generation held a stable set of pool objects.
+### Worked Example: Node.js Streaming JSON
+A Node.js API server serialized responses using `JSON.stringify` on objects up to 50MB. At peak load (100 requests/second), peak old-gen usage reached 3.8GB (close to the 4GB `--max-old-space-size` limit), triggering 300ms major GC pauses every 30 seconds.
+Fix: switched to streaming JSON serialization (`json-stream-stringify`) which serializes incrementally, producing string chunks that are flushed immediately and collected by minor GC. Peak old-gen usage dropped from 3.8GB to 1.2GB because large intermediate string objects no longer accumulated in old space. Major GC pauses dropped to 15ms.
+### Anti-Patterns
+**Creating objects in hot loops.** `array.map(item => ({ ...item, computed: calc(item) }))` creates a new object per item. At 60fps with 100 items, that is 6,000 objects/second becoming garbage. Use in-place mutation or pre-allocated arrays when GC sensitivity is critical.
+**String concatenation in loops.** Each `str += chunk` creates a new string; the old one becomes garbage. For building large strings, use an array and `join()`, or use a single template literal.
+```javascript
+// BAD — O(n) strings become garbage
+let html = '';
+for (const item of items) {
+  html += `<div>${item.name}</div>`; // new string each iteration
+}
+// GOOD — one allocation at the end
+const parts = items.map((item) => `<div>${item.name}</div>`);
+const html = parts.join('');
+```
+**Not reusing arrays/objects across animation frames.** Creating new arrays or objects each frame for position calculations, collision detection, or particle updates creates constant Scavenge pressure. Pre-allocate and reuse.
+**Relying on `--expose-gc` and manual `global.gc()` in production.** Manual GC calls cause a full stop-the-world pause at the worst possible time (when you call it). V8's automatic GC is highly optimized to find the best time to collect. Manual GC is only useful for benchmarking and debugging.
+**Promoting short-lived objects to old generation.** Holding references to temporary objects across multiple GC cycles (in closures, module-scope variables, caches without eviction) causes them to be promoted to old generation. Old generation collection is much more expensive. Ensure temporary objects go out of scope quickly.
+## Source
+- V8 Blog: "Trash talk: the Orinoco garbage collector" — https://v8.dev/blog/trash-talk
+- V8 Blog: "Jank Busters" — https://v8.dev/blog/jank-busters
+- Chrome DevTools Memory panel documentation
+- Node.js `--trace-gc` flag documentation — https://nodejs.org/api/cli.html#--trace-gc
+## 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.
+- GC pauses are monitored and stay under 50ms during user interactions.
+- Allocation rate in hot paths is minimized through object reuse and pooling.

package/dist/agents/skills/cursor/perf-garbage-collection/skill.yaml ADDED Viewed

@@ -0,0 +1,40 @@
+name: perf-garbage-collection
+version: '1.0.0'
+description: Garbage collection — generational GC, V8 heap architecture, GC pauses, allocation pressure
+stability: static
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths: []
+related_skills:
+  - perf-memory-leaks
+  - perf-heap-profiling
+  - perf-event-loop
+  - perf-long-tasks
+  - node-performance-profiling
+stack_signals: []
+keywords:
+  - garbage collection
+  - GC
+  - V8
+  - generational GC
+  - Scavenge
+  - Mark-Sweep
+  - Mark-Compact
+  - heap
+  - allocation pressure
+  - GC pause
+metadata:
+  author: community
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/cursor/perf-heap-profiling/SKILL.md ADDED Viewed

@@ -0,0 +1,160 @@
+# Heap Profiling
+> Master heap snapshot analysis — Summary, Comparison, Containment, and Dominator views — to precisely identify what objects consume memory, why they are retained, and how to reclaim leaked memory using the 3-snapshot technique and allocation tracking.
+## When to Use
+- Memory usage grows over time and you need to identify which objects are accumulating
+- The 3-snapshot technique is needed to isolate memory leaks in an SPA
+- You need to understand the difference between shallow size and retained size for a specific object
+- A heap snapshot shows unexpected objects surviving garbage collection
+- You need to trace the retaining path from a leaked object to its GC root
+- Node.js heap profiling with `--heap-prof` or `v8.writeHeapSnapshot()` is needed
+- Allocation tracking over time is needed to find what code path allocates the most
+- The dominator tree reveals a single object retaining a disproportionate amount of memory
+- You need to compare heap state before and after a specific user action
+- Production memory profiling with low overhead is needed (allocation sampling)
+## Instructions
+1. **Take a heap snapshot.** In Chrome DevTools Memory panel, select "Heap snapshot" and click "Take snapshot." The snapshot captures every object on the V8 heap with its size, type, and references. Note: taking a snapshot triggers a full GC first, so only live objects appear.
+2. **Understand the four views:**
+   - **Summary** — groups objects by constructor name. Shows count, shallow size, and retained size per type. Start here to find which object types dominate memory.
+   - **Comparison** — compares two snapshots. Shows objects added, deleted, and delta between snapshots. Use this with the 3-snapshot technique.
+   - **Containment** — shows the object graph from GC roots. Drill down from Window/Global to see what each root retains.
+   - **Statistics** — pie chart of memory by object type category (code, strings, arrays, typed arrays, system).
+3. **Understand shallow vs retained size:**
+   - **Shallow size** — the memory the object itself occupies (its own properties, not referenced objects). A typical JavaScript object is 32-56 bytes shallow.
+   - **Retained size** — the total memory that would be freed if this object were garbage collected. Includes all objects exclusively retained by this object. This is almost always the metric you want.
+   Example: a 56-byte `Map` object (shallow) that holds 10,000 entries with 1KB values each has a retained size of ~10MB.
+4. **Execute the 3-snapshot technique:**
+   ```
+   1. Load page, wait for stabilization → Take Snapshot 1 (baseline)
+   2. Perform suspected leaking action (navigate, open dialog, etc.)
+   3. Undo the action (navigate back, close dialog)
+   4. Force GC (click trash can icon) → Take Snapshot 2
+   5. Repeat step 2-3
+   6. Force GC → Take Snapshot 3
+   7. In Snapshot 3, switch to Comparison view, compare against Snapshot 2
+   8. Filter by "Objects allocated between Snapshot 2 and Snapshot 3"
+   9. Objects that appear here survived two rounds → these are leaking
+   ```
+5. **Read retaining paths.** Select an object in the snapshot. The "Retainers" panel at the bottom shows every path from a GC root to this object. The shortest path is usually the most informative:
+   ```
+   system / Context → () @123456 → map property → Object @789012 (your leaked object)
+   ```
+   Each arrow represents a reference. To fix the leak, break one link in the chain.
+6. **Use allocation tracking for time-based analysis.** Instead of a static snapshot, use "Allocation instrumentation on timeline" in the Memory panel. This records every allocation over time with call stacks. Blue bars are allocations that survived, gray bars are collected. Focus on the blue bars — these are retained allocations that may be leaking.
+7. **Profile Node.js heaps:**
+   ```javascript
+   // Take a heap snapshot programmatically
+   const v8 = require('v8');
+   const fs = require('fs');
+   const snapshotStream = v8.writeHeapSnapshot();
+   console.log('Heap snapshot written to:', snapshotStream);
+   // Or use --heap-prof for allocation profiling
+   // node --heap-prof --heap-prof-interval=512 server.js
+   // Produces .heapprofile files loadable in Chrome DevTools
+   ```
+8. **Use allocation sampling for low-overhead production profiling:**
+   ```javascript
+   // Start sampling (low overhead, suitable for production)
+   const inspector = require('inspector');
+   const session = new inspector.Session();
+   session.connect();
+   session.post('HeapProfiler.startSampling');
+   // ... run workload ...
+   session.post('HeapProfiler.stopSampling', (err, result) => {
+     fs.writeFileSync('heap-profile.heapprofile', JSON.stringify(result.profile));
+   });
+   ```
+## Details
+### How to Read the Summary View
+The Summary view groups objects by constructor name. Key columns:
+| Column        | Meaning                                                                        |
+| ------------- | ------------------------------------------------------------------------------ |
+| Constructor   | The object type (e.g., `Array`, `Object`, `HTMLDivElement`, `(closure)`)       |
+| Distance      | Number of references from GC root to object (lower = more directly referenced) |
+| Shallow Size  | Memory of the object itself (bytes)                                            |
+| Retained Size | Memory freed if this object were GC'd (bytes)                                  |
+Sort by "Retained Size" descending to find the biggest memory consumers. Look for unexpectedly large retained sizes on objects you expect to be small.
+### Worked Example: 3-Snapshot SPA Leak Isolation
+A team used the 3-snapshot comparison to isolate a 2MB/navigation leak in an SPA:
+1. Snapshot 1: baseline (50MB heap)
+2. Navigate to detail page, navigate back
+3. Snapshot 2: 52MB heap
+4. Navigate to detail page, navigate back
+5. Snapshot 3: 54MB heap
+Comparing Snapshot 3 vs Snapshot 2: 2,400 new `HTMLDivElement` objects with retaining paths through a module-level variable declared as `const elementCache = new WeakMap()`. Investigation revealed a typo — the actual code was `const elementCache = new Map()` (regular Map, not WeakMap). DOM elements used as Map keys were strongly referenced, preventing GC of the entire detached subtree.
+Fix: changed `Map` to `WeakMap`. Leak eliminated — heap stabilized at 52MB across navigations.
+### Worked Example: Node.js Heap Profiling with --heap-prof
+A Node.js service used `--heap-prof` with `--heap-prof-interval=512` to sample production heap allocations at 512KB intervals. The resulting `.heapprofile` file was loaded in Chrome DevTools.
+Analysis revealed that 40% of all allocations came from `Buffer.from(JSON.stringify(logEntry))` in a logging middleware, called on every HTTP request. Each request created a 2-4KB Buffer that was immediately written to a log stream and discarded.
+Fix: implemented a Buffer pool that reused pre-allocated Buffers for log serialization. Allocation rate from logging dropped by 90%, reducing Scavenge frequency from every 200ms to every 2 seconds.
+### Anti-Patterns
+**Taking heap snapshots in production without understanding the pause.** Taking a snapshot triggers a full GC and serialization. For a 2GB heap, this can pause the process for 1-10 seconds. In production, use allocation sampling (low overhead) instead of full snapshots.
+**Comparing snapshots across page reloads.** Each page load creates a fresh V8 heap with new object IDs. Comparing snapshots from different page loads shows everything as "new" — the comparison is meaningless. Always compare within the same session.
+**Ignoring "system" and "compiled code" entries.** These represent V8 internal structures and JIT-compiled code. They are not application memory leaks. Focus on application-level constructors (your classes, DOM elements, closures, strings, arrays).
+**Using shallow size to prioritize investigation.** A small object (56 bytes shallow) can retain 100MB if it is the sole reference to a large object graph. Always sort by retained size when looking for leaks. Shallow size is only useful for understanding per-object overhead.
+**Not forcing GC before taking snapshots.** Without forcing GC, dead objects appear in the snapshot alongside live ones, making analysis confusing. Click the trash can icon (or call `gc()` in Node.js with `--expose-gc`) before each snapshot.
+## Source
+- Chrome DevTools Memory panel documentation — https://developer.chrome.com/docs/devtools/memory
+- V8 blog "Memory Management Reference"
+- Node.js `--heap-prof` documentation — https://nodejs.org/api/cli.html#--heap-prof
+- "Memory Profiling with Chrome DevTools" (Google Developers)
+## 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.
+- The 3-snapshot technique is used to verify no memory leaks exist in critical user flows.
+- Heap analysis is performed with retained size as the primary metric.