@nextcommerce/campaigns-os 1.60.0 → 1.61.0

package/src/stage-record.mjs

@@ -23,12 +23,12 @@
 // stylesheets must also match the built output byte for byte).
 import { createHash } from "node:crypto";
 import { existsSync, readFileSync, statSync } from "node:fs";
-import { dirname, join, relative, resolve, sep } from "node:path";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 
 import Ajv2020 from "ajv/dist/2020.js";
 
-import { BRAND_LAYER_FILENAMES } from "./brand-theme.mjs";
+import { BRAND_FONTS_FILENAME, BRAND_LAYER_FILENAMES } from "./brand-theme.mjs";
 import { ADAPTER_DECISION_SCALAR_VALUES } from "./adapter-decision-contract.mjs";
 import { buildManifestEntries, computeBuildFingerprint, resolveBuiltSiteScope } from "./built-site-scope.mjs";
 import { resolveCampaignWorkspace, targetRepoFor } from "./campaign-workspace.mjs";
@@ -127,7 +127,7 @@ function typeName(value) {
 
 // visual_review keys only `polish capture` writes. `record polish --evidence`
 // refuses them by name and carries the captured values forward.
-export const PACKAGE_OWNED_VISUAL_REVIEW_KEYS = Object.freeze(["page_load", "media_weight", "readability"]);
+export const PACKAGE_OWNED_VISUAL_REVIEW_KEYS = Object.freeze(["page_load", "media_weight", "readability", "captures", "element_parity"]);
 export const PACKAGE_OWNED_KEY_REFUSAL = "package_owned_key";
 
 export function refuseRecord(stage, problems) {
@@ -512,10 +512,24 @@ const routeKey = (route) => String(route || "").replace(/^\/+|\/+$/g, "");
 // family components, so it must load a brand layer (brand-theme.css or
 // checkout-brand.css) after it, and that file must be in the built output. A
 // page that loads neither renders the design's own markup and needs no brand
-// layer (docs/brand-theme-bridge.md, "Where next-core.css belongs"). Any page
+// layer (docs/brand-theme-bridge.md, "Where next-core.css belongs"). When
+// theme generate wrote brand-fonts.css (the design's own faces), each styled
+// page must load the campaign's copy too, or the families brand-theme.css
+// names fall back to the system font. Where it was written is the Build
+// Context's theme.generated.fonts_css_path (theme generate --out-dir moves
+// it); the default path is read only when the context names none. Any page
 // that breaks the rule is a refusal naming the page.
-function brandLayerFacts(doctor) {
+function brandLayerFacts(doctor, context = null) {
   const derived = doctor.derived || {};
+  const recordedFonts = context?.theme?.generated?.fonts_css_path;
+  const generatedFonts = typeof recordedFonts === "string" && recordedFonts
+    ? resolve(derived.target_repo, recordedFonts)
+    : (context?.theme?.generated ? null : resolve(derived.target_repo, ".campaign-runtime/theme", BRAND_FONTS_FILENAME));
+  const fontsRequired = Boolean(generatedFonts) && existsSync(generatedFonts);
+  const insideSite = (file) => {
+    const rel = relative(site.site_root, file);
+    return Boolean(rel) && !rel.startsWith("..") && !isAbsolute(rel);
+  };
   const commerce = commerceScopeFromScope(derived.scope);
   if (!commerce.all.length) {
     throw refuseRecord("theme", ["The campaign ships no commerce pages, so there is no brand layer to record; the theme gate does not apply."]);
@@ -566,6 +580,30 @@ function brandLayerFacts(doctor) {
       problems.push(`${label}: ${builtRel} links ${hrefs[brand]}, which is not in the built output.`);
       continue;
     }
+    // brand-fonts.css holds only @font-face rules, so unlike the brand layer
+    // its position relative to next-core.css does not matter.
+    if (fontsRequired) {
+      const fontsHref = hrefs.find((candidate) => hrefName(candidate) === BRAND_FONTS_FILENAME);
+      const bare = fontsHref ? fontsHref.split(/[?#]/)[0] : null;
+      const fontsFile = bare && !/^(?:[a-z][a-z0-9+.-]*:)?\/\//i.test(bare)
+        ? (bare.startsWith("/") ? join(site.site_root, bare) : resolve(dirname(built.built_path), bare))
+        : null;
+      const generatedRel = relative(derived.target_repo, generatedFonts);
+      const problem = !fontsHref
+        ? `${label}: ${builtRel} links no ${BRAND_FONTS_FILENAME}. Theme generate wrote the design's font faces to ${generatedRel}; copy it into the campaign assets/css folder beside the brand layer, list it in the page's frontmatter styles and rebuild.`
+        : !fontsFile || !insideSite(fontsFile)
+          ? `${label}: ${builtRel} links ${fontsHref}, which is not a file in this campaign's built output; link the campaign's own copy of ${generatedRel}.`
+          : !existsSync(fontsFile)
+            ? `${label}: ${builtRel} links ${fontsHref}, which is not in the built output.`
+            : readFileSync(fontsFile, "utf8") !== readFileSync(generatedFonts, "utf8")
+              ? `${label}: ${builtRel} links ${fontsHref}, which differs from the generated ${generatedRel}; copy the generated file and rebuild.`
+              : null;
+      if (problem) {
+        problems.push(problem);
+        continue;
+      }
+      evidence.push(`${label}: ${builtRel} loads ${relative(derived.target_repo, fontsFile)}, identical to the generated ${generatedRel}.`);
+    }
     layers.push(file);
     styled.push(label);
     evidence.push(`${label}: ${builtRel} loads ${relative(derived.target_repo, file)} after ${CORE_STYLESHEET}.`);
@@ -865,7 +903,7 @@ function validateRecord(stage, { report, context, packet, fingerprint }) {
     // over the report this record would write. A blocked or skipped Polish is
     // not a pass the gate could grant; doctor keeps QA blocked on it.
     const hiddenEagerMediaGate = evaluateRecordedHiddenEagerMediaCheckpoint({ packet, report });
-    const gate = evaluatePolishGate({ report, hiddenEagerMediaGate, currentOutputFingerprint: fingerprint });
+    const gate = evaluatePolishGate({ report, hiddenEagerMediaGate, currentOutputFingerprint: fingerprint, newEvidence: true });
     if (gate.status === "blocked") {
       problems.push(`${gate.code}: ${gate.reason}`);
       for (const problem of gate.problems || []) problems.push(problem);
@@ -1180,7 +1218,7 @@ function recordUnderLock({ stage, packetPath, sidecars, lockedTarget, input, dry
     }
     facts = doctorFacts(stage, doctor, report, packet);
     if (typeof afterDoctorRead === "function") afterDoctorRead();
-    if (stage === "theme") layer = brandLayerFacts(doctor);
+    if (stage === "theme") layer = brandLayerFacts(doctor, readJsonIfExists(contextPath));
     if (stage === "deploy") deployFacts(doctor, packet, input, facts.fingerprint);
     const next = stage === "setup"
       ? composeSetup(report, context, { now: timestamp, recordedBy })

package/src/theme-gate.mjs

@@ -166,13 +166,13 @@ export function evaluateThemeGate({ reportTheme = null, contextTheme = null, sco
         id: "theme_generate",
         kind: "command",
         command: `campaigns-os theme generate --packet ${packetArg}`,
-        description: "Generate .campaign-runtime/theme/brand-theme.css from the inspected source tokens.",
+        description: "Generate .campaign-runtime/theme/brand-theme.css from the inspected source tokens, and brand-fonts.css beside it when the design source ships the faces its headings, body copy or buttons use.",
       },
       {
         id: "apply_brand_layer",
         kind: "manual",
         command: null,
-        description: `Copy brand-theme.css into the campaign assets/css folder, list it after next-core.css in the frontmatter styles of the commerce pages that render family components, rebuild, run campaigns-os record build, then campaigns-os record theme --packet ${packetArg}, which records report.theme from the built pages.`,
+        description: `Copy brand-theme.css (and brand-fonts.css, when theme generate wrote one) into the campaign assets/css folder, list brand-theme.css after next-core.css, and brand-fonts.css anywhere, in the frontmatter styles of the commerce pages that render family components, rebuild, run campaigns-os record build, then campaigns-os record theme --packet ${packetArg}, which records report.theme from the built pages.`,
       },
       {
         id: "waive_theme",

package/src/visual-diff.mjs

@@ -0,0 +1,296 @@
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { boundedDimensions, VISUAL_MAX_DECODE_PIXELS } from "./png-header.mjs";
+
+const own = (value, key) => value !== null && ["object", "function"].includes(typeof value) && Object.hasOwn(value, key) ? value[key] : undefined;
+const boundedArea = boundedDimensions;
+function geometry(image) {
+  boundedArea(own(image, "width"), own(image, "height"));
+  if (!ArrayBuffer.isView(image.data) || image.data.length !== image.width * image.height * 4) throw new RangeError("invalid_image_geometry");
+}
+const track = (memory, data) => { memory?.acquire(data); return data; };
+function release(image, memory) {
+  const data = image.data;
+  image.data = null;
+  if (data) memory?.release(data);
+}
+const allocate = (length, memory) => track(memory, Buffer.alloc(length));
+function maskRects(rects) {
+  if (!Array.isArray(rects) || rects.some((r) => !r || ![r.x, r.y].every(Number.isFinite)
+      || ![r.width, r.height].every((n) => Number.isFinite(n) && n >= 0))) throw new RangeError("invalid_mask");
+}
+
+// Comparisons consume their RGBA inputs. Callbacks must finish encoding/writing
+// artifacts synchronously; only metrics survive into the next comparison.
+export function readRgba(source, memory) {
+  boundedArea(own(source, "width"), own(source, "height"));
+  if (typeof own(source, "load") !== "function") { geometry(source); return source; }
+  const image = source.load();
+  geometry(image);
+  if (image.width !== source.width || image.height !== source.height) throw new RangeError("invalid_image_geometry");
+  track(memory, image.data); return image;
+}
+export function releaseComparison(part, memory) {
+  for (const key of ["basis_crop", "build_crop", "heatmap"]) if (part?.[key]) {
+    release(part[key], memory); delete part[key];
+  }
+  delete part.mismatches; delete part.mask;
+}
+
+export const DIFF_OPTIONS = Object.freeze({ threshold: 0.1, include_aa: false, alpha: 0.1 });
+// Neither package exports its version: read it from the package.json above the
+// resolved entry whose name is the package's. Unknown is null, never a guess.
+export function installedPackageVersion(name, { resolveEntry = (specifier) => import.meta.resolve(specifier) } = {}) {
+  try {
+    let directory = dirname(fileURLToPath(resolveEntry(name)));
+    for (;;) {
+      const file = join(directory, "package.json");
+      if (existsSync(file)) {
+        const manifest = JSON.parse(readFileSync(file, "utf8"));
+        if (manifest?.name === name) return typeof manifest.version === "string" ? manifest.version : null;
+      }
+      const parent = dirname(directory);
+      if (parent === directory) return null;
+      directory = parent;
+    }
+  } catch { return null; }
+}
+export async function loadVisualDependencies({ importer = (name) => import(name), versionOf = installedPackageVersion } = {}) {
+  async function load(name, type) {
+    try {
+      const module = await importer(name);
+      const api = own(module, "default") || module;
+      const result = { status: "available", version: own(module, "version") ?? own(api, "version") ?? versionOf(name), package: name };
+      if (type === "decoder") {
+        const PNG = own(module, "PNG") || own(api, "PNG");
+        const sync = own(PNG, "sync");
+        if (typeof own(sync, "read") !== "function" || typeof own(sync, "write") !== "function") throw new TypeError("Invalid PNG module");
+        result.decode = (bytes) => PNG.sync.read(bytes);
+        result.encode = (image) => PNG.sync.write(image);
+      } else {
+        if (typeof api !== "function") throw new TypeError("Invalid diff module");
+        result.compare = api;
+      }
+      return result;
+    } catch (error) {
+      // A missing transitive import is a broken installation, not this package being absent.
+      const missing = ["ERR_MODULE_NOT_FOUND", "MODULE_NOT_FOUND"].includes(error?.code)
+        && new RegExp(`(?:package|module) ['\"]${name}['\"]`).test(error.message || "");
+      return { status: missing ? "missing" : "failed", version: null, package: name,
+        install_hint: `Install ${name} where campaigns-os is installed (npm install ${name}).` };
+    }
+  }
+  const [decoder, diff] = await Promise.all([load("pngjs", "decoder"), load("pixelmatch", "diff")]);
+  return { decoder, diff };
+}
+
+export function padRgba(image, width, height, color = [255, 255, 255, 255], memory) {
+  boundedArea(width, height);
+  geometry(image);
+  if (width < image.width || height < image.height || image.data.length !== image.width * image.height * 4) throw new RangeError("invalid_image_geometry");
+  const data = allocate(width * height * 4, memory);
+  for (let i = 0; i < data.length; i += 4) data.set(color, i);
+  for (let y = 0; y < image.height; y++) data.set(image.data.subarray(y * image.width * 4, (y + 1) * image.width * 4), y * width * 4);
+  return { width, height, data };
+}
+
+export function paintMaskUnion(images, rectsA = [], rectsB = [], color = [255, 0, 255, 255]) {
+  maskRects(rectsA); maskRects(rectsB);
+  if (typeof color === "string" && /^#[a-f0-9]{6}$/i.test(color)) color = [1, 3, 5].map((offset) => Number.parseInt(color.slice(offset, offset + 2), 16)).concat(255);
+  if (!images.length) return { masked_pixels: 0, mask: new Uint8Array() };
+  for (const image of images) geometry(image);
+  const { width, height } = images[0];
+  boundedArea(width, height);
+  if (images.some((image) => image.width !== width || image.height !== height)) throw new RangeError("mask_canvas_mismatch");
+  const mask = new Uint8Array(width * height);
+  let masked_pixels = 0;
+  for (const rect of [...rectsA, ...rectsB]) {
+    if (!rect.width || !rect.height) continue;
+    const x0 = Math.max(0, Math.floor(rect.x)), y0 = Math.max(0, Math.floor(rect.y));
+    const x1 = Math.min(width, Math.ceil(rect.x + rect.width)), y1 = Math.min(height, Math.ceil(rect.y + rect.height));
+    for (let y = y0; y < y1; y++) for (let x = x0; x < x1; x++) {
+      const index = y * width + x;
+      if (!mask[index]) { mask[index] = 1; masked_pixels++; }
+      for (const image of images) image.data.set(color, index * 4);
+    }
+  }
+  return { masked_pixels, mask };
+}
+
+export function compareImages(basis, build, { diff, rectsA = [], rectsB = [], dpr = 1, memory } = {}) {
+  geometry(basis); geometry(build);
+  maskRects(rectsA); maskRects(rectsB);
+  if (!Number.isFinite(dpr) || dpr <= 0) throw new RangeError("invalid_dpr");
+  const compare = typeof diff === "function" ? diff : own(diff, "compare");
+  if (typeof compare !== "function") throw new Error("dependency_missing");
+  const width = Math.max(basis.width, build.width), height = Math.max(basis.height, build.height);
+  boundedArea(width, height);
+  const originalA = { width: basis.width, height: basis.height }, originalB = { width: build.width, height: build.height };
+  track(memory, basis.data); track(memory, build.data);
+  const inputs = [{ ...basis }, { ...build }];
+  basis.data = null; build.data = null;
+  const consume = (image) => {
+    if (image.width === width && image.height === height) {
+      const result = { ...image }; image.data = null; return result;
+    }
+    const padded = padRgba(image, width, height, undefined, memory);
+    release(image, memory); return padded;
+  };
+  let a, b, heatmap, completed = false;
+  try {
+  if (inputs[0].data.buffer === inputs[1].data.buffer
+      && inputs[0].data.byteOffset < inputs[1].data.byteOffset + inputs[1].data.byteLength
+      && inputs[1].data.byteOffset < inputs[0].data.byteOffset + inputs[0].data.byteLength) {
+    const original = inputs[0].data;
+    inputs[0].data = allocate(original.length, memory);
+    inputs[0].data.set(original);
+    if (original !== inputs[1].data) memory?.release(original);
+  }
+  a = consume(inputs[0]); b = consume(inputs[1]);
+  const { mask, masked_pixels } = paintMaskUnion([a, b], rectsA, rectsB);
+  heatmap = { width, height, data: allocate(width * height * 4, memory) };
+  compare(a.data, b.data, heatmap.data, width, height,
+    { threshold: DIFF_OPTIONS.threshold, includeAA: DIFF_OPTIONS.include_aa, alpha: DIFF_OPTIONS.alpha });
+  const mismatches = new Uint8Array(width * height);
+  let mismatch_pixels = 0;
+  for (let y = 0; y < height; y++) for (let x = 0; x < width; x++) {
+    const i = y * width + x, p = i * 4;
+    const missing = (x >= originalA.width || y >= originalA.height) !== (x >= originalB.width || y >= originalB.height);
+    if (!mask[i] && (missing || (heatmap.data[p] === 255 && heatmap.data[p + 1] === 0 && heatmap.data[p + 2] === 0))) {
+      mismatches[i] = 1; mismatch_pixels++;
+      heatmap.data.set([255, 0, 0, 255], p);
+    }
+  }
+  const compared_pixels = width * height - masked_pixels;
+  const unpad = (image, original) => {
+    for (let y = 0; y < original.height; y++) image.data.copyWithin(y * original.width * 4, y * width * 4, (y * width + original.width) * 4);
+    return { ...original, data: image.data.subarray(0, original.width * original.height * 4) };
+  };
+  const result = { status: "compared", reason: null, width_delta_px: originalB.width - originalA.width,
+    height_delta_px: originalB.height - originalA.height, canvas: { width, height }, masked_pixels,
+    mismatch_pixels, compared_pixels, mismatch_ratio: compared_pixels ? mismatch_pixels / compared_pixels : 0,
+    heatmap, basis_crop: unpad(a, originalA), build_crop: unpad(b, originalB), mismatches, mask,
+    worst_tiles: worstTiles({ width, height, mismatches, mask }, { tile: Math.min(32 * dpr, Math.max(width, height)) }) };
+  completed = true; return result;
+  } finally {
+    if (!completed) for (const image of [a, b, heatmap, ...inputs]) if (image?.data) release(image, memory);
+  }
+}
+
+export function worstTiles({ width, height, mismatches, mask = [] }, { tile = 32, count = 3 } = {}) {
+  boundedArea(width, height);
+  if (!Number.isFinite(tile) || tile <= 0 || !Number.isSafeInteger(count) || count < 0) throw new RangeError("invalid_tile_options");
+  tile = Math.max(1, Math.round(tile));
+  count = Math.min(count, 3);
+  if (!mismatches || mismatches.length !== width * height || (mask.length && mask.length !== width * height)) throw new RangeError("invalid_tile_geometry");
+  const tiles = [];
+  for (let y = 0; y < height; y += tile) for (let x = 0; x < width; x += tile) {
+    const w = Math.min(tile, width - x), h = Math.min(tile, height - y);
+    let mismatch = 0, compared = 0;
+    for (let row = y; row < y + h; row++) for (let col = x; col < x + w; col++) {
+      const i = row * width + col;
+      if (!mask[i]) { compared++; mismatch += mismatches[i]; }
+    }
+    tiles.push({ x, y, width: w, height: h, mismatch_ratio: compared ? mismatch / compared : 0 });
+    tiles.sort((a, b) => b.mismatch_ratio - a.mismatch_ratio || a.y - b.y || a.x - b.x);
+    if (tiles.length > count) tiles.pop();
+  }
+  return tiles.sort((a, b) => b.mismatch_ratio - a.mismatch_ratio || a.y - b.y || a.x - b.x).slice(0, count);
+}
+
+export function encodeHeatmap(image, decoder) {
+  geometry(image?.heatmap || image);
+  return decoder.encode(image.heatmap || image);
+}
+
+export function pairCompatibility(build, basis, { reference = false } = {}) {
+  const fail = (reason) => ({ ok: false, reason });
+  if (!build || typeof build !== "object" || !basis || typeof basis !== "object") return fail("capture_unavailable");
+  if (reference) {
+    if (!build || basis.viewport !== build.viewport) return fail("viewport_not_captured");
+    if (basis.css_width == null) return fail(basis.dpr == null ? "dpr_unknown" : "width_unknown");
+    if (basis.dpr == null) return fail("dpr_unknown");
+    if (basis.css_width !== build.width) return fail("width_mismatch");
+    if (basis.dpr !== build.device_scale_factor) return fail("dpr_mismatch");
+  } else if ([build, basis].some((cell) => cell?.stabilized?.treatment?.mask_cap_reached)) return fail("mask_cap_reached");
+  return { ok: true, reason: null };
+}
+export function pageCompatibility(a, b) {
+  return a?.truncated || b?.truncated ? { ok: false, reason: "capture_truncated" } : { ok: true, reason: null };
+}
+
+function pixelBand(source, band, dpr) {
+  const top = Math.floor(band.top * dpr), bottom = Math.ceil((band.top + band.height) * dpr);
+  const left = Math.floor((band.left ?? 0) * dpr);
+  const right = Math.ceil(((band.left ?? 0) + (band.width ?? source.width / dpr)) * dpr);
+  return { top, left, width: right - left, height: bottom - top };
+}
+function insideCapture(source, band, dpr) {
+  const left = band.left ?? 0, width = band.width ?? source.width / dpr;
+  return band.top >= 0 && left >= 0
+    && (band.top + band.height) * dpr <= source.height && (left + width) * dpr <= source.width;
+}
+// A rectangle not wholly inside the decoded image is refused before any copy,
+// so no zero-filled pixel is ever presented as image data.
+export function crop(source, { top, left, width, height }, memory) {
+  boundedArea(width, height);
+  const image = readRgba(source, memory);
+  if (![top, left].every(Number.isSafeInteger) || top < 0 || left < 0
+      || left + width > image.width || top + height > image.height) {
+    release(image, memory);
+    throw new RangeError("invalid_image_geometry");
+  }
+  const data = allocate(width * height * 4, memory);
+  for (let row = 0; row < height; row++) data.set(image.data.subarray(((row + top) * image.width + left) * 4,
+    ((row + top) * image.width + left + width) * 4), row * width * 4);
+  release(image, memory);
+  return { width, height, data };
+}
+export function compareBands(basis, build, { basisSections, buildSections, rectsA = [], rectsB = [], dpr = 1, diff, cap = 40, memory, onComparison } = {}) {
+  boundedArea(own(basis, "width"), own(basis, "height")); boundedArea(own(build, "width"), own(build, "height"));
+  if (!Number.isFinite(dpr) || dpr <= 0) throw new RangeError("invalid_dpr");
+  if (!Number.isSafeInteger(cap) || cap < 0) throw new RangeError("invalid_band_cap");
+  cap = Math.min(cap, 40);
+  maskRects(rectsA); maskRects(rectsB);
+  const a = basisSections?.bands || [], b = buildSections?.bands || [];
+  if (!Array.isArray(a) || !Array.isArray(b) || [...a, ...b].some((band) => !band || typeof band !== "object")) throw new RangeError("invalid_band_geometry");
+  for (const [source, sections] of [[basis, a], [build, b]]) for (const band of sections) {
+    const width = band.width ?? source.width / dpr;
+    if (![band.top, band.height, band.left ?? 0, width].every(Number.isFinite)) throw new RangeError("invalid_band_geometry");
+    // Section boxes are signed, fractional CSS document coordinates. Only
+    // non-finite values and over-cap areas refuse the comparison (A-C1).
+    if (width > 0 && band.height > 0 && width * dpr * band.height * dpr > VISUAL_MAX_DECODE_PIXELS) throw new RangeError("image_too_large");
+  }
+  // Repeated bands read fresh images from caller-provided sources (normally
+  // capture files). No decoded originals or encoded snapshots are retained.
+  if ([basis, build].some((source) => typeof own(source, "load") !== "function" || source.data != null)) throw new RangeError("image_source_required");
+  const keys = [...new Set([...a, ...b].map((band) => band.key))].sort();
+  const bands = [], members = [];
+  const unsupported = (key, reason) => {
+    bands.push({ key, status: "unsupported", reason }); members.push({ key, result: "unexercised", reason_code: reason });
+  };
+  if (!keys.length) members.push({ key: "sections", result: "unexercised", reason_code: "no_section_keys" });
+  for (const [index, key] of keys.entries()) {
+    const aa = a.filter((band) => band.key === key), bb = b.filter((band) => band.key === key);
+    if (index >= cap) { unsupported(key, "band_cap_reached"); continue; }
+    if (aa.length > 1 || bb.length > 1 || [basisSections, buildSections].some((s) => s?.duplicated_keys?.includes(key))) { unsupported(key, "section_mapping_duplicate"); continue; }
+    if (!aa.length || !bb.length) { unsupported(key, "section_mapping_missing"); continue; }
+    const [sa] = aa, [sb] = bb;
+    if (sa.height <= 0 || sb.height <= 0 || sa.width <= 0 || sb.width <= 0) { unsupported(key, "section_not_rendered"); continue; }
+    if (!insideCapture(basis, sa, dpr) || !insideCapture(build, sb, dpr)) { unsupported(key, "beyond_capture_height"); continue; }
+    const pa = pixelBand(basis, sa, dpr), pb = pixelBand(build, sb, dpr);
+    if (pa.width <= 0 || pa.height <= 0 || pb.width <= 0 || pb.height <= 0) { unsupported(key, "section_not_rendered"); continue; }
+    const relativeRects = (rects, section) => rects.filter((r) => r.y < section.top + section.height && r.y + r.height > section.top)
+      .map((r) => ({ ...r, x: r.x - section.left, y: Math.max(0, r.y - section.top), height: Math.min(r.y + r.height, section.top + section.height) - Math.max(r.y, section.top) }));
+    const comparison = compareImages(crop(basis, pa, memory), crop(build, pb, memory), { diff, dpr, memory,
+      rectsA: relativeRects(rectsA, pa), rectsB: relativeRects(rectsB, pb) });
+    Object.assign(comparison, { key, basis: { top: sa.top, height: sa.height }, build: { top: sb.top, height: sb.height } });
+    try { onComparison?.(comparison); } finally { releaseComparison(comparison, memory); }
+    bands.push(comparison);
+  }
+  if (basisSections?.capped || buildSections?.capped) members.push({ key: "sections_cap", result: "unexercised", reason_code: "band_cap_reached" });
+  bands.sort((a, b) => (b.mismatch_ratio ?? -1) - (a.mismatch_ratio ?? -1)
+    || Math.abs(b.height_delta_px || 0) - Math.abs(a.height_delta_px || 0) || a.key.localeCompare(b.key));
+  return { bands, members };
+}

package/src/visual-reference.mjs

@@ -0,0 +1,126 @@
+import { openSync, readSync, closeSync, realpathSync, existsSync } from "node:fs";
+import { resolve, relative, isAbsolute } from "node:path";
+import { readPngStructure, boundedInflate, sha256Hex, VISUAL_MAX_DECODE_PIXELS, VISUAL_MAX_REFERENCE_BYTES } from "./png-header.mjs";
+
+const inside = (root, path) => {
+  if (!root || !path) return false;
+  const rel = relative(root, path);
+  return rel === "" || (!isAbsolute(rel) && rel !== ".." && !rel.startsWith("../"));
+};
+const real = (path) => { try { return realpathSync(path); } catch { return resolve(path); } };
+const hash = (bytes) => `sha256:${sha256Hex(bytes)}`;
+const object = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+const own = (value, key) => object(value) && Object.hasOwn(value, key) ? value[key] : undefined;
+
+export function referenceViewport({ ihdr, scale_factor, width, height } = {}) {
+  if (!Number.isFinite(scale_factor) || scale_factor <= 0) return { css_width: null, dpr: null, reason: "dpr_unknown" };
+  const w = ihdr?.width_px ?? width;
+  return { css_width: Number.isFinite(w) && w > 0 ? w / scale_factor : null,
+    dpr: scale_factor, reason: w > 0 ? null : "width_unknown" };
+}
+
+// linkedSource is the independently read html_file identity + provenance.
+export function classifyProvenance({ path, sourceRoot, targetRepo, kind = "source_screenshot", sha256,
+  buildCaptureHashes = [], builtHtmlHashes = [], pageKitTargets = [], linkedSource = null,
+  recorded = {}, source_ref_id = own(recorded, "source_ref_id"), captured_at = own(recorded, "captured_at") } = {}) {
+  recorded = object(recorded) ? recorded : {};
+  const reasons = [];
+  const html = kind === "html_file" || kind === "source_html";
+  const resolved = path ? real(path) : null;
+  const paths = html ? [resolved, sourceRoot ? real(sourceRoot) : null] : [resolved];
+  if (targetRepo) {
+    if (paths.some((p) => inside(real(resolve(targetRepo, "_site")), p))) reasons.push("path_in_build_output");
+    if (paths.some((p) => inside(real(resolve(targetRepo, ".campaign-runtime")), p))) reasons.push("path_in_runtime_dir");
+  }
+  if (html) {
+    if (sha256 && new Set(builtHtmlHashes).has(sha256)) reasons.push("hash_equals_built_html");
+    if (resolved && pageKitTargets.some((p) => real(resolve(targetRepo || ".", p)) === resolved)) reasons.push("source_is_campaign_page");
+  } else {
+    const hex = String(sha256 || "").replace(/^sha256:/, "");
+    if (sha256 && (new Set(buildCaptureHashes).has(sha256) || (targetRepo && /^[a-f0-9]{64}$/.test(hex)
+        && ["captures", "readability", "diff"].some((dir) => existsSync(resolve(targetRepo, `.campaign-runtime/polish/${dir}/${hex}.png`)))))) reasons.push("hash_equals_package_capture");
+    if (linkedSource?.provenance?.class === "self_referential") reasons.push("linked_source_self_referential");
+  }
+  if (reasons.length) return { class: "self_referential", reasons };
+  if (!html && !captured_at) reasons.push("capture_time_unrecorded");
+  if (!html && (!source_ref_id || !linkedSource || !["html_file", "source_html"].includes(linkedSource.kind))) reasons.push("source_link_missing");
+  else {
+    const identity = html ? { sha256, sha256_recorded: own(recorded, "sha256") } : own(linkedSource, "identity");
+    // The source HTML applies the hash rules to its own html_file ref (§5.2):
+    // a ref that records no sha256 is unrecorded whether or not the file was
+    // read; a recorded ref whose file was not read is missing.
+    if (html && !identity.sha256_recorded) reasons.push("source_hash_unrecorded");
+    else if (!identity?.sha256) reasons.push("linked_source_missing");
+    else if (!identity.sha256_recorded) reasons.push("source_hash_unrecorded");
+    else if (identity.sha256_recorded !== identity.sha256) reasons.push("source_hash_mismatch");
+  }
+  return { class: reasons.length ? "unknown" : "declared_source", reasons };
+}
+
+function readBounded(path, maxBytes) {
+  const fd = openSync(path, "r");
+  try {
+    const chunks = [];
+    let length = 0;
+    while (length <= maxBytes) {
+      const chunk = Buffer.alloc(Math.min(65536, maxBytes + 1 - length));
+      const n = readSync(fd, chunk, 0, chunk.length, null);
+      if (!n) break;
+      chunks.push(chunk.subarray(0, n)); length += n;
+    }
+    if (length > maxBytes) return null;
+    return Buffer.concat(chunks, length);
+  } finally { closeSync(fd); }
+}
+
+export async function verifyReference({ path, url, recorded = {}, sourceRoot, targetRepo, decoder,
+  budget = null, kind = "source_screenshot", ...provenanceInputs } = {}) {
+  recorded = object(recorded) ? Object.fromEntries(Object.entries(recorded)) : {};
+  let resolved = null;
+  const identity = { sha256: null, sha256_recorded: recorded.sha256 ?? null, bytes: null,
+    ...Object.fromEntries(["captured_at", "browser", "device_profile", "scale_factor", "width", "height", "source_ref_id"].map((key) => [key, own(recorded, key) ?? null])) };
+  const result = { kind, path_rel: path ? relative(targetRepo || sourceRoot || ".", resolve(sourceRoot || ".", path)) : null, url_present: Boolean(url), identity,
+    verification: { level: "unverifiable", reason: null, png: null }, css_width: null, dpr: null };
+  const finish = (reason, level = "unverifiable") => {
+    result.verification.reason = reason; result.verification.level = level;
+    result.provenance = classifyProvenance({ ...provenanceInputs, path: resolved, sourceRoot, targetRepo, kind,
+      sha256: identity.sha256, recorded });
+    return result;
+  };
+  if (!path) return finish(url ? "remote_not_fetched" : "file_missing");
+  try { resolved = realpathSync(resolve(sourceRoot || ".", path)); } catch { return finish("file_missing"); }
+  result.path_rel = relative(targetRepo || sourceRoot || ".", resolved);
+  if (!inside(real(sourceRoot || "."), resolved)
+      && !(targetRepo && ["_site", ".campaign-runtime"].some((dir) => inside(real(resolve(targetRepo, dir)), resolved)))) return finish("path_outside_source_root");
+  let bytes;
+  try { bytes = readBounded(resolved, VISUAL_MAX_REFERENCE_BYTES); } catch { return finish("file_missing"); }
+  if (!bytes) return finish("too_large");
+  identity.bytes = bytes.length; identity.sha256 = hash(bytes);
+  if (["html_file", "source_html"].includes(kind)) {
+    // HTML needs only a successful read/hash for verification. Its declared
+    // source hash is a separate provenance member (§5.2), not a decode claim.
+    return finish(null, "decoded");
+  }
+  const structure = readPngStructure(bytes);
+  if (!structure.ok) return finish(structure.reason);
+  const ihdr = structure.ihdr;
+  result.verification.png = ihdr;
+  Object.assign(result, referenceViewport({ ihdr, ...recorded }));
+  delete result.reason;
+  if (ihdr.width_px * ihdr.height_px > VISUAL_MAX_DECODE_PIXELS) return finish("image_too_large");
+  const decode = typeof decoder === "function" ? decoder : own(decoder, "decode");
+  const available = typeof decode === "function" && (!decoder.status || decoder.status === "available");
+  if (available) {
+    if (budget && ((typeof budget.remaining === "function" && budget.remaining() <= 0)
+        || (Number.isFinite(budget.deadline) && (budget.clock || Date.now)() >= budget.deadline))) return finish("verify_budget_exhausted");
+    try {
+      boundedInflate(bytes, ihdr);
+      const image = await decode(bytes);
+      if (image.width !== ihdr.width_px || image.height !== ihdr.height_px) throw new Error("dimensions");
+    } catch { return finish("decode_failed"); }
+  }
+  if (recorded.sha256 && recorded.sha256 !== identity.sha256) return finish("recorded_hash_mismatch");
+  if ((recorded.width != null && recorded.width !== ihdr.width_px)
+      || (recorded.height != null && recorded.height !== ihdr.height_px)) return finish("recorded_dimensions_mismatch");
+  return finish(null, available ? "decoded" : "header_checked");
+}