@tokenoftrust/cli 2.0.24 → 2.0.25

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenoftrust/cli",
-  "version": "2.0.24",
+  "version": "2.0.25",
   "description": "Token of Trust developer CLI — clone a tenant store, run it locally with save→reload, and submit it for preview. Installs the `tot` command.",
   "license": "Apache-2.0",
   "author": "Token of Trust",
@@ -36,6 +36,9 @@
     "access": "public",
     "registry": "https://registry.npmjs.org"
   },
+  "dependencies": {
+    "sharp": "^0.34.5"
+  },
   "devDependencies": {
     "@types/node": "^20.16.0",
     "typescript": "^5.6.3"

package/src/commands/revert.mjs

@@ -24,12 +24,13 @@
  *
  * TRANSPORT — `POST /api/changes/revert` (opens the corrective candidate, then
  * runs it through the SAME `TenantIntegrationQueue.enqueue` accept pipeline
- * `tot accept` drives). Like `tot accept` / `tot ship`, the CLI reaches it with
- * the OPERATOR-SECRET Bearer transport (`resolveOperatorSecret` + `X-Tot-Owner`
- * + `x-tot-capability`). The response is the honest terminal aggregate state —
- * `queueState` / `runState` / `pointerMoved` / `aggregateSha` / `changeId` (the
- * corrective candidate's own id) / `statusMessage` — rendered VERBATIM, never a
- * bare "reverted".
+ * `tot accept` drives). Like `tot accept`, the CLI reaches it with either the
+ * operator-secret Bearer transport (`resolveOperatorSecret` + `X-Tot-Owner` +
+ * `x-tot-capability`) or a signed-in developer's viewer session when they hold
+ * a live `ship-on-behalf` grant. The response is the honest terminal aggregate
+ * state — `queueState` / `runState` / `pointerMoved` / `aggregateSha` /
+ * `changeId` (the corrective candidate's own id) / `statusMessage` — rendered
+ * VERBATIM, never a bare "reverted".
  *
  * HUMAN GATE — correcting the shared preview is a decision a human makes, so
  * this ALWAYS states the EXACT plan (a NEW corrective candidate, merged through
@@ -44,6 +45,9 @@ import { planForAction, printPlanAndConfirm } from "../plan.mjs";
 // Reuse `tot ship`'s operator-secret precedence verbatim so accept + ship + revert
 // speak ONE operator-auth contract.
 import { resolveOperatorSecret } from "./ship.mjs";
+// No-operator-secret path: mint a viewer session from the developer's OWN `tot`
+// login. The server still gates the request on their live ship-on-behalf grant.
+import { resolveViewerTransport } from "../viewer-session.mjs";
 
 const DEFAULT_STOREFRONT_URL = "https://storefront.tokenoftrust.store";
 
@@ -97,6 +101,9 @@ Options:
 
   To undo something already LIVE, use \`tot rollback\` — not \`tot revert\`.
 
+  Authentication: a signed-in developer with a live \`ship-on-behalf\` grant can
+  use their own \`tot login\` session. Operators/CI may instead provide a secret.
+
   Operator secret (from env, first found): PREVIEW_RECONCILE_SECRET,
   GRANTS_ADMIN_SECRET, TOT_OPERATOR_SECRET (or pass --secret).`;
 
@@ -212,22 +219,25 @@ export function reportReverted(result, { tenant, label }) {
 
 /**
  * The revert flow after args are parsed: state the exact plan, confirm, then POST
- * `/api/changes/revert` (operator-secret transport) and render the honest terminal
- * aggregate status. `fetch`/`confirmPlan` injected so it is unit-tested with no
- * network/TTY.
+ * `/api/changes/revert` over either the operator-secret or developer viewer-session
+ * transport and render the honest terminal aggregate status. Dependencies are
+ * injected so it is unit-tested with no network/TTY.
  *
  * @param {{ tenant:string, prNumber:number|null, changeId:string|null,
- *   message:string|null, secret:string, storefrontUrl?:string|null, yes?:boolean }} params
- * @param {{ fetch?:typeof fetch, confirmPlan?:typeof printPlanAndConfirm }} [deps]
+ *   message:string|null, secret:string, storefrontUrl?:string|null, yes?:boolean,
+ *   env?:NodeJS.ProcessEnv }} params
+ * @param {{ fetch?:typeof fetch, confirmPlan?:typeof printPlanAndConfirm,
+ *   resolveViewerTransport?:typeof resolveViewerTransport }} [deps]
  * @returns {Promise<number>} process exit code
  */
 export async function runRevert(
-  { tenant, prNumber, changeId, message = null, secret, storefrontUrl = null, yes = false },
+  { tenant, prNumber, changeId, message = null, secret, storefrontUrl = null, yes = false, env = process.env },
   deps = {},
 ) {
   const fetchImpl = deps.fetch || globalThis.fetch;
   const confirmPlan = deps.confirmPlan || printPlanAndConfirm;
-  const base = (storefrontUrl || DEFAULT_STOREFRONT_URL).trim().replace(/\/+$/, "");
+  const resolveViewer = deps.resolveViewerTransport || resolveViewerTransport;
+  let base = (storefrontUrl || DEFAULT_STOREFRONT_URL).trim().replace(/\/+$/, "");
   const label = prNumber != null ? `PR #${prNumber}` : `change ${changeId}`;
 
   // 1. State the EXACT plan (shared affordance) — a NEW corrective candidate
@@ -257,22 +267,25 @@ export async function runRevert(
     return 1;
   }
 
-  // 2. Operator-secret transport — the CLI holds no storefront cookie.
-  if (!secret) {
-    console.error(
-      fail(
-        "undoing an integrated PR is an OPERATOR action — it needs an operator secret",
-        "set PREVIEW_RECONCILE_SECRET (or GRANTS_ADMIN_SECRET / TOT_OPERATOR_SECRET), or pass --secret",
-      ),
-    );
-    return 2;
+  // 2. Resolve the transport. Operators/CI use the secret on the generic host;
+  //    invited developers use their own `tot login` identity on the tenant-scoped
+  //    host. Both reach the same server route and the same live capability gate.
+  let authHeaders;
+  if (secret) {
+    authHeaders = {
+      authorization: `Bearer ${secret}`,
+      "x-tot-owner": tenant,
+      "x-tot-capability": "ship-on-behalf",
+    };
+  } else {
+    const viewer = await resolveViewer({ tenant, env, fetchImpl, storefrontUrl });
+    if (!viewer.ok) {
+      console.error(fail(viewer.message, viewer.hint));
+      return 2;
+    }
+    base = viewer.base;
+    authHeaders = viewer.authHeaders;
   }
-  const authHeaders = {
-    "content-type": "application/json",
-    authorization: `Bearer ${secret}`,
-    "x-tot-owner": tenant,
-    "x-tot-capability": "ship-on-behalf",
-  };
   const requestBody = {
     repo: tenant,
     ...(prNumber != null ? { prNumber } : {}),
@@ -285,7 +298,7 @@ export async function runRevert(
   try {
     res = await fetchImpl(`${base}/api/changes/revert`, {
       method: "POST",
-      headers: authHeaders,
+      headers: { "content-type": "application/json", ...authHeaders },
       body: JSON.stringify(requestBody),
     });
   } catch (e) {
@@ -311,7 +324,7 @@ export async function runRevert(
       fail(
         `the revert request was refused: ${msg}`,
         res.status === 401 || res.status === 403
-          ? "check the operator secret and that it's authorised for this tenant"
+          ? "you need a live ship-on-behalf grant on this tenant (ask the store owner) — or an operator secret authorised for it"
           : "check --tenant / --url / --preview, then re-run",
       ),
     );
@@ -366,5 +379,6 @@ export async function run(argv, ctx) {
     secret: resolveOperatorSecret(args.secret, env),
     storefrontUrl,
     yes: args.yes,
+    env,
   });
 }

package/src/commands/validate.mjs

@@ -16,14 +16,19 @@
 import { existsSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { validateTenant, ERROR, WARN, printLoudAdvisories } from "../validate.mjs";
+import { validateVisualParityClosure } from "../visual-parity.mjs";
 import { fail } from "../errors.mjs";
 import { tenantDirSegments } from "../tenant-dirs.mjs";
 
+const mergeFindings = (...groups) => [...new Map(groups.flat().map((item) => [JSON.stringify(item), item])).values()]
+  .sort((a, b) => `${a.file}\0${a.rule}\0${a.message}`.localeCompare(`${b.file}\0${b.rule}\0${b.message}`));
+
 function parseArgs(argv) {
-  const a = { tenant: null, workspace: null, json: false, help: false };
+  const a = { tenant: null, workspace: null, json: false, help: false, profile: null, profileSpecified: false };
   for (let i = 0; i < argv.length; i++) {
     const t = argv[i];
     if (t === "--workspace") a.workspace = argv[++i];
+    else if (t === "--profile") { a.profileSpecified = true; a.profile = argv[++i] ?? null; }
     else if (t === "--json") a.json = true;
     else if (t === "--help" || t === "-h") a.help = true;
     else if (!t.startsWith("--") && !a.tenant) a.tenant = t;
@@ -36,6 +41,7 @@ const USAGE = `tot validate — lint your store before you submit
   tot validate                  (inside a checkout) lint this store
   tot validate <tenant>         (inside the monorepo) lint tenants/<tenant>/
   tot validate --workspace <dir>  lint a specific checkout directory
+  tot validate --profile visual-parity  close portable page/asset/link migration scope
   tot validate --json           machine-readable findings`;
 
 /**
@@ -78,7 +84,11 @@ export function run(argv, ctx) {
     return 2;
   }
 
-  const { ok, findings } = validateTenant(dir, {
+  if (args.profileSpecified && args.profile !== "visual-parity") {
+    console.error(fail(`unknown validation profile: ${args.profile}`, "use --profile visual-parity"));
+    return 2;
+  }
+  const baseline = validateTenant(dir, {
     tenantId: target.tenantId ?? undefined,
     scope: target.scope ?? undefined,
     // A checkout / bare-tenant target is served by the ToT storefront platform, so
@@ -86,6 +96,14 @@ export function run(argv, ctx) {
     // arbitrary --workspace <dir> stays conservative (unless its config resolves the host).
     mode: args.workspace ? "workspace" : "monorepo",
   });
+  const result = args.profile === "visual-parity"
+    ? (() => {
+      const parity = validateVisualParityClosure(dir, { tenantId: target.tenantId ?? undefined });
+      const findings = mergeFindings(baseline.findings, parity.findings);
+      return { ok: !findings.some((item) => item.level === ERROR), findings };
+    })()
+    : baseline;
+  const { ok, findings } = result;
 
   if (args.json) {
     console.log(JSON.stringify({ ok, findings }, null, 2));
@@ -105,7 +123,7 @@ export function run(argv, ctx) {
   // the findings below say why; the header should say so too, not disguise
   // a directory as a domain.
   const label = target.tenantId ? target.tenantId : `(tenant unresolved) ${target.dir}`;
-  console.log(`\ntot validate — ${label}\n`);
+  console.log(`\ntot validate${args.profile ? ` --profile ${args.profile}` : ""} — ${label}\n`);
   for (const f of findings) {
     const tag = f.level === ERROR ? "✗" : "⚠";
     console.log(`  ${tag} [${f.rule}] ${f.file}\n      ${f.message}${f.fix ? `\n      → ${f.fix}` : ""}`);

package/src/validate.mjs

@@ -142,8 +142,8 @@ function validateRawHtmlBody(html) {
 // CLI bundle can't reach the repo's public-runtime package at runtime (same
 // constraint as the KNOWN_EMBEDS mirror above), so this is a copy — parity
 // test: packages/public-runtime/tests/chrome-config-shape-parity.test.ts.
-const CHROME_HEADER_VARIANTS = new Set(["primary", "minimal"]);
-const CHROME_FOOTER_VARIANTS = new Set(["default"]);
+const CHROME_HEADER_VARIANTS = new Set(["primary", "minimal", "compact-centered"]);
+const CHROME_FOOTER_VARIANTS = new Set(["default", "light-collapsible"]);
 /**
  * The declarative-interaction-tracking rule, mirrored: every actionable item —
  * an object carrying both `id` and `href` — declares EXACTLY ONE of a non-empty

package/src/visual-parity.mjs

@@ -0,0 +1,321 @@
+/**
+ * Read-only closure checks for the optional visual-parity migration module.
+ * The tenant checkout remains portable: this reads only content/, public/, and
+ * .tot/visual-parity.json, never a preview host or a delivery provider.
+ */
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { extname, join, relative } from "node:path";
+
+const ERROR = "error";
+// Public routes implemented by the renderer. Authentication and cart URLs are
+// deliberately absent: they are flow-specific, not portable parity targets.
+const PLATFORM_ROUTES = ["/collections", "/collections/", "/products/", "/search", "/saved", "/account", "/account/", "/blog", "/blog/"];
+const ASSET_EXTENSIONS = new Set([".avif", ".gif", ".jpeg", ".jpg", ".png", ".svg", ".webp"]);
+
+const finding = (rule, file, message, fix) => ({ level: ERROR, rule, file, message, fix });
+const walk = (dir) => !existsSync(dir) ? [] : readdirSync(dir).flatMap((name) => {
+  const path = join(dir, name);
+  return statSync(path).isDirectory() ? walk(path) : [path];
+});
+const pointer = (parts) => parts.length ? `/${parts.map((part) => String(part).replace(/~/g, "~0").replace(/\//g, "~1")).join("/")}` : "/";
+const stripQuery = (value) => value.split(/[?#]/, 1)[0];
+const normalizeRoute = (value) => {
+  const path = stripQuery(value).replace(/\/+/g, "/").replace(/\/$/, "") || "/";
+  return path.startsWith("/") ? path : `/${path}`;
+};
+const hasDotSegment = (value) => stripQuery(value).split("/").some((part) => part === "." || part === ".." || /^%2e(?:%2e)?$/i.test(part));
+const safeLocator = (value) => {
+  try {
+    const url = new URL(value.startsWith("//") ? `https:${value}` : value);
+    return url.origin;
+  } catch {
+    if (value.startsWith("/")) return normalizeRoute(value);
+    return "[redacted authored value]";
+  }
+};
+
+function parseConfig(tenantDir) {
+  const path = join(tenantDir, ".tot", "visual-parity.json");
+  if (!existsSync(path)) return { value: {}, findings: [] };
+  try {
+    const value = JSON.parse(readFileSync(path, "utf8"));
+    if (!value || Array.isArray(value) || typeof value !== "object") throw new Error("must be a JSON object");
+    const findings = [];
+    if (value.externalNavigationAllowlist !== undefined && !Array.isArray(value.externalNavigationAllowlist)) {
+      findings.push(finding("parity-config-shape", ".tot/visual-parity.json", "externalNavigationAllowlist must be an array of HTTPS origins or URLs", "replace it with an explicit reviewed array, for example [\"https://partner.example\"]"));
+    }
+    for (const [index, entry] of (Array.isArray(value.externalNavigationAllowlist) ? value.externalNavigationAllowlist : []).entries()) {
+      try {
+        const url = new URL(entry);
+        if (typeof entry !== "string" || url.protocol !== "https:" || url.username || url.password || /[?#]/.test(entry)) throw new Error("invalid");
+      } catch {
+        findings.push(finding("parity-allowlist-entry", `.tot/visual-parity.json/externalNavigationAllowlist/${index}`, "allowlist entries must be HTTPS origins or exact path prefixes without credentials, query, or fragment", "use https://partner.example for an origin or https://partner.example/returns for that path boundary"));
+      }
+    }
+    return { value, findings };
+  } catch {
+    return { value: {}, findings: [finding("parity-config-parse", ".tot/visual-parity.json", "invalid JSON", "fix .tot/visual-parity.json before closing visual parity")] };
+  }
+}
+
+function tenantFromConfig(tenantDir) {
+  try {
+    const value = JSON.parse(readFileSync(join(tenantDir, ".tot", "config.json"), "utf8"));
+    return typeof value?.tenant === "string" ? value.tenant : null;
+  } catch { return null; }
+}
+
+function allowedNavigation(value, allowlist) {
+  try {
+    const url = new URL(value);
+    return allowlist.some((entry) => {
+      try {
+        const allowed = new URL(entry);
+        if (allowed.protocol !== "https:" || allowed.username || allowed.password) return false;
+        if (allowed.pathname === "/") return url.origin === allowed.origin;
+        return url.origin === allowed.origin && (url.pathname === allowed.pathname || url.pathname.startsWith(`${allowed.pathname.replace(/\/$/, "")}/`));
+      } catch { return false; }
+    });
+  } catch { return false; }
+}
+
+function assetType(bytes) {
+  const ascii = bytes.subarray(0, 256).toString("utf8").trimStart().toLowerCase();
+  if (pngValid(bytes)) return ".png";
+  if (bytes.subarray(0, 3).toString("ascii") === "GIF") return ".gif";
+  if (jpegValid(bytes)) return ".jpg";
+  if (bytes.subarray(0, 4).toString("ascii") === "RIFF" && bytes.subarray(8, 12).toString("ascii") === "WEBP") return ".webp";
+  if (bytes.subarray(4, 8).toString("ascii") === "ftyp" && bytes.subarray(8, 12).toString("ascii").toLowerCase().includes("avif")) return ".avif";
+  if (bytes.subarray(0, 4).toString("ascii") === "wOFF") return ".woff";
+  if (bytes.subarray(0, 4).toString("ascii") === "wOF2") return ".woff2";
+  if (icoValid(bytes)) return ".ico";
+  if (ascii.startsWith("<svg") || ascii.startsWith("<?xml") && ascii.includes("<svg")) return ".svg";
+  return null;
+}
+function pngValid(bytes) {
+  if (bytes.length < 45 || !bytes.subarray(0, 8).equals(Buffer.from([137,80,78,71,13,10,26,10]))) return false;
+  let pos = 8, sawIhdr = false;
+  let sawIdat = false;
+  while (pos + 12 <= bytes.length) {
+    const length = bytes.readUInt32BE(pos); const type = bytes.subarray(pos + 4, pos + 8).toString("ascii");
+    if (length > bytes.length - pos - 12) return false;
+    if (type === "IHDR") { if (sawIhdr || length !== 13 || bytes.readUInt32BE(pos + 8) === 0 || bytes.readUInt32BE(pos + 12) === 0) return false; sawIhdr = true; }
+    if (type === "IDAT" && length > 0) sawIdat = true;
+    pos += 12 + length; if (type === "IEND") return sawIhdr && sawIdat && length === 0 && pos === bytes.length;
+  } return false;
+}
+function jpegValid(bytes) {
+  if (bytes.length < 10 || bytes[0] !== 0xff || bytes[1] !== 0xd8) return false;
+  let pos = 2, sof = false;
+  while (pos < bytes.length) {
+    if (bytes[pos++] !== 0xff) return false; while (bytes[pos] === 0xff) pos++;
+    const marker = bytes[pos++]; if (marker === 0xd9) return sof && pos === bytes.length;
+    if (marker === 0xda) { if (pos + 2 > bytes.length) return false; const length = bytes.readUInt16BE(pos); const scan = pos + length; return sof && scan < bytes.length - 2 && bytes[bytes.length - 2] === 0xff && bytes[bytes.length - 1] === 0xd9; }
+    if (marker === 0x01 || marker >= 0xd0 && marker <= 0xd7) continue;
+    if (pos + 2 > bytes.length) return false; const length = bytes.readUInt16BE(pos); if (length < 2 || pos + length > bytes.length) return false;
+    if (marker >= 0xc0 && marker <= 0xc3 && length >= 8) { if (bytes.readUInt16BE(pos + 3) === 0 || bytes.readUInt16BE(pos + 5) === 0) return false; sof = true; }
+    pos += length;
+  } return false;
+}
+function icoValid(bytes) {
+  if (bytes.length < 22 || bytes.readUInt16LE(0) !== 0 || bytes.readUInt16LE(2) !== 1) return false;
+  const count = bytes.readUInt16LE(4); if (!count || bytes.length < 6 + count * 16) return false;
+  for (let i = 0; i < count; i++) { const at = 6 + i * 16, size = bytes.readUInt32LE(at + 8), offset = bytes.readUInt32LE(at + 12); if (size && offset >= 6 + count * 16 && offset + size <= bytes.length) { const payload = bytes.subarray(offset, offset + size); if (pngValid(payload) || payload.length >= 40 && payload.readInt32LE(0) >= 40 && payload.readInt32LE(4) > 0 && payload.readInt32LE(8) > 0) return true; } }
+  return false;
+}
+
+function checkAsset(value, at, file, context) {
+  const { findings, tenantId, publicDir } = context;
+  if (!value || value.startsWith("#")) return;
+  if (/^data:/i.test(value)) {
+    findings.push(finding("parity-data-asset", `${file}${at}`, "embedded data assets are not portable parity inputs", "copy the asset into public/ and use a tenant-local path"));
+    return;
+  }
+  if (/^[a-z][a-z\d+.-]*:/i.test(value) || value.startsWith("//")) {
+    findings.push(finding("parity-external-asset", `${file}${at}`, `asset source ${safeLocator(value)} is off-host`, "copy the asset into public/ and reference it with /tenants/<tenant>/..."));
+    return;
+  }
+  const path = stripQuery(value);
+  let rel;
+  if (path.startsWith("/tenants/")) {
+    const prefix = `/tenants/${tenantId}/`;
+    if (!tenantId || !path.startsWith(prefix)) {
+      findings.push(finding("parity-cross-tenant-asset", `${file}${at}`, "asset does not belong to this tenant", "copy the asset into this tenant's public/ directory"));
+      return;
+    }
+    rel = path.slice(prefix.length);
+  } else if (path.startsWith("/")) {
+    findings.push(finding("parity-unowned-asset", `${file}${at}`, "asset is not tenant-local", "use a tenant-local asset committed under public/"));
+    return;
+  } else rel = path;
+  if (!rel || hasDotSegment(rel)) {
+    findings.push(finding("parity-asset-path", `${file}${at}`, "asset path escapes or does not name public/", "use a direct tenant-local path under public/"));
+    return;
+  }
+  const asset = join(publicDir, rel);
+  if (!existsSync(asset)) {
+    findings.push(finding("parity-asset-missing", `${file}${at}`, "tenant-local asset is absent from public/", "add the referenced asset under public/ or correct the reference"));
+    return;
+  }
+  const extension = extname(rel).toLowerCase();
+  if (!ASSET_EXTENSIONS.has(extension)) {
+    findings.push(finding("parity-asset-extension", `${file}${at}`, "asset has an unsupported extension", "re-export favicon/assets as PNG or SVG; font containers require platform-managed validation"));
+    return;
+  }
+  if (statSync(asset).isDirectory()) {
+    findings.push(finding("parity-asset-directory", `${file}${at}`, "asset names a directory", "reference a file under public/"));
+    return;
+  }
+  if (ASSET_EXTENSIONS.has(extension)) {
+    const actual = assetType(readFileSync(asset));
+    const compatible = actual === extension || actual === ".jpg" && extension === ".jpeg";
+    if (!actual) findings.push(finding("parity-asset-undecodable", `${file}${at}`, `asset does not pass bounded ${extension} structural integrity checks`, "replace it with a structurally valid file of the declared type"));
+    else if (!compatible) findings.push(finding("parity-asset-type", `${file}${at}`, `asset bytes do not match the ${extension} extension`, "export the asset in the declared format"));
+    else if ([".png", ".jpg", ".jpeg", ".gif", ".webp", ".avif", ".svg"].includes(extension)) context.decodeAssets.push({ asset, file: `${file}${at}` });
+  }
+}
+
+function decodeImages(entries) {
+  if (!entries.length) return new Set();
+  const source = "const{createRequire}=require('node:module');const sharp=createRequire(process.argv[1])('sharp');(async()=>{let a=JSON.parse(process.argv[2]);let o=[];for(const p of a){try{let r=await sharp(p,{failOn:'error'}).raw().toBuffer({resolveWithObject:true});o.push(r.info.width>0&&r.info.height>0)}catch{o.push(false)}}process.stdout.write(JSON.stringify(o))})().catch(()=>process.exit(1));";
+  const result = spawnSync(process.execPath, ["-e", source, import.meta.url, JSON.stringify(entries.map((entry) => entry.asset))], { encoding: "utf8", timeout: 15000 });
+  try { if (result.status !== 0) throw new Error(); const output = JSON.parse(result.stdout); return new Set(entries.flatMap((_, index) => output[index] ? [] : [index])); } catch { return new Set(entries.map((_, index) => index)); }
+}
+
+function inspectHtml(html, file, at, context) {
+  const attr = /\b(href|src)\s*=\s*(?:(["'])(.*?)\2|([^\s>]+))/gi;
+  let index = 0;
+  for (const match of html.matchAll(attr)) {
+    const value = (match[3] ?? match[4] ?? "").trim();
+    inspectReference(match[1].toLowerCase(), value, `${at}/html-attribute-${index++}`, file, context);
+  }
+}
+function inspectReference(kind, value, at, file, context) {
+  if (kind === "src") return checkAsset(value, at, file, context);
+  if (!value || value.startsWith("#") || /^(mailto:|tel:)/i.test(value)) return;
+  if (/^(javascript|vbscript|data):/i.test(value)) {
+    context.findings.push(finding("parity-executable-link", `${file}${at}`, "link uses an executable scheme", "replace it with a local route or a reviewed HTTPS destination"));
+    return;
+  }
+  if (/^https?:\/\//i.test(value) || value.startsWith("//")) {
+    if (!allowedNavigation(value.startsWith("//") ? `https:${value}` : value, context.allowlist)) context.findings.push(finding("parity-external-navigation", `${file}${at}`, `external navigation ${safeLocator(value)} is not on the reviewed allowlist`, "add its HTTPS origin or URL to .tot/visual-parity.json only after human review"));
+    return;
+  }
+  if (!value.startsWith("/")) {
+    context.findings.push(finding("parity-relative-link", `${file}${at}`, "relative link has no stable paired route", "use a root-absolute local route"));
+    return;
+  }
+  if (hasDotSegment(value)) {
+    context.findings.push(finding("parity-route-path", `${file}${at}`, "local route contains a dot segment", "use a canonical root-absolute route"));
+    return;
+  }
+  const route = normalizeRoute(value);
+  if (!context.routes.has(route) && !PLATFORM_ROUTES.some((platform) => platform.endsWith("/") ? route.startsWith(platform) : route === platform)) context.findings.push(finding("parity-route-missing", `${file}${at}`, "local route is not declared by a page slug or platform", "add the matching content/pages JSON record or correct the link"));
+}
+
+function inspectValue(value, file, parts, context) {
+  if (Array.isArray(value)) return value.forEach((item, index) => inspectValue(item, file, [...parts, index], context));
+  if (!value || typeof value !== "object") return;
+  for (const [key, child] of Object.entries(value)) {
+    const next = [...parts, key];
+    if (key === "body_html" && typeof child === "string") inspectHtml(child, file, pointer(next), context);
+    if ((key === "href" || key === "ctaHref") && typeof child === "string") inspectReference("href", child, pointer(next), file, context);
+    if ((key === "src" || key === "image" || key === "icon" || key === "logo" || key === "logoDark" || key === "favicon") && typeof child === "string") checkAsset(child, pointer(next), file, context);
+    if (typeof child === "string" && /(?:css|style|stylesheet)$/i.test(key)) {
+      for (const match of child.matchAll(/url\(\s*(["']?)(.*?)\1\s*\)/gi)) checkAsset(match[2].trim(), `${pointer(next)}/css`, file, context);
+    }
+    inspectValue(child, file, next, context);
+  }
+}
+
+function pageShape(value, file) {
+  const findings = [];
+  const required = [["slug", "string"], ["title", "string"]];
+  for (const [key, type] of required) {
+    const valid = type === "array" ? Array.isArray(value[key]) : typeof value[key] === type;
+    if (!valid || (type === "string" && value[key].trim() === "")) findings.push(finding("parity-page-field", `${file}/${key}`, `${key} must be a non-empty ${type}`, `set ${key} to the page value expected by the renderer`));
+  }
+  if (value.isPolicy !== undefined && typeof value.isPolicy !== "boolean") findings.push(finding("parity-page-field", `${file}/isPolicy`, "isPolicy must be a boolean when present", "set isPolicy to true or false"));
+  if (value.sections !== undefined && !Array.isArray(value.sections)) findings.push(finding("parity-page-field", `${file}/sections`, "sections must be an array when present", "set sections to an array of renderer-supported sections"));
+  if (Array.isArray(value.sections)) value.sections.forEach((section, index) => {
+    const at = `${file}/sections/${index}`;
+    if (!section || typeof section !== "object" || Array.isArray(section)) return findings.push(finding("parity-section-shape", at, "section must be an object", "use a renderer-supported prose section"));
+    const string = (v) => typeof v === "string" && v.trim() !== "";
+    const rich = (v) => typeof v === "string" ? v.trim() !== "" : Array.isArray(v) && v.length > 0 && v.every((run) => run && typeof run === "object" && !Array.isArray(run) && ((run.kind === "text" && string(run.text) && (run.strong === undefined || typeof run.strong === "boolean") && (run.em === undefined || typeof run.em === "boolean")) || (run.kind === "link" && string(run.text) && string(run.href) && (run.external === undefined || typeof run.external === "boolean"))));
+    switch (section.kind) {
+      case "heading": if (!string(section.text) || section.level !== undefined && section.level !== 2 && section.level !== 3 || section.id !== undefined && !string(section.id)) findings.push(finding("parity-section-shape", at, "heading requires string text, optional id, and level 2 or 3", "supply a valid heading")); break;
+      case "paragraph": if (!rich(section.text)) findings.push(finding("parity-section-shape", at, "paragraph requires RichText", "supply a valid string or inline-run array")); break;
+      case "list": if (!Array.isArray(section.items) || !section.items.length || section.items.some((item) => !rich(item)) || section.ordered !== undefined && typeof section.ordered !== "boolean") findings.push(finding("parity-section-shape", at, "list requires RichText items and optional boolean ordered", "supply valid list items")); break;
+      case "definitions": if (!Array.isArray(section.items) || !section.items.length || section.items.some((item) => !item || !string(item.term) || !rich(item.description))) findings.push(finding("parity-section-shape", at, "definitions require string terms and RichText descriptions", "supply valid definition items")); break;
+      case "callout": if (!rich(section.body) || !["info", "warning", "legal", "success"].includes(section.tone) || section.title !== undefined && !string(section.title)) findings.push(finding("parity-section-shape", at, "callout requires supported tone, RichText body, and optional string title", "supply a valid callout")); break;
+      case "contact": if (section.heading !== undefined && !string(section.heading) || section.email !== undefined && !string(section.email) || section.phone !== undefined && !string(section.phone) || section.address !== undefined && (!Array.isArray(section.address) || section.address.some((line) => !string(line))) || !string(section.email) && !string(section.phone) && !(Array.isArray(section.address) && section.address.length)) findings.push(finding("parity-section-shape", at, "contact requires string members and email, phone, or address", "supply valid contact details")); break;
+      case "needs_review": if (!string(section.reason) || section.severity !== undefined && !["blocker", "note"].includes(section.severity) || section.owner !== undefined && !string(section.owner) || section.href !== undefined && !string(section.href)) findings.push(finding("parity-section-shape", at, "needs_review requires reason and valid optional severity/owner/href", "supply a valid needs_review section")); break;
+      default: findings.push(finding("parity-section-kind", `${at}/kind`, "section kind is not supported by the renderer", "use heading, paragraph, list, definitions, callout, contact, or needs_review"));
+    }
+  });
+  const bodyHtml = typeof value.body_html === "string" && value.body_html.trim() !== "";
+  const sections = Array.isArray(value.sections) && value.sections.length > 0;
+  if (!bodyHtml && !sections) findings.push(finding("parity-page-body", file, "page needs non-empty body_html or non-empty sections", "add rendered body_html or one or more sections"));
+  return findings;
+}
+
+function readStructured(path, file, findings) {
+  try { return JSON.parse(readFileSync(path, "utf8")); }
+  catch { findings.push(finding("parity-content-parse", file, "invalid JSON", "repair the JSON before visual-parity closure")); return null; }
+}
+
+/** @typedef {{level:string, rule:string, file:string, message:string, fix:string}} ParityFinding */
+/** @typedef {{asset:string, file:string}} DecodeAsset */
+/** @typedef {{tenantId?: string}} VisualParityOptions */
+/** Validate the portable content closure required before human visual-parity review.
+ * @param {string} tenantDir
+ * @param {VisualParityOptions} [options]
+ */
+export function validateVisualParityClosure(tenantDir, options = {}) {
+  const { tenantId } = options;
+  /** @type {ParityFinding[]} */
+  const findings = [];
+  const { value: config, findings: configFindings } = parseConfig(tenantDir);
+  findings.push(...configFindings);
+  const pagesDir = join(tenantDir, "content", "pages");
+  const files = walk(pagesDir).filter((file) => file.endsWith(".json")).sort();
+  if (files.length === 0) findings.push(finding("parity-pages-missing", "content/pages/", "no page JSON files define the visual-parity route scope", "add the paired authored page records under content/pages/ before closing parity"));
+  const pages = [];
+  for (const path of files) {
+    const file = relative(tenantDir, path);
+    try {
+      const value = JSON.parse(readFileSync(path, "utf8"));
+      if (!value || Array.isArray(value) || typeof value !== "object") {
+        findings.push(finding("parity-page-shape", file, "page JSON must be an object", "write a page object with a non-empty slug")); continue;
+      }
+      findings.push(...pageShape(value, file));
+      if (typeof value.slug !== "string" || !value.slug.trim()) continue;
+      pages.push({ file, value });
+    } catch { findings.push(finding("parity-page-parse", file, "invalid JSON", "repair the JSON before visual-parity closure")); }
+  }
+  const routes = new Set(["/"]);
+  for (const page of pages) routes.add(normalizeRoute(page.value.slug));
+  /** @type {{findings:ParityFinding[], tenantId:string|null, publicDir:string, routes:Set<string>, allowlist:string[], decodeAssets:DecodeAsset[]}} */
+  const context = { findings, tenantId: tenantId ?? tenantFromConfig(tenantDir), publicDir: join(tenantDir, "public"), routes, allowlist: Array.isArray(config.externalNavigationAllowlist) ? config.externalNavigationAllowlist : [], decodeAssets: [] };
+  if (!context.tenantId) findings.push(finding("parity-tenant-id", ".tot/config.json", "tenant id is required to verify /tenants/<tenant>/ assets", "set tenant in .tot/config.json or pass a resolved tenant id"));
+  for (const page of pages) inspectValue(page.value, page.file, [], context);
+  for (const name of ["home.json", "chrome.json"]) {
+    const path = join(tenantDir, "content", name);
+    if (existsSync(path)) {
+      const value = readStructured(path, `content/${name}`, findings);
+      if (value != null) inspectValue(value, `content/${name}`, [], context);
+    }
+  }
+  const themePath = join(tenantDir, "theme.json");
+  if (existsSync(themePath)) {
+    const value = readStructured(themePath, "theme.json", findings);
+    if (value != null) inspectValue(value, "theme.json", [], context);
+  }
+  for (const index of decodeImages(context.decodeAssets)) {
+    const entry = context.decodeAssets[index];
+    if (entry) findings.push(finding("parity-asset-decode", entry.file, "image decoder could not produce nonzero pixels", "replace the image with a decodable file"));
+  }
+  findings.sort((a, b) => `${a.file}\0${a.rule}`.localeCompare(`${b.file}\0${b.rule}`));
+  return { ok: findings.length === 0, profile: "visual-parity", findings };
+}