/screenshot-html

name: screenshot-html
description: Capture pixel-exact PNG screenshots of design artifact components inside HTML files produced by design-* skills (LinkedIn, Instagram, YouTube, Twitch, OBS overlays, blog hero, business card, etc.). Targets the `.canvas` / `.canvas-*` / `.scene` containers — not full pages. Use after generating design artifacts and visual exports are needed.

Skill: screenshot-html

Targeted artifact-node screenshots via headless Chromium. Skips browser chrome and page background — captures just the design canvas.

When to use

• After running any `design-*` skill that produces artifact HTML (LinkedIn post, Instagram card, YouTube thumbnail, Twitter card, blog hero, podcast cover, quote card, carousel, business card, speaker bio, Twitch panels, OBS scene pack, stream overlay, newsletter header, OG/hero pair, talk slides, etc.) and you want PNG exports of each artifact.
• When you need a clean image asset to attach to a post, deck, or PR — without the surrounding page padding the artifact HTML uses for preview backdrop.

Skip if:

• The HTML is a deliverable page (e.g. `design-landing-page`, `design-link-in-bio`) — the page IS the artifact, not a `.canvas` inside it. Use `--full-page` for those.
• The user wants browser-rendered review (open in a browser instead).

What it targets

The script queries for these conventions used by `design-*` skills:

• `.canvas` — the primary fixed-size artifact wrapper (most skills).
• `[class*="canvas-"]` — modifier variants: `canvas-front` / `canvas-back` (business card), `canvas-main` / `canvas-compact` (speaker bio), `canvas-full` / `canvas-safe` (YouTube channel art), `canvas-og` / `canvas-hero` (blog hero), `canvas-square` / `canvas-story` (quote card), `canvas-offline` (Twitch offline banner), `canvas-panel` (Twitch info panels).
• `.scene` — hash-routed scenes inside stream-overlay and OBS scene-pack files (`<section id="scene-starting" class="scene">` etc.). The script navigates each scene's hash before capture so the `.is-active` toggle applies.

Nested matches are deduped — only top-level artifact containers are screenshotted.

If a file has no matches, the script falls back to a full-page screenshot. `--full-page` forces fallback for every file.

How to run

From the project root where the design HTML lives (Playwright must resolve there):

node skills/screenshot-html/scripts/screenshot-html.mjs <dir> [--output <dir>] [--width <px>] [--height <px>] [--full-page]

Flags:

• `<dir>` (positional, default `.`): directory to scan recursively for `*.html`. The `screenshots/` subdirectory and hidden dirs are skipped.
• `--output <dir>` (default `<dir>/screenshots`): where PNGs are written. Output is flat (one file per artifact target), not mirrored from the input tree — filenames disambiguate via slug + index.
• `--width <px>` / `--height <px>` (default `1920 × 1080`): browser viewport. Artifact canvases set their own pixel size, so the viewport just needs to be big enough to contain them. Bump up for very tall canvases (Instagram story 1080×1920, YouTube channel art 2560×1440).
• `--full-page`: force full-page screenshots for every file, skipping artifact targeting.

The browser runs at `deviceScaleFactor: 1` so PNG pixel dimensions match the canvas's declared size exactly (matches what `design-*` skills assume for export).

Prerequisites

**None — the script self-bootstraps on first run.**

If Playwright isn't resolvable, the script installs it (and the Chromium binary) into its own `node_modules` next to `screenshot-html.mjs`. First run takes ~10–60s for the install; subsequent runs hit the fast path (~1s overhead).

$ node screenshot-html.mjs ./design/<brand>/artifacts
Playwright not found. Installing into <skill-dir>/scripts/node_modules (one-time)…
added 2 packages in 986ms
…

The bootstrap also catches the "Chromium binary missing" failure mode (post-upgrade, fresh CI runner) and self-heals with `playwright install chromium` before retrying the launch.

How the bootstrap stays scoped

The script anchors npm to its own directory by writing a stub `package.json` and passing `--prefix=<scripts-dir>`. Without those, npm walks up looking for the closest ancestor `package.json` and the install bleeds into a parent project. The bootstrap deliberately avoids that.

A local `.gitignore` covers `node_modules/`, `package.json`, and `package-lock.json` — none of the install artifacts are checked in.

What does NOT work (intentional non-fallbacks)

These were considered and rejected; documented so future maintainers don't waste time re-discovering them:

• ❌ `npx -y playwright` / `npx -y --package=playwright -- node …` — `npx` only puts the playwright CLI on `PATH`; it does not make the package importable from an arbitrary `.mjs` file.
• ❌ `NODE_PATH=…` — ignored by Node's ESM resolver.
• ❌ Relying on a sibling project's `node_modules` — ESM resolves `import 'playwright'` from the script file's location, not cwd.

Script location

`skills/screenshot-html/scripts/screenshot-html.mjs` (lives alongside this skill in the config repo). Always invoke with `node skills/screenshot-html/scripts/screenshot-html.mjs ...` from a directory where Playwright resolves — typically the project containing the design HTML, not this config repo. The script is self-contained — no relative imports — so calling it by absolute path from any cwd works too.

Output naming

For each top-level artifact in a file, the script derives a hint from the element's id (preferred, e.g. `scene-starting`) or its most specific class token (`canvas-front`, `canvas-og`, etc.):

| Source file | Targets | Output filenames | |---|---|---| | `linkedin-2026-05-02-field-note.html` | one `.canvas` | `linkedin-2026-05-02-field-note.png` | | `business-card.html` | `.canvas-front`, `.canvas-back` | `business-card--canvas-front.png`, `business-card--canvas-back.png` | | `blog-hero.html` | `.canvas-og`, `.canvas-hero` | `blog-hero--ca