Eng UI Screenshot

Compozy UI Screenshot

Capture deterministic PNG evidence through the bundled CDP helper. The helper owns load/font settling and viewport emulation; the procedure owns target resolution, evidence checks, and process cleanup.

When a task or spec names a trusted visual reference, read .agents/skills/eng/eng-ui-screenshot/references/visual-contract.md before the first capture or implementation; reuse its resolved contract while it remains current. Its evidence bundle, not an implementation-only screenshot, is the completion contract.

Procedure

Step 1: Prepare an Owned Workdir

1. Start at the repository root and record it: REPO_ROOT="$(pwd)".
2. Run the bootstrap helper with a unique directory: WORKDIR="$(bash "$REPO_ROOT/.agents/skills/eng/eng-ui-screenshot/scripts/setup-workdir.sh" "$(mktemp -d /tmp/eng-ui-screenshot.XXXXXX)")"
3. The bootstrap copies the current capture helpers into WORKDIR so Bun resolves their dependencies from the isolated package. Keep REPO_ROOT for references and server packages; execute the materialized helpers from WORKDIR.

Done when: one unique workdir exists, its dependencies are installed, and every helper path resolves independently of the current directory.

Step 2: Establish Storybook Ownership

1. Skip this step when the capture set has no Storybook target. Otherwise read .agents/skills/eng/eng-ui-screenshot/references/storybook-urls.md in full.
2. Probe the required server (6006 for web, 6007 for packages/ui) and reuse it only when its index.json is healthy.
3. If a server is absent, start the matching bun run storybook from its package, redirect logs into WORKDIR, and immediately record its PID as WORKDIR/web-storybook.pid or WORKDIR/ui-storybook.pid.
4. Poll the health endpoint until it returns 200 or the owned process exits; on exit, fail with its log.

Done when: every required Storybook is healthy and each server started by this run has exactly one PID file; pre-existing servers have none.

Step 3: Resolve Story IDs

1. Skip this step for arbitrary non-Storybook URLs.
2. From WORKDIR, run the materialized read-only helper: bun run "$WORKDIR/list-stories.mjs" http://localhost:6006 [--filter <substring>]
3. Confirm every requested story id appears exactly in the output; never infer an id from the app URL.

Done when: every Storybook target is backed by a real index.json entry.

Step 4: Capture Through CDP

1. From WORKDIR, run the materialized mutating helper: bun run "$WORKDIR/cap.mjs" --out <output-dir> --width <W> --height <H> --wait <ms> --shot <name> <url> [...]
2. Use 1440 × 900 for routes, 1680 × 1050 for wide breakpoints, 1100 × 700 for primitives, and 320 × 800 for collapsed navigation. Read .agents/skills/eng/eng-ui-screenshot/references/cdp-flow.md in full before changing capture mechanics or defaults.
3. Use 2200 ms as the current route settle floor; increase to 4000 ms only when captured evidence shows fallback fonts.
4. Treat a non-zero helper exit as a failed capture set. A sub-20 KB PNG is also suspicious and requires inspection even when capture succeeded.

Done when: every requested target prints saved, the helper exits zero, and every expected PNG exists with a plausible size.

Step 5: Capture a Proposal Mock When Requested

1. Only for proposal-side state not reachable from the canonical HTML, read .agents/skills/eng/eng-ui-screenshot/references/proposal-mock-capture.md in full and follow its clone-and-patch branch.
2. Start the static server as an owned process and record its PID in WORKDIR/proposal-server.pid.
3. Capture with the same WORKDIR/cap.mjs, then remove the throwaway wrapper without editing the canonical proposal.