@nextcommerce/campaigns-os 1.59.0 → 1.61.0

package/src/spec-derive.mjs

@@ -56,15 +56,29 @@ const ROUTING_HINT_FIELDS = Object.freeze({
 });
 
 // The directories page-kit's own discovery ignores (`_layouts`, `_includes`;
-// everything else under the campaign root, `assets/` and `_data/` included,
-// is rendered when it is .html), plus the two no build reads. The CLI walker
-// prunes with this and pageRouteForFile filters with it, so the list lives
-// in one place.
+// on 0.2.x everything else under the campaign root, `assets/` and `_data/`
+// included, is rendered when it is .html), plus the two no build reads. The
+// CLI walker prunes with this and pageRouteForFile filters with it, so the
+// list lives in one place.
 export const PAGE_TREE_IGNORED_DIRS = Object.freeze(["_layouts", "_includes", "node_modules", ".git"]);
 export function isPageTreeIgnoredDir(name) {
   return PAGE_TREE_IGNORED_DIRS.includes(name);
 }
 
+// Whether a campaign-relative file sits where page-kit renders no page. From
+// 0.3.0 page-kit also skips the campaign's top-level `assets/` (its
+// `*/assets/**` glob; a nested `offers/assets/` still renders), so the caller
+// says which rule the target's installed page-kit follows. Backslashes and
+// leading slashes read as pageRouteForFile reads them.
+export function isPageTreeIgnoredPath(relativePath, { assetsHtmlIgnored = false } = {}) {
+  const dirs = normalizePageTreePath(relativePath).split("/").slice(0, -1);
+  return dirs.some(isPageTreeIgnoredDir) || (assetsHtmlIgnored && dirs[0] === "assets");
+}
+
+function normalizePageTreePath(relativePath) {
+  return String(relativePath || "").replace(/\\/g, "/").replace(/^\/+/, "");
+}
+
 function isPlainObject(value) {
   return value !== null && typeof value === "object" && !Array.isArray(value);
 }
@@ -114,13 +128,14 @@ function containerProblem(spec, path) {
 // `upsell/`, intermediate directories ignored with its NESTED_NO_PERMALINK
 // warning), and `index.html` is the entry route "". A nested `index.html`
 // would collide with the campaign root (page-kit's DUPLICATE_OUTPUT), so it
-// is not a page this reads. Files under `_layouts/` or `_includes/` return
-// null, as page-kit never renders them.
-export function pageRouteForFile(relativePath) {
-  const path = String(relativePath || "").replace(/\\/g, "/").replace(/^\/+/, "");
+// is not a page this reads. Files under `_layouts/` or `_includes/` (and,
+// with assetsHtmlIgnored, the top-level `assets/`) return null, as page-kit
+// never renders them.
+export function pageRouteForFile(relativePath, { assetsHtmlIgnored = false } = {}) {
+  const path = normalizePageTreePath(relativePath);
   if (!path || !/\.html$/i.test(path)) return null;
   const segments = path.split("/");
-  if (segments.slice(0, -1).some(isPageTreeIgnoredDir)) return null;
+  if (isPageTreeIgnoredPath(path, { assetsHtmlIgnored })) return null;
   const basename = segments[segments.length - 1].replace(/\.html$/i, "");
   if (basename === "index") return segments.length === 1 ? "" : null;
   return `${basename}/`;

package/src/stage-ledger.mjs

@@ -11,7 +11,6 @@ import {
   NEXT_STAGE_CONTRACTS,
   NEXT_STAGE_OWNERS,
   stageIsBlocked,
-  stageIsTerminal,
 } from "./orchestration-stage-contract.mjs";
 
 const PRODUCER_STAGES = new Set(["doctor", "qa"]);
@@ -200,6 +199,33 @@ export function archiveSupersededRecord(stage, previous, { by, reason, at }) {
   return appendHistoryEntry(isPlainObject(stage) ? { ...stage } : {}, historyEntry(previous, { by, reason, at }));
 }
 
+/**
+ * #668: the Polish record a CampaignSpec change moved to `polish.history`,
+ * restored as the live record stamped with `stamps` (the current inputs), or
+ * null. It is the same review of the same pages, so it is restored only when
+ * the live record's input_change is a CampaignSpec change over exactly
+ * `fingerprint`, the newest history entry is the completed Polish that change
+ * archived (same build fingerprint and source package fingerprint), and the
+ * brief's presentation stamp is unchanged: a presentation change still owes a
+ * new review. The caller decides that the operator kept this output.
+ */
+export function restorePolishKeptWithOutput(polish, { fingerprint, sourcePackageFingerprint = null, stamps = {}, completedStatuses }) {
+  const change = isPlainObject(polish) ? polish.input_change : null;
+  if (!isPlainObject(change) || change.reason !== "spec_material_changed" || change.superseded_build_fingerprint !== fingerprint) return null;
+  const history = Array.isArray(polish.history) ? polish.history : [];
+  const superseded = history[history.length - 1];
+  if (!isPlainObject(superseded) || superseded.archived_at !== change.at || !completedStatuses.includes(superseded.status)) return null;
+  if (superseded.source_build_fingerprint !== fingerprint) return null;
+  if ((superseded.source_package_material_fingerprint ?? null) !== (sourcePackageFingerprint ?? null)) return null;
+  if ((superseded.source_brief_material?.presentation ?? null) !== (stamps.source_brief_material?.presentation ?? null)) return null;
+  const restored = { ...polish };
+  for (const field of ["required_by", "required_for", "input_change", "source_brief_material", "source_spec_material_hash"]) delete restored[field];
+  for (const field of ["status", "completed_at", "recorded_by", "performed_by", "source_build_fingerprint", "source_package_material_fingerprint", "outputs", "evidence"]) {
+    if (Object.hasOwn(superseded, field)) restored[field] = JSON.parse(JSON.stringify(superseded[field]));
+  }
+  return { ...restored, stage: "polish", ...stamps };
+}
+
 /**
  * True when any stage of `report` carries a non-empty history: recorded
  * operator-visible state an intake must not silently drop.

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";
@@ -52,7 +52,7 @@ import {
 import { evaluateRecordedHiddenEagerMediaCheckpoint } from "./polish-node.mjs";
 import { effectiveStageStatus, effectiveStatusIsTerminal, inputStamps, stageWriteInputs } from "./input-currency.mjs";
 import { demoteStages, recordBrief, recordSpec } from "./input-refresh.mjs";
-import { applyDerivedAssemblyReportSummary, archiveStageRecord, archiveSupersededRecord, assemblyReportMatchesPacket, commitAssemblyReport, inputChangeFor } from "./stage-ledger.mjs";
+import { applyDerivedAssemblyReportSummary, archiveStageRecord, archiveSupersededRecord, assemblyReportMatchesPacket, commitAssemblyReport, inputChangeFor, restorePolishKeptWithOutput } from "./stage-ledger.mjs";
 import { withTargetLockSync } from "./target-lock.mjs";
 import { commerceScopeFromScope } from "./theme-gate.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) {
@@ -382,9 +382,15 @@ function composeBuild(report, { now, recordedBy, fingerprint, manifest = null, b
   if (detected) {
     const cause = detected === "spec_material_changed" ? "spec" : "presentation";
     const demoted = demoteStages({ ...nextReport, stages: { ...nextReport.stages, assembly, ...deploy } }, { causes: [cause], now, by: "record build", only: ["polish", "qa"] });
-    return { report: demoted.report, context: null };
+    const kept = keptPolishFor(demoted.report.stages.polish, { assembly, fingerprint, sourcePackageFingerprint, stamps });
+    return { report: kept ? { ...demoted.report, stages: { ...demoted.report.stages, polish: kept } } : demoted.report, context: null };
   }
   const previousPolish = stageObject(report, "polish");
+  // The usual #668 path: intake (prepare-build --force or record spec) already
+  // recorded the change on assembly, so nothing is detected here, but the
+  // carried input_change makes this build a replay the operator kept.
+  const keptPolish = keptPolishFor(previousPolish, { assembly, fingerprint, sourcePackageFingerprint, stamps });
+  if (keptPolish) return { report: { ...nextReport, stages: { ...nextReport.stages, assembly, polish: keptPolish, ...deploy } }, context: null };
   const polishStillCurrent = stageIsTerminal(String(previousPolish.status || ""))
     && optionalString(previousPolish.source_build_fingerprint) === fingerprint;
   const polish = polishStillCurrent
@@ -399,6 +405,16 @@ function composeBuild(report, { now, recordedBy, fingerprint, manifest = null, b
   return { report: { ...nextReport, stages: { ...nextReport.stages, assembly, polish, ...deploy } }, context: null };
 }
 
+// #668: the Polish a CampaignSpec change superseded comes back when the
+// operator's --deviation-reason kept the output it reviewed (stage-ledger's
+// restorePolishKeptWithOutput decides from the archived record). A terminal
+// Polish, or a build the operator did not keep, is left alone.
+function keptPolishFor(polish, { assembly, fingerprint, sourcePackageFingerprint, stamps }) {
+  if (!isObject(assembly.unchanged_output_reason) || stageIsTerminal(String(polish?.status || ""))) return null;
+  const kept = restorePolishKeptWithOutput(polish, { fingerprint, sourcePackageFingerprint, stamps, completedStatuses: POLISH_COMPLETED_STATUSES });
+  return kept ? withoutKeys(kept, ["skip_reason"]) : null;
+}
+
 // stages.deploy after a build of `fingerprint`, or null when it is kept: a
 // completed deploy whose source_build_fingerprint names other output goes
 // whole into history (archived_by "record build", reason_code
@@ -496,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."]);
@@ -550,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}.`);
@@ -849,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);
@@ -1164,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 };
+}