@nextcommerce/campaigns-os 1.59.0 → 1.61.0

package/src/qa-analytics-correctness.mjs

@@ -114,13 +114,25 @@ export function assessAnalyticsInventory(capture = {}, contract = {}, options =
   if (providers.facebook && providers.facebook.enabled !== false) {
     const id = providers.facebook.pixelId;
     const present = inventoryHas(inventory, "meta", id);
+    // #686: page code replaced window.fbq, so in-page calls after that were
+    // not observed. Without a matching pixel request the row is unmeasured,
+    // not a clean absence.
+    const unmeasured = !present && capture.metaObserver === "disarmed";
     assertions.push(emit({
       id: "analytics-correctness:tag:meta",
       status: present ? STATUS.PASS : STATUS.FAIL,
       severity: SEVERITY.BLOCKER,
       expected: `Meta pixel ${id || ""} fires on the page`.trim(),
-      actual: present ? "present" : `absent (${(inventory.meta || []).length} meta pixel(s) fired, none matching)`,
-      evidence: { declared: id || null, observed_count: (inventory.meta || []).length },
+      actual: present
+        ? "present"
+        : unmeasured
+          ? `unmeasured: the page replaced window.fbq, so in-page pixel calls could not be observed (${(inventory.meta || []).length} meta pixel(s) seen, none matching)`
+          : `absent (${(inventory.meta || []).length} meta pixel(s) fired, none matching)`,
+      evidence: {
+        declared: id || null,
+        observed_count: (inventory.meta || []).length,
+        ...(unmeasured ? { reason: "fbq_observer_disarmed" } : {}),
+      },
     }));
   }
 

package/src/qa-analytics-parity.mjs

@@ -107,6 +107,53 @@ export function analyticsInitScript(layers = HOOKED_DATA_LAYERS) {
         set(next) { backing = wrap(name, next || []); },
       });
     }
+    // Meta pixel calls (#686). Headless Chromium can run fbq init/track without
+    // fbevents.js ever requesting facebook.com/tr, so the pixel is also observed
+    // in-page: a pixel id counts once it is initialised and a track call follows
+    // in the same document. Only the id and event name leave the page.
+    const metaInits = [];
+    // Mirrored into the in-page store as well, like record(), for pages where
+    // the binding could not attach.
+    store.metaCalls = [];
+    const metaFire = (id, ev) => {
+      const call = { id: String(id), ev: ev ? String(ev) : null };
+      store.metaCalls.push(call);
+      emit({ type: "meta_call", call, document: documentState });
+    };
+    const pixelId = (value) => (typeof value === "string" || typeof value === "number") && String(value) ? String(value) : null;
+    const recordFbq = (args) => {
+      try {
+        const method = String(args[0] || "");
+        // fbq('init', pixelId[, userData]): the pixel id is always args[1].
+        if (method === "init" && pixelId(args[1])) {
+          const id = pixelId(args[1]);
+          if (!metaInits.includes(id)) metaInits.push(id);
+        } else if (method === "track" || method === "trackCustom") {
+          for (const id of metaInits) metaFire(id, args[1]);
+        } else if ((method === "trackSingle" || method === "trackSingleCustom") && metaInits.includes(pixelId(args[1]))) {
+          metaFire(args[1], args[2]);
+        }
+      } catch (_) {}
+    };
+    const wrapFbq = (fn) => {
+      if (typeof fn !== "function" || fn.__nextQaWrapped || typeof Proxy !== "function") return fn;
+      // A Proxy keeps fbq's own properties (queue, callMethod, loaded) on the
+      // real function, so fbevents.js sees the object it installed.
+      return new Proxy(fn, {
+        apply(target, self, args) { recordFbq(args); return Reflect.apply(target, self, args); },
+        get(target, key, receiver) { return key === "__nextQaWrapped" ? true : Reflect.get(target, key, receiver); },
+      });
+    };
+    let fbqBacking = wrapFbq(window.fbq);
+    // The getter is marked so a read can tell this accessor from one page code
+    // installed, or from a deleted property.
+    const fbqGet = function () { return fbqBacking; };
+    Object.defineProperty(fbqGet, "__nextQaFbqAccessor", { value: true });
+    Object.defineProperty(window, "fbq", {
+      configurable: true,
+      get: fbqGet,
+      set(next) { fbqBacking = wrapFbq(next); },
+    });
   })();`;
 }
 
@@ -209,6 +256,18 @@ export async function attachAnalyticsCapture(page, options = {}) {
           }
           return;
         }
+        if (payload?.type === "meta_call") {
+          // An in-page fbq call is pixel inventory only. Its event name stays
+          // out of `params`, so it never counts as a Meta Purchase fire or
+          // supplies a CAPI dedup key; those still need the /tr request.
+          const id = payload.call?.id;
+          if (!id) return;
+          const document = payload.document
+            ? lookupDocument(payload.document, { fallbackUrl: sourceUrl, mainFrame })
+            : (mainFrame ? activeMainDocument : null) || lookupDocument({}, { fallbackUrl: sourceUrl, mainFrame });
+          tagFires.push({ kind: "meta", id: String(id), host: null, params: {}, source: "fbq", event: payload.call?.ev || null, document });
+          return;
+        }
         const entry = payload?.type === "event" ? payload.entry : payload;
         const attributed = attributeEvent(entry, { mainFrame, fallbackUrl: sourceUrl });
         if (attributed) accumulatedEvents.push(attributed);
@@ -243,6 +302,19 @@ export async function attachAnalyticsCapture(page, options = {}) {
     try {
       const raw = await page.evaluate(() => ({
         events: window.__nextQaAnalytics?.events || [],
+        metaCalls: window.__nextQaAnalytics?.metaCalls || [],
+        // Whether in-page fbq calls were still observable when read: page code
+        // that redefines window.fbq removes the wrapper (#686).
+        // Deleting or redefining the property disarms it too; "absent" means
+        // the QA accessor is still installed and no pixel was ever set.
+        metaObserver: (() => {
+          if (!window.__nextQaAnalytics) return null;
+          const descriptor = Object.getOwnPropertyDescriptor(window, "fbq");
+          if (!descriptor || !descriptor.get || descriptor.get.__nextQaFbqAccessor !== true) return "disarmed";
+          const fbq = window.fbq;
+          if (fbq === undefined || fbq === null) return "absent";
+          return fbq.__nextQaWrapped === true ? "armed" : "disarmed";
+        })(),
         document: window.__nextQaAnalytics?.document || { url: String(location.href || "") },
       }));
       snapshot = Array.isArray(raw) ? { events: raw, document: null } : (raw || snapshot);
@@ -272,18 +344,28 @@ export async function attachAnalyticsCapture(page, options = {}) {
     const journeyEvents = bindingAttached
       ? [...accumulatedEvents, ...snapshotEvents]
       : snapshotEvents;
+    // Without the binding, in-page fbq calls come only from this document's
+    // store; with it, they are already in tagFires.
+    const snapshotMetaFires = !bindingAttached && Array.isArray(snapshot.metaCalls)
+      ? snapshot.metaCalls.filter((call) => call?.id).map((call) => ({
+          kind: "meta", id: String(call.id), host: null, params: {}, source: "fbq", event: call.ev || null, document: snapshotDocument,
+        }))
+      : [];
+    const journeyTagFires = [...tagFires, ...snapshotMetaFires];
     const currentEvents = journeyEvents.filter(
       (entry) => entry.document?.mainFrame === true
         && entry.document.generation === currentDocument.generation,
     );
-    const currentTagFires = tagFires.filter(
+    const currentTagFires = journeyTagFires.filter(
       (fire) => fire.document?.mainFrame === true
         && fire.document.generation === currentDocument.generation,
     );
+    const metaObserver = typeof snapshot.metaObserver === "string" ? snapshot.metaObserver : null;
     return {
-      journey: normalizeCapture({ events: journeyEvents, tagFires }),
+      journey: { ...normalizeCapture({ events: journeyEvents, tagFires: journeyTagFires }), metaObserver },
       currentDocument: {
         ...normalizeCapture({ events: currentEvents, tagFires: currentTagFires }),
+        metaObserver,
         document: publicDocument(currentDocument),
       },
     };
@@ -457,13 +539,16 @@ export function normalizeCapture({ events = [], tagFires = [] } = {}) {
   }
 
   const inventory = { gtm: [], ga4: [], google_ads: [], meta: [], tiktok: [], everflow: [], other: [] };
+  // Pixel ids seen on a facebook.com request, apart from in-page fbq calls.
+  const metaRequestIds = [];
   let metaPurchaseEventId = null;
   let metaPurchaseFired = false;
   let ga4PurchaseFired = false;
   for (const fire of tagFires) {
     if (!fire || !inventory[fire.kind]) continue;
     if (fire.id && !inventory[fire.kind].includes(fire.id)) inventory[fire.kind].push(fire.id);
-    if (fire.kind === "meta") {
+    if (fire.kind === "meta" && fire.source !== "fbq") {
+      if (fire.id && !metaRequestIds.includes(fire.id)) metaRequestIds.push(fire.id);
       const ev = fire.params?.ev || fire.params?.event;
       if (ev && String(ev).toLowerCase() === "purchase") {
         metaPurchaseFired = true;
@@ -483,6 +568,7 @@ export function normalizeCapture({ events = [], tagFires = [] } = {}) {
     purchase: purchase ? { present: true, ...purchase } : { present: false },
     purchasesByEvent,
     inventory,
+    metaRequestIds,
     metaPurchaseEventId,
     // Purchase can fire from any of three sources (dataLayer event, Meta pixel,
     // GA4) — campaigns that block the SDK event and fire Meta/GA4 manually still
@@ -680,8 +766,11 @@ export function diffAnalyticsParity(baseline, candidate, options = {}) {
 
     // 5. Meta CAPI dedup — candidate's Meta Purchase fire carries an eventID,
     //    consistent with the order id so client + server events dedup.
-    const baselineHasMeta = (b.inventory?.meta || []).length > 0;
-    const candidateHasMeta = (c.inventory?.meta || []).length > 0;
+    //    Keyed on pixel requests: an in-page fbq call with no /tr request has
+    //    no eventID to compare (#686).
+    const metaRequests = (cap) => cap.metaRequestIds || cap.inventory?.meta || [];
+    const baselineHasMeta = metaRequests(b).length > 0;
+    const candidateHasMeta = metaRequests(c).length > 0;
     if (baselineHasMeta || candidateHasMeta) {
       const eid = c.metaPurchaseEventId;
       const consistent = eid && cp.transactionId && String(eid) === String(cp.transactionId);

package/src/qa-node.mjs

@@ -138,7 +138,7 @@ Usage:
   campaigns-os qa publish --packet <campaign-runtime.build.json> [--verdict <full-verdict.json>] [--republish] [--proxy-base <url>] [--dry-run] [--json]   # post an already-stored verdict to the QA portal; no re-run, no orders
   campaigns-os qa resolve <map-id> --spec <campaign-spec.json> [--base-url <url>]
   campaigns-os qa run <map-id> --spec <campaign-spec.json> --base-url <url>
-  campaigns-os qa run --site <page-kit-target-repo> --base-url <url> --family <family> [--slug <slug>] [--browser]   # L7: QA a built _site/ with no packet/spec
+  campaigns-os qa run --site <page-kit-target-repo> --base-url <url> --family <family> [--slug <slug>] [--currency <code>] [--browser]   # L7: QA a built _site/ with no packet/spec
   campaigns-os qa install-browser [--json]   # one-time: install the package-owned Playwright Chromium (same as npm run qa:install-browser from a checkout)
 
 Options:
@@ -249,6 +249,19 @@ Options:
   --test-exp-year <yyyy>          Test card expiration year. Default: 2030.
   --test-email <email>            Customer email for browser test orders. Env CAMPAIGNS_OS_QA_TEST_EMAIL is also recognized.
   --test-email-prefix <prefix>    Legacy unique email prefix override.
+  --test-first-name <name>        Test customer first name. Default: QA.
+  --test-last-name <name>         Test customer last name. Default: Playwright.
+  --test-phone <phone>            Test customer phone, filled when the checkout has the field. Default: empty.
+  --test-country <code>           Shipping (and billing) country, as the checkout's country select option value
+                                  or label (e.g. GB). Default: US. Changing it does not change the run's currency:
+                                  pair it with --currency <code>, and pass the four address flags below for that
+                                  country, since their defaults are a US address. A non-USD --currency on an
+                                  ordering run with no --test-country prints a warning; the run still goes ahead.
+  --test-address1 <line>          Street address. Default: 1600 Amphitheatre Pkwy.
+  --test-city <city>              City. Default: Mountain View.
+  --test-province <code>          State, province or region, as the province select's option value or label.
+                                  Default: CA. The checkout must show a province select for the country.
+  --test-postal <code>            Postal code. Default: 94043.
   --legacy-api-test-order <off|accept|decline|both>
                                   Diagnostic-only direct Campaigns API order creation; bypasses deployed checkout.
   --api-key <key>                 Campaigns API key for legacy direct API diagnostics. Env QA_CAMPAIGNS_API_KEY is also recognized.
@@ -765,8 +778,8 @@ function resolvedFromBlockedCheckpointPreflight(preflight, args) {
 // yields "not_applicable" rather than blocking, so browser QA still runs the
 // residue/placeholder/demo gates. Test orders are not attempted (no policy).
 export function resolveQaInputsFromSite(args) {
-  const baseUrl = normalizeBaseUrl(stringArg(args["base-url"]));
-  if (!baseUrl) {
+  const inputBaseUrl = normalizeBaseUrl(stringArg(args["base-url"]));
+  if (!inputBaseUrl) {
     throw refused("Non-packet site QA requires --base-url <served-campaign-root> so built pages have a fetchable URL.");
   }
   const templateFamily = stringArg(args.family);
@@ -778,6 +791,10 @@ export function resolveQaInputsFromSite(args) {
   if (!scope.ok) {
     throw new Error(scope.error || `Could not resolve a built campaign from ${targetRepo}.`);
   }
+  // The built pages live under _site/<slug>/, so compose the slug onto a site
+  // origin the way packet QA does; a base URL already ending in the slug is
+  // left alone (#683).
+  const baseUrl = normalizeQaBaseUrl(inputBaseUrl, scope.slug);
   const brandContract = loadBrandContract(templateFamily);
   if (brandContract.status !== "loaded" || !brandContract.contract) {
     throw new Error(`Non-packet site QA requires a loadable template brand contract for --family "${templateFamily}" (got ${brandContract.status}).`);
@@ -800,8 +817,8 @@ export function resolveQaInputsFromSite(args) {
     polishGate,
     // Non-packet site QA has no Assembly Report, so no recorded waivers.
     qaWaivers: {},
-    // Non-packet site QA: --base-url IS the served campaign root by this
-    // mode's contract (no spec identity exists to compose from).
+    // Non-packet site QA: the served campaign root is --base-url with the
+    // built slug composed on (no spec identity exists to compose from).
     analyticsCaptureTarget: buildAnalyticsCaptureTarget({
       url: ensureUrlTrailingSlash(baseUrl),
       publicRouteSlug: scope.slug || null,
@@ -2175,6 +2192,21 @@ function qaRunCurrency(args) {
   return value.toUpperCase();
 }
 
+// `qa run --currency <code>` pins the market the pages and orders run in, but
+// the order runner's shipping address comes from the --test-* flags and
+// defaults to a US one. A non-USD currency with no --test-country is the
+// likely mismatch, so it is named on stderr. Only the missing flag is judged:
+// a currency such as EUR has many markets, so an explicit --test-country is
+// taken as the operator's choice. The run is never refused.
+function warnCurrencyWithoutTestCountry(args, write = (message) => process.stderr.write(message)) {
+  const currency = qaRunCurrency(args);
+  if (!currency || currency === "USD") return false;
+  if (String(args["test-order"] || "off").toLowerCase() === "off") return false;
+  if (stringArg(args["test-country"])) return false;
+  write(`[qa:test-order] --currency ${currency} with no --test-country: test orders use the default US shipping address. Pass --test-country, --test-address1, --test-city, --test-province and --test-postal for the ${currency} market, or ignore this if a US address is intended.\n`);
+  return true;
+}
+
 async function runParityQa(args) {
   // Checked here as well as on the budget itself: the budget is built after a
   // browser has launched, and a flag the operator typed wrong should cost them
@@ -2253,7 +2285,7 @@ async function runQa(args, options = {}) {
   // Fail-fast before anything resolves or launches. The authoritative check
   // lives on the creation budget itself, which every browser path builds.
   refuseBadOrderCreationLimit(args);
-  qaRunCurrency(args);
+  warnCurrencyWithoutTestCountry(args);
   // Match dispatch: an active browser mode takes precedence over legacy API
   // diagnostics. Only the selected legacy path requires a cart and API mode.
   const browserMode = String(args["test-order"] || "off").toLowerCase();
@@ -4260,6 +4292,7 @@ export const __qaNodeTestHooks = Object.freeze({
   templateBrandContractAssertion,
   deriveEntryUrls,
   qaRunCurrency,
+  warnCurrencyWithoutTestCountry,
   withEntryCurrency,
   derivePageUrls,
   deriveTestedUrlsFromAssertions,

package/src/qc-accept.mjs

@@ -13,6 +13,7 @@ import { existsSync, readFileSync } from "node:fs";
 import { isNamedHuman, validateWaiverAttribution } from "./checkpoint-waiver.mjs";
 import { DOCTOR_SIDECAR_SCHEMA } from "./doctor-sidecar.mjs";
 import { cmd } from "./install-invocation.mjs";
+import { PARITY_TOLERANCES } from "./parity/compare.mjs";
 import { canonicalJson } from "./polish-capture.mjs";
 import { QC_CHECK_REGISTRY } from "./qc-check-registry.mjs";
 import { QC_LEGS, QC_REASON, fingerprint12, qcResultRef } from "./qc-results.mjs";
@@ -27,7 +28,117 @@ export const QC_DISPOSITION = Object.freeze({ OPEN: "open", OPERATOR_ACCEPTED: "
 // full QA verdict, or, on the Polish leg, the package-owned record the
 // accepted check is read from (QC_CHECK_REGISTRY `record`).
 const QC_LEG_SOURCES = Object.freeze({ doctor: "doctor_sidecar", qa: "qa_full_verdict" });
-export const QC_POLISH_RECORD_SOURCES = Object.freeze({ media_weight: "polish_media_weight", readability: "polish_readability" });
+export const QC_POLISH_RECORD_SOURCES = Object.freeze({ media_weight: "polish_media_weight", readability: "polish_readability", captures: "polish_captures", element_parity: "polish_element_parity" });
+
+const DESIGN_ACCESS_TEXT = Object.freeze({
+  design_access_missing: "A design file is recorded for this page, but this version of Campaigns OS cannot read design files. Element parity compares the built page with the page's source HTML export instead, so differences between the export and the design file are not checked. Nothing needs to change to continue. Where it matters, compare the export with the design file by hand.",
+  design_reference_not_recorded: "This page names a design file that the Design Source Package does not record. Rerun intake with `--force` to record it (this resets stage evidence), or continue: element parity still runs against the source HTML.",
+  design_reference_missing: "The Design Source Package records a design file, but this page no longer has a design-file declaration. Restore the declaration, or rerun intake with `--force` to drop the recorded file.",
+  design_reference_changed: "The design file named for this page differs from the one the Design Source Package records. Rerun intake with `--force` to record the current one.",
+  design_reference_conflict: "The CampaignSpec page and the source-html manifest name different design files or frames for this page (or the manifest's producer file key differs). The package records the CampaignSpec's. Correct the wrong one and rerun intake with `--force`.",
+});
+const probeIncomplete = (code) => `The element probe did not complete (${code}); not compared.`;
+const notRendered = (code) => `The source or built page did not render (${code}).`;
+const partlyRead = "Only part of the page was read; findings are not accept-eligible.";
+const textNotRead = "Some page text was not read (long text, closed components or frames) on the source page, the built page or both. Where the built page's text was not read, copy is not called missing.";
+const packageMismatch = "The Design Source Package on disk does not match the build's; rerun intake or polish capture.";
+const PARITY_COVERAGE_TEXT = Object.freeze({
+  ...Object.fromEntries(["navigation_failed", "http_error", "producer_timeout", "browser_unavailable", "source_html_missing", "source_root_unavailable"].map((code) => [code, notRendered(code)])),
+  ...Object.fromEntries(["probe_timeout", "probe_failed", "probe_not_run", "document_changed", "run_budget_exhausted"].map((code) => [code, probeIncomplete(code)])),
+  page_not_captured: "Not captured for element parity: beyond the 32-page run limit, or added since the last capture. Rerun polish capture.",
+  readiness_incomplete: "Fonts or awaited content were not ready in time; not compared.",
+  source_identity_unrecorded: "The Design Source Package records no hash for this source file; not compared.",
+  probe_file_absent: "Probe files are local and not committed; rerun polish capture on this machine.",
+  design_elements_unavailable: "The source has no text elements (for example an image-only export); element parity is unavailable.",
+  viewport_mismatch: "Source and build rendered at different sizes or pixel ratios; nothing is resized.",
+  probe_output_invalid: "The page measurements could not be read; not compared.",
+  comparator_failed: "The comparison could not run; not compared.",
+  element_cap_reached: partlyRead,
+  probe_time_cap_reached: partlyRead,
+  page_text_truncated: textNotRead,
+  closed_shadow_root_not_read: textNotRead,
+  frame_not_read: textNotRead,
+  font_face_cap_reached: "More than 200 font faces; web-font availability was not fully checked.",
+  source_package_unavailable: packageMismatch,
+  source_package_stale: packageMismatch,
+});
+export const QC_COVERAGE_TEXT = Object.freeze({
+  "design.access": Object.freeze({
+    design_access_missing: DESIGN_ACCESS_TEXT.design_access_missing,
+    design_reference_not_recorded: DESIGN_ACCESS_TEXT.design_reference_not_recorded,
+  }),
+  "parity.element": PARITY_COVERAGE_TEXT,
+});
+export const QC_COVERAGE_LIMIT_TEXT = Object.freeze({ "parity.element": Object.freeze({
+  font_usage_not_observed: "The font each glyph was drawn with is not read; a web font that loaded is assumed used.",
+}) });
+
+export function designAccessSummary(row) {
+  return row.check === "design.access" && row.result === "review" ? DESIGN_ACCESS_TEXT[row.reason_code] ?? null : null;
+}
+
+// A parity.element row in words, from its read-time observation: the design
+// element's label, then each comparator member with its measured values and
+// tolerance. Geometry also names the design selector path. Null for any other
+// row, and for a parity row with nothing to say (an unexercised row has no
+// observation members).
+const signed = (value, unit = "") => `${value < 0 ? "−" : "+"}${Math.abs(value)}${unit}`;
+const px = (value) => (typeof value === "number" ? `${value}px` : String(value));
+const rgb = (value) => (Array.isArray(value) ? `rgb(${value.join(",")})` : "not measured");
+const PARITY_GEOMETRY_TEXT = Object.freeze({
+  gap: (delta) => `moved ${signed(delta, "px")} against the element above (gap, tolerance ${PARITY_TOLERANCES.gap_px}px)`,
+  x_position: (delta) => `moved ${signed(delta, "px")} horizontally (x position, tolerance ${PARITY_TOLERANCES.position_px}px)`,
+  width: (delta) => `resized ${signed(delta, "px")} in width (width, tolerance ${PARITY_TOLERANCES.size_px}px)`,
+  height: (delta) => `resized ${signed(delta, "px")} in height (height, tolerance ${PARITY_TOLERANCES.size_px}px)`,
+});
+const PARITY_TYPE_TOLERANCES = Object.freeze({ font_size: `${PARITY_TOLERANCES.font_size_px}px`, line_height: `${PARITY_TOLERANCES.line_height_px}px`,
+  letter_spacing: `${PARITY_TOLERANCES.letter_spacing_px}px`, font_weight: "0" });
+const PARITY_COPY_TEXT = Object.freeze({
+  copy_missing: () => "design copy not found on the built page",
+  copy_changed: (similarity) => `design copy changed (similarity ${similarity})`,
+  page_text_truncated: () => "design copy not found in the readable part of the built page (review)",
+  build_text_not_read: () => "design copy not found in the readable part of the built page (review)",
+});
+
+function parityMemberText(category, member, reason, result) {
+  const { property, design, build, delta } = member;
+  const review = result === "review" ? " (review)" : "";
+  if (category === "geom") return PARITY_GEOMETRY_TEXT[property]?.(delta) ?? `${property} ${signed(delta, "px")}`;
+  if (category === "type") {
+    const name = property === "font_face" ? "web font" : property.replace(/_/g, "-");
+    const units = ["font_size", "line_height", "letter_spacing"].includes(property) ? "px" : "";
+    const tolerance = typeof delta === "number" && Object.hasOwn(PARITY_TYPE_TOLERANCES, property) ? ` (${signed(delta, units)}, tolerance ${PARITY_TYPE_TOLERANCES[property]})` : "";
+    const value = units ? px : String;
+    return `${name} ${value(design)} → ${value(build)}${tolerance}${review}`;
+  }
+  if (category === "color") {
+    if (property === "color") return `colour not measured (source ${design ?? "unresolved"}, build ${build ?? "unresolved"})${review}`;
+    const name = property === "background_color" ? "background colour" : "text colour";
+    const tolerance = typeof delta === "number" ? ` (${delta}/255, tolerance ${PARITY_TOLERANCES.color_channel})` : "";
+    return `${name} ${rgb(design)} → ${rgb(build)}${tolerance}${review}`;
+  }
+  return PARITY_COPY_TEXT[reason]?.(delta) ?? null;
+}
+
+export function parityRowSummary(row) {
+  if (row?.check !== "parity.element") return null;
+  const key = String(row.subject?.key ?? "");
+  if (key === "comparison") return row.result === "review" && row.reason_code === "source_identity_mismatch"
+    ? "source on disk differs from the recorded source; element parity not compared" : null;
+  const category = key.split(":")[0];
+  const observation = isPlainObject(row.observation) ? row.observation : {};
+  const members = Array.isArray(observation.members) ? observation.members.filter(isPlainObject) : [];
+  if (!["copy", "type", "color", "geom"].includes(category) || !members.length) return null;
+  const results = new Map((Array.isArray(row.members) ? row.members : []).map((member) => [member?.key, member]));
+  const texts = members.map((member) => {
+    const reported = results.get(member.property);
+    return parityMemberText(category, member, reported?.reason_code ?? row.reason_code, reported?.result ?? row.result);
+  }).filter(Boolean);
+  if (!texts.length) return null;
+  const selector = isNonEmptyString(observation.design_selector_path) ? observation.design_selector_path : null;
+  const label = isNonEmptyString(observation.label) ? observation.label : selector ?? key;
+  return `${label}${category === "geom" && selector && label !== selector ? ` (${selector})` : ""}: ${texts.join("; ")}`;
+}
 
 // Null for a Polish check with no record, or a leg with no source.
 export function measuredSourceFor(leg, check) {
@@ -165,9 +276,12 @@ function assessOne(record, currentById, nowMs) {
   if (!(Date.parse(record.accepted_at) > Date.parse(record.measured_at))) return { status: "inert", why: "accepted_not_after_measurement" };
   const current = currentById.get(record.result_id);
   if (!current) return { status: "orphaned", why: "no_current_result" };
-  if (current.result === "unexercised" && [QC_REASON.STALE_BINDING, QC_REASON.EVIDENCE_NOT_REPRODUCIBLE].includes(current.reason_code)) {
+  if (current.result === "unexercised" && [QC_REASON.STALE_BINDING, QC_REASON.EVIDENCE_NOT_REPRODUCIBLE, "capture_file_absent"].includes(current.reason_code)) {
     return { status: "lapsed", why: current.reason_code, current };
   }
+  // Visual references lose their revision-baseline warning when provenance
+  // becomes independent (§6); that disposition precedes fingerprint changes.
+  if (current.check === "visual.reference" && current.result !== "warning") return { status: "inert", why: "target_not_warning", current };
   if (current.state_fingerprint !== record.state_fingerprint
     || current.check !== record.check
     || current.leg !== record.leg
@@ -325,6 +439,21 @@ function readabilityReviewCrop(row) {
   return typeof ref?.path === "string" ? ref.path : undefined;
 }
 
+function visualSummary(row) {
+  const item = row.observation;
+  if (!item || !row.check?.startsWith("visual.")) return null;
+  const label = `${row.subject.page} ${row.subject.viewport || ""}`.trim();
+  if (row.check === "visual.reference" && row.reason_code === "self_referential") {
+    return `${label} reference ${item.ref_id} is the build's own output (${(item.provenance?.reasons || []).join(", ")}); accepting adopts a revision baseline, not design proof`;
+  }
+  if (row.check !== "visual.diff" || row.result !== "review") return null;
+  const percent = (value) => Number.isFinite(value) ? `${(100 * value).toFixed(2)}%` : "unavailable";
+  const delta = (value) => Number.isFinite(value) ? `${value >= 0 ? "+" : ""}${value}px` : "unavailable";
+  const worst = item.bands?.find((band) => band.status === "compared");
+  const heatmap = item.artifacts?.find((a) => a.band_key === worst?.key)?.heatmap?.path || item.artifacts?.[0]?.heatmap?.path;
+  return `${label} vs ${item.basis === "source_html" ? "source HTML" : item.ref_id}: ${percent(item.page?.mismatch_ratio)} differing, ${delta(item.page?.height_delta_px)} height${worst ? `; worst band ${worst.key} (${percent(worst.mismatch_ratio)}, ${delta(worst.height_delta_px)})` : ""}${heatmap ? `; heatmap ${heatmap}` : ""}`;
+}
+
 function handoffEntry(row) {
   const crop = readabilityReviewCrop(row);
   return {
@@ -338,7 +467,7 @@ function handoffEntry(row) {
     reason_code: row.reason_code,
     accept_eligible: row.accept_eligible === true,
     members: Array.isArray(row.members) ? row.members : [],
-    summary: readabilityPairSummary([row]) ?? `${row.check} ${row.result}${row.reason_code ? ` (${row.reason_code})` : ""} on ${row.subject?.page ?? "(no page)"}${row.subject?.key == null ? "" : `: ${row.subject.key}`}`,
+    summary: designAccessSummary(row) ?? parityRowSummary(row) ?? visualSummary(row) ?? readabilityPairSummary([row]) ?? `${row.check} ${row.result}${row.reason_code ? ` (${row.reason_code})` : ""} on ${row.subject?.page ?? "(no page)"}${row.subject?.key == null ? "" : `: ${row.subject.key}`}`,
     ...(crop === undefined ? {} : { crop }),
   };
 }
@@ -366,7 +495,8 @@ function groupOpenWarnings(entries, rows = []) {
       pages,
       accept_eligible: results.every((entry) => entry.accept_eligible),
       summary: results.length > 1
-        ? readabilityPairSummary(results.map((entry) => rows.find((row) => qcResultRef(row) === entry.result_ref))) ?? `${lead.check} ${lead.result}${lead.reason_code ? ` (${lead.reason_code})` : ""} on ${pages.join(", ")}${lead.key == null ? "" : `: ${lead.key}`}`
+        ? parityRowSummary(rows.find((row) => qcResultRef(row) === lead.result_ref))
+          ?? readabilityPairSummary(results.map((entry) => rows.find((row) => qcResultRef(row) === entry.result_ref))) ?? `${lead.check} ${lead.result}${lead.reason_code ? ` (${lead.reason_code})` : ""} on ${pages.join(", ")}${lead.key == null ? "" : `: ${lead.key}`}`
         : lead.summary,
       results,
     };
@@ -427,6 +557,15 @@ export function buildQcHandoff({ results, coverage = [], accepts, now = new Date
   }
   const grouped = new Map();
   for (const row of results) {
+    for (const limit of new Set(row.coverage?.limits || [])) {
+      const text = QC_COVERAGE_LIMIT_TEXT[row.check]?.[limit];
+      if (!text) continue;
+      const key = JSON.stringify([row.leg, row.check, "limit", limit]);
+      const entry = grouped.get(key) || { check: row.check, leg: row.leg, result: "limit", reason_code: limit, count: 0, pages: [], text };
+      entry.count += 1;
+      if (row.subject?.page != null && !entry.pages.includes(row.subject.page)) entry.pages.push(row.subject.page);
+      grouped.set(key, entry);
+    }
     if (row.result !== "unexercised" && row.result !== "excluded") continue;
     const key = JSON.stringify([row.leg, row.check, row.result, row.reason_code]);
     const entry = grouped.get(key) || { check: row.check, leg: row.leg, result: row.result, reason_code: row.reason_code, count: 0, pages: [] };
@@ -435,7 +574,10 @@ export function buildQcHandoff({ results, coverage = [], accepts, now = new Date
     grouped.set(key, entry);
   }
   const coverageEntries = [...grouped.values(), ...coverage]
-    .map((entry) => ({ ...entry, pages: [...entry.pages].sort(compareText) }))
+    .map((entry) => {
+      const text = entry.text ?? QC_COVERAGE_TEXT[entry.check]?.[entry.reason_code];
+      return { ...entry, pages: [...entry.pages].sort(compareText), ...(text ? { text } : {}) };
+    })
     .sort((a, b) => (LEG_ORDER[a.leg] ?? 9) - (LEG_ORDER[b.leg] ?? 9) || compareText(a.check, b.check) || compareText(a.reason_code, b.reason_code) || compareText(a.result, b.result));
   const openGroups = groupOpenWarnings(open, results);
   review.sort(byCheckKeyPage);
@@ -473,7 +615,7 @@ export function qcHandoffTextLines(handoff) {
     : openLine(entry)));
   section("Review", handoff.review, (entry) => `${entry.result_ref} ${entry.summary}${entry.crop ? ` crop: ${entry.crop}` : ""}${members(entry)}`);
   section("Lapsed accepts", handoff.lapsed, (entry) => `${entry.result_ref} ${entry.summary}; accepted by ${entry.accepted_by} at ${entry.accepted_at}; lapsed: ${entry.why}`);
-  section("Coverage", handoff.coverage, (entry) => `${entry.leg} ${entry.check}: ${entry.result} (${entry.reason_code})${entry.count ? ` x${entry.count}` : ""}${entry.pages.length ? ` on ${entry.pages.join(", ")}` : ""}`);
+  section("Coverage", handoff.coverage, (entry) => `${entry.leg} ${entry.check}: ${entry.result} (${entry.reason_code})${entry.count ? ` x${entry.count}` : ""}${entry.pages.length ? ` on ${entry.pages.join(", ")}` : ""}${entry.text ? ` — ${entry.text}` : ""}`);
   section("Accepted", handoff.accepted, (entry) => `${entry.result_ref} accepted by ${entry.accepted_by} at ${entry.accepted_at}: ${entry.reason}${members(entry)}`);
   section("Inert accepts", handoff.inert_accepts, (entry) => `${entry.result_id ?? "(no result id)"}: ${entry.why}`);
   if (lines.length === 1) lines.push("  (no QC results)");

package/src/qc-check-registry.mjs

@@ -19,7 +19,12 @@
 //
 // The table holds only the shipped QC checks. A stand-in check never comes
 // from here: tests pass theirs in-process (qcStandIns).
+import { createRequire } from "node:module";
+
+const require = createRequire(import.meta.url);
+
 export const QC_CHECK_REGISTRY = Object.freeze({
+  "design.access": Object.freeze({ leg: "doctor", unit: "4.1", module: "./parity/design-access.mjs", rederive: "evaluateDesignAccess" }),
   // Tracking params reach the order
   "tracking.url": Object.freeze({ leg: "qa", unit: "1.1", module: "./qa-tracking-params.mjs", rederive: "rederiveQcResult" }),
   "tracking.order": Object.freeze({ leg: "qa", unit: "1.1", module: "./qa-tracking-params.mjs", rederive: "rederiveQcResult" }),
@@ -34,6 +39,10 @@ export const QC_CHECK_REGISTRY = Object.freeze({
   "policy.availability": Object.freeze({ leg: "qa", unit: "1.4", module: "./qa-policy-links.mjs", rederive: "rederiveQcResult" }),
   // Text readability
   "readability.contrast": Object.freeze({ leg: "polish", unit: "2.4", module: "./polish-readability.mjs", rederive: "READABILITY_QC_RULES", record: "readability" }),
+  "visual.reference": Object.freeze({ leg: "polish", unit: "3.2", module: "./polish-visual.mjs", rederive: "VISUAL_QC_RULES", record: "captures" }),
+  "visual.diff": Object.freeze({ leg: "polish", unit: "3.4", module: "./polish-visual.mjs", rederive: "VISUAL_QC_RULES", record: "captures" }),
+  // Element parity against the source HTML
+  "parity.element": Object.freeze({ leg: "polish", unit: "4.3", module: "./parity/element-parity-record.mjs", rederive: "ELEMENT_PARITY_QC_RULES", record: "element_parity" }),
   // Cart placeholders
   cart_placeholders: Object.freeze({ leg: "doctor", unit: "1.5", module: "./cart-placeholders.mjs", rederive: "evaluateCartPlaceholders" }),
   // Built-output smoke checks
@@ -58,6 +67,24 @@ function isMissingModule(error, href) {
 
 let loaded = null;
 
+async function elementParityRules(rules) {
+  const { planPolishCapture } = await import("./polish-node.mjs");
+  return { ...rules, plan: planPolishCapture,
+    read(context, activeRules) {
+      // QC reads are synchronous. Node >=20.19 supports synchronous loading
+      // of this ESM graph; defer it until a selected packet has a mapped
+      // route. Loading the registry alone must never load snapshot/probe.
+      let applicable = false;
+      if (rules.applies(context?.packet)) {
+        try { applicable = planPolishCapture({ packet: context.packet, baseUrl: "http://127.0.0.1" })?.routes?.length > 0; } catch { /* reader refuses the invalid plan */ }
+      }
+      if (!applicable) return rules.read(context, activeRules);
+      const { readParityFile, readParityFileForIdentity } = require("./parity/snapshot.mjs");
+      return rules.read(context, { ...activeRules, readFile: readParityFile, readFileForIdentity: readParityFileForIdentity });
+    },
+  };
+}
+
 // Loads every registered module of the given legs once per process and
 // returns { "<check>": {status: "loaded", rederive} | {status: "missing"} |
 // {status: "failed", error} }. `importer` resolves a specifier relative to
@@ -79,7 +106,16 @@ export async function loadQcRederivers({ legs = ["qa", "polish"], registry = QC_
     if (outcome.missing) cache[check] = Object.freeze({ status: "missing" });
     else if (outcome.error) cache[check] = Object.freeze({ status: "failed", error: String(outcome.error?.message || outcome.error) });
     else if (outcome.module?.[entry.rederive] == null) cache[check] = Object.freeze({ status: "failed", error: `${entry.module} has no export ${entry.rederive}` });
-    else cache[check] = Object.freeze({ status: "loaded", rederive: outcome.module[entry.rederive] });
+    else {
+      // Load the planner after the QC substrate has initialized: polish-node
+      // itself uses that substrate, so a static import would form a TDZ cycle.
+      // Element parity also reads its probe files through the file module,
+      // which the capture node imports only when a plan has a route.
+      const rules = outcome.module[entry.rederive];
+      const rederive = entry.record === "captures" ? { ...rules, plan: (await import("./polish-node.mjs")).planPolishCapture }
+        : entry.record === "element_parity" ? await elementParityRules(rules) : rules;
+      cache[check] = Object.freeze({ status: "loaded", rederive });
+    }
   }
   if (useCache) loaded = cache;
   return Object.freeze({ ...cache });