@nextcommerce/campaigns-os 1.60.0 → 1.61.0

package/src/parity/probe.mjs

@@ -0,0 +1,205 @@
+// Element parity probe: one read-only isolated-world read per side of every
+// visual cell, run through C's runVisualPass probe hook (RC-1 to RC-4). It
+// reads text-bearing elements (readability's rule, through the shared
+// contrast helper) and returns a ProbeOutput (stream P contract Appendix A).
+// The output is written only to the local probe files (src/parity/snapshot.mjs),
+// never to the report.
+import { contrastToolkit } from "../contrast.mjs";
+import { PARITY_MAX_ROUTES, PARITY_PROBE_CELL_MS, PARITY_PROBE_RUN_MS, PARITY_PROBE_WALK_MS } from "../polish-deadline.mjs";
+import { PARITY_PROBE_LIMITS } from "./compare.mjs";
+
+export const PARITY_PROBE_NAME = "element_parity";
+export { PARITY_PROBE_VERSION } from "./element-parity-record.mjs";
+export const PARITY_PROBE_LIMITS_ARG = Object.freeze({ ...PARITY_PROBE_LIMITS, walk_ms: PARITY_PROBE_WALK_MS });
+
+// The page-side read. It never clicks, focuses, hovers, scrolls, types or
+// writes, and it never enters a frame's document or a closed shadow root:
+// those are counted in `coverage`. `closedRoots` are the closed shadow roots
+// the hook resolved into this world (RC-3).
+//
+// - page_text is assembled before element measurement:
+//   body.innerText, then for each open shadow root in walk order a space and
+//   the textContent of each of its child elements other than style, script
+//   and template; whitespace-collapsed and cut at limits.page_text_chars.
+//   If traversal exhausts the clock first, unread text is marked truncated.
+// - The walk covers the document and every open shadow root, entered right
+//   after its host, and stops at limits.elements text-bearing elements or
+//   once limits.walk_ms has passed since the probe started. A selector path
+//   is cut at limits.selector_path_chars code points (shared with the comparator).
+// - font_faces are document.fonts in iteration order, at most limits.font_faces.
+export function parityProbe(toolkit, limits, closedRoots) {
+  const started = performance.now();
+  let timeCapped = false;
+  const outOfTime = () => {
+    if (performance.now() - started >= limits.walk_ms) timeCapped = true;
+    return timeCapped;
+  };
+  const win = window;
+  const doc = document;
+  const collapse = (value) => String(value ?? "").replace(/\s+/g, " ").trim();
+  // [the first `max` code points, whether anything was cut]
+  const cut = (value, max) => {
+    let count = 0;
+    let index = 0;
+    for (const char of value) {
+      if (count === max) return [value.slice(0, index), true];
+      count += 1;
+      index += char.length;
+    }
+    return [value, false];
+  };
+  const inOrder = [];
+  const openRoots = [];
+  const enter = (top) => {
+    for (const el of top) {
+      if (outOfTime()) return;
+      inOrder.push(el);
+      if (el.shadowRoot) {
+        openRoots.push(el.shadowRoot);
+        enter(el.shadowRoot.querySelectorAll("*"));
+      }
+    }
+  };
+  if (doc.body) enter([doc.body, ...doc.body.querySelectorAll("*")]);
+
+  let textIncomplete = outOfTime();
+  let rawText = doc.body && !textIncomplete ? doc.body.innerText : "";
+  for (const root of openRoots) {
+    for (const child of root.children) {
+      if (outOfTime()) { textIncomplete = true; break; }
+      if (!["style", "script", "template"].includes(child.localName)) rawText += ` ${child.textContent}`;
+    }
+    if (timeCapped) break;
+  }
+  const [pageText, pageTextTruncated] = cut(collapse(rawText), limits.page_text_chars);
+
+  const fontFaces = [];
+  let fontFacesCapped = false;
+  for (const face of doc.fonts) {
+    if (outOfTime()) { fontFacesCapped = true; break; }
+    if (fontFaces.length >= limits.font_faces) {
+      fontFacesCapped = true;
+      break;
+    }
+    fontFaces.push({ family: String(face.family).replace(/^(["'])(.*)\1$/s, "$2"), status: face.status });
+  }
+
+  let framesNotRead = 0;
+  for (const el of inOrder) {
+    if (outOfTime()) break;
+    if ((el.localName === "iframe" || el.localName === "frame") && toolkit.isVisible(el)) framesNotRead += 1;
+  }
+
+  const round1 = (value) => Math.round(value * 10) / 10;
+  const length = (value) => (value === "normal" ? "normal" : Number.parseFloat(value));
+  const directText = (el) => (el.localName === "input"
+    ? el.value
+    : Array.from(el.childNodes).filter((node) => node.nodeType === 3).map((node) => node.data).join(""));
+  const subtreeText = (el) => (el.localName === "input" ? el.value : typeof el.innerText === "string" ? el.innerText : el.textContent);
+  const read = (el, index) => {
+    const rect = el.getBoundingClientRect();
+    const style = win.getComputedStyle(el);
+    const measured = toolkit.measureTextElement(el, win);
+    return {
+      index,
+      selector_path: cut(toolkit.selectorPath(el), limits.selector_path_chars)[0],
+      text: cut(collapse(directText(el)), limits.text_chars)[0],
+      ftext: cut(collapse(subtreeText(el)), limits.text_chars)[0],
+      box: { x: round1(rect.left + win.scrollX), y: round1(rect.top + win.scrollY), w: round1(rect.width), h: round1(rect.height) },
+      font_family: style.getPropertyValue("font-family"),
+      font_size_px: Number.parseFloat(style.getPropertyValue("font-size")),
+      font_weight: Number(style.getPropertyValue("font-weight")),
+      font_style: style.getPropertyValue("font-style"),
+      line_height: length(style.getPropertyValue("line-height")),
+      letter_spacing: length(style.getPropertyValue("letter-spacing")),
+      text_transform: style.getPropertyValue("text-transform"),
+      fg_srgb: measured.fg_srgb,
+      bg_srgb: measured.bg_srgb,
+      color_review: measured.review_reason ?? null,
+    };
+  };
+  const elements = [];
+  let elementsCapped = false;
+  for (const el of inOrder) {
+    if (outOfTime()) break;
+    if (!toolkit.isTextBearing(el, win)) continue;
+    // Visibility/text classification can itself trigger layout. Do not start
+    // a measurement after it has consumed the remaining budget.
+    if (outOfTime()) break;
+    if (elements.length >= limits.elements) {
+      elementsCapped = true;
+      break;
+    }
+    elements.push(read(el, elements.length));
+    if (outOfTime()) break;
+  }
+
+  const closedShadowRoots = new Set(closedRoots.filter((root) => root && root.nodeType === 11)).size;
+
+  const output = {
+    viewport: { width: win.innerWidth, height: win.innerHeight },
+    dpr: win.devicePixelRatio,
+    elements,
+    page_text: pageText,
+    font_faces: fontFaces,
+    coverage: {
+      elements_capped: elementsCapped,
+      time_capped: timeCapped,
+      page_text_truncated: pageTextTruncated || textIncomplete,
+      font_faces_capped: fontFacesCapped,
+      closed_shadow_roots: closedShadowRoots,
+      frames_not_read: framesNotRead,
+    },
+  };
+  // Account for the final element, viewport reads and coverage bookkeeping.
+  output.coverage.time_capped = outOfTime();
+  return output;
+}
+
+// The function declaration the hook calls in the isolated world: the probe,
+// composed with the shared contrast helper by source text, as
+// readabilityProbeSource does.
+export function parityProbeSource() {
+  return `function (limits, ...closedRoots) { return (${parityProbe.toString()})((${contrastToolkit.toString()})(), limits, closedRoots); }`;
+}
+
+const cellKey = (side, route, viewport) => JSON.stringify([side, route, viewport]);
+
+// One run's probe entry for runVisualPass({ probes }) and what it observed.
+// The grid is the first `maxRoutes` plan routes; `select` refuses every other
+// route's cells, and every cell once the elapsed_ms of the run's parity probes
+// reaches `runMs` (those cells are remembered as run_budget_exhausted).
+// `onResult` keeps each side's result by (side, route, viewport).
+export function createParityProbeRun({ routes, runMs = PARITY_PROBE_RUN_MS, maxRoutes = PARITY_MAX_ROUTES } = {}) {
+  const captured = new Set((Array.isArray(routes) ? routes : []).slice(0, maxRoutes).map((route) => route.requested_route));
+  const results = new Map();
+  const exhausted = new Set();
+  let spent = 0;
+  const probe = Object.freeze({
+    name: PARITY_PROBE_NAME,
+    source: parityProbeSource(),
+    args: [PARITY_PROBE_LIMITS_ARG],
+    boundMs: PARITY_PROBE_CELL_MS,
+    closedRoots: true,
+    select(cell) {
+      if (!captured.has(cell?.route)) return false;
+      if (spent >= runMs) {
+        exhausted.add(cellKey(cell.side, cell.route, cell.viewport));
+        return false;
+      }
+      return true;
+    },
+    onResult(cell, result) {
+      if (!captured.has(cell?.route)) return;
+      const elapsed = result?.elapsed_ms;
+      spent += Number.isFinite(elapsed) && elapsed >= 0 ? elapsed : PARITY_PROBE_CELL_MS;
+      results.set(cellKey(cell.side, cell.route, cell.viewport), result);
+    },
+  });
+  return {
+    probe,
+    spentMs: () => spent,
+    result: (side, route, viewport) => results.get(cellKey(side, route, viewport)) ?? null,
+    exhausted: (side, route, viewport) => exhausted.has(cellKey(side, route, viewport)),
+  };
+}

package/src/parity/snapshot.mjs

@@ -0,0 +1,110 @@
+// Element parity probe files: canonical JSON under
+// .campaign-runtime/polish/parity/, named by the sha256 of their bytes (the
+// writeReadabilityCrop pattern), and re-hashed on every read. The directory
+// ignores itself: before its first file the writer creates its .gitignore
+// (`*`) with exclusive create and never overwrites one that exists, as C's
+// capture writer does for captures/ and diff/. Files carry no timestamp, so an
+// unchanged probe output keeps its content address across runs.
+import { createHash } from "node:crypto";
+import { mkdirSync, realpathSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+
+import { canonicalJson } from "../polish-capture.mjs";
+import { containedWritePath } from "../polish-visual.mjs";
+import { readRegularFileSync } from "../source-html-server.mjs";
+
+export const PARITY_DIR = ".campaign-runtime/polish/parity";
+// Above every bounded ProbeOutput (1 500 elements of capped text, 256 Ki code
+// points of page text) by a wide margin.
+export const PARITY_FILE_MAX_BYTES = 64 * 1024 * 1024;
+const FILE_PATH = /^\.campaign-runtime\/polish\/parity\/([a-f0-9]{64})\.json$/;
+const FILE_SHA = /^sha256:([a-f0-9]{64})$/;
+const sha256Hex = (bytes) => createHash("sha256").update(bytes).digest("hex");
+const isPlainObject = (value) => Boolean(value) && typeof value === "object" && !Array.isArray(value);
+
+// Check every existing ancestor against the target before treating parity as
+// a read root. The shared reader then opens, fstats and verifies the file's
+// contained realpath/inode before reading any bytes (C A-C3).
+function parityDirectory(targetRepo) {
+  const root = realpathSync(targetRepo);
+  return containedWritePath(root, PARITY_DIR);
+}
+
+function readProbeBytes(ref, targetRepo, maxBytes = PARITY_FILE_MAX_BYTES) {
+  const directory = parityDirectory(targetRepo);
+  return readRegularFileSync(resolve(directory, `${ref.sha256.slice(7)}.json`), { maxBytes, root: directory, noFollow: true });
+}
+
+// A probe file reference names its file by the sha256 of its bytes.
+export function parityRefShapeOk(ref) {
+  if (!isPlainObject(ref) || Object.keys(ref).length !== 2 || typeof ref.path !== "string" || typeof ref.sha256 !== "string") return false;
+  const path = FILE_PATH.exec(ref.path);
+  const sha = FILE_SHA.exec(ref.sha256);
+  return Boolean(path && sha && path[1] === sha[1]);
+}
+
+// Writes `value` as canonical JSON and returns {path, sha256}. A file already
+// at that address is re-read and must hold the same bytes; anything else
+// throws, so the caller records the side as failed.
+export function writeParityFile(targetRepo, value) {
+  const bytes = Buffer.from(canonicalJson(value), "utf8");
+  if (bytes.length > PARITY_FILE_MAX_BYTES) throw new Error("parity_file_too_large");
+  const hex = sha256Hex(bytes);
+  const root = realpathSync(targetRepo);
+  const path = `${PARITY_DIR}/${hex}.json`;
+  const directory = containedWritePath(root, PARITY_DIR);
+  containedWritePath(root, `${PARITY_DIR}/.gitignore`);
+  containedWritePath(root, path);
+  mkdirSync(directory, { recursive: true });
+  try { writeFileSync(resolve(directory, ".gitignore"), "*\n", { flag: "wx" }); } catch (error) { if (error.code !== "EEXIST") throw error; }
+  // Exclusive create must not turn EEXIST into approval of a directory,
+  // device, link, or an ignore file that exposes the probes. Preserve operator
+  // bytes; refuse the write when they do not keep this directory ignored.
+  try {
+    const ignore = readRegularFileSync(resolve(directory, ".gitignore"), { root: directory, noFollow: true }).toString("utf8");
+    const patterns = ignore.split(/\r?\n/).map((line) => line.trim()).filter((line) => line && !line.startsWith("#"));
+    if (!patterns.includes("*") || patterns.some((line) => line.startsWith("!"))) throw new Error("ignore_patterns_invalid");
+  } catch {
+    throw new Error("parity_ignore_invalid");
+  }
+  try { writeFileSync(resolve(root, path), bytes, { flag: "wx" }); } catch (error) { if (error.code !== "EEXIST") throw error; }
+  const written = readProbeBytes({ sha256: `sha256:${hex}` }, root, bytes.length);
+  if (sha256Hex(written) !== hex) throw new Error("parity_write_verification_failed");
+  return { path, sha256: `sha256:${hex}` };
+}
+
+// One referenced probe file, read beneath the parity directory and re-hashed:
+// {status: "absent"} when it is not on this machine (a clone: the directory is
+// ignored), {status: "invalid", detail} when the reference is malformed, the
+// file's realpath leaves the directory, it is not a regular file, its bytes do
+// not hash to the reference or do not parse, and {status: "ok", value}.
+// Never throws.
+export function readParityFile(ref, targetRepo) {
+  if (!parityRefShapeOk(ref)) return { status: "invalid", detail: "ref_shape_invalid" };
+  if (typeof targetRepo !== "string" || targetRepo === "") return { status: "invalid", detail: "target_unavailable" };
+  let bytes;
+  try {
+    bytes = readProbeBytes(ref, targetRepo);
+  } catch (error) {
+    return error?.code === "ENOENT" ? { status: "absent" } : { status: "invalid", detail: "file_unreadable" };
+  }
+  if (`sha256:${sha256Hex(bytes)}` !== ref.sha256) return { status: "invalid", detail: "hash_mismatch" };
+  try {
+    return { status: "ok", value: JSON.parse(bytes.toString("utf8")) };
+  } catch {
+    return { status: "invalid", detail: "parse_failed" };
+  }
+}
+
+// The parsed content of a referenced file whatever its hash, for naming the
+// rows of a refused cell only (an accept then lapses instead of orphaning).
+// Null when it cannot be read or parsed. Never authorizes evidence.
+export function readParityFileForIdentity(ref, targetRepo) {
+  if (!parityRefShapeOk(ref) || typeof targetRepo !== "string" || targetRepo === "") return null;
+  try {
+    const bytes = readProbeBytes(ref, targetRepo);
+    return JSON.parse(bytes.toString("utf8"));
+  } catch {
+    return null;
+  }
+}

package/src/png-header.mjs

@@ -0,0 +1,87 @@
+import { createHash } from "node:crypto";
+import { inflateSync } from "node:zlib";
+
+export const VISUAL_MAX_DECODE_PIXELS = 17_280_000;
+export const VISUAL_MAX_REFERENCE_BYTES = 67_108_864;
+const signature = Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]);
+const depths = new Map([[0, [1, 2, 4, 8, 16]], [2, [8, 16]], [3, [1, 2, 4, 8]], [4, [8, 16]], [6, [8, 16]]]);
+const channels = new Map([[0, 1], [2, 3], [3, 1], [4, 2], [6, 4]]);
+export function boundedDimensions(width, height) {
+  if (!Number.isSafeInteger(width) || !Number.isSafeInteger(height) || width <= 0 || height <= 0
+      || width * height > VISUAL_MAX_DECODE_PIXELS) throw new RangeError("image_too_large");
+}
+export const sha256Hex = (bytes) => createHash("sha256").update(bytes).digest("hex");
+
+const crcTable = Uint32Array.from({ length: 256 }, (_, byte) => {
+  let crc = byte;
+  for (let bit = 0; bit < 8; bit++) crc = (crc >>> 1) ^ ((crc & 1) ? 0xedb88320 : 0);
+  return crc >>> 0;
+});
+
+export function crc32(bytes) {
+  let crc = 0xffffffff;
+  for (let i = 0; i < bytes.length; i++) crc = (crc >>> 8) ^ crcTable[(crc ^ bytes[i]) & 0xff];
+  return (crc ^ 0xffffffff) >>> 0;
+}
+
+export function readPngStructure(bytes, { maxBytes = VISUAL_MAX_REFERENCE_BYTES } = {}) {
+  const fail = (reason) => ({ ok: false, level: "unverifiable", ihdr: null, reason });
+  if (!Number.isFinite(maxBytes) || maxBytes < 0) return fail("too_large");
+  maxBytes = Math.min(maxBytes, VISUAL_MAX_REFERENCE_BYTES);
+  if (!Buffer.isBuffer(bytes)) return fail("not_png");
+  if (bytes.length > maxBytes) return fail("too_large");
+  if (bytes.length < 8 || !Buffer.from(bytes.subarray(0, 8)).equals(signature)) return fail("not_png");
+  if (bytes.length < 33) return fail("truncated");
+  if (bytes.readUInt32BE(8) !== 13 || bytes.toString("ascii", 12, 16) !== "IHDR"
+      || crc32(bytes.subarray(12, 29)) !== bytes.readUInt32BE(29)) return fail("ihdr_invalid");
+  const ihdr = {
+    width_px: bytes.readUInt32BE(16), height_px: bytes.readUInt32BE(20),
+    bit_depth: bytes[24], color_type: bytes[25], compression: bytes[26], filter: bytes[27], interlace: bytes[28],
+  };
+  if (!ihdr.width_px || !ihdr.height_px || ihdr.width_px > 0x7fffffff || ihdr.height_px > 0x7fffffff
+      || !depths.get(ihdr.color_type)?.includes(ihdr.bit_depth) || ihdr.compression !== 0
+      || ihdr.filter !== 0 || ![0, 1].includes(ihdr.interlace)) return fail("ihdr_invalid");
+  const idat = [];
+  let offset = 8;
+  while (offset < bytes.length) {
+    if (offset + 12 > bytes.length) return fail("truncated");
+    const length = bytes.readUInt32BE(offset);
+    const end = offset + 12 + length;
+    if (end > bytes.length) return fail("truncated");
+    const type = bytes.toString("ascii", offset + 4, offset + 8);
+    if (crc32(bytes.subarray(offset + 4, end - 4)) !== bytes.readUInt32BE(end - 4)) return fail("chunk_crc_mismatch");
+    if (type === "IHDR" && offset !== 8) return fail("ihdr_invalid");
+    if (type === "IDAT") idat.push(bytes.subarray(offset + 8, end - 4));
+    if (type === "IEND") {
+      if (length || end !== bytes.length || !idat.length) return fail("truncated");
+      return { ok: true, level: "header_checked", ihdr, reason: null, idat };
+    }
+    offset = end;
+  }
+  return fail("truncated");
+}
+
+export function rawImageBytes(ihdr) {
+  if (!ihdr || typeof ihdr !== "object") throw new RangeError("image_too_large");
+  const { width_px: width, height_px: height, bit_depth, color_type, interlace } = ihdr;
+  boundedDimensions(width, height);
+  if (!["width_px", "height_px", "bit_depth", "color_type", "interlace"].every((key) => Object.hasOwn(ihdr, key))
+      || !depths.get(color_type)?.includes(bit_depth) || ![0, 1].includes(interlace)) throw new RangeError("ihdr_invalid");
+  const bits = bit_depth * channels.get(color_type);
+  const passBytes = (x, y, dx, dy) => {
+    const w = Math.max(0, Math.ceil((width - x) / dx));
+    const h = Math.max(0, Math.ceil((height - y) / dy));
+    return w && h ? h * (1 + Math.ceil(w * bits / 8)) : 0;
+  };
+  return interlace ? [[0, 0, 8, 8], [4, 0, 8, 8], [0, 4, 4, 8], [2, 0, 4, 4], [0, 2, 2, 4], [1, 0, 2, 2], [0, 1, 1, 2]]
+    .reduce((sum, pass) => sum + passBytes(...pass), 0) : passBytes(0, 0, 1, 1);
+}
+
+export function boundedInflate(bytes, ihdr) {
+  const expected = rawImageBytes(ihdr);
+  const structure = readPngStructure(bytes);
+  if (!structure.ok) throw new Error(structure.reason);
+  const raw = inflateSync(Buffer.concat(structure.idat), { maxOutputLength: expected });
+  if (raw.length !== expected) throw new Error("decode_failed");
+  return raw;
+}