@zaip-ai/cli 6.3.0 → 7.6.0

package/templates/.agents/skills/zaip-skill-website-readiness/scripts/site-audit.test.mjs

@@ -0,0 +1,287 @@
+import assert from "node:assert/strict";
+import { createServer } from "node:http";
+import test from "node:test";
+import { collectSite } from "./audit-site.mjs";
+import { htmlFacts } from "./html-facts.mjs";
+import { qualityPlan } from "./quality-plan.mjs";
+import { auditSite } from "./site-audit.mjs";
+
+const html = `<!doctype html><html lang="pt-BR"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><title>Serviços de exemplo</title><meta name="description" content="Descrição real dos serviços disponíveis."><link rel="canonical" href="https://example.com/"><meta property="og:title" content="Serviços de exemplo"><meta property="og:description" content="Descrição real dos serviços disponíveis."><meta property="og:url" content="https://example.com/"><meta property="og:type" content="website"><meta property="og:locale" content="pt_BR"><meta property="og:image" content="https://example.com/social.png"><meta property="og:image:type" content="image/png"><meta property="og:image:width" content="1200"><meta property="og:image:height" content="630"><meta name="twitter:card" content="summary_large_image"><script type="application/ld+json">{"@context":"https://schema.org","@type":"WebPage","name":"Serviços de exemplo"}</script></head><body><main><h1>Serviços de exemplo</h1><p>Conheça nosso processo, condições de atendimento e fale com a equipe.</p><img src="/hero.0123456789ab.webp" width="800" height="500" alt="Equipe trabalhando" fetchpriority="high"><a href="/contato">Contato</a></main></body></html>`;
+function fixture() {
+  const config = {
+    origin: "https://example.com",
+    routes: [{ path: "/", indexable: true }],
+    missingPaths: ["/absent"],
+  };
+  const snapshot = {
+    pages: [
+      { url: config.origin + "/", status: 200, headers: { "content-type": "text/html" }, html },
+    ],
+    resources: [
+      {
+        url: config.origin + "/social.png",
+        status: 200,
+        headers: { "content-type": "image/png" },
+        width: 1200,
+        height: 630,
+      },
+    ],
+    robots: {
+      status: 200,
+      body: "User-agent: *\nAllow: /\nSitemap: https://example.com/sitemap.xml",
+    },
+    sitemap: { status: 200, body: "<urlset><url><loc>https://example.com/</loc></url></urlset>" },
+    missing: [{ url: config.origin + "/absent", status: 404 }],
+  };
+  return { config, snapshot };
+}
+test("complete initial HTML and HTTP evidence passes bounded checks", () => {
+  const { config, snapshot } = fixture();
+  assert.deepEqual(auditSite(snapshot, config).findings, []);
+});
+const mutations = [
+  [
+    "missing title",
+    "metadata-title",
+    (s) => (s.pages[0].html = s.pages[0].html.replace(/<title>.*?<\/title>/, "")),
+  ],
+  [
+    "duplicate description",
+    "metadata-description",
+    (s) =>
+      (s.pages[0].html = s.pages[0].html.replace(
+        "</head>",
+        '<meta name="description" content="other"></head>',
+      )),
+  ],
+  [
+    "wrong canonical",
+    "canonical-target",
+    (s) =>
+      (s.pages[0].html = s.pages[0].html.replace(
+        'href="https://example.com/"',
+        'href="https://wrong.example/"',
+      )),
+  ],
+  [
+    "sitemap noindex",
+    "sitemap-noindex",
+    (s) =>
+      (s.pages[0].html = s.pages[0].html.replace(
+        "</head>",
+        '<meta name="robots" content="noindex"></head>',
+      )),
+  ],
+  [
+    "broken JSON-LD",
+    "jsonld-invalid",
+    (s) => (s.pages[0].html = s.pages[0].html.replace('"@type":"WebPage"', '"@type":')),
+  ],
+  ["social asset broken", "social-image", (s) => (s.resources[0].status = 404)],
+  ["social dimensions wrong", "social-dimensions", (s) => (s.resources[0].width = 500)],
+  ["SPA missing route", "missing-status", (s) => (s.missing[0].status = 200)],
+  [
+    "lazy hero",
+    "hero-lazy",
+    (s) =>
+      (s.pages[0].html = s.pages[0].html.replace(
+        'fetchpriority="high"',
+        'fetchpriority="high" loading="lazy"',
+      )),
+  ],
+  [
+    "preload different image",
+    "preload-mismatch",
+    (s) =>
+      (s.pages[0].html = s.pages[0].html.replace(
+        "</head>",
+        '<link rel="preload" as="image" href="/wrong.webp"></head>',
+      )),
+  ],
+  [
+    "dimensions absent",
+    "image-dimensions",
+    (s) => (s.pages[0].html = s.pages[0].html.replace('width="800"', "")),
+  ],
+  [
+    "immutable HTML",
+    "cache-immutable",
+    (s) => (s.pages[0].headers["cache-control"] = "public, max-age=31536000, immutable"),
+  ],
+  [
+    "immutable mutable image",
+    "cache-immutable",
+    (s) => (s.resources[0].headers["cache-control"] = "immutable"),
+  ],
+  ["crawler SPA", "crawler-spa-fallback", (s) => (s.robots.body = html)],
+  ["HTTP noindex", "sitemap-noindex", (s) => (s.pages[0].headers["x-robots-tag"] = "noindex")],
+  [
+    "robots none means noindex",
+    "sitemap-noindex",
+    (s) =>
+      (s.pages[0].html = s.pages[0].html.replace(
+        "</head>",
+        '<meta name="robots" content="none"></head>',
+      )),
+  ],
+  [
+    "googlebot noindex",
+    "sitemap-noindex",
+    (s) =>
+      (s.pages[0].html = s.pages[0].html.replace(
+        "</head>",
+        '<meta name="googlebot" content="noindex"></head>',
+      )),
+  ],
+  [
+    "robots blocks noindex",
+    "robots-blocks-noindex",
+    (s) => {
+      s.pages[0].headers["x-robots-tag"] = "noindex";
+      s.robots.body = "User-agent: *\nDisallow: /\nSitemap: https://example.com/sitemap.xml";
+    },
+  ],
+];
+for (const [name, code, mutate] of mutations)
+  test(name, () => {
+    const { config, snapshot } = fixture();
+    mutate(snapshot);
+    const result = auditSite(snapshot, config);
+    assert.equal(result.passed, false);
+    assert.ok(
+      result.findings.some((f) => f.code === code),
+      JSON.stringify(result),
+    );
+  });
+test("HTML immutable remains prohibited even on explicit allowlist", () => {
+  const { config, snapshot } = fixture();
+  config.immutableAssets = [snapshot.pages[0].url];
+  snapshot.pages[0].headers["cache-control"] = "immutable";
+  assert.ok(auditSite(snapshot, config).findings.some((f) => f.code === "cache-immutable"));
+});
+test("only real initial head tags count; comments, JS and body do not satisfy metadata", () => {
+  const f = htmlFacts(
+    '<html><head><!-- <title>fake</title> --><script>"<title>fake</title>"</script></head><body><title>late</title></body></html>',
+  );
+  assert.deepEqual(f.titles, []);
+});
+test("crawled routes have unique titles and descriptions", () => {
+  const { config, snapshot } = fixture();
+  config.routes.push({ path: "/copy", indexable: false });
+  snapshot.pages.push({ ...snapshot.pages[0], url: config.origin + "/copy" });
+  assert.ok(auditSite(snapshot, config).findings.some((f) => f.code === "duplicate-title"));
+});
+test("HTML decoding handles single-quoted tags and entities", () =>
+  assert.equal(
+    htmlFacts("<head><meta name='description' content='A &amp; B'></head>").meta("description")[0],
+    "A & B",
+  ));
+test("HTTP collector exercises real initial HTML, social and missing resources", async () => {
+  const server = createServer((req, res) => {
+    if (req.url === "/") {
+      res.setHeader("content-type", "text/html");
+      res.end(html);
+    } else if (req.url === "/robots.txt")
+      res.end("User-agent: *\nSitemap: https://example.com/sitemap.xml");
+    else if (req.url === "/sitemap.xml")
+      res.end("<urlset><url><loc>https://example.com/</loc></url></urlset>");
+    else if (req.url === "/social.png") {
+      res.setHeader("content-type", "image/png");
+      res.end("fixture bytes (not decoding proof)");
+    } else {
+      res.statusCode = 404;
+      res.end("missing");
+    }
+  });
+  await new Promise((r) => server.listen(0, "127.0.0.1", r));
+  try {
+    const { config } = fixture();
+    config.baseUrl = `http://127.0.0.1:${server.address().port}`;
+    const snapshot = await collectSite(config);
+    assert.equal(snapshot.pages[0].html, html);
+    assert.equal(snapshot.missing[0].status, 404);
+    assert.equal(auditSite(snapshot, config).passed, true);
+  } finally {
+    await new Promise((r) => server.close(r));
+  }
+});
+test("collector rejects off-origin route rather than following arbitrary URLs", async () => {
+  await assert.rejects(
+    () =>
+      collectSite({ origin: "https://example.com", routes: [{ path: "https://other.example/" }] }),
+    /same-origin/,
+  );
+});
+
+test("collector keeps declared agent content separate and diagnoses SPA fallback", async (t) => {
+  const server = createServer((req, res) => {
+    res.setHeader("content-type", req.url === "/site.md" ? "text/markdown" : "text/html");
+    res.end(req.url === "/site.md" ? "# Approved public facts" : html);
+  });
+  await new Promise((r) => server.listen(0, "127.0.0.1", r));
+  t.after(() => new Promise((r) => server.close(r)));
+  const config = {
+    origin: "https://example.com",
+    baseUrl: `http://127.0.0.1:${server.address().port}`,
+    routes: [{ path: "/" }],
+    agentResources: [
+      { url: "https://example.com/site.md" },
+      { url: "https://example.com/llms.txt" },
+    ],
+  };
+  const snapshot = await collectSite(config);
+  assert.equal(snapshot.agentResources.length, 2);
+  assert.equal(snapshot.agentResources[0].body, "# Approved public facts");
+  assert.equal(snapshot.pages[0].html, html);
+  assert(
+    auditSite(snapshot, config).findings.some(
+      (f) => f.code === "agent-resource-html-fallback-or-mime" && f.url.endsWith("/llms.txt"),
+    ),
+  );
+});
+test("create LP and every site creation automatically select all four capabilities", () => {
+  for (const request of [
+    "crie uma LP",
+    "crie um site",
+    "create a landing page",
+    "build a website",
+  ]) {
+    const p = qualityPlan(request);
+    assert.equal(p.automatic, true);
+    assert.equal(p.capabilities.length, 4);
+    assert.equal(p.publish_authorized, false);
+    assert.equal(p.heavy_audit, false);
+  }
+});
+test("image-only, SEO/GEO and report requests select proportionate workflows", () => {
+  assert.deepEqual(qualityPlan("otimize imagens").skills, ["zaip-skill-image-optimization"]);
+  assert.ok(qualityPlan("melhore SEO/GEO").skills.includes("zaip-skill-website-readiness"));
+  const report = qualityPlan("analise este relatório de performance");
+  assert.equal(report.mode, "audit");
+  assert.equal(report.writes_product, false);
+  assert.deepEqual(report.skills, ["zaip-skill-performance-engineering"]);
+  assert.deepEqual(qualityPlan("corrija um botão", { surface: "site" }).checks, [
+    "review-diff-and-map-impact",
+  ]);
+});
+test("site visual edit and publication use the central scoped checks even with a form", () => {
+  const impact = {
+    diffReviewed: true,
+    changedFiles: ["src/Form.tsx"],
+    impacts: ["spacing"],
+    formPresent: true,
+  };
+  for (const mode of ["fix", "publication-check"]) {
+    const p = qualityPlan("mude o espaço do formulário do site", { mode, impact });
+    assert.equal(p.validation_scope, "visual-only");
+    assert.equal(p.full_conversion_flow, false);
+    assert.equal(p.backend_checks, false);
+    assert.equal(p.integration_checks, false);
+    assert.ok(p.checks.includes("inspect-screenshot"));
+  }
+  assert.equal(
+    qualityPlan("corrija formulário do site", { impact: { ...impact, impacts: ["submission"] } })
+      .full_conversion_flow,
+    true,
+  );
+});

package/templates/.agents/skills/zaip-skill-website-readiness/scripts/sitemap-policy.mjs

@@ -0,0 +1,111 @@
+import { decode } from "./html-facts.mjs";
+
+export function sitemapEntries(body = "") {
+  return [...body.matchAll(/<loc\b[^>]*>([^<]+)<\/loc\s*>/gi)].map((m) => decode(m[1].trim()));
+}
+
+export function auditSitemaps(snapshot, config, pages, canonicalURLs, add, noindex) {
+  const origin = new URL(config.origin).origin;
+  const documents =
+    snapshot.sitemaps ??
+    (snapshot.sitemap ? [{ url: new URL("/sitemap.xml", origin).href, ...snapshot.sitemap }] : []);
+  const paths =
+    config.sitemapPaths ?? (documents.some((d) => d.status === 200) ? ["/sitemap.xml"] : []);
+  const roots = paths.map((p) => new URL(p, origin).href);
+  const observed = new Map(documents.map((d) => [d.url, d]));
+  const visited = new Set(),
+    active = new Set(),
+    locs = new Set();
+  let partial = false;
+  const walk = (url, depth) => {
+    if (active.has(url)) {
+      add("sitemap-cycle", url, "Cyclic sitemap index");
+      return;
+    }
+    if (visited.has(url)) return;
+    if (depth > 3 || visited.size >= 20) {
+      partial = true;
+      add("sitemap-budget", url, "Traversal budget exhausted");
+      return;
+    }
+    visited.add(url);
+    active.add(url);
+    const doc = observed.get(url);
+    if (!doc || doc.status !== 200) {
+      partial = true;
+      add("sitemap-unobserved", url, "Declared sitemap was not observed successfully");
+      active.delete(url);
+      return;
+    }
+    if (/<html\b/i.test(doc.body) || !/<(?:urlset|sitemapindex)\b/i.test(doc.body)) {
+      add("sitemap-invalid", url, "Expected XML sitemap document");
+      active.delete(url);
+      return;
+    }
+    const entries = sitemapEntries(doc.body);
+    if (!entries.length) add("sitemap-invalid", url, "No URL entries");
+    if (/<sitemapindex\b/i.test(doc.body)) {
+      for (const entry of entries) {
+        let target;
+        try {
+          target = new URL(entry);
+        } catch {
+          add("sitemap-invalid", url, "Invalid child URL");
+          continue;
+        }
+        if (target.origin !== origin || target.username || target.password) {
+          partial = true;
+          add(
+            "sitemap-external-unverified",
+            entry,
+            "External child is never fetched automatically",
+          );
+          continue;
+        }
+        walk(target.href, depth + 1);
+      }
+    } else for (const entry of entries) locs.add(entry);
+    active.delete(url);
+  };
+  for (const url of roots) walk(url, 0);
+  for (const loc of locs) {
+    const route = config.routes.find((r) => new URL(r.path, origin).href === loc);
+    if (!route) {
+      partial = true;
+      add(
+        "sitemap-url-unobserved",
+        loc,
+        "Outside declared sample; indexability unknown",
+        "warning",
+      );
+      continue;
+    }
+    if (
+      route.indexable === false ||
+      (route.status ?? 200) !== 200 ||
+      (pages.some((p) => p.url === loc) && !canonicalURLs.has(loc))
+    )
+      add("sitemap-nonindexable", loc, "Observed or declared indexability conflict");
+    const page = pages.find((p) => p.url === loc);
+    if (page && noindex(page)) add("sitemap-noindex", loc, "Agent sees noindex");
+  }
+  if (roots.length)
+    for (const route of config.routes) {
+      const canonical = route.canonical ?? new URL(route.path, origin).href;
+      if (
+        route.indexable &&
+        (route.status ?? 200) === 200 &&
+        new URL(canonical).origin === origin &&
+        !locs.has(canonical)
+      ) {
+        add(
+          "sitemap-missing-route",
+          route.path,
+          "Route absent from observed maps; completeness is project-declared",
+          config.sitemapCoverage === "complete" ? "error" : "warning",
+        );
+        if (config.sitemapCoverage !== "complete") partial = true;
+      }
+    }
+  return { partial, roots };
+}

package/templates/.agents/skills/zaip-skill-website-readiness/scripts/verify-site-design.mjs

@@ -0,0 +1,130 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { createRequire } from "node:module";
+import { resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { compareVisualSnapshots, visualSnapshot } from "./visual-preservation.mjs";
+
+export async function verifySiteDesign(config, { chromium } = {}) {
+  if (!config.outputDir) throw Error("Declare outputDir for evidence");
+  const urls = [config.baselineUrl, config.candidateUrl].map((value) => {
+    const url = new URL(value);
+    if (
+      !["http:", "https:"].includes(url.protocol) ||
+      !["127.0.0.1", "localhost", "[::1]"].includes(url.hostname) ||
+      url.username ||
+      url.password
+    )
+      throw Error("Use credential-free local preview URLs; no production browsing");
+    return url;
+  });
+  if (!chromium) {
+    const require = createRequire(resolve(config.projectRoot ?? process.cwd(), "package.json"));
+    ({ chromium } = require("@playwright/test"));
+  }
+  await mkdir(config.outputDir, { recursive: true });
+  const browser = await chromium.launch({ headless: true }),
+    runs = [],
+    blocked = [];
+  try {
+    for (const [device, viewport] of [
+      ["mobile", { width: 390, height: 844 }],
+      ["desktop", { width: 1365, height: 900 }],
+    ])
+      for (const javaScriptEnabled of [true, false]) {
+        const captures = [];
+        for (const [i, url] of urls.entries()) {
+          const context = await browser.newContext({
+            viewport,
+            javaScriptEnabled,
+            reducedMotion: "reduce",
+            serviceWorkers: "block",
+          });
+          try {
+            if (typeof context.routeWebSocket !== "function")
+              throw Error("Read-only previews require Playwright WebSocket routing support");
+            await context.routeWebSocket("**/*", (socket) => {
+              blocked.push({ method: "WEBSOCKET", url: socket.url() });
+              socket.close();
+            });
+            await context.route("**/*", (route) => {
+              const request = route.request();
+              if (
+                new URL(request.url()).origin !== url.origin ||
+                !["GET", "HEAD"].includes(request.method())
+              ) {
+                blocked.push({ method: request.method(), url: request.url() });
+                return route.abort();
+              }
+              return route.continue();
+            });
+            const page = await context.newPage();
+            const response = await page.goto(url.href, {
+              waitUntil: "networkidle",
+              timeout: 30000,
+            });
+            if (!response || response.status() !== 200)
+              throw Error(
+                `Preview must return HTTP 200: ${url.href} (${response?.status() ?? "no response"})`,
+              );
+            if (!/^text\/html\b/i.test(response.headers()["content-type"] ?? ""))
+              throw Error("Preview must return HTML");
+            await page.evaluate(() => document.fonts.ready);
+            if (config.readySelector && javaScriptEnabled)
+              await page.waitForSelector(config.readySelector, { timeout: 10000 });
+            captures.push(await page.evaluate(visualSnapshot));
+            const stem = `${device}-${javaScriptEnabled ? "js" : "nojs"}-${i ? "candidate" : "baseline"}`;
+            await page.screenshot({
+              path: resolve(config.outputDir, stem + "-full.png"),
+              fullPage: true,
+            });
+            await page.evaluate(() => window.scrollTo(0, document.documentElement.scrollHeight));
+            await page.screenshot({ path: resolve(config.outputDir, stem + "-end.png") });
+          } finally {
+            await context.close();
+          }
+        }
+        runs.push({
+          device,
+          javaScriptEnabled,
+          before: captures[0],
+          after: captures[1],
+          ...compareVisualSnapshots(...captures, { approvedFooterLink: config.approvedFooterLink }),
+        });
+      }
+    const result = {
+      kind: "zaip-visual-preservation",
+      passed: runs.every((r) => r.passed),
+      runs,
+      blocked,
+      conditions: {
+        tool: "Playwright Chromium",
+        version: browser.version(),
+        date: new Date().toISOString(),
+        urls: urls.map((u) => u.href),
+        dpr: 1,
+        reducedMotion: "reduce",
+        cache: "new contexts",
+        source: config.source ?? null,
+      },
+      screenshots_inspected: false,
+      limitations: [
+        "Inspect the generated screenshots; successful capture is not visual acceptance.",
+        "Local previews only; external resources and writes blocked. No consumer form or production integration tested.",
+      ],
+    };
+    await writeFile(
+      resolve(config.outputDir, "design-report.json"),
+      JSON.stringify(result, null, 2) + "\n",
+    );
+    return result;
+  } finally {
+    await browser.close();
+  }
+}
+if (process.argv[1] && import.meta.url === pathToFileURL(resolve(process.argv[1])).href) {
+  if (process.argv.length !== 3)
+    throw Error("Usage: node verify-site-design.mjs design-check.json");
+  const report = await verifySiteDesign(JSON.parse(await readFile(process.argv[2], "utf8")));
+  process.stdout.write(JSON.stringify(report, null, 2) + "\n");
+  if (!report.passed) process.exitCode = 1;
+}

package/templates/.agents/skills/zaip-skill-website-readiness/scripts/visual-preservation.mjs

@@ -0,0 +1,160 @@
+/** Runs inside a real browser, with JS enabled and disabled in separate contexts. */
+export function visualSnapshot() {
+  const rect = (el) => {
+    const r = el.getBoundingClientRect();
+    return [r.x, r.y, r.width, r.height].map((v) => Math.round(v * 100) / 100);
+  };
+  const footer = [...document.querySelectorAll('footer,[role="contentinfo"]')].find(
+    (el) => el.getBoundingClientRect().height > 0,
+  );
+  const technical = "script,style,link,meta,template,head";
+  const elements = [];
+  for (const el of document.body.querySelectorAll("*")) {
+    if (el.closest(technical)) continue;
+    const text = [...el.childNodes]
+      .filter((n) => n.nodeType === Node.TEXT_NODE)
+      .map((n) => n.textContent)
+      .join(" ")
+      .replace(/\s+/g, " ")
+      .trim();
+    const tag = el.tagName.toLowerCase(),
+      href = el.getAttribute("href");
+    if (
+      !text &&
+      !href &&
+      !["img", "input", "select", "textarea", "button", "iframe", "video", "canvas"].includes(tag)
+    )
+      continue;
+    const css = getComputedStyle(el),
+      box = rect(el);
+    const hidden = el.checkVisibility
+      ? !el.checkVisibility({ checkOpacity: true, checkVisibilityCSS: true })
+      : css.display === "none" || css.visibility === "hidden" || box[2] === 0 || box[3] === 0;
+    elements.push({
+      tag,
+      text,
+      href,
+      alt: el.getAttribute("alt"),
+      role: el.getAttribute("role"),
+      hidden,
+      box,
+      inFooter: Boolean(footer?.contains(el)),
+      afterFooter: Boolean(
+        footer &&
+          !footer.contains(el) &&
+          footer.compareDocumentPosition(el) & Node.DOCUMENT_POSITION_FOLLOWING,
+      ),
+      font: [css.fontFamily, css.fontSize, css.fontWeight, css.lineHeight, css.color],
+      // Retain legitimate hidden/a11y/interactive content in the baseline rather than blacklist classes.
+      interactive: Boolean(el.closest('dialog,[role="dialog"],[aria-live]')),
+    });
+  }
+  return {
+    schema: 1,
+    viewport: [innerWidth, innerHeight],
+    elements,
+    footer: footer ? rect(footer) : null,
+    page: [document.documentElement.scrollWidth, document.documentElement.scrollHeight],
+    overflow: document.documentElement.scrollWidth > innerWidth,
+    title: document.title,
+    jsonld: [...document.querySelectorAll('head script[type="application/ld+json"]')].map(
+      (el) => el.textContent,
+    ),
+  };
+}
+
+/** Human approval is source evidence, not a boolean silently inferred by the checker. */
+export function compareVisualSnapshots(
+  before,
+  after,
+  { approvedFooterLink, tolerancePx = 1 } = {},
+) {
+  if (
+    before?.schema !== 1 ||
+    after?.schema !== 1 ||
+    JSON.stringify(before.viewport) !== JSON.stringify(after.viewport)
+  )
+    throw Error("Comparable browser snapshots required");
+  if (!Number.isFinite(tolerancePx) || tolerancePx < 0 || tolerancePx > 2)
+    throw Error("Use equivalent capture conditions; tolerance is at most 2px");
+  const findings = [];
+  let current = after.elements;
+  if (approvedFooterLink) {
+    const p = approvedFooterLink;
+    if (
+      typeof p.authorization !== "string" ||
+      !p.authorization.trim() ||
+      typeof p.text !== "string" ||
+      typeof p.href !== "string"
+    )
+      throw Error("Exact visible link and human authorization reference required");
+    const matches = current.filter(
+      (el) => el.tag === "a" && el.href === p.href && el.text === p.text,
+    );
+    if (matches.length !== 1 || !matches[0].inFooter || matches[0].hidden)
+      findings.push({
+        code: "approved-link-contract",
+        detail: "Expected exactly the agreed visible link inside the existing footer",
+      });
+    else current = current.filter((el) => el !== matches[0]);
+  }
+  const shape = (el) =>
+    JSON.stringify([
+      el.tag,
+      el.text,
+      el.href,
+      el.alt,
+      el.role,
+      el.hidden,
+      el.inFooter,
+      el.interactive,
+    ]);
+  if (JSON.stringify(before.elements.map(shape)) !== JSON.stringify(current.map(shape)))
+    findings.push({
+      code: "presentation-content-changed",
+      detail:
+        "Content/structure changed irrespective of component name; review authorization, accessibility and interactive changes",
+    });
+  const oldAfter = before.elements
+    .filter((el) => el.afterFooter && !el.hidden && !el.interactive)
+    .map(shape);
+  const newAfter = current
+    .filter((el) => el.afterFooter && !el.hidden && !el.interactive)
+    .map(shape);
+  if (JSON.stringify(oldAfter) !== JSON.stringify(newAfter))
+    findings.push({
+      code: "editorial-after-footer",
+      detail: "Visible content after footer differs from approved baseline",
+    });
+  if (before.elements.length === current.length)
+    for (let i = 0; i < current.length; i++) {
+      if (shape(before.elements[i]) !== shape(current[i])) continue;
+      if (
+        current[i].box.some((v, j) => Math.abs(v - before.elements[i].box[j]) > tolerancePx) ||
+        JSON.stringify(current[i].font) !== JSON.stringify(before.elements[i].font)
+      ) {
+        findings.push({
+          code: "presentation-geometry-changed",
+          detail: `Rendered element ${i} moved or changed typography`,
+        });
+        break;
+      }
+    }
+  if (
+    JSON.stringify(before.footer) !== JSON.stringify(after.footer) ||
+    after.page.some((v, i) => Math.abs(v - before.page[i]) > tolerancePx)
+  )
+    findings.push({
+      code: "footer-or-page-geometry-changed",
+      detail: "Footer/page dimensions require explicit visual approval",
+    });
+  if (after.overflow && !before.overflow) findings.push({ code: "horizontal-overflow" });
+  return {
+    passed: findings.length === 0,
+    findings,
+    limitations: [
+      "Measured DOM and geometry are not universal pixel or accessibility proof. Inspect comparable mobile/desktop screenshots, including page end.",
+      "A changed legitimate modal or accessibility aid requires targeted review; this report does not label it cloaking.",
+    ],
+  };
+}