@piagent/platform 1.40.0 → 1.42.0

package/packages/piagent-core/runtime/inspection/document-workspace-projection.ts

@@ -142,6 +142,10 @@ function walkRoot(root: DocumentRoot, budget: { remaining: number }, isProtected
     // an operator keeps documents, and reading all of it is what makes a listing
     // take seconds.
     if (entries.length > DOCUMENT_WORKSPACE_LIMITS.entriesPerDirectory) continue;
+    // A change report's shots/ folder holds screenshots and the capture
+    // bookkeeping (meta.json, regions.json). The report opens them itself, so
+    // listing them would only bury report.json among its own working files.
+    const changeReport = entries.some((entry) => entry.isFile() && entry.name === "report.json");
     for (const entry of entries.sort((left, right) => left.name.localeCompare(right.name))) {
       if (budget.remaining <= 0) break;
       // A Dirent already reports a link as a link, so the isFile and isDirectory
@@ -151,7 +155,7 @@ function walkRoot(root: DocumentRoot, budget: { remaining: number }, isProtected
       const absolute = path.join(current.directory, entry.name);
       const relative = path.relative(root.path, absolute).split(path.sep).join("/");
       if (entry.isDirectory()) {
-        if (entry.name.startsWith(".") || SKIPPED_DIRECTORIES.has(entry.name)) continue;
+        if (entry.name.startsWith(".") || SKIPPED_DIRECTORIES.has(entry.name) || (changeReport && entry.name === "shots")) continue;
         if (current.depth + 1 > DOCUMENT_WORKSPACE_LIMITS.depth) continue;
         if (isProtected(relative, absolute)) continue;
         queue.push({ directory: absolute, depth: current.depth + 1 });
@@ -223,39 +227,50 @@ export function projectDocumentWorkspaceListing(input: DocumentWorkspaceInput):
   return collectDocuments(input).listing;
 }
 
-export function projectDocumentWorkspaceDocument(input: DocumentWorkspaceInput & { documentRef: string }): DocumentWorkspaceDocument {
-  const now = (input.now ?? (() => new Date()))();
-  const base = { schemaVersion: 1 as const, version: "piagent-webui-document-workspace-v1" as const,
-    messageType: "document" as const, generatedAt: timestamp(now), documentRef: input.documentRef };
-  const unavailable = (reasonCode: string): DocumentWorkspaceDocument => ({ ...base, state: "unavailable", name: null, relativePath: null,
-    rootRef: null, format: null, text: null, sizeBytes: null, truncated: false, redacted: false, reasonCode });
-
+// A read names a document only by the ref a listing handed out, so every read
+// goes through this: re-list, match, resolve, and re-prove the ref.
+function locateListedDocument(input: DocumentWorkspaceInput, documentRef: string): { reasonCode: string }
+  | { entry: DocumentWorkspaceEntry; resolved: Extract<ReturnType<typeof resolveDocumentPath>, { status: "ok" }>;
+    isProtected: (relative: string, absolute: string) => boolean } {
   // The ref is matched against a listing taken now, so opening a document proves
   // it is still listable rather than trusting a ref the browser has been holding.
   const { listing, roots, paths } = collectDocuments(input);
-  if (listing.state !== "ready") return unavailable(listing.reasonCode ?? "document-roots-unavailable");
-  const entry = listing.documents.find((candidate) => candidate.documentRef === input.documentRef);
-  const absolute = paths.get(input.documentRef);
-  if (!entry || !absolute) return unavailable("document-not-listed");
+  if (listing.state !== "ready") return { reasonCode: listing.reasonCode ?? "document-roots-unavailable" };
+  const entry = listing.documents.find((candidate) => candidate.documentRef === documentRef);
+  const absolute = paths.get(documentRef);
+  if (!entry || !absolute) return { reasonCode: "document-not-listed" };
 
   // Resolution runs against the same roots the walk used, so the extension gate,
   // the size cap, the symlink canonicalisation and the containment check are the
   // ones the document tool applies — including the identity that extractDocument
   // re-proves when it opens the file.
   const resolved = resolveDocumentPath(absolute, roots, { cwd: input.cwd, home: input.home });
-  if (resolved.status === "error") return unavailable("document-unavailable");
+  if (resolved.status === "error") return { reasonCode: "document-unavailable" };
   // The walk above already dropped protected documents, so a protected ref fails
   // to match a listing entry before it reaches here. Both of the next two checks
   // are the invariant stated rather than assumed: they hold the guarantee in
   // place if the listing filter is ever loosened or the ref scheme changes.
   const isProtected = protectedPredicate(input);
   const relative = path.relative(resolved.root.path, resolved.absolutePath).split(path.sep).join("/");
-  if (isProtected(relative, resolved.absolutePath)) return unavailable("document-protected");
+  if (isProtected(relative, resolved.absolutePath)) return { reasonCode: "document-protected" };
   // Roots are canonical and the walk never traverses a link, so the listed path
   // is already the canonical one and this equality holds by construction. It is
   // re-derived anyway: the cost is a hash, and what it protects is the rule that
   // the browser can only ever name a document the listing chose to expose.
-  if (ref("document", resolved.absolutePath) !== input.documentRef) return unavailable("document-changed");
+  if (ref("document", resolved.absolutePath) !== documentRef) return { reasonCode: "document-changed" };
+  return { entry, resolved, isProtected };
+}
+
+export function projectDocumentWorkspaceDocument(input: DocumentWorkspaceInput & { documentRef: string }): DocumentWorkspaceDocument {
+  const now = (input.now ?? (() => new Date()))();
+  const base = { schemaVersion: 1 as const, version: "piagent-webui-document-workspace-v1" as const,
+    messageType: "document" as const, generatedAt: timestamp(now), documentRef: input.documentRef };
+  const unavailable = (reasonCode: string): DocumentWorkspaceDocument => ({ ...base, state: "unavailable", name: null, relativePath: null,
+    rootRef: null, format: null, text: null, sizeBytes: null, truncated: false, redacted: false, reasonCode });
+
+  const located = locateListedDocument(input, input.documentRef);
+  if ("reasonCode" in located) return unavailable(located.reasonCode);
+  const { entry, resolved } = located;
 
   const extracted = extractDocument(resolved);
   if (extracted.status === "error") {
@@ -274,3 +289,51 @@ export function projectDocumentWorkspaceDocument(input: DocumentWorkspaceInput &
     format: extracted.kind, text: capped.text, sizeBytes: entry.sizeBytes,
     truncated: extracted.truncated || capped.truncated, redacted: safe.redacted, reasonCode: null };
 }
+
+// Screenshots of a front-end change report. The report itself is a listed
+// `report.json`; its images are never listed and are named only relative to it,
+// so the browser still cannot point at an arbitrary file. Images cross as base64
+// inside JSON: the read model, the session IPC and the company relay already
+// carry JSON, and a PNG drawn into an <img> runs nothing.
+export const DOCUMENT_ASSET_NAME = /^(before|after|diff)-[a-z0-9][a-z0-9-]{0,100}\.png$/;
+const MAX_DOCUMENT_ASSET_BYTES = 8 * 1024 * 1024;
+const PNG_SIGNATURE = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+
+export type DocumentWorkspaceAsset = {
+  schemaVersion: 1;
+  version: "piagent-webui-document-asset-v1";
+  generatedAt: string;
+  documentRef: string;
+  // Null when the requested name was refused: a refusal never echoes it back.
+  name: string | null;
+  state: "ready" | "unavailable";
+  mediaType: "image/png" | null;
+  sizeBytes: number | null;
+  base64: string | null;
+  reasonCode: string | null;
+};
+
+export function projectDocumentWorkspaceAsset(input: DocumentWorkspaceInput & { documentRef: string; name: string }): DocumentWorkspaceAsset {
+  const base = { schemaVersion: 1 as const, version: "piagent-webui-document-asset-v1" as const,
+    generatedAt: timestamp((input.now ?? (() => new Date()))()), documentRef: input.documentRef,
+    name: DOCUMENT_ASSET_NAME.test(input.name) ? input.name : null };
+  const unavailable = (reasonCode: string): DocumentWorkspaceAsset => ({ ...base, state: "unavailable", mediaType: null, sizeBytes: null, base64: null, reasonCode });
+  if (base.name === null) return unavailable("document-asset-name-invalid");
+  const located = locateListedDocument(input, input.documentRef);
+  if ("reasonCode" in located) return unavailable(located.reasonCode);
+  if (path.basename(located.resolved.absolutePath) !== "report.json") return unavailable("document-asset-not-a-report");
+  const directory = path.join(path.dirname(located.resolved.absolutePath), "shots"), absolute = path.join(directory, input.name);
+  const relative = path.relative(located.resolved.root.path, absolute).split(path.sep).join("/");
+  if (located.isProtected(relative, absolute)) return unavailable("document-protected");
+  let bytes: Buffer;
+  try {
+    // lstat on both levels: a linked shots folder or image could lead out of the root.
+    if (!fs.lstatSync(directory).isDirectory()) return unavailable("document-asset-unavailable");
+    const stat = fs.lstatSync(absolute);
+    if (!stat.isFile()) return unavailable("document-asset-unavailable");
+    if (stat.size > MAX_DOCUMENT_ASSET_BYTES) return unavailable("document-asset-too-large");
+    bytes = fs.readFileSync(absolute);
+  } catch { return unavailable("document-asset-unavailable"); }
+  if (bytes.length > MAX_DOCUMENT_ASSET_BYTES || !bytes.subarray(0, 8).equals(PNG_SIGNATURE)) return unavailable("document-asset-unreadable");
+  return { ...base, state: "ready", mediaType: "image/png", sizeBytes: bytes.length, base64: bytes.toString("base64"), reasonCode: null };
+}

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`);
+}