@nextcommerce/campaigns-os 1.61.0 → 1.62.0

package/src/local-preview-policy.mjs

@@ -22,6 +22,9 @@ import { normalizePublicRouteSlug } from "./route-identity.mjs";
 
 export const LOCAL_PREVIEW_POLICY = "local_preview";
 export const HOSTED_TEMPLATE_PREVIEW_POLICY = "hosted_template_preview";
+// A page-only change since Polish last reviewed the campaign (#720): Polish
+// is advisory for it, on any target, so its stale evidence is carried.
+export const PAGE_ONLY_CHANGE_POLICY = "page_only_change";
 export const CARRIED_FORWARD = "carried_forward";
 
 // The checks carried forward, one by one. Each is evidence the campaign does
@@ -136,7 +139,9 @@ export function carried(gate, policy = LOCAL_PREVIEW_POLICY, packet = null) {
     ...(policy === HOSTED_TEMPLATE_PREVIEW_POLICY
       ? { required_actions: [hostedTemplateQaAction(previewUrl)] }
       : {}),
-    carried_forward: { policy, from_status: gate.status, evidence: "missing" },
+    // A page-only carry stands on a review of an older build, so its evidence
+    // is stale, except where no Polish was ever recorded.
+    carried_forward: { policy, from_status: gate.status, evidence: policy === PAGE_ONLY_CHANGE_POLICY && gate.code !== "polish.evidence_missing" ? "stale" : "missing" },
   };
 }
 
@@ -156,13 +161,38 @@ export function applyLocalPreviewToCheckpoint(gate, { packet, report, baseUrl =
 }
 
 // The polish gate folds the checkpoint in, so it is carried forward only when
-// whatever it owns from the checkpoint was carried forward too.
+// whatever it owns from the checkpoint was carried forward too. Advisory
+// Polish for a page-only change is never a ladder step.
 export function polishCarriedForwardForLadder(report, gate) {
+  if (gate?.status === CARRIED_FORWARD && gate.carried_forward?.policy === PAGE_ONLY_CHANGE_POLICY) return true;
   return gate?.status === CARRIED_FORWARD
     && !report?.theme?.waiver
     && !report?.stages?.polish?.evidence?.visual_review?.page_load;
 }
 
+// The Polish gate codes and checkpoint codes that mean "evidence for an older
+// build": the only blocks a page-only change carries. A Polish recorded as
+// blocked, self-certified or incomplete stays a block.
+const PAGE_ONLY_POLISH_CODES = Object.freeze(new Set(["polish.evidence_missing", "polish.stale", "polish.output_drift"]));
+const PAGE_ONLY_CHECKPOINT_CODES = Object.freeze(new Set(["polish.hidden_eager_media.capture_stale"]));
+
+export function isPageOnlyCarry(gate) {
+  return gate?.status === CARRIED_FORWARD && gate.carried_forward?.policy === PAGE_ONLY_CHANGE_POLICY;
+}
+
+// `debt` is assessEvidenceDebt's result for the same packet and report.
+export function applyPageOnlyChangeToCheckpoint(gate, debt) {
+  if (gate?.status !== "blocked" || debt?.polish?.advisory !== true || !PAGE_ONLY_CHECKPOINT_CODES.has(gate.code)) return gate;
+  return carried(gate, PAGE_ONLY_CHANGE_POLICY);
+}
+
+export function applyPageOnlyChangeToPolishGate(gate, { debt, checkpointGate = null } = {}) {
+  if (gate?.status !== "blocked" || debt?.polish?.advisory !== true) return gate;
+  if (gate.owned_checkpoint_only) return isPageOnlyCarry(checkpointGate) ? carried(gate, PAGE_ONLY_CHANGE_POLICY) : gate;
+  if (gate.owned_checkpoint_status === "blocked" && !isPageOnlyCarry(checkpointGate) && checkpointGate?.status !== CARRIED_FORWARD) return gate;
+  return PAGE_ONLY_POLISH_CODES.has(gate.code) ? carried(gate, PAGE_ONLY_CHANGE_POLICY) : gate;
+}
+
 export function applyLocalPreviewToPolishGate(gate, { packet, checkpointGate = null, baseUrl = null } = {}) {
   if (gate?.status !== "blocked") return gate;
   // A template-stock map has no route that capture can measure, even when
@@ -189,6 +219,9 @@ export function starterResidueIsExpected(themeGate, { packet, baseUrl = null } =
 }
 
 export function carriedForwardMessage(gate) {
+  if (gate?.carried_forward?.policy === PAGE_ONLY_CHANGE_POLICY) {
+    return `Advisory for a page-only change: ${gate.reason} The change since Polish last reviewed this campaign touches only page copy, images or styling, so Polish is reported and not required; run it when the change needs a visual review.`;
+  }
   if (gate?.carried_forward?.policy === HOSTED_TEMPLATE_PREVIEW_POLICY) {
     return `Carried forward on the hosted preview: ${gate.reason} This evidence is missing, not passed; production QA still requires it.`;
   }

package/src/page-kit-analytics-vendors.mjs

@@ -0,0 +1,132 @@
+// Doctor's advisory read of the starter-template vendor keys (#689): whether
+// the vendors the CampaignSpec declares under analytics.vendors and the
+// vendors the target's _data/campaigns.json entry switches on agree.
+//
+// A vendor adapter loads when its id key in the entry is non-empty (absent or
+// empty is off), so the entry is what ships. The spec is what the Map says
+// should ship, and spec derive mirrors the id from the entry back into it.
+// Every finding is a warning: a vendor that is off, on by accident or pointed
+// at a placeholder account loses or pollutes attribution, but never an order,
+// and the operator may have a reason. Read-only: nothing is written.
+import { ANALYTICS_VENDORS, isPlaceholderVendorId } from "../campaign-spec/dist/index.js";
+import { PAGE_KIT_CAMPAIGNS_REL_PATH } from "./page-kit-campaign-config.mjs";
+import { SPEC_DERIVE_COMMAND } from "./page-kit-sdk-version.mjs";
+
+export const PAGE_KIT_ANALYTICS_VENDORS_SCOPE = "page_kit.analytics_vendors";
+
+function isPlainObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+// The analytics kill switch the Map Builder honours: with it set, the spec
+// compiler writes no vendor key, so the spec declares no vendor.
+function analyticsDisabled(analytics) {
+  return isPlainObject(analytics) && (analytics.enabled === false || analytics.mode === "disabled");
+}
+
+// The template gate is `campaign.<key> and campaign.<key> != ""`: any value
+// but an absent, null, false or blank one switches the vendor on.
+function keySwitchesVendorOn(value) {
+  if (value === undefined || value === null || value === false) return false;
+  return typeof value !== "string" || value.trim() !== "";
+}
+
+// The vendors the spec declares, keyed by vendor: an object entry not turned
+// off with enabled:false. A declared vendor with no id is still declared (the
+// AnalyticsContractShape rule names the missing id).
+function declaredVendors(analytics) {
+  const declared = new Map();
+  if (!isPlainObject(analytics) || analyticsDisabled(analytics) || !isPlainObject(analytics.vendors)) return declared;
+  for (const { key } of ANALYTICS_VENDORS) {
+    const vendor = analytics.vendors[key];
+    if (isPlainObject(vendor) && vendor.enabled !== false) declared.set(key, vendor);
+  }
+  return declared;
+}
+
+// Compare the spec's vendors with the target entry. `targetLoad` is the
+// loadPageKitCampaignEntry result doctor already holds. Returns the vendors
+// either side switches on and one finding per disagreement; findings name keys
+// and vendors only, never a value read from campaigns.json.
+export function evaluatePageKitAnalyticsVendors({ spec, targetLoad }) {
+  // Without a readable spec there is nothing to compare the entry with; the
+  // spec checks report why it is unreadable.
+  if (!isPlainObject(spec) || targetLoad?.status !== "ok" || !isPlainObject(targetLoad.entry)) {
+    return { scope: PAGE_KIT_ANALYTICS_VENDORS_SCOPE, status: "not_applicable", vendors: [], findings: [] };
+  }
+  const entry = targetLoad.entry;
+  const slug = targetLoad.public_route_slug;
+  const source = (key) => `${PAGE_KIT_CAMPAIGNS_REL_PATH}[${slug}].${key}`;
+  const analytics = spec?.analytics;
+  const disabled = analyticsDisabled(analytics);
+  const declared = declaredVendors(analytics);
+  const vendors = [];
+  const findings = [];
+  const finding = (code, def, message, repair) => findings.push({
+    code: `${PAGE_KIT_ANALYTICS_VENDORS_SCOPE}.${code}`,
+    vendor: def.key,
+    id_key: def.idKey,
+    message,
+    repair,
+  });
+
+  for (const def of ANALYTICS_VENDORS) {
+    const field = `analytics.vendors.${def.key}`;
+    const raw = Object.hasOwn(entry, def.idKey) ? entry[def.idKey] : undefined;
+    const on = keySwitchesVendorOn(raw);
+    const specVendor = declared.get(def.key);
+    if (on || specVendor) vendors.push(def.key);
+    if (specVendor && !on) {
+      finding(
+        "key_missing",
+        def,
+        `The CampaignSpec declares ${field}, but ${source(def.idKey)} is absent or empty, so the template never loads ${def.label} and it receives no events. Set the key (the Map's spec compiler writes it), or remove the vendor from the Map if the campaign should not send to ${def.label}.`,
+        { kind: "edit", target: source(def.idKey) },
+      );
+      continue;
+    }
+    if (!specVendor && on) {
+      // spec derive can record an undeclared vendor; it cannot undo an
+      // authored "off", so that case is pointed at the Map instead.
+      const turnedOff = disabled
+        ? "turns analytics off (analytics.enabled false or mode disabled)"
+        : isPlainObject(analytics?.vendors?.[def.key]) ? `turns ${field} off (enabled: false)` : null;
+      finding(
+        "undeclared",
+        def,
+        turnedOff
+          ? `${source(def.idKey)} switches ${def.label} on, but the CampaignSpec ${turnedOff}. The template loads ${def.label} on every page regardless. Clear the key if ${def.label} should be off, or turn it back on in the Map.`
+          : `${source(def.idKey)} switches ${def.label} on, but the CampaignSpec does not declare ${field}. The template loads ${def.label} on every page. Record it in the spec with \`${SPEC_DERIVE_COMMAND}\` (or in the Map), or clear the key if ${def.label} should be off.`,
+        turnedOff ? { kind: "edit", target: source(def.idKey) } : { kind: "command", command: SPEC_DERIVE_COMMAND },
+      );
+      continue;
+    }
+    if (!specVendor) continue;
+    const value = typeof raw === "string" ? raw.trim() : null;
+    if (value !== null && isPlaceholderVendorId(value)) {
+      finding(
+        "key_placeholder",
+        def,
+        `${source(def.idKey)} holds a placeholder, not a real ${def.label} id. The template loads ${def.label} for any non-empty value, so events go to an account that does not exist. Replace it with the merchant's id.`,
+        { kind: "edit", target: source(def.idKey) },
+      );
+      continue;
+    }
+    const specId = typeof specVendor.id === "string" ? specVendor.id.trim() : "";
+    if (specId && value !== null && value !== specId) {
+      finding(
+        "id_mismatch",
+        def,
+        `${source(def.idKey)} and ${field}.id name different ${def.label} ids. The campaigns.json value is what ships; \`${SPEC_DERIVE_COMMAND}\` mirrors it into the spec, or correct the key if the spec is right.`,
+        { kind: "command", command: SPEC_DERIVE_COMMAND },
+      );
+    }
+  }
+
+  return {
+    scope: PAGE_KIT_ANALYTICS_VENDORS_SCOPE,
+    status: findings.length ? "advisory" : "ok",
+    vendors,
+    findings,
+  };
+}

package/src/polish-browser.mjs

@@ -849,7 +849,8 @@ async function runImageProbe({ session, mainFrame, documentContextChanged, probe
 // screenshot failed, crop_unavailable; so does every crop taken when the
 // bound ends before the re-read. crop_ms runs from the first crop step to the
 // end of the re-read.
-// Returns { status, capped, coverage_gaps, elements, crops, probe_ms, crop_ms }.
+// Returns { status, capped, coverage_gaps, elements, crops, layout, probe_ms,
+// crop_ms }; layout only when the probe read it.
 async function probeReadabilityDocument(options) {
   const token = { cancelled: false };
   const cropToken = { cancelled: false };
@@ -946,6 +947,7 @@ async function runReadabilityProbe({ session, mainFrame, documentContextChanged,
     coverage_gaps: read.coverage_gaps,
     elements,
     crops,
+    ...(read.layout ? { layout: read.layout } : {}),
     probe_ms: probeMs,
     crop_ms: cropMs,
   };

package/src/polish-readability.mjs

@@ -17,14 +17,19 @@
 //   the fields the helper derives from them;
 // - coverage_gaps[]: what the probe could not measure: closed shadow roots,
 //   cross-origin frames, loading, hidden or generated-text role elements, and
-//   selected, active or expanded states not present at load.
+//   selected, active or expanded states not present at load;
+// - layout (cells of a record that carries layout_conventions, measured cells
+//   only): the viewport size and the floating CTA containers the probe found,
+//   read by the layout.conventions check (LAYOUT_QC_RULES).
 import { createHash } from "node:crypto";
-import { mkdirSync, writeFileSync } from "node:fs";
-import { join, relative, sep } from "node:path";
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join, relative, sep } from "node:path";
+import { fileURLToPath } from "node:url";
 
 import { resolveBuiltSiteScope } from "./built-site-scope.mjs";
 import { CART_PLACEHOLDERS_LIMITS } from "./cart-placeholders.mjs";
 import { contrastToolkit } from "./contrast.mjs";
+import { canonicalJson } from "./polish-capture.mjs";
 import {
   READABILITY_ADDED_RUN_MS,
   READABILITY_CROP_RUN_MS,
@@ -35,6 +40,7 @@ import { MAX_POLISH_CAPTURE_ROUTES, POLISH_CAPTURE_VIEWPORTS } from "./polish-no
 import { QC_PRODUCERS, aggregateQcResults, polishRecordIntegrity } from "./qc-results.mjs";
 
 export const READABILITY_CHECK = "readability.contrast";
+export const LAYOUT_CHECK = "layout.conventions";
 export const READABILITY_SCHEMA = "campaigns-os-polish-readability/v0";
 export const READABILITY_PRODUCER = QC_PRODUCERS.polish;
 export const READABILITY_ROUTE_SOURCE = "built_site";
@@ -402,6 +408,162 @@ export const READABILITY_QC_RULES = Object.freeze({
   },
 });
 
+// ---------------------------------------------------------------------------
+// Layout conventions
+
+// The layout_conventions block of the shared commerce brand contract, without
+// its prose (`rule` fields): the selectors the probe reads with and the
+// thresholds the layout.conventions check judges with. A record stores the
+// block it was measured with; a reader re-derives only with the same block.
+const SHARED_COMMERCE_CONTRACT = join(dirname(fileURLToPath(import.meta.url)), "..", "contracts", "template-brand-contract.shared-commerce.v0.json");
+const withoutProse = (value) => (isPlainObject(value)
+  ? Object.freeze(Object.fromEntries(Object.entries(value).filter(([field]) => field !== "rule").map(([field, entry]) => [field, withoutProse(entry)])))
+  : Array.isArray(value) ? Object.freeze(value.map(withoutProse)) : value);
+export const LAYOUT_CONVENTIONS = withoutProse(JSON.parse(readFileSync(SHARED_COMMERCE_CONTRACT, "utf8")).layout_conventions);
+
+// What the probe needs from the block: the floating CTA selector contract.
+const layoutProbeArgs = () => {
+  const { positions, control_selector, exclude_selector, form_field_selector } = LAYOUT_CONVENTIONS.floating_cta;
+  return { positions, control_selector, exclude_selector, form_field_selector };
+};
+
+const isRect = (value) => isPlainObject(value) && ["x", "y", "width", "height"].every((field) => Number.isFinite(value[field]));
+const isPathList = (value) => Array.isArray(value) && value.every(isNonEmptyString);
+
+// The layout a measured cell records: the probe's viewport and one entry per
+// floating CTA container, with its rect, its controls (each with its rect)
+// and the selector paths of the visible text outside them.
+export function layoutShapeOk(layout) {
+  return isPlainObject(layout)
+    && isPlainObject(layout.viewport) && Number.isFinite(layout.viewport.width) && Number.isFinite(layout.viewport.height)
+    && Array.isArray(layout.floating_ctas)
+    && layout.floating_ctas.every((entry) => isPlainObject(entry)
+      && isNonEmptyString(entry.selector_path)
+      && LAYOUT_CONVENTIONS.floating_cta.positions.includes(entry.position)
+      && isRect(entry.rect)
+      && Array.isArray(entry.controls) && entry.controls.every((control) => isPlainObject(control) && isNonEmptyString(control.selector_path) && isRect(control.rect))
+      && isPathList(entry.other_text)
+      && Number.isInteger(entry.other_text_count) && entry.other_text_count >= entry.other_text.length);
+}
+
+const FLOATING_FIELDS = Object.freeze(["selector_path", "position", "rect", "controls", "other_text", "other_text_count"]);
+
+// The layout a cell keeps from the probe's observation, or null when the
+// observation carries none.
+function cellLayout(observation) {
+  const layout = observation?.layout;
+  if (!isPlainObject(layout)) return null;
+  return {
+    viewport: { width: layout.viewport?.width, height: layout.viewport?.height },
+    floating_ctas: (Array.isArray(layout.floating_ctas) ? layout.floating_ctas : []).map((entry) => ({
+      ...pick(entry, FLOATING_FIELDS),
+      controls: (Array.isArray(entry?.controls) ? entry.controls : []).map((control) => pick(control, ["selector_path", "rect"])),
+    })),
+  };
+}
+
+// The row keys the layout check names for a cell at its viewport, and
+// `cell`; none at a viewport no convention applies to. Read without checking
+// the cell, so an accept of a row of a cell that fails its checks lapses
+// rather than orphans. Never throws.
+export function layoutRowKeys(cell) {
+  const viewport = isPlainObject(cell) ? cell.viewport : null;
+  const keys = Object.values(LAYOUT_CONVENTIONS).filter((convention) => convention.viewports.includes(viewport)).map((convention) => convention.key);
+  return keys.length ? [...keys, "cell"].sort(byCodeUnit) : [];
+}
+
+// The layout.conventions results of one cell of the readability record,
+// judged with `conventions`, one per convention that applies at the cell's
+// viewport:
+// - `floating_cta`: one member per floating CTA container no taller than
+//   max_viewport_height_share of the viewport, a warning when it holds other
+//   than one control or holds visible text outside its control; a cell with
+//   none reads pass;
+// - `cta_label_size`: one member per rendered, enabled text element of the
+//   CTA roles, a warning under min_font_size_px; a cell with none reads pass.
+//   The elements are the readability record's, so a capped cell adds the
+//   page_coverage member.
+// A cell that measured nothing reads `cell` unexercised with its status.
+export function evaluateLayoutConventions(cell, conventions = LAYOUT_CONVENTIONS) {
+  if (!isPlainObject(cell)) invalid("is not an object");
+  if (canonicalJson(conventions) !== canonicalJson(LAYOUT_CONVENTIONS)) invalid("layout conventions are not the shared contract's");
+  if (!readabilityCellShapeOk(cell)) invalid("is not in the record vocabulary");
+  const { floating_cta: floating, cta_label: label } = LAYOUT_CONVENTIONS;
+  const applies = (convention) => convention.viewports.includes(cell.viewport);
+  if (!applies(floating) && !applies(label)) return [];
+  const results = [];
+  const push = (key, members, { state, observation = {}, capReason = null }) => {
+    const aggregated = aggregateQcResults(members, { capReason });
+    const result = aggregated.result;
+    results.push({
+      check: LAYOUT_CHECK,
+      subject: { check: LAYOUT_CHECK, page: cell.route, viewport: cell.viewport, key },
+      result,
+      reason_code: result === "pass" ? null : aggregated.reason_code,
+      members: aggregated.members,
+      accept_eligible: aggregated.accept_eligible,
+      coverage: result === "unexercised" ? { observed: 0, expected: 1, limits: [aggregated.reason_code] } : { observed: 1, expected: 1, limits: [] },
+      state,
+      observation,
+    });
+  };
+
+  if (cell.cell_status !== "measured") {
+    push("cell", [{ key: "cell_status", result: "unexercised", reason_code: cell.cell_status }], { state: { reason_code: cell.cell_status } });
+    return results;
+  }
+  if (!layoutShapeOk(cell.layout)) invalid("layout is not in the record vocabulary");
+
+  if (applies(floating)) {
+    const tallest = floating.max_viewport_height_share * cell.layout.viewport.height;
+    const containers = cell.layout.floating_ctas.filter((entry) => entry.rect.height <= tallest);
+    const holdsControlOnly = (entry) => entry.controls.length === 1 && entry.other_text_count === 0;
+    const members = containers.length
+      ? containers.map((entry) => (holdsControlOnly(entry)
+        ? { key: entry.selector_path, result: "pass", reason_code: null }
+        : { key: entry.selector_path, result: "warning", reason_code: floating.reason_code }))
+      : [{ key: "no_floating_cta", result: "pass", reason_code: null }];
+    push(floating.key, members, {
+      state: { containers: sortedUnique(containers.map(({ selector_path, controls, other_text, other_text_count }) => ({ selector_path, controls: controls.map((control) => control.selector_path), other_text, other_text_count }))) },
+      observation: {
+        max_height_px: tallest,
+        containers: containers.map(({ selector_path, position, rect, controls, other_text, other_text_count }) => ({ selector_path, position, rect, controls, other_text, other_text_count })),
+      },
+    });
+  }
+
+  if (applies(label)) {
+    const labels = cell.elements.filter((element) => label.roles.includes(element.role) && element.rendered && !element.disabled);
+    const members = labels.length
+      ? labels.map((element) => (element.font_size_px >= label.min_font_size_px
+        ? { key: element.selector_path, result: "pass", reason_code: null }
+        : { key: element.selector_path, result: "warning", reason_code: label.reason_code }))
+      : [{ key: "no_cta_label", result: "pass", reason_code: null }];
+    push(label.key, members, {
+      capReason: cell.capped ? "element_cap_reached" : null,
+      state: { min_font_size_px: label.min_font_size_px, members: sortedUnique(labels.map(({ role, selector_path, font_size_px }) => ({ role, selector_path, font_size_px }))) },
+      observation: {
+        min_font_size_px: label.min_font_size_px,
+        smallest_px: labels.length ? Math.min(...labels.map((element) => element.font_size_px)) : null,
+        members: labels.map(({ role, selector_path, font_size_px }) => ({ role, selector_path, font_size_px })),
+      },
+    });
+  }
+  return results;
+}
+
+// The layout.conventions rules, read from the readability record
+// (src/qc-check-registry.mjs): `thresholds` is the conventions block a record
+// must store to be judged. The reader re-derives the check's rows only
+// for a record that stores `layout_conventions`; an earlier record holds no
+// layout and the check reads not_captured_by_this_version.
+export const LAYOUT_QC_RULES = Object.freeze({
+  thresholds: LAYOUT_CONVENTIONS,
+  vocabulary: Object.freeze({ key: Object.freeze([...Object.values(LAYOUT_CONVENTIONS).map((convention) => convention.key), "cell"]) }),
+  evaluate: evaluateLayoutConventions,
+  rowKeys: layoutRowKeys,
+});
+
 // ---------------------------------------------------------------------------
 // Probe
 
@@ -419,7 +581,8 @@ export const READABILITY_QC_RULES = Object.freeze({
 // (or, for one inside a frame, that frame's element); `generatedText` is
 // generatedTextRenders. Every element carries its rectangle in the main
 // frame's viewport (`rect`, clipped to its frames) for crops, which the
-// record does not keep.
+// record does not keep. With `limits.layout` it also returns `layout`: the
+// viewport and the floating CTA containers, whose rects the record keeps.
 export function readabilityProbe(toolkit, limits, closedRoots, generatedText) {
   const win = window;
   const doc = document;
@@ -684,14 +847,56 @@ export function readabilityProbe(toolkit, limits, closedRoots, generatedText) {
     if (isVisible(frame) && !readable) gap("cross_origin_text", null, frame);
   }
 
-  return { status: "measured", capped, coverage_gaps: gaps, elements, viewport };
+  // Floating CTA containers (limits.layout, the layout conventions' selector
+  // contract), in the main frame's trees: for each visible control, the
+  // nearest box at or around it whose computed position is one of
+  // `positions`, unless that box is hidden, matches or sits inside
+  // `exclude_selector`, or holds a visible form field. Each container keeps
+  // its rect, its outermost visible controls with their rects, and the
+  // selector paths of the visible text outside them (rendered or generated),
+  // the first ten listed and all counted.
+  let layout = null;
+  if (limits.layout) {
+    const { positions, control_selector: controlSelector, exclude_selector: excludeSelector, form_field_selector: fieldSelector } = limits.layout;
+    const main = { offset: { x: 0, y: 0 }, clip: null };
+    const positioned = (el) => positions.includes(win.getComputedStyle(el).getPropertyValue("position"));
+    const boxes = [];
+    for (const [el, scope] of inOrder) {
+      if (scope.win !== win || !el.matches(controlSelector) || !isVisible(el)) continue;
+      let box = el;
+      while (box && box.nodeType === 1 && !positioned(box)) box = flatParent(box);
+      if (box && box.nodeType === 1 && !boxes.includes(box)) boxes.push(box);
+    }
+    const floating_ctas = [];
+    for (const box of boxes) {
+      if (!isVisible(box) || flatClosest(box, excludeSelector)) continue;
+      const inside = flatSubtree(box);
+      if (inside.some((node) => node.matches(fieldSelector) && isVisible(node))) continue;
+      const visibleControls = inside.filter((node) => node.matches(controlSelector) && isVisible(node));
+      const controls = visibleControls.filter((node) => !visibleControls.some((other) => other !== node && flatContains(other, node)));
+      const other = inside.filter((node) => !controls.some((control) => flatContains(control, node))
+        && (toolkit.isTextBearing(node, windowOf(node)) || generatedText(node, windowOf(node))));
+      floating_ctas.push({
+        selector_path: toolkit.selectorPath(box),
+        position: win.getComputedStyle(box).getPropertyValue("position"),
+        rect: rectOf(box, main),
+        controls: controls.map((control) => ({ selector_path: toolkit.selectorPath(control), rect: rectOf(control, main) })),
+        other_text: other.slice(0, 10).map((node) => toolkit.selectorPath(node)),
+        other_text_count: other.length,
+      });
+    }
+    layout = { viewport, floating_ctas };
+  }
+
+  return { status: "measured", capped, coverage_gaps: gaps, elements, viewport, ...(layout ? { layout } : {}) };
 }
 
 // The function declaration the adapter calls in the isolated world: the
 // probe, composed with the shared contrast helper and generatedTextRenders
-// by source text.
+// by source text, its limits carrying the layout conventions' selector
+// contract.
 export function readabilityProbeSource() {
-  return `function (limits, ...closedRoots) { return (${readabilityProbe.toString()})((${contrastToolkit.toString()})(), limits, closedRoots, ${generatedTextRenders.toString()}); }`;
+  return `function (limits, ...closedRoots) { return (${readabilityProbe.toString()})((${contrastToolkit.toString()})(), Object.assign({ layout: ${JSON.stringify(layoutProbeArgs())} }, limits), closedRoots, ${generatedTextRenders.toString()}); }`;
 }
 
 // Whether an element's ::before or ::after renders text: its computed
@@ -760,6 +965,7 @@ const pick = (value, fields) => Object.fromEntries(fields.map((field) => [field,
 export function readabilityObservationOk(observation) {
   return isPlainObject(observation)
     && inVocabulary("cell_status", observation.status)
+    && (observation.layout === undefined || isPlainObject(observation.layout))
     && (observation.status !== "measured"
       || (Array.isArray(observation.elements) && observation.elements.every(isPlainObject)
         && Array.isArray(observation.coverage_gaps) && observation.coverage_gaps.every(isPlainObject)
@@ -768,7 +974,9 @@ export function readabilityObservationOk(observation) {
 
 // One cell of the record. `status` is the cell status; a measured cell's
 // `observation` is the adapter's probe read ({capped, coverage_gaps,
-// elements, crops}). Only the record's fields are kept. Each crop the adapter
+// elements, crops, layout}). Only the record's fields are kept; a layout
+// outside the record vocabulary is dropped, which the layout check reads as
+// not reproducible. Each crop the adapter
 // took (crops[] of {element, data}, base64 PNG) is written by `writeCrop`
 // and referenced by path and sha256; one that cannot be written reads
 // crop_unavailable. A measured cell outside the record vocabulary reads
@@ -789,6 +997,7 @@ export function buildReadabilityCell({ route, viewport, pageLoadIntegrity = null
       element.crop_reason = "crop_unavailable";
     }
   }
+  const layout = cellLayout(observation);
   const cell = {
     route,
     viewport,
@@ -797,13 +1006,15 @@ export function buildReadabilityCell({ route, viewport, pageLoadIntegrity = null
     capped: observation.capped,
     coverage_gaps: observation.coverage_gaps.map((entry) => pick(entry, GAP_FIELDS)),
     elements,
+    ...(layout && layoutShapeOk(layout) ? { layout } : {}),
   };
   return readabilityCellShapeOk(cell) ? cell : unmeasured("document_changed");
 }
 
 // The record for one Polish run: its cells (one per captured route ×
 // viewport), bound to the current build and source package; the built routes
-// over the route cap; whether the enumeration ceiling was reached.
+// over the route cap; whether the enumeration ceiling was reached; and, when
+// a cell recorded layout, the layout conventions it was measured with.
 export function buildReadabilityRecord({ buildFingerprint, sourceFingerprint = null, slug, routes, uncapturedRoutes = [], routeEnumerationCapped = false, cells, measuredAt = new Date().toISOString() }) {
   const record = {
     schema_version: READABILITY_SCHEMA,
@@ -819,6 +1030,7 @@ export function buildReadabilityRecord({ buildFingerprint, sourceFingerprint = n
     },
     thresholds: { ...READABILITY_THRESHOLDS },
     limits: { ...readabilityLimits() },
+    ...(cells.some((cell) => isPlainObject(cell?.layout)) ? { layout_conventions: structuredClone(LAYOUT_CONVENTIONS) } : {}),
     cells,
     uncaptured_routes: [...uncapturedRoutes],
     route_enumeration_capped: routeEnumerationCapped === true,

package/src/polish-visual.mjs

@@ -477,10 +477,17 @@ export function evaluateVisualReference(reference) {
     : reference.provenance?.class === "declared_source" ? member("provenance", null, "pass") : member("provenance", "provenance_unknown", "review"));
   if (reference.reference_cap_reached) members.push(member("reference_cap", "reference_cap_reached"));
   // A file refused for where it is, not what it is, names that location.
-  if (level !== "decoded" && reference.verification?.reason === "path_outside_source_root") members.push(member("location", "path_outside_source_root"));
+  members.push(...referenceLocationMembers(reference));
   return aggregateQcResults(members);
 }
 
+// The location member of a reference refused for where it is. It does not
+// depend on the build, so a stale-bound row keeps it (#707).
+function referenceLocationMembers(reference) {
+  return reference?.verification?.level !== "decoded" && reference?.verification?.reason === "path_outside_source_root"
+    ? [member("location", "path_outside_source_root")] : [];
+}
+
 // The only diff decision table. Scores are intentionally absent from its predicates.
 export function evaluateVisualDiff(comparison, { record, reference, build, basis, readerFailure = null,
   staleBinding = false, pageMissing = false, fileAbsent = false, budgetExhausted = false } = {}) {
@@ -590,7 +597,7 @@ function evaluate(record, context = {}) {
       ? { ...original, reference_cap_reached: true } : original;
     row("visual.reference", ref, failure
     ? { result: "unexercised", reason_code: "evidence_not_reproducible", members: [member("evidence", failure)] }
-    : context.staleBinding ? { result: "unexercised", reason_code: "stale_binding" } : evaluateVisualReference(ref));
+    : context.staleBinding ? { result: "unexercised", reason_code: "stale_binding", members: referenceLocationMembers(ref) } : evaluateVisualReference(ref));
   }
   for (const comparison of record.comparisons) {
     if (comparison.basis === "reference" && cappedReferences.has(referenceKey(comparison))) continue;

package/src/progress-node.mjs

@@ -97,7 +97,7 @@ export function projectProgressObservation({workspace,context,report,doctor,cont
 }
 function lock(dir,fn,{budgetMs=1500}={}) {
   const lockPath=join(dir,'.allocation-lock');
-  return withDirectoryLock(lockPath,fn,{budgetMs,unavailable:(error)=>Object.assign(new Error('progress.lock_unavailable'),{lockPath,code:error?.code,obstruction:error?.obstruction})});
+  return withDirectoryLock(lockPath,fn,{budgetMs,unavailable:(error)=>Object.assign(new Error('progress.lock_unavailable'),{lockPath,code:error?.code,obstruction:error?.obstruction,holderPid:error?.holderPid})});
 }
 export async function persistProgressObservation(observation,{dir,now=()=>new Date(),historyLimit=32}={}) {
   mkdirSync(dir,{recursive:true,mode:0o700});
@@ -165,7 +165,8 @@ export async function observeProgress(args,continuation,{qaResult=null,packageVe
     if(remit.state==='failed')warn('[campaigns-os] Progress delivery pending; the local observation is retained. Lifecycle result is unchanged.');
     return {...remit,snapshot_id:snapshot.snapshot_id,reused};
   } catch(error) {
-    if(error?.message==='progress.lock_unavailable'&&error.obstruction)warn(`[campaigns-os] Progress allocation lock path ${error.lockPath} is occupied by ${error.obstruction}; it is never removed automatically. Move it out of the way. Lifecycle result is unchanged.`);
+    if(error?.message==='progress.lock_unavailable'&&error.code==='ELOCKFORMAT')warn(`[campaigns-os] Progress allocation lock at ${error.lockPath} is held by process ${error.holderPid} of a different campaigns-os release; capture stops instead of waiting. Run one campaigns-os release against this target at a time. Lifecycle result is unchanged.`);
+    else if(error?.message==='progress.lock_unavailable'&&error.obstruction)warn(`[campaigns-os] Progress allocation lock path ${error.lockPath} is occupied by ${error.obstruction}; it is never removed automatically. Move it out of the way. Lifecycle result is unchanged.`);
     else if(error?.message==='progress.lock_unavailable')warn(`[campaigns-os] Progress allocation lock occupied${error.lockPath?` at ${error.lockPath}`:''}; wait for the current writer. If it stays occupied (an abandoned, ownerless or interrupted lock), stop all campaigns-os writers for this target, then remove that lock directory (docs/progress-snapshots.md). Lifecycle result is unchanged.`);
     else warn('[campaigns-os] Progress observation unavailable; lifecycle result is unchanged.');
     return {state:'failed',reason:'capture_unavailable'};

package/src/qa-analytics-parity.mjs

@@ -27,6 +27,7 @@
 
 import { SEVERITY, STATUS } from "./qa-verdict.mjs";
 import { redactUrlQuery } from "./qa-url-privacy.mjs";
+import { readVendorBeacon, VENDOR_KEYS, vendorBeaconFor } from "./qa-vendor-endpoints.mjs";
 
 // Data layers the SDK and legacy funnels push through. The SDK's GTMAdapter
 // mirrors every `dl_*` event to window.dataLayer AND window.ElevarDataLayer;
@@ -280,6 +281,12 @@ export async function attachAnalyticsCapture(page, options = {}) {
     const url = typeof request.url === "function" ? request.url() : request.url;
     const fire = classifyTagFire(url, extraHosts);
     if (!fire) return;
+    // A listed vendor beacon can carry its id in the body (Snap, TikTok).
+    if (!fire.id) {
+      let body = null;
+      try { body = typeof request.postData === "function" ? request.postData() : null; } catch { /* no body */ }
+      fire.id = readVendorBeacon(url, body)?.ids[0] || null;
+    }
     let documentUrl = safePageUrl();
     try {
       let frame = typeof request.frame === "function" ? request.frame() : null;
@@ -420,6 +427,14 @@ export function classifyTagFire(urlString, extraHostSubstrings = []) {
   const fire = (kind, id) => ({ kind, id: id ? String(id) : null, host, params });
   const subs = [...DEFAULT_EXTRA_ANALYTICS_HOST_SUBSTRINGS, ...extraHostSubstrings];
 
+  // A listed vendor beacon (qa-vendor-endpoints.mjs) is that vendor's fire,
+  // answered locally or not, with the id from its query or path when it has one.
+  const beacon = vendorBeaconFor(url.href);
+  if (beacon) {
+    const pathId = beacon.idPath ? path.match(beacon.idPath)?.[1] : null;
+    return fire(beacon.vendor, pathId || (beacon.id && !beacon.id.includes(".") ? params[beacon.id] : null) || null);
+  }
+
   if (hostMatches(host, "googletagmanager.com")) {
     const id = params.id || null;
     if (id && /^GTM-/i.test(id)) return fire("gtm", id);
@@ -539,6 +554,7 @@ export function normalizeCapture({ events = [], tagFires = [] } = {}) {
   }
 
   const inventory = { gtm: [], ga4: [], google_ads: [], meta: [], tiktok: [], everflow: [], other: [] };
+  for (const vendor of VENDOR_KEYS) inventory[vendor] ||= [];
   // Pixel ids seen on a facebook.com request, apart from in-page fbq calls.
   const metaRequestIds = [];
   let metaPurchaseEventId = null;
@@ -787,7 +803,7 @@ export function diffAnalyticsParity(baseline, candidate, options = {}) {
 
   // 6. Carried-over tag regression — any baseline container/pixel absent on the
   //    candidate is a WARN (likely attribution regression; human confirms drop).
-  const kinds = ["gtm", "ga4", "google_ads", "meta", "tiktok", "everflow", "other"];
+  const kinds = [...new Set(["gtm", "ga4", "google_ads", "meta", "tiktok", "everflow", "other", ...VENDOR_KEYS])];
   for (const kind of kinds) {
     const baselineIds = (b.inventory?.[kind]) || [];
     const candidateIds = new Set((c.inventory?.[kind]) || []);