@piagent/platform 1.40.0 → 1.41.0

package/packages/piagent-core/skills/fe-change-report/SKILL.md

@@ -0,0 +1,175 @@
+---
+name: fe-change-report
+description: "Use when a front-end task asks for a change report: before/after screenshots with numbered red frames, headless E2E, and what changed in business rules, logic, and UI/UX, delivered as one HTML file the dashboard shows."
+---
+
+# Front-end change report
+
+The report answers four questions for the person who asked for the change:
+what the business now does differently, what logic changed, what the screen
+looked like before and after, and whether the checks passed. Everything in it
+must come from something you ran or read in this task. Never describe a screen
+you did not capture or a check you did not run.
+
+The scripts are in `scripts/` next to this file; resolve that path against
+this skill's directory. They use the Playwright installed in the project under
+test (`--project <dir>` when you run them from elsewhere), run Chromium
+headless, and add no dependency. If the project has Playwright but no browser,
+`npx playwright install chromium` downloads one: ask the member first.
+
+## 1. Scope
+
+- Read the diff against the base (`git diff <base>...HEAD` plus uncommitted
+  work) and list the routes and states the change can show: pages, dialogs,
+  empty and error states, desktop and mobile. A change with no visible effect
+  gets a report without screenshots; say so in the summary.
+- Pick a slug such as `2026-10-24-listing-seo` and work in
+  `reports/fe-change/<slug>/` at the project root. Unless the project already
+  tracks reports, add `reports/fe-change/` to `.git/info/exclude` so the
+  report never lands in a commit by accident.
+- Write `reports/fe-change/<slug>/shots/shots.json`. Everything the capture
+  needs or produces stays in `shots/`, so the dashboard lists only the report:
+
+```json
+{
+  "viewports": [{ "name": "desktop", "width": 1440, "height": 1000 }, { "name": "mobile", "width": 390, "height": 844 }],
+  "mask": ["[data-testid=clock]"],
+  "pages": [
+    { "key": "listings", "title": "Listings page", "path": "/listings", "clipHeight": 900 },
+    { "key": "detail", "title": "Listing detail", "path": "/listings/demo", "scroll": true },
+    { "key": "market", "title": "Market section", "path": "/", "selector": "[data-testid=market-data-section]" }
+  ]
+}
+```
+
+Page options:
+
+| Option | Effect |
+|---|---|
+| `fullPage` | Whole page, default `true` |
+| `clipHeight` | Only the top N pixels |
+| `selector` | One element only |
+| `waitFor` | A selector that must appear before the shot |
+| `scroll` | Scroll through the page first so lazy sections render |
+| `settleMs` | Extra wait before the shot, default 600 |
+| `mask` | Selectors painted grey on both sides |
+| `viewports` | Subset of viewport names for this page |
+
+Top-level `mask`, `locale`, `colorScheme`, `ignoreHTTPSErrors`, and
+`storageState` (a Playwright login state file, path relative to where you run
+the script) apply to every page. A viewport narrower than 768 px is emulated
+as a touch phone unless it sets `isMobile`. Keys and viewport names are
+lowercase letters, digits and dashes.
+
+Mask anything that changes on its own (clocks, relative times, random ids,
+carousels, ads). Otherwise it shows up as a change you did not make.
+
+## 2. Run both sides on the same data
+
+- **Before:** `git worktree add <tmp>/fe-report-base <base>` and install there
+  the way the project installs (a lockfile install, never an upgrade).
+- **After:** the current working tree.
+- Start each one on its own free port in the background, with output going to
+  a log file. Wait until each URL answers before capturing. Prefer the
+  project's own production-like E2E setup (built app plus mock API or seed
+  data) so both sides show the same records. Screenshots of two different
+  data sets are not a comparison. If live data was unavoidable, say so in
+  `lede`.
+
+Run the scripts from `reports/fe-change/<slug>/`. Below, `scripts/` stands for
+the absolute path of this skill's `scripts/` folder; `shots/` and the report
+files are relative to the report folder.
+
+```bash
+node scripts/capture.mjs --config shots/shots.json --side before --base-url http://127.0.0.1:<before-port> --out shots
+node scripts/capture.mjs --config shots/shots.json --side after  --base-url http://127.0.0.1:<after-port> --out shots
+node scripts/diff-regions.mjs --dir shots
+```
+
+`capture.mjs` exits non-zero and names the shot when a page fails to load, a
+`waitFor` never appears, or a screenshot is over the 8 MB the dashboard
+shows. Fix the cause and capture again; do not report around a missing shot.
+
+`diff-regions.mjs` writes two things:
+- `shots/regions.json`: proposed boxes per page and viewport, in image pixels.
+- `shots/diff-<page>-<viewport>.png`: the new screenshot with changed pixels in red.
+
+It also names any page that exists on one side only.
+
+**Look before you frame.** Open the before, after and diff images and decide
+the boxes yourself:
+- Merge boxes that belong to one change.
+- Drop boxes caused only by content moving down. When a new block pushes the
+  rest of the page down, frame only the new block.
+- Use separate `before`/`after` coordinates when the same element moved.
+- Write one plain sentence per box saying what changed for the user.
+
+## 3. Verify
+
+Run the project's own checks after the last code change, headless and in the
+background with output to a log file: typecheck, lint, unit tests, and the
+full E2E suite. Never use `--headed`, `--ui`, `--debug` or `PWDEBUG`.
+- Record the exact command, the counts, and the duration.
+- A test that also fails on the base worktree is a baseline failure: say so in
+  `detail`, and do not call the check passed.
+- A check you could not run is `skipped` with the reason.
+
+## 4. Write report.json and build
+
+```json
+{
+  "kind": "fe-change-report",
+  "title": "Listing SEO: before and after",
+  "lede": "Production build with E2E mock data, 1440 px.",
+  "base": "main@ecc3944f", "head": "feature/seo@1a2b3c4d", "lang": "vi", "viewports": ["desktop", "mobile"],
+  "summary": ["One line per user-visible outcome"],
+  "business": [{ "title": "Listing heading", "before": "3 listings · Buy", "after": "Homes for sale in {ward}", "impact": "Area keyword in H1" }],
+  "logic": [{ "title": "Same-area links", "before": "None", "after": "Up to 6 from the same ward, then province", "files": ["src/features/listings/logic/index.ts"] }],
+  "sections": [{ "key": "listings", "title": "Listings page", "note": "Optional context", "viewport": "desktop",
+    "boxes": [{ "x": 70, "y": 92, "w": 520, "h": 56, "text": "New heading and live count" }],
+    "otherBoxes": { "mobile": [{ "x": 10, "y": 98, "w": 268, "h": 44 }] } }],
+  "e2e": { "command": "npm run test:e2e", "result": "passed", "passed": 214, "failed": 0, "skipped": 3, "duration": "6m12s" },
+  "checks": [{ "name": "typecheck", "result": "passed" }, { "name": "unit", "result": "failed", "detail": "1 baseline failure, also on main" }],
+  "files": [{ "path": "src/app/sitemap.ts", "kind": "logic", "summary": "Listing sitemap" }],
+  "risks": ["What was not verified and why"]
+}
+```
+
+- `kind` must be `fe-change-report`: it is how the dashboard knows to draw
+  the file as a report.
+- `viewports` lists the sizes captured, with the primary one first.
+- `business` is what a user or the business sees differently.
+- `logic` is the rule or data flow behind it.
+- `files` covers every changed file with a short reason.
+- `result` is `passed`, `failed` or `skipped`.
+- A box uses the same coordinates on both images unless it has its own
+  `before` or `after` box (`{ "x", "y", "w", "h" }`).
+- `lang` is `vi` (default) or `en`.
+
+Then build:
+
+```bash
+node scripts/build-report.mjs --spec report.json --dir shots --out report.html
+```
+
+The builder refuses a box outside its image or a key that is not a plain
+name, and says which section. `report.html` is self-contained, has no
+scripts, and opens in any browser, so it can be sent to someone. Keep it under
+15 MB: clip long pages with `clipHeight` or `selector`.
+
+Read the result before you report it:
+- open `report.html`, or screenshot it with Playwright;
+- check that every frame sits on the change it describes, on both sides.
+
+## 5. Finish
+
+1. Stop both servers, remove the base worktree
+   (`git worktree remove <tmp>/fe-report-base`), and leave
+   `reports/fe-change/<slug>/` in place.
+2. Reply with:
+   - the report path;
+   - where to see it: the Piagent dashboard draws it under Documents from
+     `reports/fe-change/<slug>/report.json`, with a full-screen view;
+   - one line per check;
+   - anything not verified.
+3. Do not commit the report unless asked.

package/packages/piagent-core/skills/fe-change-report/scripts/build-report.mjs

@@ -0,0 +1,183 @@
+#!/usr/bin/env node
+// Builds one self-contained HTML report (no scripts, images embedded once) from
+// report.json and the screenshots captured by capture.mjs.
+//   node build-report.mjs --spec report.json --dir <shots dir> --out report.html
+import fs from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { parseArgs, pngSize, SAFE_NAME } from "./capture.mjs";
+
+export const REPORT_MARKER = "piagent-fe-change-report-v1";
+
+const TEXT = {
+  vi: {
+    summary: "Tóm tắt", business: "Business thay đổi", logic: "Logic thay đổi", ui: "UI/UX cũ và mới", tests: "Kiểm thử",
+    files: "File đã đổi", risks: "Rủi ro và việc còn lại", item: "Mục", before: "Cũ", after: "Mới", impact: "Ảnh hưởng",
+    where: "File", zoom: "Phóng to theo số", other: "Khổ khác", pixels: "Pixel khác nhau (tô đỏ trên ảnh mới)",
+    check: "Kiểm tra", result: "Kết quả", detail: "Chi tiết", passed: "Đạt", failed: "Lỗi", skipped: "Bỏ qua",
+    generated: "Tạo lúc", missing: "Không có ảnh", e2e: "E2E", noChanges: "Không có thay đổi giao diện được ghi nhận."
+  },
+  en: {
+    summary: "Summary", business: "Business changes", logic: "Logic changes", ui: "UI/UX before and after", tests: "Verification",
+    files: "Changed files", risks: "Risks and follow-ups", item: "Item", before: "Before", after: "After", impact: "Impact",
+    where: "Files", zoom: "Zoom by number", other: "Other sizes", pixels: "Changed pixels (red on the new screenshot)",
+    check: "Check", result: "Result", detail: "Detail", passed: "Passed", failed: "Failed", skipped: "Skipped",
+    generated: "Generated", missing: "No screenshot", e2e: "E2E", noChanges: "No visual change was recorded."
+  }
+};
+
+const escape = (value) => String(value ?? "").replace(/[&<>"']/g, (character) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[character]);
+const percent = (value) => `${Number(value.toFixed(3))}%`;
+const list = (value) => (Array.isArray(value) ? value : value ? [value] : []);
+
+function checkBox(box, image, where) {
+  for (const key of ["x", "y", "w", "h"]) {
+    if (!Number.isFinite(box[key]) || box[key] < 0) throw new Error(`${where}: box.${key} must be a non-negative number`);
+  }
+  if (box.w === 0 || box.h === 0) throw new Error(`${where}: box must have a width and height`);
+  // Clamp rather than fail: a box drawn on the taller "after" page may run past a shorter "before" page.
+  const x = Math.min(box.x, image.width - 1), y = Math.min(box.y, image.height - 1);
+  return { x, y, w: Math.min(box.w, image.width - x), h: Math.min(box.h, image.height - y) };
+}
+
+class Images {
+  #dir; #classes = new Map(); rules = [];
+  constructor(dir) { this.#dir = dir; }
+  get(name) {
+    const file = path.join(this.#dir, `${name}.png`);
+    if (!fs.existsSync(file)) return undefined;
+    if (!this.#classes.has(name)) {
+      const bytes = fs.readFileSync(file), id = `i${this.#classes.size}`;
+      this.#classes.set(name, { id, ...pngSize(bytes) });
+      this.rules.push(`.${id}{background-image:url(data:image/png;base64,${bytes.toString("base64")})}`);
+    }
+    return this.#classes.get(name);
+  }
+}
+
+function shot(image, boxes, label, t) {
+  if (!image) return `<figure><figcaption>${escape(label)}</figcaption><p class="missing">${t.missing}</p></figure>`;
+  const frames = boxes.map(({ n, box }) => `<span class="box" style="left:${percent(box.x / image.width * 100)};top:${percent(box.y / image.height * 100)};width:${percent(box.w / image.width * 100)};height:${percent(box.h / image.height * 100)}"><b>${n}</b></span>`).join("");
+  return `<figure><figcaption>${escape(label)}</figcaption><div class="shot ${image.id}" role="img" aria-label="${escape(label)}" style="aspect-ratio:${image.width}/${image.height}">${frames}</div></figure>`;
+}
+
+function crop(image, box, label) {
+  if (!image) return "";
+  const size = image.width / box.w * 100;
+  const left = image.width === box.w ? 0 : box.x / (image.width - box.w) * 100;
+  const top = image.height === box.h ? 0 : box.y / (image.height - box.h) * 100;
+  // Past about 2.5x a screenshot only gets blurrier, so a small box stays small.
+  return `<div class="zoom"><span class="zl">${escape(label)}</span><div class="crop ${image.id}" style="max-width:${Math.round(box.w * 2.5)}px;aspect-ratio:${box.w}/${box.h};background-size:${percent(size)} auto;background-position:${percent(left)} ${percent(top)}"></div></div>`;
+}
+
+function sectionHtml(section, images, viewports, t) {
+  const viewport = section.viewport ?? viewports[0];
+  // Keys and viewport names become file names; anything else could name a file outside the shots folder.
+  for (const name of [section.key, viewport, ...Object.keys(section.otherBoxes ?? {})]) {
+    if (!SAFE_NAME.test(String(name))) throw new Error(`section key and viewport names must match ${SAFE_NAME}: ${name}`);
+  }
+  const before = images.get(`before-${section.key}-${viewport}`), after = images.get(`after-${section.key}-${viewport}`);
+  const boxes = list(section.boxes).map((box, index) => {
+    const n = box.n ?? index + 1, where = `section ${section.key} box ${n}`;
+    return {
+      n, text: box.text,
+      before: before && checkBox(box.before ?? box, before, where),
+      after: after && checkBox(box.after ?? box, after, where)
+    };
+  });
+  const pair = shot(before, boxes.map(({ n, before: box }) => ({ n, box })).filter(({ box }) => box), `${t.before} · ${viewport}`, t)
+    + shot(after, boxes.map(({ n, after: box }) => ({ n, box })).filter(({ box }) => box), `${t.after} · ${viewport}`, t);
+  const zooms = boxes.map((box) => `<div class="zrow"><p class="zt"><b class="num">${box.n}</b> ${escape(box.text)}</p><div class="pair">${box.before ? crop(before, box.before, t.before) : ""}${box.after ? crop(after, box.after, t.after) : ""}</div></div>`).join("");
+  const others = viewports.filter((name) => name !== viewport).map((name) => {
+    const oldShot = images.get(`before-${section.key}-${name}`), newShot = images.get(`after-${section.key}-${name}`);
+    if (!oldShot && !newShot) return "";
+    const otherBoxes = list(section.otherBoxes?.[name]).map((box, index) => ({ n: box.n ?? index + 1, box }));
+    const fit = (image) => otherBoxes.filter(() => image).map(({ n, box }) => ({ n, box: checkBox(box, image, `section ${section.key} ${name}`) }));
+    return `<details><summary>${t.other}: ${escape(name)}</summary><div class="pair narrow">${shot(oldShot, fit(oldShot), `${t.before} · ${name}`, t)}${shot(newShot, fit(newShot), `${t.after} · ${name}`, t)}</div></details>`;
+  }).join("");
+  const overlay = images.get(`diff-${section.key}-${viewport}`);
+  const pixels = overlay ? `<details><summary>${t.pixels}</summary><div class="shot ${overlay.id}" role="img" aria-label="${escape(t.pixels)}" style="aspect-ratio:${overlay.width}/${overlay.height}"></div></details>` : "";
+  return `<section class="card"><h3>${escape(section.title ?? section.key)}</h3>${section.note ? `<p class="note">${escape(section.note)}</p>` : ""}<div class="pair">${pair}</div>${zooms ? `<h4>${t.zoom}</h4>${zooms}` : ""}${others}${pixels}</section>`;
+}
+
+function table(headers, rows) {
+  if (!rows.length) return "";
+  return `<div class="scroll"><table><thead><tr>${headers.map((header) => `<th>${escape(header)}</th>`).join("")}</tr></thead><tbody>${rows.map((row) => `<tr>${row.map((cell) => `<td>${cell}</td>`).join("")}</tr>`).join("")}</tbody></table></div>`;
+}
+
+function badge(result, t) {
+  const kind = ["passed", "failed", "skipped"].includes(result) ? result : "skipped";
+  return `<span class="badge ${kind}">${escape(t[kind])}</span>`;
+}
+
+export const REPORT_KIND = "fe-change-report";
+
+export function buildReport({ spec, dir }) {
+  // The dashboard draws a report.json only when it says what it is.
+  if (spec.kind !== REPORT_KIND) throw new Error(`report.json must have "kind": "${REPORT_KIND}"`);
+  const t = TEXT[spec.lang === "en" ? "en" : "vi"];
+  const meta = fs.existsSync(path.join(dir, "meta.json")) ? JSON.parse(fs.readFileSync(path.join(dir, "meta.json"), "utf8")) : { shots: {} };
+  const viewports = list(spec.viewports).length ? list(spec.viewports) : [...new Set(Object.values(meta.shots).map((entry) => entry.viewport))];
+  for (const name of viewports) if (!SAFE_NAME.test(String(name))) throw new Error(`viewport names must match ${SAFE_NAME}: ${name}`);
+  if (!viewports.length) viewports.push("desktop");
+  const images = new Images(dir);
+  const block = (title, body) => (body ? `<section class="block"><h2>${escape(title)}</h2>${body}</section>` : "");
+  const changeRows = (items, last) => list(items).map((item) => [`<b>${escape(item.title)}</b>`, escape(item.before), escape(item.after), last(item)]);
+  const tests = [
+    ...(spec.e2e ? [[escape(`${t.e2e}${spec.e2e.command ? ` · ${spec.e2e.command}` : ""}`), badge(spec.e2e.result, t),
+      escape([spec.e2e.passed !== undefined && `${spec.e2e.passed} ${t.passed.toLowerCase()}`, spec.e2e.failed && `${spec.e2e.failed} ${t.failed.toLowerCase()}`,
+        spec.e2e.skipped && `${spec.e2e.skipped} ${t.skipped.toLowerCase()}`, spec.e2e.duration, ...list(spec.e2e.notes)].filter(Boolean).join(" · "))]] : []),
+    ...list(spec.checks).map((check) => [escape(check.name), badge(check.result, t), escape(check.detail)])
+  ];
+  const files = list(spec.files).map((file) => [`<code>${escape(file.path)}</code>`, escape(file.kind), escape(file.summary)]);
+  const sections = list(spec.sections).map((section) => sectionHtml(section, images, viewports, t)).join("");
+  const chips = [spec.base && `${t.before}: ${spec.base}`, spec.head && `${t.after}: ${spec.head}`, `${t.generated}: ${spec.generatedAt ?? new Date().toISOString().slice(0, 16).replace("T", " ")}`]
+    .filter(Boolean).map((chip) => `<span class="chip">${escape(chip)}</span>`).join("");
+  const body = [
+    `<header><h1>${escape(spec.title ?? "Front-end change report")}</h1>${spec.lede ? `<p class="lede">${escape(spec.lede)}</p>` : ""}<div class="chips">${chips}</div></header>`,
+    block(t.summary, list(spec.summary).length ? `<ul>${list(spec.summary).map((line) => `<li>${escape(line)}</li>`).join("")}</ul>` : ""),
+    block(t.business, table([t.item, t.before, t.after, t.impact], changeRows(spec.business, (item) => escape(item.impact)))),
+    block(t.logic, table([t.item, t.before, t.after, t.where], changeRows(spec.logic, (item) => list(item.files).map((file) => `<code>${escape(file)}</code>`).join("<br>")))),
+    block(t.ui, sections || `<p class="note">${t.noChanges}</p>`),
+    block(t.tests, table([t.check, t.result, t.detail], tests)),
+    block(t.files, table([t.where, t.item, t.detail], files)),
+    block(t.risks, list(spec.risks).length ? `<ul>${list(spec.risks).map((line) => `<li>${escape(line)}</li>`).join("")}</ul>` : "")
+  ].join("");
+  return `<!doctype html>
+<html lang="${spec.lang === "en" ? "en" : "vi"}"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
+<meta name="generator" content="${REPORT_MARKER}"><title>${escape(spec.title ?? "Front-end change report")}</title>
+<style>${STYLE}${images.rules.join("")}</style></head><body><main>${body}</main></body></html>
+`;
+}
+
+const STYLE = `
+:root{--bg:#f6f7f5;--fg:#1b1f1d;--muted:#5d6762;--card:#fff;--line:#d9dfdb;--mark:#d4202a;--on-mark:#fff;--ok:#0b7a3e;--bad:#c62828;--skip:#8a6d00;
+--sans:system-ui,-apple-system,"Segoe UI",sans-serif;color-scheme:light}
+@media (prefers-color-scheme:dark){:root{--bg:#141816;--fg:#e8ece9;--muted:#9fa9a4;--card:#1d2320;--line:#323a36;--mark:#ff5a5f;--ok:#5ccf8f;--bad:#ff7a7a;--skip:#e0c25c;color-scheme:dark}}
+*{box-sizing:border-box}body{margin:0;background:var(--bg);color:var(--fg);font:15px/1.55 var(--sans);padding:24px 16px 48px}
+main{max-width:1180px;margin:0 auto;display:grid;gap:28px}h1{font-size:1.6rem;margin:0 0 6px}h2{font-size:1.2rem;margin:0 0 12px}
+h3{font-size:1.05rem;margin:0 0 4px}h4{font-size:.78rem;margin:18px 0 8px;color:var(--muted);text-transform:uppercase;letter-spacing:.08em}
+.lede,.note{color:var(--muted);max-width:75ch;margin:0 0 12px}.chips{display:flex;flex-wrap:wrap;gap:6px}
+.chip{border:1px solid var(--line);border-radius:999px;padding:2px 10px;font-size:.82rem;color:var(--muted)}
+.block>ul{margin:0;padding-left:20px}.card{background:var(--card);border:1px solid var(--line);border-radius:12px;padding:18px;margin-bottom:16px}
+.pair{display:grid;grid-template-columns:repeat(auto-fit,minmax(min(100%,400px),1fr));gap:16px}.pair.narrow{grid-template-columns:repeat(auto-fit,minmax(min(100%,260px),390px))}
+figure{margin:0;min-width:0}figcaption{font-weight:700;margin-bottom:6px}.missing{color:var(--muted);border:1px dashed var(--line);border-radius:8px;padding:24px;text-align:center}
+.shot{position:relative;width:100%;border:1px solid var(--line);border-radius:8px;background-size:100% auto;background-repeat:no-repeat}
+.box{position:absolute;border:3px solid var(--mark);border-radius:4px}
+.box b,.num{display:inline-grid;place-items:center;width:24px;height:24px;border-radius:50%;background:var(--mark);color:var(--on-mark);font-size:.8rem;line-height:1;flex:none}
+.box b{position:absolute;top:-12px;left:-12px;box-shadow:0 0 0 2px var(--card)}.zrow{display:grid;gap:8px;margin-bottom:14px}.zt{margin:0;display:flex;gap:8px;align-items:center}
+.zoom{min-width:0}.zl{font-size:.8rem;color:var(--muted)}.crop{width:100%;border:3px solid var(--mark);border-radius:6px;background-repeat:no-repeat}
+details{margin-top:14px}summary{cursor:pointer;font-weight:600}details>.shot,details>.pair{margin-top:10px}
+.scroll{overflow-x:auto}table{border-collapse:collapse;width:100%;background:var(--card);border:1px solid var(--line);border-radius:10px;overflow:hidden}
+th,td{text-align:left;vertical-align:top;padding:8px 10px;border-bottom:1px solid var(--line)}th{font-size:.82rem;color:var(--muted)}
+code{font-size:.85em;word-break:break-all}.badge{font-weight:700;font-size:.82rem}.badge.passed{color:var(--ok)}.badge.failed{color:var(--bad)}.badge.skipped{color:var(--skip)}
+`.trim();
+
+if (import.meta.url === pathToFileURL(process.argv[1] ?? "").href) {
+  const options = parseArgs(process.argv.slice(2));
+  if (!options.spec || !options.dir || !options.out) { console.error("usage: build-report.mjs --spec report.json --dir <shots dir> --out report.html"); process.exit(2); }
+  const html = buildReport({ spec: JSON.parse(fs.readFileSync(options.spec, "utf8")), dir: options.dir });
+  fs.mkdirSync(path.dirname(path.resolve(options.out)), { recursive: true });
+  fs.writeFileSync(options.out, html);
+  console.log(`${options.out} ${Math.round(html.length / 1024)} KB`);
+}

package/packages/piagent-core/skills/fe-change-report/scripts/capture.mjs

@@ -0,0 +1,150 @@
+#!/usr/bin/env node
+// Headless screenshots of one side (before or after) of a front-end change.
+// Playwright comes from the project under test, so the skill adds no dependency.
+//   node capture.mjs --config shots.json --side before --base-url http://127.0.0.1:3001 --out <dir>
+import fs from "node:fs";
+import path from "node:path";
+import { createRequire } from "node:module";
+import { pathToFileURL } from "node:url";
+
+export function parseArgs(argv) {
+  const options = {};
+  for (let index = 0; index < argv.length; index += 1) {
+    const match = /^--([a-z-]+)$/.exec(argv[index]);
+    if (!match || argv[index + 1] === undefined) throw new Error(`unexpected argument: ${argv[index]}`);
+    options[match[1]] = argv[++index];
+  }
+  return options;
+}
+
+export async function loadChromium(projectDir) {
+  const require = createRequire(path.join(path.resolve(projectDir), "package.json"));
+  for (const name of ["playwright", "@playwright/test", "playwright-core"]) {
+    let module;
+    try { module = await import(pathToFileURL(require.resolve(name)).href); } catch { continue; }
+    // A CommonJS package imported from ESM keeps its exports under `default`.
+    const chromium = module.chromium ?? module.default?.chromium;
+    if (chromium) return chromium;
+  }
+  throw new Error(`Playwright was not found from ${projectDir}; install it in the project or pass --project <dir>`);
+}
+
+// Width and height sit at fixed offsets of the IHDR chunk that opens every PNG.
+export function pngSize(bytes) {
+  if (bytes.length < 24 || bytes.readUInt32BE(12) !== 0x49484452) throw new Error("not a PNG file");
+  return { width: bytes.readUInt32BE(16), height: bytes.readUInt32BE(20) };
+}
+
+const DEFAULT_VIEWPORTS = [{ name: "desktop", width: 1440, height: 1000 }, { name: "mobile", width: 390, height: 844 }];
+export const SAFE_NAME = /^[a-z0-9][a-z0-9-]{0,63}$/;
+// The dashboard refuses a screenshot larger than this; say so at capture time.
+export const MAX_SHOT_BYTES = 8 * 1024 * 1024;
+
+export function readConfig(file) {
+  const config = JSON.parse(fs.readFileSync(file, "utf8"));
+  const viewports = config.viewports ?? DEFAULT_VIEWPORTS;
+  if (!Array.isArray(config.pages) || config.pages.length === 0) throw new Error("config.pages must list at least one page");
+  for (const entry of [...config.pages.map((page) => page.key), ...viewports.map((viewport) => viewport.name)]) {
+    if (!SAFE_NAME.test(String(entry))) throw new Error(`page keys and viewport names must match ${SAFE_NAME}: ${entry}`);
+  }
+  // A login state that is named but missing would silently capture the logged-out page on both sides.
+  if (config.storageState && !fs.existsSync(config.storageState)) throw new Error(`storageState not found: ${config.storageState}`);
+  return { ...config, viewports };
+}
+
+async function settle(page, entry) {
+  await page.waitForLoadState("networkidle", { timeout: 15_000 }).catch(() => undefined);
+  if (entry.waitFor) await page.locator(entry.waitFor).first().waitFor({ timeout: 30_000 });
+  if (entry.scroll) {
+    // Lazy sections render only after they enter the viewport.
+    await page.evaluate(async () => {
+      for (let y = 0; y < document.body.scrollHeight; y += window.innerHeight / 2) {
+        window.scrollTo(0, y); await new Promise((resolve) => setTimeout(resolve, 120));
+      }
+      window.scrollTo(0, 0);
+    });
+  }
+  await page.evaluate(() => document.fonts?.ready);
+  await page.waitForTimeout(entry.settleMs ?? 600);
+}
+
+// Where the masked elements sit in the screenshot. A masked clock is grey on
+// both sides, but its width still follows the time it showed, so the diff has
+// to skip these areas rather than compare two grey boxes of different sizes.
+async function maskRects(page, mask, target) {
+  const scroll = await page.evaluate(() => ({ x: window.scrollX, y: window.scrollY }));
+  const origin = target ? await target.boundingBox() : { x: -scroll.x, y: -scroll.y };
+  const rects = [];
+  for (const locator of mask) {
+    for (const element of await locator.all()) {
+      const box = await element.boundingBox();
+      if (box && origin) rects.push({ x: Math.floor(box.x - origin.x), y: Math.floor(box.y - origin.y), w: Math.ceil(box.width), h: Math.ceil(box.height) });
+    }
+  }
+  return rects;
+}
+
+export async function capture({ config, side, baseUrl, out, chromium }) {
+  fs.mkdirSync(out, { recursive: true });
+  const metaFile = path.join(out, "meta.json");
+  const meta = fs.existsSync(metaFile) ? JSON.parse(fs.readFileSync(metaFile, "utf8")) : { shots: {} };
+  meta[`${side}BaseUrl`] = baseUrl;
+  const browser = await chromium.launch({ headless: true });
+  const failures = [];
+  try {
+    for (const viewport of config.viewports) {
+      const context = await browser.newContext({
+        viewport: { width: viewport.width, height: viewport.height }, deviceScaleFactor: 1,
+        // A phone-sized viewport without a touch device still renders desktop hover and meta-viewport behaviour.
+        isMobile: viewport.isMobile ?? viewport.width < 768, hasTouch: viewport.isMobile ?? viewport.width < 768,
+        reducedMotion: "reduce", locale: config.locale, colorScheme: config.colorScheme ?? "light",
+        ignoreHTTPSErrors: config.ignoreHTTPSErrors === true, storageState: config.storageState || undefined
+      });
+      for (const entry of config.pages) {
+        if (entry.viewports && !entry.viewports.includes(viewport.name)) continue;
+        const name = `${side}-${entry.key}-${viewport.name}`;
+        const page = await context.newPage();
+        try {
+          await page.goto(new URL(entry.path, baseUrl).href, { waitUntil: "load", timeout: 60_000 });
+          await settle(page, entry);
+          const file = path.join(out, `${name}.png`);
+          // Masked regions (clocks, random ids, ads) are painted the same colour on both sides, so they never count as a change.
+          const mask = [...(config.mask ?? []), ...(entry.mask ?? [])].map((selector) => page.locator(selector));
+          const shot = { path: file, animations: "disabled", caret: "hide", mask, maskColor: "#c8c8c8" };
+          const target = entry.selector ? page.locator(entry.selector).first() : null;
+          if (target) await target.scrollIntoViewIfNeeded();
+          const masks = await maskRects(page, mask, target);
+          if (target) await target.screenshot(shot);
+          else if (entry.clipHeight) {
+            // fullPage lets the clip reach below the first screen.
+            const height = Math.min(entry.clipHeight, await page.evaluate(() => document.documentElement.scrollHeight));
+            await page.screenshot({ ...shot, fullPage: true, clip: { x: 0, y: 0, width: viewport.width, height } });
+          } else await page.screenshot({ ...shot, fullPage: entry.fullPage !== false });
+          const bytes = fs.readFileSync(file), size = pngSize(bytes);
+          meta.shots[name] = { key: entry.key, title: entry.title ?? entry.key, viewport: viewport.name, url: page.url(), ...size, bytes: bytes.length, masks };
+          console.log(`captured ${name} ${size.width}x${size.height}`);
+          if (bytes.length > MAX_SHOT_BYTES) failures.push(`${name}: ${Math.round(bytes.length / 1048576)} MB is over the 8 MB the dashboard shows; use clipHeight or selector`);
+        } catch (error) {
+          failures.push(`${name}: ${error.message.split("\n")[0]}`);
+        } finally { await page.close(); }
+      }
+      await context.close();
+    }
+  } finally { await browser.close(); }
+  fs.writeFileSync(metaFile, `${JSON.stringify(meta, null, 2)}\n`);
+  return failures;
+}
+
+if (import.meta.url === pathToFileURL(process.argv[1] ?? "").href) {
+  const options = parseArgs(process.argv.slice(2));
+  if (!options.config || !["before", "after"].includes(options.side) || !options["base-url"] || !options.out) {
+    console.error("usage: capture.mjs --config shots.json --side before|after --base-url <url> --out <dir> [--project <dir>]");
+    process.exit(2);
+  }
+  const failures = await capture({
+    config: readConfig(options.config), side: options.side, baseUrl: options["base-url"], out: options.out,
+    chromium: await loadChromium(options.project ?? process.cwd())
+  });
+  for (const failure of failures) console.error(`failed ${failure}`);
+  process.exit(failures.length ? 1 : 0);
+}

package/packages/piagent-core/skills/fe-change-report/scripts/diff-regions.mjs

@@ -0,0 +1,110 @@
+#!/usr/bin/env node
+// Finds where each before/after screenshot pair differs and proposes numbered
+// red boxes. Pixels are compared on a canvas inside headless Chromium, so no
+// image library is needed; grouping the changed cells into boxes runs here.
+//   node diff-regions.mjs --dir <shots dir> [--project <dir>] [--cell 8] [--gap 3]
+import fs from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { loadChromium, parseArgs } from "./capture.mjs";
+
+// cells: Uint8Array-like grid, 1 where the cell changed. Cells closer than
+// `gap` cells join one box so a changed paragraph becomes one frame, not forty.
+export function groupCells({ cells, columns, rows, cell, gap = 3, pad = 6, width, height, limit = 12 }) {
+  const seen = new Uint8Array(columns * rows), boxes = [];
+  for (let start = 0; start < cells.length; start += 1) {
+    if (!cells[start] || seen[start]) continue;
+    let minX = Infinity, minY = Infinity, maxX = -1, maxY = -1, count = 0;
+    const queue = [start]; seen[start] = 1;
+    while (queue.length) {
+      const index = queue.pop(), x = index % columns, y = Math.floor(index / columns);
+      count += 1; minX = Math.min(minX, x); maxX = Math.max(maxX, x); minY = Math.min(minY, y); maxY = Math.max(maxY, y);
+      for (let dy = -gap; dy <= gap; dy += 1) {
+        for (let dx = -gap; dx <= gap; dx += 1) {
+          const nx = x + dx, ny = y + dy, next = ny * columns + nx;
+          if (nx < 0 || ny < 0 || nx >= columns || ny >= rows || seen[next] || !cells[next]) continue;
+          seen[next] = 1; queue.push(next);
+        }
+      }
+    }
+    const x = Math.max(0, minX * cell - pad), y = Math.max(0, minY * cell - pad);
+    boxes.push({ x, y, w: Math.min(width, (maxX + 1) * cell + pad) - x, h: Math.min(height, (maxY + 1) * cell + pad) - y, cells: count });
+  }
+  return boxes.sort((a, b) => b.cells - a.cells).slice(0, limit)
+    .sort((a, b) => a.y - b.y || a.x - b.x)
+    .map(({ cells: _cells, ...box }, index) => ({ n: index + 1, ...box }));
+}
+
+async function comparePair(page, beforeFile, afterFile, cell, masks) {
+  return page.evaluate(async ({ before, after, cell, masks }) => {
+    const masked = (x, y) => masks.some((rect) => x >= rect.x - 2 && x < rect.x + rect.w + 2 && y >= rect.y - 2 && y < rect.y + rect.h + 2);
+    const load = async (source) => {
+      const bitmap = await createImageBitmap(await (await fetch(source)).blob());
+      const canvas = new OffscreenCanvas(bitmap.width, bitmap.height), context = canvas.getContext("2d");
+      context.drawImage(bitmap, 0, 0);
+      return { width: bitmap.width, height: bitmap.height, data: context.getImageData(0, 0, bitmap.width, bitmap.height).data, bitmap };
+    };
+    const [a, b] = await Promise.all([load(before), load(after)]);
+    const width = Math.max(a.width, b.width), height = Math.max(a.height, b.height);
+    const columns = Math.ceil(width / cell), rows = Math.ceil(height / cell), cells = new Array(columns * rows).fill(0);
+    const overlay = new OffscreenCanvas(b.width, b.height), draw = overlay.getContext("2d");
+    draw.globalAlpha = 0.35; draw.drawImage(b.bitmap, 0, 0); draw.globalAlpha = 1;
+    const mark = draw.createImageData(b.width, b.height);
+    let changed = 0;
+    for (let y = 0; y < height; y += 1) {
+      for (let x = 0; x < width; x += 1) {
+        const inA = x < a.width && y < a.height, inB = x < b.width && y < b.height;
+        let differs = inA !== inB;
+        if (inA && inB) {
+          const i = (y * a.width + x) * 4, j = (y * b.width + x) * 4;
+          differs = Math.max(Math.abs(a.data[i] - b.data[j]), Math.abs(a.data[i + 1] - b.data[j + 1]), Math.abs(a.data[i + 2] - b.data[j + 2])) > 40;
+        }
+        if (!differs || masked(x, y)) continue;
+        changed += 1; cells[Math.floor(y / cell) * columns + Math.floor(x / cell)] += 1;
+        if (inB) { const j = (y * b.width + x) * 4; mark.data[j] = 220; mark.data[j + 1] = 30; mark.data[j + 2] = 40; mark.data[j + 3] = 255; }
+      }
+    }
+    const markCanvas = new OffscreenCanvas(b.width, b.height); markCanvas.getContext("2d").putImageData(mark, 0, 0);
+    draw.drawImage(markCanvas, 0, 0);
+    const blob = await overlay.convertToBlob({ type: "image/png" });
+    const bytes = new Uint8Array(await blob.arrayBuffer());
+    let binary = ""; for (let i = 0; i < bytes.length; i += 32_768) binary += String.fromCharCode(...bytes.subarray(i, i + 32_768));
+    // A cell counts once a few pixels changed, so antialiasing noise stays out.
+    return { width, height, columns, rows, changed, total: width * height, cells: cells.map((count) => (count > 3 ? 1 : 0)), overlay: btoa(binary) };
+  }, { before: dataUrl(beforeFile), after: dataUrl(afterFile), cell, masks });
+}
+
+const dataUrl = (file) => `data:image/png;base64,${fs.readFileSync(file).toString("base64")}`;
+
+export async function diffRegions({ dir, chromium, cell = 8, gap = 3 }) {
+  const meta = JSON.parse(fs.readFileSync(path.join(dir, "meta.json"), "utf8"));
+  const names = Object.keys(meta.shots);
+  const pairs = names.filter((name) => name.startsWith("after-")).map((name) => name.slice("after-".length)).filter((name) => meta.shots[`before-${name}`]);
+  // A page captured on one side only is a new or removed page, or a failed capture: say which shots have no partner.
+  for (const name of names) {
+    const [side, rest] = [name.slice(0, name.indexOf("-")), name.slice(name.indexOf("-") + 1)];
+    if (!pairs.includes(rest)) console.log(`${rest}: only the ${side} screenshot exists, nothing to compare`);
+  }
+  const browser = await chromium.launch({ headless: true });
+  const regions = {};
+  try {
+    const page = await browser.newPage();
+    for (const name of pairs) {
+      const masks = [...(meta.shots[`before-${name}`].masks ?? []), ...(meta.shots[`after-${name}`].masks ?? [])];
+      const result = await comparePair(page, path.join(dir, `before-${name}.png`), path.join(dir, `after-${name}.png`), cell, masks);
+      fs.writeFileSync(path.join(dir, `diff-${name}.png`), Buffer.from(result.overlay, "base64"));
+      const boxes = groupCells({ ...result, cell, gap });
+      regions[name] = { changedRatio: Number((result.changed / result.total).toFixed(5)), boxes };
+      console.log(`${name}: ${(regions[name].changedRatio * 100).toFixed(2)}% changed, ${boxes.length} box(es)`);
+    }
+  } finally { await browser.close(); }
+  fs.writeFileSync(path.join(dir, "regions.json"), `${JSON.stringify(regions, null, 2)}\n`);
+  return regions;
+}
+
+if (import.meta.url === pathToFileURL(process.argv[1] ?? "").href) {
+  const options = parseArgs(process.argv.slice(2));
+  if (!options.dir) { console.error("usage: diff-regions.mjs --dir <shots dir> [--project <dir>] [--cell 8] [--gap 3]"); process.exit(2); }
+  await diffRegions({ dir: options.dir, chromium: await loadChromium(options.project ?? process.cwd()),
+    cell: Number(options.cell ?? 8), gap: Number(options.gap ?? 3) });
+}