build: add puppeteer-based screenshot script#75
Merged
Conversation
Adds build/screenshot.mjs and an 'npm run screenshot' command that captures the local dev server (http://localhost:3000) at four viewports — X/Twitter card (1200x675), OpenGraph image (1200x630), desktop (1440x900), mobile (390x844) — across the homepage (EN/ZH) and two representative content pages. Uses puppeteer-core with the system Chrome/Chromium binary so we don't pull in the ~150 MB bundled Chromium download. Falls back to CHROME_PATH env var. Output goes to assets/screenshots/ (gitignored). The script is a review aid — it underwrites the social-card-crop check referenced in rules/design-intent.md (homepage section order was reverted on 2026-05-14 after this exact crop revealed the problem). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Contributor
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
wilsonwangdev
added a commit
that referenced
this pull request
Jun 1, 2026
) (#77) ## Summary Archives a 2026-05-08 investigation that had been sitting uncommitted in a feature worktree until today, and closes the loop with the fix that just shipped. [journal/2026-05-08-wide-viewport-whitespace.md](journal/2026-05-08-wide-viewport-whitespace.md) records: - **What happened** — capturing 1280×720 social-launch screenshots revealed ~35% horizontal whitespace because the site had exactly one breakpoint (`max-width: 640px`) and a fixed `--max-w: 52rem` - **Root cause** — review processes (Lighthouse, frontend-interaction-review skill) optimized for correctness, not visual density at wide viewports - **Resolution** — closed by #76, which added `@media (min-width: 1100px)` widening `--max-w` to `64rem`. The two alternative options (2-col layout, decorative frame) were rejected because they conflict with `rules/design-intent.md` §5 (wide viewports widen content, not whitespace or chrome) - **Prevention** — ROADMAP item to add a viewport-density check to the frontend-interaction-review skill's next revision [ROADMAP.md](ROADMAP.md) gains three matching `[x]` rows in **Now** for #74 / #75 / #76. [.gitignore](.gitignore) adds `assets/social/` — launch screenshots are local promotional artifacts. The first batch (May 8) is staying on disk but won't be committed. ## Why this matters The journal entry is exactly the "failures captured for agent self-evolution" use case in CLAUDE.md. Without committing it, the institutional memory of *why* PR #76 added that specific breakpoint at 1100px (and not, say, 1280px or 1440px) would have been lost. This PR makes the chain `1280px screenshot reveals issue → root cause → option list → chosen fix → rule §5` discoverable from a single file. ## Tested Lint-only / docs-only changes. No build impact. Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds build/screenshot.mjs and an
npm run screenshotcommand that captures the local dev server across four viewports and four representative pages — used as a manual review aid for visual changes.x-cardog-imagedesktopmobilePages:
/en/,/zh/,/en/concepts/harness-engineering/,/en/guides/skills-ecosystem/.Why
The homepage section order was reverted on 2026-05-14 specifically because the X-card crop showed only the prompt block — without the timeline, the hero gave the wrong first impression. That signal came from a one-off manual screenshot. Codifying it as a script means the next visual change can run the same check in one command.
This complements rules/design-intent.md (PR #74) — the rule states the intent, this script gives reviewers a concrete way to verify it.
Implementation choices
puppeteer-core+ system Chrome instead of fullpuppeteer. The full package downloads ~150 MB of bundled Chromium on every install;puppeteer-corereuses the user's installed Chrome / Chromium. Falls back toCHROME_PATHenv var if auto-detection fails.assets/screenshots/, gitignored. Screenshots are a local-only review artifact, not committed.huskystyle inpackage.json.Tested
npm installsucceeds;package-lock.jsonupdated forpuppeteer-coretransitive deps (lockfile diff is large but is entirely puppeteer's dependency closure — no typosquatting candidates spotted).npm run screenshotruns against a localnpm run devinstance and produces 16 PNGs underassets/screenshots/.Notes for reviewer
node_modules/puppeteer-core/**and its declared dependencies..claude/worktrees/is intentionally not added to.gitignorehere — that's agent-runtime state, better handled in a global gitignore.