Stitch::extract Static HTML

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.

[!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

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

Troubleshooting

Auth-Gated Pages

For apps with login guards (Vue Router beforeEach, React ProtectedRoute, etc.), create a small auth script that runs in the Puppeteer session:

// auth-myapp.ts
import type { Page } from 'puppeteer';

export default async function authenticate(page: Page) {
  // Example 1: Fill and submit a login form
  await page.type('#username', 'admin');
  await page.type('#password', 'password123');
  await page.click('#login-button');
  await page.waitForNavigation({ waitUntil: 'networkidle2' });

  // Example 2: Inject cookies/localStorage directly
  // await page.evaluate(() => {
  //   localStorage.setItem('token', 'mock-jwt-token');
  // });

  // Example 3: Call the app's own login API via module injection (Vue/Vite)
  // await page.evaluate(() => {
  //   return new Promise((resolve) => {
  //     const script = document.createElement('script');
  //     script.type = 'module';
  //     script.textContent = `
  //       import { useUserStore } from '/src/store/modules/user.ts';
  //       import { fetchLogin } from '/src/api/auth.ts';
  //       const res = await fetchLogin({ userName: 'Admin', password: '123456' });
  //       useUserStore().setToken(res.token, res.refreshToken);
  //       window.dispatchEvent(new CustomEvent('auth-done'));
  //     `;
  //     document.head.appendChild(script);
  //     window.addEventListener('auth-done', () => resolve(true), { once: true });
  //   });
  // });
}

Then use it:

npx tsx <SKILL_DIR>/scripts/snapshot.ts \
  --url http://localhost:5173/#/dashboard \
  --output .stitch/dashboard.html \
  --auth-script ./auth-myapp.ts \
  --inline-canvas \
  --wait 5000

The script navigates to the --url first (which may redirect to login), runs your auth function, then re-navigates to the original --url with the authenticated session.

Strategy B: Browser Subagent Capture

Use when you need to interact with the page (click buttons, fill forms, navigate tabs) before capturing. The browser subagent gives you full control but output may truncate for large pages.

Workflow

1. Start the App locally.

2. Navigate using a browser subagent.

3. Interact as needed (click, scroll, fill forms).

4. Extract DOM: document.documentElement.outerHTML

   [!WARNING] Large pages may truncate. To handle this:

   • Remove <style> tags before extraction: document.querySelectorAll('style').forEach(el => el.remove())
   • Re-add styles statically (Tailwind CDN link, source CSS)

5. Save to file.

Appendix: Static Fallback (MockPage.jsx)

[!NOTE] This method is a last resort for when the app cannot run locally (broken deps, missing backend, auth walls with no bypass). It requires manually flattening React components into a single JSX file. Prefer Strategy A whenever possible.

When to Use

• App can't run locally at all
• Page requires auth with no mock/bypass
• You need a specific UI state that's impossible to reach by navigation (error screens, empty states)

Quick Reference

npx tsx <SKILL_DIR>/scripts/extract_inline_html.ts \
  --index-css src/css/App.css \
  --extra-css index.html \
  --outdir .stitch \
  --page src/MockPage.jsx:Page.html:"Page Title"

Key flags: --no-tailwind (non-Tailwind apps), --html-class dark (dark mode), --css-files (extra CSS files).

Auto-detection: Tailwind config is auto-detected. @apply directives automatically use <style type="text/tailwindcss">.

MockPage.jsx Rules

1. Include the full layout — header, sidebar, footer (read App.js first)
2. Flatten all conditionals — pick one state, remove all ternaries and && guards
3. Hardcode all data — replace {variable} with concrete values, unroll .map() loops
4. Preserve logos — use <img> with local paths (post-process will inline them)
5. Remove floating elements — cookie banners, chat widgets, feedback buttons

Post-Processing

Inline local images:

npx tsx <SKILL_DIR>/scripts/post_process.ts \
  .stitch/Page.html --base-dir <app-directory>