/extract-static-html

name: stitch::extract-static-html
description: >-
  Extract self-contained static HTML from a built web application or React components by inlining CSS and images. Use this skill whenever you need to capture a specific UI state, share a static version of a page, or prepare assets for Stitch upload, even if the user just asks to 'save the HTML' or 'mock the view'.
allowed-tools:
  - "stitch*:*"
  - "Bash"
  - "Read"
  - "Write"
  - "web_fetch"

Extract Static HTML

Extract a self-contained static HTML file from any web application.

Which Strategy to Use

You MUST ask the user to choose which strategy to use before proceeding. Present the options clearly, **recommend Strategy A** as the preferred default, and **provide a brief pros/cons summary** for each option to help them make an informed decision.

| | Strategy A (Puppeteer) | Strategy B (Browser Subagent) | | :--- | :--- | :--- | | **When** | App runs locally, no auth wall | Need to interact with page first (click, fill forms) | | **Fidelity** | **Highest — computed styles resolved** | High — rendered DOM | | **Setup** | **Zero — no mock needed** | Zero — no mock needed | | **Framework** | **Any** | Any | | **Output** | **Writes to file — no size limit** | May truncate in agent context |

> [!WARNING] > **Checkpoint — User Confirmation Required.** > You **MUST** ask the user which strategy they prefer before proceeding. > Present the comparison table above, recommend Strategy A as the default, and > wait for explicit approval. Do **NOT** make the decision yourself or proceed > until the user confirms.

***

Strategy A: Puppeteer Snapshot (Recommended)

Launches headless Chrome, captures the fully rendered DOM, and produces a self-contained HTML file with all CSS inlined and images as base64. Works with **any framework** — no MockPage.jsx needed.

Prerequisites

• App running locally (e.g., `npm run dev`)
• Node.js with `puppeteer` available (check: `node -e "require('puppeteer')"`)

Workflow

1. **Start the App** and note the port.

> [!WARNING] > **Checkpoint — User Confirmation Required.** > After starting the local server, you **MUST** pause and ask the user for > confirmation before running the snapshot script or launching a browser > subagent. Report the URL and port to the user so they can verify the app > is running and rendering correctly. Do **NOT** proceed to the snapshot > step until the user confirms.

2. **Run the Snapshot Script**:

    npx tsx <SKILL_DIR>/scripts/snapshot.ts \
      --url http://localhost:5173 \
      --output .stitch/home.html \
      --wait 2000

3. **Multiple pages** — run once per route:

    npx tsx <SKILL_DIR>/scripts/snapshot.ts \
      --url http://localhost:5173 --output .stitch/home.html --wait 2000
    npx tsx <SKILL_DIR>/scripts/snapshot.ts \
      --url http://localhost:5173/pricing --output .stitch/pricing.html --wait 2000
    npx tsx <SKILL_DIR>/scripts/snapshot.ts \
      --url http://localhost:5173/dashboard --output .stitch/dashboard.html --wait 2000 --html-class dark

4. **Clean Up Dev Server**: If a local dev server was started specifically for snapshot extraction, make sure to stop the server process or terminate the background task once extraction is completed.

Script Flags

| Flag | Default | Description | | :--- | :--- | :--- | | `--url` | *(required)* | URL to capture | | `--output` | *(required)* | Output file path | | `--wait` | `1000` | Extra wait (ms) after network idle. Increase for lazy-loading apps. | | `--viewport` | `1280x800` | Viewport size as `WIDTHxHEIGHT` | | `--html-class` | — | Class(es) for `<html>` element (e.g., `dark`) | | `--remove-fixed` | `false` | Remove fixed/sticky elements (cookie banners, chat widgets) | | `--full-height` | `false` | Resize viewport to full scroll height | | `--title` | — | Override page title (set to the route path, e.g. `/dashboard` or `/settings/profile`) | | `--auth-script` | — | Path to a JS/TS module that exports a default `async (page) => void` function for authentication | | `--inline-canvas` | `false` | Convert `<canvas>` elements (ECharts, Chart.js, D3) to base64 `<img>` tags |

What It Does Automatically

• Captures all CSSOM rules from `document.styleSheets` (preserves dynamic Vite/Tailwind dev styles and CSS-in-JS)
• Inlines all `<link rel="stylesheet">` → `<style>` blocks
• Converts `<img>` `src` **and `srcset`** → base64 data URIs (skips external fonts)
• Inlines same-origin and relative icon font files (`@font-face`) as base64 data URIs so ligatures never render as ASCII text
• Inlines `<source srcset>` URLs as base64
• Removes failed/dead `srcset` entries so the browser falls back to the inlined `src`
• Removes `<script>` tags, Vite HMR dev style blocks (`createHotContext`, `import.meta.hot`), and dev overlays
• Resolves relative CSS `url()` paths before inlining

Framework Notes

| Framework | Notes | | :--- | :--- | | **React + Vite** | Works out of the box. `--wait 1000`. | | **Next.js** | `--wait 3000` for SSR hydration. URL: `http://localhost:3000`. `<img srcset>` from `/_next/image` is auto-inlined as base64. | | **Angular (@angular/cli / v17+)** | Works out of the box with `ng serve` (default URL: `http://localhost:4200`). `--wait 2000` for Angular Material / PrimeNG animation hydration and lazy-loaded routes. | | **Vue / Nuxt** | Works out of the box. | | **Svelte / SvelteKit** | Works out of the box. | | **Storybook** | Use story URL: `--url http://localhost:6006/?path=/story/...` | | **SSR (Webpack)** | May need longer `--wait`. |

Troubleshooting

| Issue | Solution | | :--- | :--- | | Images missing | Increase `--wait` | | Images show as broken after server stops | Verify `srcset` was inlined — check log for "Inlined N images". If `srcset` URLs failed, they are auto-removed so `src` (inlined) is used. | | Icons display as text / Serif unstyled font | Ensure `snapshot.ts` captures CSSOM from