developer-agent-skills 1.0.0

package/skills/git-branch-report/scripts/generate_branch_report.py

@@ -0,0 +1,226 @@
+#!/usr/bin/env python3
+"""Generate a Markdown report for one branch compared with a base branch."""
+
+from __future__ import annotations
+
+import argparse
+import re
+import subprocess
+from collections import defaultdict
+from datetime import datetime, timezone
+from pathlib import Path
+
+
+STATUS_LABELS = {
+    "A": "Added",
+    "C": "Copied",
+    "D": "Deleted",
+    "M": "Modified",
+    "R": "Renamed",
+    "T": "Type Changed",
+    "U": "Unmerged",
+    "X": "Unknown",
+}
+
+AREA_RULES = (
+    ("Documentation", ("docs/", "README", ".md")),
+    ("Configuration and build", ("package.json", "package-lock.json", "webpack", "babel", "jest", "config/", ".eslintrc", ".prettierrc", ".nvmrc")),
+    ("Routes and pages", ("overrides/app/routes", "overrides/app/pages/")),
+    ("Components", ("overrides/app/components/",)),
+    ("Hooks and data access", ("overrides/app/hooks/", "commerce-sdk-react", "useCustom")),
+    ("Checkout and cart", ("checkout", "cart", "basket", "payment", "paypal", "applepay", "amazon")),
+    ("Product and catalog", ("product", "plp", "pdp", "category", "algolia")),
+    ("Account and auth", ("account", "login", "registration", "password", "wishlist")),
+    ("Integrations", ("braintree", "amazon", "algolia", "stylitics", "powerreviews", "marketing", "agentforce", "spectrum", "osano")),
+    ("Tests", (".test.", ".spec.", "tests/")),
+    ("Translations and assets", ("translations/", "assets/", ".svg", ".woff", ".png", ".jpg", ".webp")),
+)
+
+
+def run_git(repo: Path, args: list[str], check: bool = True) -> str:
+    result = subprocess.run(
+        ["git", *args],
+        cwd=repo,
+        text=True,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        check=False,
+    )
+    if check and result.returncode != 0:
+        message = result.stderr.strip() or result.stdout.strip()
+        raise SystemExit(f"git {' '.join(args)} failed: {message}")
+    return result.stdout.strip()
+
+
+def resolve_ref(repo: Path, ref: str) -> str:
+    candidates = [ref]
+    if not ref.startswith("origin/"):
+        candidates.append(f"origin/{ref}")
+    for candidate in candidates:
+        result = subprocess.run(
+            ["git", "rev-parse", "--verify", f"{candidate}^{{commit}}"],
+            cwd=repo,
+            text=True,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            check=False,
+        )
+        if result.returncode == 0:
+            return candidate
+    raise SystemExit(f"Branch or ref not found: {ref}")
+
+
+def safe_name(branch: str) -> str:
+    cleaned = re.sub(r"[^A-Za-z0-9._-]+", "-", branch).strip("-")
+    return cleaned or "branch"
+
+
+def parse_name_status(raw: str) -> dict[str, list[str]]:
+    grouped: dict[str, list[str]] = defaultdict(list)
+    for line in raw.splitlines():
+        if not line.strip():
+            continue
+        parts = line.split("\t")
+        status = parts[0]
+        label_key = status[0]
+        if label_key == "R" and len(parts) >= 3:
+            path = f"{parts[1]} -> {parts[2]}"
+        else:
+            path = parts[-1]
+        grouped[label_key].append(path)
+    return dict(sorted(grouped.items()))
+
+
+def infer_areas(files: list[str], commits: str) -> list[str]:
+    haystack = "\n".join(files) + "\n" + commits
+    lower = haystack.lower()
+    summaries: list[str] = []
+    for area, needles in AREA_RULES:
+        matches = [needle for needle in needles if needle.lower() in lower]
+        if not matches:
+            continue
+        examples = [path for path in files if any(needle.lower() in path.lower() for needle in needles)]
+        example_text = ""
+        if examples:
+            sample = ", ".join(examples[:4])
+            more = f" and {len(examples) - 4} more" if len(examples) > 4 else ""
+            example_text = f" Touched: {sample}{more}."
+        summaries.append(f"- {area}: changes are indicated by matching paths or commit messages.{example_text}")
+    if summaries:
+        return summaries
+    return ["- General code changes: inspect the changed files and commits for implementation details."]
+
+
+def render_report(
+    repo: Path,
+    branch_input: str,
+    branch_ref: str,
+    base_ref: str,
+    merge_base: str,
+    ahead: str,
+    behind: str,
+    commits: str,
+    grouped_files: dict[str, list[str]],
+    diffstat: str,
+) -> str:
+    generated = datetime.now(timezone.utc).strftime("%Y-%m-%d %H:%M:%S UTC")
+    all_files = [path for paths in grouped_files.values() for path in paths]
+    test_files = [path for path in all_files if ".test." in path or ".spec." in path or path.startswith("tests/")]
+
+    lines: list[str] = [
+        f"# Branch Change Report: `{branch_input}`",
+        "",
+        "## Metadata",
+        "",
+        f"- Branch: `{branch_ref}`",
+        f"- Base: `{base_ref}`",
+        f"- Merge base: `{merge_base}`",
+        f"- Generated: {generated}",
+        f"- Ahead of base: {ahead} commit(s)",
+        f"- Behind base: {behind} commit(s)",
+        "",
+        "## Unique Commits",
+        "",
+    ]
+    if commits:
+        lines.extend(commits.splitlines())
+    else:
+        lines.append("- No commits unique to this branch.")
+
+    lines.extend(["", "## Changed Files", ""])
+    if grouped_files:
+        for status, files in grouped_files.items():
+            label = STATUS_LABELS.get(status, status)
+            lines.extend([f"### {label}", ""])
+            for path in files:
+                lines.append(f"- `{path}`")
+            lines.append("")
+    else:
+        lines.append("- No changed files found.")
+        lines.append("")
+
+    lines.extend(["## Diffstat", ""])
+    if diffstat:
+        lines.extend(["```text", diffstat, "```"])
+    else:
+        lines.append("- No diffstat available.")
+
+    lines.extend(["", "## Impact Summary", ""])
+    lines.extend(infer_areas(all_files, commits))
+
+    lines.extend(["", "## Testing Notes", ""])
+    if test_files:
+        lines.append("Test files touched in this branch:")
+        lines.append("")
+        for path in test_files:
+            lines.append(f"- `{path}`")
+    else:
+        lines.append("- No test files were changed in this branch diff.")
+    lines.append("- This report generator does not run tests; runtime verification is not included.")
+
+    lines.extend(["", "## Verification Gaps", ""])
+    lines.append("- Review the changed source files for business behavior before treating this report as release documentation.")
+    lines.append("- Full patch output is intentionally omitted by default.")
+    lines.append("")
+    return "\n".join(lines)
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--branch", required=True, help="Branch or ref to report on.")
+    parser.add_argument("--base", default="origin/main", help="Base branch or ref. Defaults to origin/main.")
+    parser.add_argument("--output-dir", default="docs/branch-change-reports", help="Output directory for the report.")
+    parser.add_argument("--repo", default=".", help="Repository root. Defaults to current directory.")
+    args = parser.parse_args()
+
+    repo = Path(args.repo).resolve()
+    branch_ref = resolve_ref(repo, args.branch)
+    base_ref = resolve_ref(repo, args.base)
+    merge_base = run_git(repo, ["merge-base", base_ref, branch_ref])
+    behind, ahead = run_git(repo, ["rev-list", "--left-right", "--count", f"{base_ref}...{branch_ref}"]).split()
+    commits = run_git(repo, ["log", "--pretty=format:- `%h` %s", f"{base_ref}..{branch_ref}"], check=False)
+    name_status = run_git(repo, ["diff", "--name-status", f"{base_ref}...{branch_ref}"], check=False)
+    diffstat = run_git(repo, ["diff", "--stat", f"{base_ref}...{branch_ref}"], check=False)
+
+    output_dir = repo / args.output_dir
+    output_dir.mkdir(parents=True, exist_ok=True)
+    output_path = output_dir / f"{safe_name(args.branch)}.md"
+    report = render_report(
+        repo,
+        args.branch,
+        branch_ref,
+        base_ref,
+        merge_base,
+        ahead,
+        behind,
+        commits,
+        parse_name_status(name_status),
+        diffstat,
+    )
+    output_path.write_text(report, encoding="utf-8")
+    print(output_path)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/skills/project-docs-sync/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: project-docs-sync
+description: Sync whole-project documentation with the current codebase. Use when asked to audit or refresh project docs, regenerate comprehensive docs, align docs with source code, document architecture, routes, APIs, environment variables, testing, deployment, or make stale documentation source-backed and current.
+---
+
+# Project Docs Sync
+
+Use this skill when the task is to synchronize project documentation with the actual codebase.
+
+## Core Rules
+
+- Inspect the repository before editing docs. Prefer `rg`, `find`, `git status`, package manifests, config files, routes, tests, and existing docs.
+- Update existing documentation instead of duplicating it.
+- Document only source-backed behavior. If behavior is inferred or externally owned, label it clearly as an assumption or external dependency.
+- Preserve the repo's documentation style, file names, and cross-linking conventions.
+- Keep source references concrete enough for maintainers to verify.
+- Do not change runtime code unless the user explicitly asks for code changes.
+
+## Recommended Workflow
+
+1. Check scope.
+   - Identify whether the user wants all docs refreshed or a specific documentation area.
+   - Run `git status --short` and avoid overwriting unrelated user changes.
+
+2. Gather repo facts.
+   - Run `python3 scripts/audit_project_docs.py` from the repo root (or skill directory).
+   - Supplement the audit with targeted reads of relevant files.
+   - For web apps, inspect routes, SSR/server handlers, package scripts, config files, env var references, tests, and integration points.
+
+3. Map source to documentation.
+   - Architecture docs should come from app entrypoints, routes, server handlers, providers, state/data hooks, and config.
+   - API docs should include local server endpoints, generated or framework routes, and external/custom API calls used by the app.
+   - Environment docs should include env vars found in source, package scripts, deployment config, and `.env*` files when present.
+   - Database docs should describe actual persistence. If there is no local database, document the external data stores and domain entities instead of inventing tables.
+
+4. Edit docs.
+   - Keep sections substantial but maintainable.
+   - Add Mermaid diagrams when they clarify architecture, flows, lifecycle, or state transitions.
+   - Cross-link related docs.
+   - Mark unsupported, absent, or unclear behavior explicitly.
+
+5. Verify.
+   - Confirm requested docs exist and contain real content.
+   - Check Markdown links/headings where practical.
+   - Run `git diff -- docs` and ensure changes are documentation-only unless otherwise requested.
+   - Report verification gaps honestly.
+
+## Completion Criteria
+
+- Docs reflect the current source tree and config.
+- Missing or unclear behavior is labeled rather than assumed.
+- New docs are discoverable from the docs index or README.
+- The final response lists edited docs and verification performed.

package/skills/project-docs-sync/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "Project Docs Sync"
+  short_description: "Sync project docs with source code"
+  default_prompt: "Use $project-docs-sync to audit this repository and update the project documentation from source-backed behavior."
+
+policy:
+  allow_implicit_invocation: true

package/skills/project-docs-sync/scripts/audit_project_docs.py

@@ -0,0 +1,169 @@
+#!/usr/bin/env python3
+"""Print source-backed facts useful for syncing project documentation."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+from pathlib import Path
+
+
+ENV_RE = re.compile(r"process\.env\.([A-Z0-9_]+)")
+ROUTE_RE = re.compile(r"path:\s*['\"]([^'\"]+)['\"]")
+API_NAME_RE = re.compile(r"apiName:\s*['\"]([^'\"]+)['\"]")
+ENDPOINT_RE = re.compile(r"endpointPath:\s*['\"]([^'\"]+)['\"]")
+METHOD_RE = re.compile(r"method:\s*['\"]([^'\"]+)['\"]")
+
+
+def iter_files(root: Path, patterns: tuple[str, ...]) -> list[Path]:
+    files: list[Path] = []
+    for pattern in patterns:
+        files.extend(root.glob(pattern))
+    return sorted({path for path in files if path.is_file()})
+
+
+def read_text(path: Path) -> str:
+    try:
+        return path.read_text(encoding="utf-8")
+    except UnicodeDecodeError:
+        return path.read_text(encoding="utf-8", errors="ignore")
+
+
+def rel(root: Path, path: Path) -> str:
+    try:
+        return str(path.relative_to(root))
+    except ValueError:
+        return str(path)
+
+
+def print_section(title: str) -> None:
+    print(f"\n## {title}")
+
+
+def package_summary(root: Path) -> None:
+    print_section("Package")
+    package_path = root / "package.json"
+    if not package_path.exists():
+        print("- package.json: not found")
+        return
+
+    data = json.loads(read_text(package_path))
+    print(f"- name: {data.get('name', 'unknown')}")
+    print(f"- version: {data.get('version', 'unknown')}")
+    print(f"- engines: {json.dumps(data.get('engines', {}), sort_keys=True)}")
+    scripts = data.get("scripts", {})
+    print("- scripts:")
+    for name in sorted(scripts):
+        print(f"  - {name}: {scripts[name]}")
+    print(f"- dependencies: {len(data.get('dependencies', {}))}")
+    print(f"- devDependencies: {len(data.get('devDependencies', {}))}")
+
+
+def config_summary(root: Path) -> None:
+    print_section("Config Files")
+    files = iter_files(root, ("config/*.js", "*.config.js", ".*rc", ".nvmrc", ".prettierrc*", ".eslintrc*"))
+    if not files:
+        print("- none found")
+        return
+    for path in files:
+        print(f"- {rel(root, path)}")
+
+
+def docs_summary(root: Path) -> None:
+    print_section("Existing Docs")
+    files = iter_files(root, ("docs/**/*.md", "*.md", "*.MD"))
+    if not files:
+        print("- none found")
+        return
+    for path in files:
+        print(f"- {rel(root, path)}")
+
+
+def env_summary(root: Path) -> None:
+    print_section("Environment Variables")
+    found: dict[str, set[str]] = {}
+    files = iter_files(root, ("**/*.js", "**/*.jsx", "**/*.ts", "**/*.tsx", "package.json", ".env*"))
+    for path in files:
+        if "node_modules" in path.parts or "build" in path.parts:
+            continue
+        for match in ENV_RE.finditer(read_text(path)):
+            found.setdefault(match.group(1), set()).add(rel(root, path))
+    if not found:
+        print("- none found")
+        return
+    for name in sorted(found):
+        print(f"- {name}: {', '.join(sorted(found[name]))}")
+
+
+def routes_summary(root: Path) -> None:
+    print_section("Routes")
+    route_files = iter_files(root, ("**/routes.jsx", "**/routes.js", "**/routes.tsx", "**/routes.ts"))
+    if not route_files:
+        print("- no route files found")
+        return
+    for path in route_files:
+        if "node_modules" in path.parts:
+            continue
+        routes = ROUTE_RE.findall(read_text(path))
+        print(f"- {rel(root, path)}")
+        for route in routes:
+            print(f"  - {route}")
+
+
+def custom_api_summary(root: Path) -> None:
+    print_section("Custom API Usages")
+    files = iter_files(root, ("**/*.js", "**/*.jsx", "**/*.ts", "**/*.tsx"))
+    rows: list[tuple[str, str, str, str]] = []
+    for path in files:
+        if "node_modules" in path.parts or "build" in path.parts or "static" in path.parts:
+            continue
+        text = read_text(path)
+        api_names = API_NAME_RE.findall(text)
+        endpoints = ENDPOINT_RE.findall(text)
+        methods = METHOD_RE.findall(text)
+        if not api_names and not endpoints:
+            continue
+        count = max(len(api_names), len(endpoints), 1)
+        for index in range(count):
+            api_name = api_names[index] if index < len(api_names) else "unknown"
+            endpoint = endpoints[index] if index < len(endpoints) else "unknown"
+            method = methods[index] if index < len(methods) else "unknown"
+            rows.append((api_name, endpoint, method, rel(root, path)))
+    if not rows:
+        print("- none found")
+        return
+    for api_name, endpoint, method, source in sorted(rows):
+        print(f"- {api_name}/{endpoint} [{method}] in {source}")
+
+
+def tests_summary(root: Path) -> None:
+    print_section("Tests")
+    files = iter_files(root, ("**/*.test.js", "**/*.test.jsx", "**/*.spec.js", "**/*.spec.jsx", "tests/**/*"))
+    files = [path for path in files if "node_modules" not in path.parts and "build" not in path.parts]
+    if not files:
+        print("- none found")
+        return
+    for path in files:
+        print(f"- {rel(root, path)}")
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--repo", default=".", help="Repository root. Defaults to current directory.")
+    args = parser.parse_args()
+
+    root = Path(args.repo).resolve()
+    print(f"# Project Documentation Audit: {root}")
+    package_summary(root)
+    config_summary(root)
+    docs_summary(root)
+    env_summary(root)
+    routes_summary(root)
+    custom_api_summary(root)
+    tests_summary(root)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/skills/ui-visual-feedback-loop/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: ui-visual-feedback-loop
+description: Implement and verify frontend UIs from screenshots, mockups, design images, or Figma references using an iterative visual feedback loop. Supports Chrome DevTools MCP browser inspection as well as automated Playwright capture and visual comparison scripts. Use when building or refining a UI component/page from visual references, taking live screenshots, comparing against the reference, and iterating until high visual parity is achieved.
+---
+
+# UI Visual Feedback Loop
+
+Use this skill when implementing or refining a UI from a reference image, mockup, screenshot, or design URL, and iteratively verifying the live rendering against the reference.
+
+## Primary Workflows
+
+Choose the workflow suited to your environment:
+- **Workflow A: Chrome DevTools MCP** (Interactive live inspection via Chrome DevTools MCP tools).
+- **Workflow B: Playwright Automated Scripts** (Automated script-based screenshot capture and visual mismatch diffing).
+
+---
+
+## Reference Intake
+
+1. **Inspect Reference**:
+   - If the input is a Figma link, inspect the frame/node in Chrome using the `figma` skill.
+   - Inspect the target layout regions, viewport width/height, colors, spacing rhythm, typography, buttons, forms, and responsive breakpoints.
+2. **Setup Local Surface**:
+   - Identify or start the local web application dev server.
+   - Ensure the page renders deterministically (use seed mock data if needed).
+
+---
+
+## Workflow A: Chrome DevTools MCP (Recommended for Interactive Agents)
+
+1. **Launch & Connect**:
+   - Start the local dev server (e.g. `http://localhost:3000`).
+   - Open target page with Chrome DevTools MCP tools (`open_url` / `navigate_to`).
+   - Set browser dimensions matching reference (`resize_page` or `emulate`).
+
+2. **First Pass Implementation**:
+   - Match structure, layout hierarchy, and design tokens (colors, fonts, padding/margins) before polishing micro-details.
+
+3. **Iterative Verification Loop**:
+   - Take live screenshot (`take_screenshot`).
+   - Take accessibility/DOM snapshot (`take_snapshot`) for layout structure checks.
+   - Use `evaluate_script` to inspect computed styles, element bounding boxes, font sizes, and scroll overflows.
+   - Check `list_console_messages` or `list_network_requests` if assets or data fail to render.
+   - Dismiss dialogs, popups, or tooltips before capturing screenshots.
+
+4. **Compare & Refine**:
+   - Compare live screenshot with reference image.
+   - Apply targeted code fixes (alignment, font weight, border-radius, container widths, flex/grid rules).
+   - Re-capture fresh Chrome DevTools screenshot after every edit cycle.
+
+---
+
+## Workflow B: Playwright Automated Scripts (Scripted Visual Diffing)
+
+1. **Prerequisites**:
+   - Ensure Playwright helper script dependencies are present:
+     ```bash
+     npm install -D playwright sharp pixelmatch pngjs
+     ```
+
+2. **Run Orchestration Loop**:
+   ```bash
+   bash scripts/ui_loop.sh \
+     --reference path/to/reference.png \
+     --url http://127.0.0.1:3000 \
+     --start "npm run dev -- --host 127.0.0.1 --port 3000" \
+     --max-loops 5
+   ```
+
+3. **Manual Capture & Diff Step**:
+   ```bash
+   node scripts/capture.js --url http://127.0.0.1:3000 --out artifacts/latest.png
+   node scripts/compare.js --reference path/to/reference.png --candidate artifacts/latest.png --diff artifacts/diff.png --json artifacts/report.json
+   ```
+
+4. **Interpret Visual Diff Output**:
+   - Review `artifacts/report.json` mismatch metrics and `artifacts/diff.png`.
+   - Update code to fix visual discrepancies highlighted in diff report.
+
+---
+
+## General Operating Rules
+
+- Default to 3 to 5 iteration loops. Stop when visual gaps are minor or blocked by missing font assets.
+- Do not mark tasks complete without fetching a final post-edit live screenshot.
+- State clearly:
+  1. What the reference shows
+  2. What code changes were applied
+  3. What the latest screenshot/diff confirms
+  4. What remaining discrepancies exist (if any)

package/skills/ui-visual-feedback-loop/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "ui-visual-feedback-support",
+  "private": true,
+  "version": "1.0.0",
+  "description": "Support scripts for the ui-visual-feedback-loop Agent Skill",
+  "scripts": {
+    "capture": "node scripts/capture.js",
+    "compare": "node scripts/compare.js",
+    "ui:loop": "bash scripts/ui_loop.sh"
+  },
+  "devDependencies": {
+    "pixelmatch": "^6.0.0",
+    "playwright": "^1.53.0",
+    "pngjs": "^7.0.0",
+    "sharp": "^0.34.0"
+  }
+}

package/skills/ui-visual-feedback-loop/references/notes.md

@@ -0,0 +1,17 @@
+# Notes for UI Visual Feedback Loop
+
+## Features
+- Works with live Chrome DevTools MCP tools for interactive agent feedback.
+- Uses Playwright for headless scripted automated captures.
+- Produces image diffs (`artifacts/diff.png`) and structured metrics (`artifacts/report.json`).
+- Standardizes visual verification across web projects.
+
+## Optional Extensions
+- Add custom viewport presets (e.g. mobile 375x812, tablet 768x1024, desktop 1440x900).
+- Add screenshot element-cropping for component-isolated diffing.
+
+## Support npm packages
+```bash
+npm install -D playwright sharp pixelmatch pngjs
+npx playwright install chromium
+```

package/skills/ui-visual-feedback-loop/scripts/capture.js

@@ -0,0 +1,69 @@
+#!/usr/bin/env node
+const fs = require('fs');
+const path = require('path');
+const { chromium } = require('playwright');
+const sharp = require('sharp');
+
+function arg(name, fallback = undefined) {
+  const idx = process.argv.indexOf(name);
+  return idx >= 0 ? process.argv[idx + 1] : fallback;
+}
+
+async function inferViewportFromReference(referencePath) {
+  if (!referencePath || !fs.existsSync(referencePath)) return null;
+  const meta = await sharp(referencePath).metadata();
+  if (!meta.width || !meta.height) return null;
+  return { width: meta.width, height: meta.height };
+}
+
+(async () => {
+  const url = arg('--url');
+  const out = arg('--out', 'artifacts/latest.png');
+  const waitMs = Number(arg('--wait-ms', '1500'));
+  const reference = arg('--reference');
+  let width = Number(arg('--viewport-width', '0'));
+  let height = Number(arg('--viewport-height', '0'));
+  const fullPage = !process.argv.includes('--no-full-page');
+
+  if (!url) {
+    console.error('Missing --url');
+    process.exit(1);
+  }
+
+  if (!width || !height) {
+    const inferred = await inferViewportFromReference(reference);
+    if (inferred) {
+      width = width || inferred.width;
+      height = height || inferred.height;
+    }
+  }
+
+  width = width || 1440;
+  height = height || 1024;
+
+  fs.mkdirSync(path.dirname(out), { recursive: true });
+
+  const browser = await chromium.launch({ headless: true });
+  const page = await browser.newPage({ viewport: { width, height }, deviceScaleFactor: 1 });
+
+  await page.goto(url, { waitUntil: 'networkidle', timeout: 120000 });
+  await page.addStyleTag({
+    content: `
+      *, *::before, *::after {
+        animation-duration: 0s !important;
+        animation-delay: 0s !important;
+        transition-duration: 0s !important;
+        caret-color: transparent !important;
+      }
+      html { scroll-behavior: auto !important; }
+    `,
+  });
+  await page.waitForTimeout(waitMs);
+  await page.screenshot({ path: out, fullPage });
+  await browser.close();
+
+  console.log(JSON.stringify({ ok: true, out, viewport: { width, height }, fullPage }, null, 2));
+})().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});