@nextcommerce/campaigns-os 1.60.0 → 1.61.0

package/src/polish-browser.mjs

@@ -34,10 +34,48 @@ import {
   polishProducerCleanupError,
   polishProducerTimeoutError,
   runWithPolishProducerDeadline,
+  VISUAL_READINESS_FONTS_MS, VISUAL_READINESS_AWAIT_MS, VISUAL_SHOT_MS, VISUAL_MAX_CAPTURE_HEIGHT_PX,
 } from "./polish-deadline.mjs";
 
 const NAVIGATION_TIMEOUT_MS = 30_000;
 const NETWORKIDLE_TIMEOUT_MS = 5_000;
+const visualMaskSelectors = ["[data-next-timer]", "[data-next-timer-display]", "[data-next-timer-expired]",
+  '[data-next-display*="price"]', '[data-next-display*="total"]'];
+
+// Self-contained functions execute in an isolated world, never the page world.
+async function visualReady(kind, ms) {
+  const started = performance.now();
+  const spent = () => Math.min(ms, Math.max(0, performance.now() - started));
+  if (kind === "fonts") {
+    let timer;
+    const status = await Promise.race([document.fonts.ready.then(() => "settled"),
+      new Promise((resolve) => { timer = setTimeout(() => resolve("timeout"), ms); })]);
+    clearTimeout(timer);
+    return { status, failed_faces: [...document.fonts].filter((face) => face.status === "error").length, waited_ms: spent() };
+  }
+  let remaining = document.querySelectorAll("[data-next-await]").length;
+  if (!remaining) return { status: "not_present", remaining_count: 0, waited_ms: spent() };
+  while (remaining && performance.now() - started < ms) {
+    await new Promise((resolve) => setTimeout(resolve, Math.min(25, Math.max(0, ms - (performance.now() - started)))));
+    remaining = document.querySelectorAll("[data-next-await]").length;
+  }
+  return { status: remaining ? "timeout" : "settled", remaining_count: remaining, waited_ms: spent() };
+}
+
+function visualGeometry() {
+  const rect = (element) => { const r = element.getBoundingClientRect();
+    return { x: r.x + scrollX, y: r.y + scrollY, width: r.width, height: r.height }; };
+  const selectors = { timer: "[data-next-timer],[data-next-timer-display],[data-next-timer-expired]",
+    price: '[data-next-display*="price"],[data-next-display*="total"]' };
+  let capped = false;
+  const masks = Object.entries(selectors).map(([group, selector]) => {
+    const elements = [...document.querySelectorAll(selector)];
+    if (elements.length > 500) capped = true;
+    const rects = elements.slice(0, 500).map(rect).filter((r) => r.width > 0 && r.height > 0);
+    return { group, count: rects.length, rects };
+  });
+  return { height: Math.max(document.documentElement.scrollHeight, document.body?.scrollHeight || 0), masks, mask_cap_reached: capped };
+}
 
 const NETWORK_EVENTS = Object.freeze([
   "Network.requestWillBeSent",
@@ -611,6 +649,8 @@ function closedShadowRoots(root, { frameOwners = false } = {}) {
 }
 
 const BOUND_ENDED = Symbol("bound ended");
+// Chromium's protocol errors for a read whose execution context or frame went away.
+const CONTEXT_LOST = /execution context was destroyed|cannot find context with specified id|no frame (?:for given id|with given id) found|frame with the given id was not found|target closed|session closed/i;
 // Readability work in a cell ends this long before the adapter cell deadline,
 // so a readability bound, not that deadline, is what stops it.
 const READABILITY_CELL_HEADROOM_MS = 1_000;
@@ -712,9 +752,15 @@ function boundedProbeSteps({ clock, session, token, started, boundMs, hardMs = I
 // function receives the root nodes themselves; with `frameOwners`, also the
 // iframes holding closed roots, see closedShadowRoots). Returns BOUND_ENDED
 // when the bound ended a step, null when a step failed (its execution
-// context destroyed), or { value } of the read.
-async function isolatedWorldRead({ steps, mainFrame, worldName, functionDeclaration, leadingArgs, frameOwners = false }) {
+// context destroyed), or { value } of the read. `onFailure`, when given, is
+// told which: "context_lost" for a protocol error naming a destroyed context
+// or frame, "failed" for any other failed step or a thrown exception.
+async function isolatedWorldRead({ steps, mainFrame, worldName, functionDeclaration, leadingArgs, frameOwners = false, closedRoots = true, awaitPromise = false, onFailure = null }) {
   const { send, step } = steps;
+  const failed = (error = null) => {
+    onFailure?.(CONTEXT_LOST.test(String(error?.message ?? "")) ? "context_lost" : "failed");
+    return null;
+  };
   const world = await step(() => send("Page.createIsolatedWorld", {
     frameId: mainFrame.id,
     worldName,
@@ -722,23 +768,24 @@ async function isolatedWorldRead({ steps, mainFrame, worldName, functionDeclarat
   }));
   if (world === BOUND_ENDED) return BOUND_ENDED;
   const contextId = world.value?.executionContextId;
-  if (world.error || !Number.isInteger(contextId)) return null;
-  const tree = await step(() => send("DOM.getDocument", { depth: -1, pierce: true }));
+  if (world.error || !Number.isInteger(contextId)) return failed(world.error);
+  const tree = closedRoots ? await step(() => send("DOM.getDocument", { depth: -1, pierce: true })) : { value: {} };
   if (tree === BOUND_ENDED) return BOUND_ENDED;
-  if (tree.error) return null;
+  if (tree.error) return failed(tree.error);
   const roots = await step(() => Promise.all(closedShadowRoots(tree.value?.root, { frameOwners })
     .map((backendNodeId) => send("DOM.resolveNode", { backendNodeId, executionContextId: contextId }))));
   if (roots === BOUND_ENDED) return BOUND_ENDED;
   const rootIds = roots.error ? null : roots.value.map((resolved) => resolved?.object?.objectId);
-  if (!rootIds || !rootIds.every((objectId) => typeof objectId === "string")) return null;
+  if (!rootIds || !rootIds.every((objectId) => typeof objectId === "string")) return failed(roots.error);
   const evaluated = await step(() => send("Runtime.callFunctionOn", {
     functionDeclaration,
     executionContextId: contextId,
     arguments: [...leadingArgs, ...rootIds.map((objectId) => ({ objectId }))],
     returnByValue: true,
+    ...(awaitPromise ? { awaitPromise: true } : {}),
   }));
   if (evaluated === BOUND_ENDED) return BOUND_ENDED;
-  if (evaluated.error || evaluated.value?.exceptionDetails) return null;
+  if (evaluated.error || evaluated.value?.exceptionDetails) return failed(evaluated.error);
   return { value: evaluated.value?.result?.value };
 }
 
@@ -1024,6 +1071,7 @@ export async function createPolishBrowserAdapter({
   cleanupDeadlineMs,
   startupDeadlineMs,
   networkIdleTimeoutMs,
+  seal = null,
 } = {}) {
   const authCookies = parseAuthCookie(authCookie);
   const boundedCellDeadlineMs = boundedPolishDeadline(cellDeadlineMs, POLISH_BROWSER_CELL_DEADLINE_MS);
@@ -1047,6 +1095,10 @@ export async function createPolishBrowserAdapter({
         chromium: injectedChromium,
         onMissing: polishBrowserMissing,
         signal: startupAbort.signal,
+        launchOptions: seal ? {
+          proxy: { server: seal.origin, bypass: `<-loopback>,127.0.0.1:${seal.port}` },
+          args: ["--host-resolver-rules=MAP * ~NOTFOUND, EXCLUDE 127.0.0.1", "--force-webrtc-ip-handling-policy=disable_non_proxied_udp"],
+        } : {},
       });
     } catch (error) {
       if (startupTimedOut) throw polishProducerTimeoutError();
@@ -1083,7 +1135,7 @@ export async function createPolishBrowserAdapter({
   // each setup call is a `step` of the caller's bound (boundedProbeSteps); a
   // bound that ends during setup makes the cell return `ended()` instead of
   // running `work`, and a context created after that is closed.
-  const inCaptureContext = async ({ url, viewport, signal, setup = null }, work) => {
+  const inCaptureContext = async ({ url, viewport, signal, setup = null, deviceScaleFactor, requestPolicy = null }, work) => {
     if (closed) throw new Error("Campaigns OS polish capture browser adapter is already closed.");
     if (poisonCode === POLISH_PRODUCER_TIMEOUT_ERROR_CODE) throw polishProducerTimeoutError();
     if (poisonCode === POLISH_PRODUCER_CLEANUP_ERROR_CODE) throw polishProducerCleanupError();
@@ -1163,6 +1215,7 @@ export async function createPolishBrowserAdapter({
         const newContext = () => Promise.resolve(browser.newContext({
           viewport: { width: viewport.width, height: viewport.height },
           serviceWorkers: "block",
+          ...(deviceScaleFactor === undefined ? {} : { deviceScaleFactor }),
         })).then((created) => {
           if (setupEnded) void Promise.resolve().then(() => created?.close()).catch(() => {});
           else context = created;
@@ -1171,7 +1224,19 @@ export async function createPolishBrowserAdapter({
         if (setup) await settle(newContext);
         else await newContext();
         assertActive();
-        if (authCookies.length > 0) {
+        if (requestPolicy) {
+          await settle(() => context.route("**/*", (route) => {
+            const origin = captureOrigin(route.request().url());
+            if (origin === requestPolicy.allowOrigin) return route.continue();
+            requestPolicy.block(origin, false);
+            return route.abort("blockedbyclient");
+          }));
+          await settle(() => context.routeWebSocket(/.*/, (socket) => {
+            requestPolicy.block(captureOrigin(socket.url().replace(/^ws/, "http")), true);
+            socket.close();
+          }));
+        }
+        if (!seal && authCookies.length > 0) {
           const origin = captureOrigin(url);
           // Fixed message: a URL containing credentials or query data is never echoed.
           if (origin === null) throw new Error("Campaigns OS polish capture requires an HTTP(S) capture URL before applying --auth-cookie.");
@@ -1219,6 +1284,118 @@ export async function createPolishBrowserAdapter({
     return observation;
   };
   return {
+    browserVersion: typeof browser.version === "function" ? `chromium/${browser.version()}` : null,
+    async renderForCompare({ url, viewport, deviceScaleFactor = 1, signal, requestPolicy = null,
+      readiness = {}, probes = [], shots = { actual: true, stabilized: {} }, maxHeightPx = VISUAL_MAX_CAPTURE_HEIGHT_PX,
+      budget = {} } = {}) {
+      if (deviceScaleFactor !== 1) throw new Error("Visual captures require deviceScaleFactor 1.");
+      const captureHeightPx = boundedPolishDeadline(maxHeightPx, VISUAL_MAX_CAPTURE_HEIGHT_PX);
+      // A sealed adapter cannot be used with a weaker per-context policy.
+      const policy = seal ? { allowOrigin: seal.origin } : requestPolicy;
+      const external = policy ? { blocked_count: 0, blocked_websocket_count: 0, blocked_origins: [] } : null;
+      const origins = new Set();
+      const block = (origin, websocket) => {
+        external.blocked_count++; if (websocket) external.blocked_websocket_count++;
+        if (origin && origins.size < 32) origins.add(origin);
+        external.blocked_origins = [...origins].sort();
+      };
+      const clock = isProbeClock(budget.clock) ? budget.clock : realProbeClock;
+      const started = clock.now();
+      return inCaptureContext({ url, viewport, signal, deviceScaleFactor,
+        requestPolicy: policy ? { ...policy, block } : null }, async ({ page, session, awaitActive, cellLeftMs }) => {
+        const skipped = () => ({ status: "skipped", bytes: null, full_height_css: null, crop: null, truncated: false });
+        const result = { status: "navigation_failed", networkidle: { status: "invalid", duration_ms: null },
+          readiness: { fonts: { status: "timeout", failed_faces: 0, waited_ms: 0 },
+            await: { status: "timeout", remaining_count: 0, waited_ms: 0 } }, external, probes: {}, actual: skipped(), stabilized: skipped() };
+        const finish = () => ({ ...result, elapsed_ms: Math.max(0, clock.now() - started) });
+        let response;
+        try { response = await awaitActive(page.goto(url, { waitUntil: "domcontentloaded", timeout: NAVIGATION_TIMEOUT_MS })); }
+        catch { return finish(); }
+        if (response?.status() >= 400) { result.status = "http_error"; return finish(); }
+        const initial = await awaitActive(session.send("Page.getFrameTree"));
+        const mainFrame = initial?.frameTree?.frame;
+        const navEnd = clock.now();
+        try {
+          await awaitActive(page.waitForLoadState("networkidle", { timeout: networkIdleMs }));
+          result.networkidle = { status: "settled", duration_ms: Math.max(0, clock.now() - navEnd) };
+        } catch (error) {
+          if (!timeoutError(error)) throw error;
+          result.networkidle = { status: "timeout", duration_ms: Math.max(0, clock.now() - navEnd) };
+        }
+        // Every read and its document check share the same bounded steps. A
+        // timeout names the bound that ended it, as the readability probe does:
+        // run_budget_exhausted when the run budget was the smaller clock bound
+        // and the cell deadline had not ended it, otherwise probe_timeout.
+        const read = async (probe, awaitPromise = false) => {
+          const begin = clock.now(), token = { cancelled: false };
+          const cellLeft = cellLeftMs(), runLeft = (budget.addedRemainingMs ?? Infinity) - (begin - started);
+          const boundMs = Math.max(0, Math.min(probe.boundMs, cellLeft, runLeft));
+          let steps = null;
+          const timedOutBy = () => (!steps?.hardEnded() && runLeft < Math.min(probe.boundMs, cellLeft) ? "run_budget_exhausted" : "probe_timeout");
+          const out = (status, value = null) => ({ status, value, elapsed_ms: Math.max(0, clock.now() - begin),
+            ...(status === "timeout" ? { ended_by: timedOutBy() } : {}) });
+          if (!(boundMs > 0)) return out("timeout");
+          steps = boundedProbeSteps({ clock, session, token, started: begin, boundMs, hardMs: cellLeft });
+          try {
+            let failure = null;
+            const called = await isolatedWorldRead({ steps, mainFrame, worldName: `campaigns-os-visual-${probe.name}`,
+              functionDeclaration: typeof probe.source === "function" ? probe.source.toString() : probe.source,
+              leadingArgs: (Array.isArray(probe.args) ? probe.args : [probe.args]).filter((v) => v !== undefined).map((value) => ({ value })),
+              closedRoots: probe.closedRoots === true, awaitPromise, onFailure: (kind) => { failure = kind; } });
+            if (called === BOUND_ENDED) return out("timeout");
+            // document_changed only on evidence: another main frame or loader,
+            // or a destroyed context. An ordinary probe defect stays failed.
+            const same = await sameMainDocument({ steps, mainFrame });
+            if (same === BOUND_ENDED) return out("timeout");
+            if (!same || failure === "context_lost") return out("document_changed");
+            return called === null ? out("failed") : out("measured", called.value);
+          } catch { return out("failed"); }
+          finally { token.cancelled = true; }
+        };
+        const fontsMs = boundedPolishDeadline(readiness.fontsMs, VISUAL_READINESS_FONTS_MS);
+        const awaitMs = boundedPolishDeadline(readiness.awaitMs, VISUAL_READINESS_AWAIT_MS);
+        for (const [name, ms] of [["fonts", fontsMs], ["await", awaitMs]]) {
+          const observed = await read({ name: `ready_${name}`, source: visualReady, args: [name, ms], boundMs: ms + 100 }, true);
+          if (observed.status === "measured") result.readiness[name] = observed.value;
+          else result.readiness[name].waited_ms = Math.min(ms, observed.elapsed_ms);
+        }
+        for (const probe of probes) {
+          if (probe.select && !probe.select()) continue;
+          result.probes[probe.name] = await read(probe);
+          probe.onResult?.(result.probes[probe.name]);
+        }
+        const layout = await read({ name: "geometry", source: visualGeometry, boundMs: 1500 });
+        // The document loaded: a geometry probe that could not measure is not a navigation failure.
+        if (layout.status !== "measured" || !Number.isFinite(layout.value?.height)) {
+          result.status = layout.status === "document_changed" ? "document_changed"
+            : layout.status === "timeout" ? layout.ended_by : "probe_failed";
+          return finish();
+        }
+        result.status = "rendered";
+        const fullHeight = Math.max(viewport.height, Math.ceil(layout.value.height));
+        const crop = { x: 0, y: 0, width: viewport.width, height: Math.min(fullHeight, captureHeightPx / deviceScaleFactor) };
+        const take = async (stabilized) => {
+          const shot = { status: "failed", bytes: null, full_height_css: fullHeight, crop, truncated: fullHeight > crop.height };
+          const treatment = { animations: "disabled", caret: "hide", mask_color: "#ff00ff", mask_selectors: "visual-masks/v1",
+            masks: layout.value.masks, mask_cap_reached: layout.value.mask_cap_reached };
+          if (stabilized) shot.treatment = treatment;
+          const remainingMs = Math.min(VISUAL_SHOT_MS, cellLeftMs(), (budget.addedRemainingMs ?? Infinity) - (clock.now() - started));
+          if (!(remainingMs > 0)) return { ...shot, status: "timeout" };
+          try {
+            // Screenshot options alone apply treatment, after the actual shot.
+            shot.bytes = await runWithPolishProducerDeadline(() => page.screenshot({ fullPage: true, clip: crop,
+              timeout: VISUAL_SHOT_MS, animations: stabilized ? "disabled" : "allow", caret: stabilized ? "hide" : "initial",
+              ...(stabilized ? { mask: visualMaskSelectors.map((selector) => page.locator(selector)), maskColor: "#ff00ff" } : {}) }),
+            { timeoutMs: remainingMs });
+            shot.status = "captured";
+          } catch (error) { shot.status = timeoutError(error) || error?.code === POLISH_PRODUCER_TIMEOUT_ERROR_CODE ? "timeout" : "failed"; }
+          return shot;
+        };
+        if (shots.actual) result.actual = await take(false);
+        if (shots.stabilized) result.stabilized = await take(true);
+        return finish();
+      });
+    },
     // `imageProbe` ({ clock, remainingMs, cellBoundMs, imageCap }) opts the
     // cell into the media-weight image probe; the observation then carries
     // `imageProbe` beside the page-load fields. `readabilityProbe` ({ clock,

package/src/polish-captures-record.mjs

@@ -0,0 +1,52 @@
+import { createHash } from "node:crypto";
+import { canonicalJson } from "./polish-capture.mjs";
+
+export const CAPTURES_SCHEMA = "campaigns-os-polish-captures/v0";
+export const CAPTURES_PRODUCER = "campaigns-os polish capture";
+const object = (value) => value !== null && typeof value === "object"
+  && [Object.prototype, null].includes(Object.getPrototypeOf(value));
+const own = (value, key) => object(value) && Object.hasOwn(value, key) ? value[key] : undefined;
+const viewports = new Map([["desktop", [1440, 1200]], ["mobile", [390, 844]]]);
+export function capturesIntegrity(record) {
+  const { integrity: _ignored, ...rest } = record || {};
+  return `sha256:${createHash("sha256").update(canonicalJson(rest)).digest("hex")}`;
+}
+
+// A-C4: one actual build capture per planned route; either viewport may supply it.
+export function capturedBuildForEveryRoute(record) {
+  const routes = record?.subject?.routes;
+  return Array.isArray(routes) && routes.length > 0 && Array.isArray(record?.cells)
+    && routes.every((route) => {
+      const path = typeof route === "string" ? route : own(route, "requested_route") ?? own(route, "route");
+      return typeof path === "string" && record.cells.some((cell) => object(cell) && cell.side === "build"
+        && cell.route === path && (typeof route === "string" || cell.page_id === route.page_id)
+        && cell.status === "rendered" && cell.actual?.status === "captured");
+    });
+}
+
+// Data only: ignored PNG files are deliberately not opened by the gate.
+export function packageCapturesSatisfy(record, report) {
+  if (!record || Object.getPrototypeOf(record) !== Object.prototype
+      || record.schema_version !== CAPTURES_SCHEMA || record.performed_by !== CAPTURES_PRODUCER
+      || record.integrity !== capturesIntegrity(record)
+      || !record.subject?.build_fingerprint
+      || record.subject.build_fingerprint !== report?.stages?.assembly?.build_fingerprint
+      || !Array.isArray(record.cells) || !record.cells.length) return false;
+  return capturedBuildForEveryRoute(record) && record.cells.every((cell) => {
+    if (!object(cell)) return false;
+    const viewport = viewports.get(own(cell, "viewport"));
+    if (cell.state !== "default_load" || cell.device_scale_factor !== 1
+        || !viewport || cell.width !== viewport[0] || cell.height !== viewport[1]) return false;
+    return [cell.actual, cell.stabilized].every((shot) => {
+      if (!object(shot)) return false;
+      if (shot.status !== "captured") return ["skipped", "failed", "timeout"].includes(own(shot, "status"));
+      const crop = shot.crop;
+      return Number.isFinite(shot.full_height_css) && shot.full_height_css > 0
+        && crop?.x === 0 && crop.y === 0 && crop.width === cell.width
+        && crop.height === Math.min(shot.full_height_css, 12000)
+        && shot.truncated === (shot.full_height_css > 12000)
+        && shot.png?.width_px === crop.width && shot.png.height_px === crop.height
+        && /^sha256:[a-f0-9]{64}$/.test(shot.png.sha256);
+    });
+  });
+}

package/src/polish-deadline.mjs

@@ -19,6 +19,20 @@ export const READABILITY_PROBE_CELL_MS = 1_500;
 export const READABILITY_PROBE_RUN_MS = 120_000;
 export const READABILITY_CROP_RUN_MS = 30_000;
 export const READABILITY_ADDED_RUN_MS = 300_000;
+export const VISUAL_READINESS_FONTS_MS = 3_000;
+export const VISUAL_READINESS_AWAIT_MS = 5_000;
+export const VISUAL_SHOT_MS = 10_000;
+export const VISUAL_CAPTURE_RUN_MS = 240_000;
+export const VISUAL_DIFF_RUN_MS = 60_000;
+export const VISUAL_ADDED_RUN_MS = 300_000;
+export const VISUAL_MAX_CAPTURE_HEIGHT_PX = 12_000;
+// Element parity bounds, spent inside the visual cells above: the routes a
+// run probes, one probe's bound per side, the probe's own in-page walk, and
+// every parity probe of a run.
+export const PARITY_MAX_ROUTES = 32;
+export const PARITY_PROBE_CELL_MS = 2_000;
+export const PARITY_PROBE_WALK_MS = 1_500;
+export const PARITY_PROBE_RUN_MS = 60_000;
 
 export function boundedPolishDeadline(value, fallback) {
   return Number.isSafeInteger(value) && value > 0 && value <= fallback ? value : fallback;

package/src/polish-gate.mjs

@@ -1,3 +1,4 @@
+import { packageCapturesSatisfy, capturedBuildForEveryRoute, capturesIntegrity, CAPTURES_SCHEMA, CAPTURES_PRODUCER } from "./polish-captures-record.mjs";
 import { HIDDEN_EAGER_MEDIA_SCOPE } from "./polish-page-load.mjs";
 import { HIDDEN_EAGER_MEDIA_ACTIONS } from "./gate-actions.mjs";
 
@@ -151,7 +152,7 @@ function polishEvidence(stage, report) {
   return null;
 }
 
-function fieldHasEvidence(value, field) {
+function fieldHasEvidence(value, field, report, newEvidence) {
   if (field === "issues") return Array.isArray(value);
   if (field === "commands") {
     if (!Array.isArray(value) || value.length === 0) return false;
@@ -159,6 +160,7 @@ function fieldHasEvidence(value, field) {
   }
   if (field === "visual_review") {
     if (!isObject(value)) return false;
+    if (newEvidence || Object.hasOwn(value, "captures")) return Object.hasOwn(value, "captures") && packageCapturesSatisfy(value.captures, report);
     const screenshots = value.screenshots || value.screenshot_paths || value.paths || value.urls;
     return Array.isArray(screenshots) && screenshots.some(nonEmptyString);
   }
@@ -308,13 +310,28 @@ function brandBleedResidualKinds(value) {
   return kinds;
 }
 
-function evidenceProblems(evidence, report) {
+function captureProblem(record, report) {
+  if (!record || Object.getPrototypeOf(record) !== Object.prototype || record.schema_version !== CAPTURES_SCHEMA || record.performed_by !== CAPTURES_PRODUCER) return "schema or producer";
+  if (record.integrity !== capturesIntegrity(record)) return "integrity";
+  if (record.subject?.build_fingerprint !== currentBuildFingerprint(report)) return "build binding";
+  if (!Array.isArray(record.cells) || !record.cells.length) return "cells";
+  if (!capturedBuildForEveryRoute(record)) return "no captured build screenshot for every planned route";
+  return "cell state, viewport, crop or PNG dimensions";
+}
+
+function evidenceProblems(evidence, report, newEvidence) {
   if (!isObject(evidence)) {
     return ["stages.polish.evidence must be an object with the required polish evidence categories."];
   }
   const problems = [];
   for (const field of POLISH_GATE_REQUIRED_EVIDENCE) {
-    if (!fieldHasEvidence(evidence[field], field)) {
+    if (!fieldHasEvidence(evidence[field], field, report, newEvidence)) {
+      if (field === "visual_review" && (newEvidence || Object.hasOwn(evidence[field] || {}, "captures"))) {
+        problems.push(Object.hasOwn(evidence[field] || {}, "captures")
+          ? `stages.polish.evidence.visual_review.captures is not a current package capture record (${captureProblem(evidence[field].captures, report)}); run polish capture.`
+          : "stages.polish.evidence.visual_review.captures is missing; record polish needs a package capture by this version; run polish capture.");
+        continue;
+      }
       problems.push(`stages.polish.evidence.${field} is missing or incomplete.`);
     }
   }
@@ -355,7 +372,7 @@ function commandMentionsBuild(stage, evidence) {
   return commands.some((entry) => /next-campaigns-build|campaigns-os\s+next\s+build/i.test(String(isObject(entry) ? entry.command || entry.name || "" : entry)));
 }
 
-function evaluateStructuredPolishGate({ report, required = false, now = Date.now(), currentOutputFingerprint = null } = {}) {
+function evaluateStructuredPolishGate({ report, required = false, now = Date.now(), currentOutputFingerprint = null, newEvidence = false } = {}) {
   if (!isObject(report)) {
     return required
       ? {
@@ -599,7 +616,7 @@ function evaluateStructuredPolishGate({ report, required = false, now = Date.now
     };
   }
 
-  const problems = evidenceProblems(evidence, report);
+  const problems = evidenceProblems(evidence, report, newEvidence);
   if (problems.length) {
     return {
       status: "blocked",
@@ -635,6 +652,7 @@ function evaluateStructuredPolishGate({ report, required = false, now = Date.now
     current_source_package_material_fingerprint: currentSourcePackageFingerprint,
     assembly_source_package_material_fingerprint: assemblySourcePackageFingerprint,
     performed_by: producer,
+    screenshot_evidence: Object.hasOwn(evidence.visual_review, "captures") ? "package_captures" : "legacy_paths",
     waiver: sourcePackageFreshnessWaiver,
     warnings,
   };
@@ -679,9 +697,10 @@ export function evaluatePolishGate({
   required = false,
   now = Date.now(),
   hiddenEagerMediaGate = undefined,
+  newEvidence = false,
   currentOutputFingerprint = null,
 } = {}) {
-  const base = evaluateStructuredPolishGate({ report, required, now, currentOutputFingerprint });
+  const base = evaluateStructuredPolishGate({ report, required, now, currentOutputFingerprint, newEvidence });
   if (!terminalAssembly(report)) return base;
   if (hiddenEagerMediaGate === undefined && !required) return base;
 

package/src/polish-node.mjs

@@ -3,6 +3,10 @@ import { NO_CAPTURABLE_ROUTES_CODE } from "./local-preview-policy.mjs";
 import { createHash } from "node:crypto";
 import { HIDDEN_EAGER_MEDIA_ACTIONS } from "./gate-actions.mjs";
 import { dirname, join, resolve } from "node:path";
+import { computeDesignSourcePackageMaterialFingerprint } from "./design-source-package.mjs";
+import { runVisualPass, unavailableCapturesRecord, CAPTURES_SCHEMA, CAPTURES_PRODUCER } from "./polish-visual.mjs";
+import { readRegularFileSync } from "./source-html-server.mjs";
+import { buildElementParityRecord, ELEMENT_PARITY_PRODUCER, ELEMENT_PARITY_SCHEMA } from "./parity/element-parity-record.mjs";
 import { computeBuildFingerprint, describeBuildOutputDrift } from "./built-site-scope.mjs";
 import {
   buildPageLoadCapture,
@@ -310,18 +314,22 @@ function canonicalJson(value) {
   return JSON.stringify(canonicalize(value));
 }
 
-// Covers every package-owned capture key: a page_load, media_weight or
-// readability record that changes during the browser pass refuses the
-// attachment.
+// Covers every package-owned capture key: a page_load, media_weight,
+// readability, captures or element_parity record that changes during the
+// browser pass refuses the attachment.
 function conflictToken(visualReview) {
   const hasPageLoad = Object.hasOwn(visualReview, "page_load");
   const hasMediaWeight = Object.hasOwn(visualReview, "media_weight");
   const hasReadability = Object.hasOwn(visualReview, "readability");
-  if (!hasPageLoad && !hasMediaWeight && !hasReadability) return "absent";
+  const hasCaptures = Object.hasOwn(visualReview, "captures");
+  const hasElementParity = Object.hasOwn(visualReview, "element_parity");
+  if (!hasPageLoad && !hasMediaWeight && !hasReadability && !hasCaptures && !hasElementParity) return "absent";
   const value = {
     ...(hasPageLoad ? { value: visualReview.page_load } : {}),
     ...(hasMediaWeight ? { media_weight: visualReview.media_weight } : {}),
     ...(hasReadability ? { readability: visualReview.readability } : {}),
+    ...(hasCaptures ? { captures: visualReview.captures } : {}),
+    ...(hasElementParity ? { element_parity: visualReview.element_parity } : {}),
   };
   return `sha256:${createHash("sha256").update(canonicalJson(value)).digest("hex")}`;
 }
@@ -444,6 +452,7 @@ export function createPolishCaptureBinding({ packet, report, plan, packetPath, t
         source_package_material_fingerprint: assemblySourcePackageMaterialFingerprint(report),
       },
       current_source_package_material_fingerprint: currentSourcePackageMaterialFingerprint(report),
+      source_package_on_disk: sourcePackageOnDisk(packet, resolvedPacketPath),
       page_load_conflict_token: conflictToken(visualReview),
     },
     plan: plan === null ? null : bindingPlanProjection(plan),
@@ -508,8 +517,11 @@ export function mergePolishPageLoadEvidence(report, pageLoad) {
 // readability attaches on its own: only a package-produced record bound to
 // the current build, whose every shared cell carries the integrity of the
 // matching page_load capture; any other value, or none, removes an earlier
-// one.
-export function mergePolishCaptureEvidence(report, { pageLoad = null, mediaWeight = null, readability = null, now = null } = {}) {
+// one. element_parity attaches under its own rule (elementParityAttaches),
+// beside the captures record this call attaches; with a pageLoad, any other
+// value, or none, removes an earlier one, and with no pageLoad it stays as it
+// is.
+export function mergePolishCaptureEvidence(report, { pageLoad = null, mediaWeight = null, readability = null, captures, elementParity, now = null } = {}) {
   let merged;
   if (pageLoad === null || pageLoad === undefined) {
     const { visualReview } = captureReportAncestors(report);
@@ -537,6 +549,14 @@ export function mergePolishCaptureEvidence(report, { pageLoad = null, mediaWeigh
     }
   }
   const visualReview = merged.stages.polish.evidence.visual_review;
+  if (pageLoad && captures !== undefined) {
+    if (!capturesAttach(captures, { report, pageLoad })) throw new Error("polish capture can attach only package-produced captures for the same page_load capture.");
+    visualReview.captures = captures;
+  }
+  if (pageLoad) {
+    delete visualReview.element_parity;
+    if (elementParityAttaches(elementParity, { report, captures })) visualReview.element_parity = elementParity;
+  }
   delete visualReview.readability;
   if (readabilityAttaches(readability, { buildFingerprint: currentBuildFingerprint(report), pageLoad: visualReview.page_load })) {
     visualReview.readability = readability;
@@ -544,6 +564,27 @@ export function mergePolishCaptureEvidence(report, { pageLoad = null, mediaWeigh
   return merged;
 }
 
+function sourcePackageOnDisk(packet, packetPath) {
+  if (!packet.design_source_package?.path) return null;
+  try { return computeDesignSourcePackageMaterialFingerprint(JSON.parse(readRegularFileSync(resolve(dirname(packetPath), packet.design_source_package.path)).toString("utf8"))); }
+  catch { return "unavailable"; }
+}
+
+export function capturesAttach(record, { report, pageLoad }) {
+  return isPlainObject(record) && record.schema_version === CAPTURES_SCHEMA && record.performed_by === CAPTURES_PRODUCER
+    && record.subject?.build_fingerprint === currentBuildFingerprint(report)
+    && ["routes", "route_scope", "viewports"].every((key) => canonicalJson(record.subject?.[key]) === canonicalJson(pageLoad?.subject?.[key]));
+}
+
+// A package-produced element_parity record bound to the current build and to
+// the captures record attached in the same merge. Readability plays no part.
+export function elementParityAttaches(record, { report, captures }) {
+  const buildFingerprint = currentBuildFingerprint(report);
+  return isPlainObject(record) && record.schema_version === ELEMENT_PARITY_SCHEMA && record.performed_by === ELEMENT_PARITY_PRODUCER
+    && Boolean(buildFingerprint) && record.subject?.build_fingerprint === buildFingerprint
+    && isPlainObject(captures) && typeof captures.integrity === "string" && record.subject?.captures_integrity === captures.integrity;
+}
+
 function readabilityAttaches(record, { buildFingerprint, pageLoad }) {
   if (!isPlainObject(record)
     || record.schema_version !== READABILITY_SCHEMA
@@ -629,7 +670,40 @@ function captureCampaignSlug(packet, report) {
 
 export async function capturePolishPageLoad(options = {}) {
   const plan = planPolishCapture({ packet: options.packet, baseUrl: options.baseUrl });
-  return runPolishCapture({ ...options, plan });
+  const result = await runPolishCapture({ ...options, plan });
+  if (!options.visual) return result;
+  const freeze = (value) => { if (value && typeof value === "object" && !Object.isFrozen(value)) {
+    Object.values(value).forEach(freeze); Object.freeze(value);
+  } return value; };
+  const frozen = freeze(result);
+  options.onFrozen?.(frozen);
+  // Element parity rides C's visual cells (its probe on both sides of each);
+  // its modules load only here, where the plan has a route.
+  let parity = null;
+  try {
+    const importer = options.visual.parityImporter ?? (() => Promise.all([import("./parity/probe.mjs"), import("./parity/snapshot.mjs")]));
+    const [probe, snapshot] = await importer();
+    parity = { snapshot, run: probe.createParityProbeRun({ routes: plan.routes }) };
+  } catch { /* no parity probe: no element_parity record, so the merge removes an earlier one */ }
+  let captures;
+  try { captures = await runVisualPass({ ...options, ...options.visual, frozen, probes: parity ? [parity.run.probe] : [] }); }
+  catch {
+    // Even unexpected artifact/dependency failures cannot discard prior work.
+    captures = unavailableCapturesRecord({ plan, subject: { ...frozen.page_load.subject,
+      source_package_material_fingerprint: currentSourcePackageMaterialFingerprint(options.report) }, measuredAt: options.now });
+  }
+  let elementParity = null;
+  if (parity) {
+    // Probe files are written after both visual browsers have closed.
+    const targetRepo = options.visual.targetRepo ?? options.targetRepo;
+    try {
+      elementParity = buildElementParityRecord({ plan, captures, run: parity.run, packet: options.packet,
+        packetPath: options.visual.packetPath ?? options.packetPath, buildFingerprint: currentBuildFingerprint(options.report),
+        sourceFingerprint: currentSourcePackageMaterialFingerprint(options.report),
+        writeFile: (value) => parity.snapshot.writeParityFile(targetRepo, value), measuredAt: options.now ?? new Date() });
+    } catch { elementParity = null; }
+  }
+  return { ...frozen, captures, ...(elementParity ? { element_parity: elementParity } : {}) };
 }
 
 // The readability-only capture of a campaign with no capturable page_load