@harness-engineering/cli 1.23.2 → 1.24.1

package/dist/agents/skills/cursor/perf-lazy-loading-media/SKILL.md

@@ -0,0 +1,233 @@
+# Media Lazy Loading
+
+> Master media lazy loading strategies — native browser lazy loading for images and iframes, video poster optimization, low-quality image placeholders (LQIP), BlurHash encoding, progressive rendering techniques, and prioritization of above-the-fold media.
+
+## When to Use
+
+- A page contains many images but only 2-3 are visible on initial load
+- Lighthouse flags "Defer offscreen images" with significant byte savings
+- Page load downloads all images regardless of whether they are in the viewport
+- Video embeds (YouTube, Vimeo) load heavy iframes before the user clicks play
+- Image-heavy galleries or product listings transfer megabytes on initial load
+- Placeholder images cause layout shift when the real image loads
+- Users perceive the page as slow because all media loads simultaneously
+- A content-heavy blog or news site loads images for the entire article at once
+- Infinite scroll feeds download images for items far below the current scroll position
+- Third-party image embeds (Instagram, Twitter) add hundreds of KB to page weight
+
+## Instructions
+
+1. **Use native lazy loading for below-fold images.** The `loading="lazy"` attribute defers image loading until the image approaches the viewport:
+
+   ```html
+   <!-- Below-fold images: lazy load -->
+   <img
+     src="product.jpg"
+     alt="Product photo"
+     width="400"
+     height="300"
+     loading="lazy"
+     decoding="async"
+   />
+
+   <!-- Above-fold / LCP images: NEVER lazy load -->
+   <img src="hero.jpg" alt="Hero banner" width="1200" height="600" fetchpriority="high" />
+   ```
+
+   The browser determines the loading threshold (typically 1250-2500px from viewport depending on connection speed). Do not add `loading="lazy"` to the LCP image or any image visible in the initial viewport.
+
+2. **Lazy load iframes for video embeds.** YouTube and Vimeo iframes load 500KB+ of JavaScript. Defer until the user indicates intent:
+
+   ```html
+   <!-- Native iframe lazy loading -->
+   <iframe
+     src="https://www.youtube.com/embed/dQw4w9WgXcQ"
+     loading="lazy"
+     width="560"
+     height="315"
+     title="Video title"
+     allow="accelerometer; autoplay; encrypted-media"
+     allowfullscreen
+   ></iframe>
+
+   <!-- Better: facade pattern — show thumbnail, load iframe on click -->
+   ```
+
+   ```typescript
+   function YouTubeFacade({ videoId, title }: { videoId: string; title: string }) {
+     const [loaded, setLoaded] = useState(false);
+
+     if (loaded) {
+       return (
+         <iframe
+           src={`https://www.youtube.com/embed/${videoId}?autoplay=1`}
+           width="560"
+           height="315"
+           title={title}
+           allow="accelerometer; autoplay; encrypted-media"
+           allowfullscreen
+         />
+       );
+     }
+
+     return (
+       <button
+         onClick={() => setLoaded(true)}
+         style={{ position: 'relative', width: 560, height: 315 }}
+         aria-label={`Play: ${title}`}
+       >
+         <img
+           src={`https://i.ytimg.com/vi/${videoId}/hqdefault.jpg`}
+           alt={title}
+           width="560"
+           height="315"
+           loading="lazy"
+         />
+         <PlayIcon />
+       </button>
+     );
+   }
+   ```
+
+3. **Implement LQIP (Low-Quality Image Placeholders).** Show a tiny blurred preview while the full image loads:
+
+   ```javascript
+   // Generate LQIP at build time with sharp
+   const sharp = require('sharp');
+
+   async function generateLQIP(inputPath) {
+     const buffer = await sharp(inputPath)
+       .resize(20) // 20px wide
+       .blur(2)
+       .jpeg({ quality: 20 })
+       .toBuffer();
+
+     return `data:image/jpeg;base64,${buffer.toString('base64')}`;
+     // ~200-400 bytes, inlineable in HTML
+   }
+   ```
+
+   ```html
+   <!-- LQIP placeholder with fade-in transition -->
+   <div class="image-container" style="aspect-ratio: 4/3;">
+     <img
+       src="data:image/jpeg;base64,/9j/4AAQSkZJ..."
+       data-src="product-full.jpg"
+       alt="Product"
+       class="lqip-image"
+       width="800"
+       height="600"
+     />
+   </div>
+
+   <style>
+     .image-container {
+       overflow: hidden;
+     }
+     .lqip-image {
+       width: 100%;
+       height: 100%;
+       object-fit: cover;
+       filter: blur(20px);
+       transform: scale(1.1);
+       transition:
+         filter 0.3s,
+         transform 0.3s;
+     }
+     .lqip-image.loaded {
+       filter: blur(0);
+       transform: scale(1);
+     }
+   </style>
+   ```
+
+4. **Use BlurHash for compact placeholders.** BlurHash encodes a placeholder in ~20-30 characters, decoded to a blurred preview on the client:
+
+   ```typescript
+   // Server: encode at upload/build time using sharp + blurhash
+   import { encode } from 'blurhash';
+   import sharp from 'sharp';
+
+   async function generateBlurHash(imagePath: string): Promise<string> {
+     const { data, info } = await sharp(imagePath)
+       .raw()
+       .ensureAlpha()
+       .resize(32, 32, { fit: 'inside' })
+       .toBuffer({ resolveWithObject: true });
+     return encode(new Uint8ClampedArray(data), info.width, info.height, 4, 3);
+   }
+
+   // Client: decode hash to pixels, render to <canvas> via ctx.putImageData()
+   ```
+
+5. **Implement video poster optimization.** For video elements, use a poster image to avoid loading video data before play:
+
+   ```html
+   <video poster="video-poster.webp" preload="none" width="1280" height="720" playsinline>
+     <source src="video.mp4" type="video/mp4" />
+   </video>
+   ```
+
+   Set `preload="none"` to prevent the browser from downloading any video data. The poster image provides the visual preview. Combine with `loading="lazy"` on a facade image for below-fold videos.
+
+6. **Implement progressive image loading with CSS transitions.** Preload the full image in a `new Image()`, swap `src` on load, and animate with `filter: blur(20px)` transitioning to `filter: none` over 300ms. This smooths the placeholder-to-image transition without layout shift.
+
+7. **Configure the loading threshold.** Browsers load lazy images before they enter the viewport. Chrome uses a distance threshold that varies by connection speed (~1250px on 4G, ~2500px on slow 3G). For custom Intersection Observer implementations, set rootMargin based on image size and expected scroll speed:
+
+   ```typescript
+   // Small thumbnails (fast to load): trigger closer
+   const observer = new IntersectionObserver(callback, { rootMargin: '200px' });
+
+   // Large hero images (slow to load): trigger earlier
+   const observer = new IntersectionObserver(callback, { rootMargin: '500px' });
+   ```
+
+## Details
+
+### Native Lazy Loading Browser Behavior
+
+When `loading="lazy"` is set, the browser defers the image fetch until the image is within a distance threshold of the viewport. This threshold is not configurable by developers — it varies by browser and connection speed. Chrome on a fast connection starts loading images ~1250px before they enter the viewport. On slow 3G, this increases to ~2500px to compensate for longer download times. Images with `loading="lazy"` that are in the initial viewport on page load are loaded immediately (no deferral).
+
+### Worked Example: Medium Article Images
+
+Medium inlines a ~200-byte blurred LQIP as a base64 data URI. When the container approaches the viewport (Intersection Observer, 300px rootMargin), the full image loads and a CSS transition fades from blur to sharp over 300ms. Result: zero layout shift, immediate visual feedback, and ~95% of image bytes deferred.
+
+### Worked Example: Instagram Feed
+
+Each API response includes a 28-character BlurHash string rendered to a canvas as an instant placeholder. The actual image loads progressively (headers first, then increasing resolution scans). Result: colored blurred previews within 50ms of scrolling, zero layout shift, and perceived-instant loading.
+
+### Anti-Patterns
+
+**Lazy loading the LCP image.** Adding `loading="lazy"` to the hero image or any image visible without scrolling delays LCP by the intersection observer threshold plus download time. The LCP image should be eagerly loaded with `fetchpriority="high"`.
+
+**Using JavaScript lazy loading when native suffices.** Libraries like lazysizes add JavaScript overhead for functionality the browser provides natively. Use `loading="lazy"` for standard cases. Reserve JavaScript solutions for LQIP, BlurHash, or Intersection Observer patterns that native lazy loading cannot provide.
+
+**Placeholders that cause layout shift.** A placeholder with different dimensions than the final image causes Cumulative Layout Shift when swapped. Always set width, height, and aspect-ratio on containers. Placeholders must match the final image's aspect ratio.
+
+**Lazy loading all images indiscriminately.** Applying `loading="lazy"` to every image on the page, including above-the-fold images, delays rendering of critical content. Audit which images are in the initial viewport and exclude them from lazy loading.
+
+## Source
+
+- web.dev: Browser-level image lazy loading — https://web.dev/articles/browser-level-image-lazy-loading
+- MDN: Lazy loading — https://developer.mozilla.org/en-US/docs/Web/Performance/Lazy_loading
+- BlurHash — https://blurha.sh/
+- lite-youtube-embed — https://github.com/niccoloborghesi/lite-youtube-embed
+
+## 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
+
+- Below-fold images use `loading="lazy"` and above-fold images do not.
+- Video embeds use a facade pattern that loads the iframe only on interaction.
+- Image placeholders (LQIP or BlurHash) are implemented for key images.
+- No media lazy loading causes layout shift (containers have explicit dimensions).
+- Initial page load transfers only images visible in the viewport.

package/dist/agents/skills/cursor/perf-lazy-loading-media/skill.yaml

@@ -0,0 +1,38 @@
+name: perf-lazy-loading-media
+version: '1.0.0'
+description: Media lazy loading — Native image lazy loading, video poster strategies, placeholder techniques, and progressive image rendering
+stability: static
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths: []
+related_skills:
+  - perf-lazy-loading
+  - perf-responsive-images
+  - perf-image-formats
+  - perf-largest-contentful-paint
+  - perf-cumulative-layout-shift
+stack_signals: []
+keywords:
+  - lazy loading images
+  - loading attribute
+  - video poster
+  - placeholder
+  - LQIP
+  - blurhash
+  - progressive jpeg
+  - native lazy loading
+metadata:
+  author: community
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/cursor/perf-long-tasks/SKILL.md

@@ -0,0 +1,194 @@
+# Long Tasks
+
+> Detect, break up, and eliminate long tasks (>50ms on the main thread) using time-slicing, scheduler APIs, Web Workers, and cooperative yielding to keep the UI responsive and meet the 50ms responsiveness budget.
+
+## When to Use
+
+- Chrome DevTools Performance panel shows red "Long Task" markers (tasks exceeding 50ms)
+- INP is poor because user interactions are delayed by long-running tasks on the main thread
+- Page initialization runs heavy synchronous work (data processing, DOM construction, parsing)
+- You are processing large datasets (sorting, filtering, searching) synchronously on the main thread
+- The Long Tasks API (`PerformanceObserver` with `longtask` type) fires frequently in production monitoring
+- You need to choose between `scheduler.yield()`, `scheduler.postTask()`, `requestIdleCallback`, and Web Workers
+- `JSON.parse` on multi-MB payloads blocks the main thread
+- Third-party scripts contribute long tasks that degrade responsiveness
+- A computationally intensive feature (syntax highlighting, markdown parsing, image processing) needs to run without blocking
+- Animation or scroll frame rate drops below 60fps due to JavaScript execution in the main thread
+
+## Instructions
+
+1. **Understand the 50ms budget.** At 60fps, each frame is 16.67ms. The browser needs ~6ms for rendering (style, layout, paint, composite). That leaves ~10ms for JavaScript per frame. The Long Tasks API defines 50ms as the threshold because: a task under 50ms allows the browser to respond to input within 100ms (the perceptual threshold for "instant" response).
+
+2. **Detect long tasks with the Performance Observer:**
+
+   ```javascript
+   const observer = new PerformanceObserver((list) => {
+     for (const entry of list.getEntries()) {
+       console.log('Long task detected:', entry.duration, 'ms');
+       console.log('Attribution:', entry.attribution[0]?.containerName);
+     }
+   });
+   observer.observe({ type: 'longtask', buffered: true });
+   ```
+
+3. **Break up long tasks with `scheduler.yield()`.** This is the preferred modern approach — it yields to the browser so pending input events can run, then resumes the work:
+
+   ```javascript
+   async function processLargeDataset(items) {
+     const CHUNK_SIZE = 100;
+     for (let i = 0; i < items.length; i += CHUNK_SIZE) {
+       const chunk = items.slice(i, i + CHUNK_SIZE);
+       processChunk(chunk);
+
+       // Yield to browser — allows input events and rendering
+       await scheduler.yield();
+     }
+   }
+   ```
+
+4. **Use `scheduler.postTask()` for priority-based scheduling:**
+
+   ```javascript
+   // High priority — respond to user action
+   await scheduler.postTask(() => updateSearchResults(query), {
+     priority: 'user-blocking',
+   });
+
+   // Low priority — prefetch next page data
+   scheduler.postTask(() => prefetchNextPage(), {
+     priority: 'background',
+   });
+   ```
+
+5. **Use `requestIdleCallback` for truly non-urgent work:**
+
+   ```javascript
+   function processAnalyticsQueue() {
+     requestIdleCallback((deadline) => {
+       // Process items while we have idle time (at least 5ms remaining)
+       while (deadline.timeRemaining() > 5 && analyticsQueue.length > 0) {
+         sendAnalyticsEvent(analyticsQueue.shift());
+       }
+       // If more items remain, schedule another idle callback
+       if (analyticsQueue.length > 0) {
+         requestIdleCallback(processAnalyticsQueue);
+       }
+     });
+   }
+   ```
+
+6. **Move CPU-intensive work to Web Workers:**
+
+   ```javascript
+   // main.js — offload to worker
+   const worker = new Worker('/syntax-worker.js');
+   worker.postMessage({ text: editorContent });
+   worker.onmessage = (e) => {
+     applyHighlighting(e.data.tokens);
+   };
+
+   // syntax-worker.js — runs on a separate thread
+   self.onmessage = (e) => {
+     const tokens = parseSyntax(e.data.text); // 150ms of CPU work
+     self.postMessage({ tokens }); // does not block main thread
+   };
+   ```
+
+7. **Use the MessageChannel trick for zero-delay yielding (pre-scheduler.yield):**
+
+   ```javascript
+   function yieldToMain() {
+     return new Promise((resolve) => {
+       const channel = new MessageChannel();
+       channel.port1.onmessage = resolve;
+       channel.port2.postMessage(null);
+     });
+   }
+
+   async function processItems(items) {
+     for (const item of items) {
+       processItem(item);
+       await yieldToMain(); // no 4ms setTimeout clamp
+     }
+   }
+   ```
+
+## Details
+
+### Why 50ms Is the Threshold
+
+The 50ms threshold comes from the RAIL performance model:
+
+- **Response** — respond to user input within 100ms
+- The 100ms budget includes input processing (event handler) plus rendering
+- If a task is already running when the user interacts, the interaction must wait for the task to finish
+- A 50ms task + 50ms event processing + rendering = ~100ms total response time
+
+Tasks under 50ms are safe because even if a user interaction arrives while the task is running, the worst-case delay is under 100ms. Tasks over 50ms risk perceptible delay.
+
+### Worked Example: Google Search Results Chunked Rendering
+
+Google's search results page renders 10 results in 5 chunks of 2 results each, yielding between chunks with `scheduler.yield()`. Without chunking, rendering all 10 results takes 80ms (a long task). With chunking:
+
+- Chunk 1 (results 1-2): 16ms, yield
+- Chunk 2 (results 3-4): 16ms, yield
+- Chunk 3 (results 5-6): 16ms, yield
+- Chunk 4 (results 7-8): 16ms, yield
+- Chunk 5 (results 9-10): 16ms
+
+Total time increases from 80ms to ~95ms (overhead from yielding), but no single task exceeds 50ms. INP improved from 200ms to 40ms because user interactions are no longer blocked by a monolithic render task.
+
+### Worked Example: Markdown Editor Web Worker
+
+A markdown editor moved syntax highlighting to a Web Worker. The main thread sends raw text via `postMessage`. The worker tokenizes the text (150ms of CPU work per keystroke on large documents) and returns highlighted tokens. The main thread applies the tokens to the DOM.
+
+Before: typing in a 10,000-line document caused 150ms input lag per keystroke (long task blocking every keypress). After: the worker processes asynchronously, main thread stays responsive, and highlighted tokens arrive 150ms after each keystroke with no input blocking. Perceived latency for typing dropped to <16ms.
+
+### Strategies Comparison
+
+| Strategy                | Latency           | Priority        | Thread     | Use Case                       |
+| ----------------------- | ----------------- | --------------- | ---------- | ------------------------------ |
+| `scheduler.yield()`     | ~0ms              | Inherits caller | Main       | Breaking up sequential work    |
+| `scheduler.postTask()`  | ~0ms              | Explicit        | Main       | Priority-based scheduling      |
+| `setTimeout(fn, 0)`     | 0-4ms             | None            | Main       | Legacy yielding                |
+| `MessageChannel`        | ~0ms              | None            | Main       | Zero-delay yielding (polyfill) |
+| `requestIdleCallback`   | Variable          | Lowest          | Main       | Non-urgent background work     |
+| `requestAnimationFrame` | Up to 16ms        | Frame-aligned   | Main       | Visual updates only            |
+| Web Worker              | Transfer overhead | N/A             | Background | CPU-intensive parallel work    |
+
+### Anti-Patterns
+
+**Processing entire large arrays synchronously.** `items.forEach(heavyFn)` on 10,000 items with 0.05ms per item creates a 500ms long task. Break into chunks with yielding between each chunk.
+
+**`JSON.parse` of multi-MB payloads on the main thread.** `JSON.parse` is synchronous and cannot be interrupted. A 5MB JSON string takes 50-200ms to parse depending on complexity. Use a streaming JSON parser in a Web Worker, or fetch data in smaller paginated chunks.
+
+**Using `requestAnimationFrame` for non-visual work.** rAF callbacks share the frame budget with rendering. Scheduling heavy computation in rAF steals time from style, layout, and paint, causing frame drops. Use `scheduler.postTask` or `requestIdleCallback` for non-visual work.
+
+**Debounce-only approach to responsiveness.** Debouncing a search input handler to 300ms hides the problem but does not fix it. When the debounced handler finally fires, it may still run a 200ms long task. Combine debouncing with chunked processing and yielding.
+
+**Assuming Web Worker communication is free.** `postMessage` uses the structured clone algorithm, which can be expensive for large objects. Transferring a 10MB ArrayBuffer is fast (transferable), but cloning a 10MB object graph with nested arrays takes 50-100ms. Use transferable objects or SharedArrayBuffer when possible.
+
+## Source
+
+- Long Tasks API specification — https://w3c.github.io/longtasks/
+- web.dev "Optimize long tasks" — https://web.dev/articles/optimize-long-tasks
+- Scheduler API specification — https://wicg.github.io/scheduling-apis/
+- Chrome DevTools Performance panel documentation — https://developer.chrome.com/docs/devtools/performance
+
+## 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.
+- No long tasks (>50ms) occur during critical user interactions.
+- The Long Tasks API is used to detect and monitor long tasks in production.

package/dist/agents/skills/cursor/perf-long-tasks/skill.yaml

@@ -0,0 +1,38 @@
+name: perf-long-tasks
+version: '1.0.0'
+description: Long task detection — breaking up work, yielding to the main thread, scheduler API, web workers
+stability: static
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths: []
+related_skills:
+  - perf-event-loop
+  - perf-interaction-to-next-paint
+  - perf-profiling-methodology
+  - ts-performance-patterns
+stack_signals: []
+keywords:
+  - long task
+  - main thread
+  - yielding
+  - scheduler.yield
+  - scheduler.postTask
+  - web worker
+  - isInputPending
+  - time slicing
+  - 50ms budget
+metadata:
+  author: community
+state:
+  persistent: false
+  files: []
+depends_on: []