@olomonhelpdesk2/helpdesk 0.1.0

package/helpdesk-capture.mjs

@@ -0,0 +1,3275 @@
+#!/usr/bin/env node
+// core/capture/contract.ts
+var CAPTURE_CONTRACT = {
+  /** Same for every shot, so type is the same size across the whole set. */
+  viewport: { width: 1600, height: 1e3 },
+  /** Stills render at 2x → 3200x2000. */
+  stillScale: 2,
+  /** Clips at 1x; video is resampled downstream anyway. */
+  clipScale: 1,
+  /** Below this a frame is a failed shot rather than a small one. */
+  minStillWidth: 2300,
+  /**
+   * Clip length.
+   *
+   * A CAP rather than a target, and inherited from a marketing site's autoplay
+   * loop — which is not this product's constraint. A help-center clip showing a
+   * multi-step task may well want twenty seconds, so the window is the contract
+   * and the number is configurable.
+   */
+  clipSeconds: { min: 6, target: 9, max: 10 },
+  maxClipBytes: 2 * 1024 * 1024,
+  /** Everything renders as though it were this instant. */
+  pinnedClock: "2026-01-15T09:00:00.000Z",
+  /**
+   * Injected before every shot. Necessary, not sufficient — see above.
+   */
+  motionOff: "*,*::before,*::after{animation:none!important;transition:none!important;caret-color:transparent!important}"
+};
+var VISUAL_STABILITY = {
+  /** Gap between comparison frames. Short enough to be cheap, long enough to differ. */
+  intervalMs: 120,
+  /** Consecutive identical frames required. */
+  identicalFrames: 2,
+  /** Give up rather than hang; a page that never settles is a finding. */
+  timeoutMs: 1e4
+};
+function pngSize(bytes) {
+  const SIGNATURE = [137, 80, 78, 71, 13, 10, 26, 10];
+  if (bytes.length < 24) return void 0;
+  if (SIGNATURE.some((byte, index) => bytes[index] !== byte)) return void 0;
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  return { width: view.getUint32(16), height: view.getUint32(20) };
+}
+var RECORDING_MISS_STATUS = 599;
+function isPublishable(result) {
+  return result === "ok" || result === "empty-state";
+}
+function actionFor(outcome) {
+  switch (outcome.result) {
+    case "ok":
+    case "empty-state":
+    case "canonical-redirect":
+      return void 0;
+    case "not-found": {
+      const noun = subjectOf(outcome.missingEndpoint ?? outcome.route);
+      return `Create one ${noun} in your test environment, then run this again.`;
+    }
+    case "thin":
+      return `Nothing rendered on ${outcome.route}. If it needs data, add some; if it is not a real screen, we will leave it out.`;
+    case "bounced":
+      return `${outcome.route} redirected${outcome.landed ? ` to ${outcome.landed}` : " somewhere else"}. If it needs a permission your test account lacks, use one that has it.`;
+    case "crashed":
+      return `${outcome.route} hit an error${outcome.error ? `: ${outcome.error}` : ""}. This is a bug in the app rather than in the setup.`;
+    case "unrecorded":
+      return `${outcome.route} asked for ${outcome.missingEndpoint ?? "data"}, which is not in the recording. Visit this screen while recording, then run this again.`;
+  }
+}
+function subjectOf(path2) {
+  const segments = path2.split("/").filter(Boolean).filter((segment) => !/^(api|v\d+)$/.test(segment));
+  while (segments.length > 1 && looksLikeAnId(segments[segments.length - 1])) segments.pop();
+  const last = segments[segments.length - 1] ?? "record";
+  return last.replace(/[-_]/g, " ").replace(/s$/, "");
+}
+function looksLikeAnId(segment) {
+  return /^\d+$/.test(segment) || /^[0-9a-f]{8}-[0-9a-f]{4}-/i.test(segment) || // `inv_123`, `cus_9f2a`: a prefix, a separator, and something with a digit
+  // in it. Deliberately narrow — `sign-up` must survive this.
+  /^[a-z]{2,}[_-][a-z0-9]*\d[a-z0-9]*$/i.test(segment) || /^[0-9a-z]{16,}$/i.test(segment);
+}
+function captureReport(outcomes) {
+  const ready = outcomes.filter((outcome) => isPublishable(outcome.result));
+  const actionable = outcomes.map((outcome) => ({ outcome, action: actionFor(outcome) })).filter((entry) => Boolean(entry.action));
+  const lines = [
+    `${ready.length} screens ready \xB7 ${actionable.length} need attention`,
+    "",
+    ...actionable.map(({ outcome, action }) => `  ${outcome.route.padEnd(30)} ${action}`)
+  ];
+  return { ready: ready.length, needData: actionable.length, lines };
+}
+
+// core/cli-package.ts
+var HELPDESK_CLI_PACKAGE = "@olomonhelpdesk2/helpdesk";
+function helpdeskCommand(command, args = []) {
+  const parts = ["npx", "--yes", "-p", HELPDESK_CLI_PACKAGE, command, ...args];
+  return parts.join(" ");
+}
+
+// core/capture/classify.ts
+var THIN_TEXT_CHARS = 25;
+var BOUNDARY_PHRASES = [
+  /\bsomething went wrong\b/i,
+  /\bapplication error\b/i,
+  /\bunhandled (runtime )?error\b/i,
+  /\bunexpected error\b/i,
+  /\binternal server error\b/i,
+  /\bthis page (could not|couldn'?t) be loaded\b/i,
+  /\bwe('| a)re sorry[ —,-]+something\b/i,
+  /\berror (id|digest)\b/i
+];
+var NOT_FOUND_PHRASES = [
+  /\b(page|it) (was )?not found\b/i,
+  /\b404\b/,
+  /\bwe (could not|couldn'?t) find\b/i,
+  /\bno longer exists\b/i,
+  /\bdoes not exist\b/i
+];
+var EMPTY_STATE_PHRASES = [
+  /\bno [a-z ]{0,20}(yet|here)\b/i,
+  /\bnothing (to show|here|yet)\b/i,
+  /\byou (have not|haven'?t|do not have|don'?t have)\b/i,
+  /\b(create|add|import) your first\b/i,
+  /\bget started by\b/i,
+  /\bno results\b/i,
+  /\bthis (list|table) is empty\b/i
+];
+function classifyRoute(observation) {
+  const text2 = observation.text.trim();
+  const unrecorded = observation.failedRequests?.find((request) => request.status === RECORDING_MISS_STATUS);
+  if (unrecorded) {
+    return { route: observation.route, result: "unrecorded", missingEndpoint: unrecorded.url };
+  }
+  const crash = crashedBecause(observation, text2);
+  if (crash) return { route: observation.route, result: "crashed", error: crash };
+  const missing = missingBecause(observation, text2);
+  if (missing) return { route: observation.route, result: "not-found", missingEndpoint: missing };
+  if (observation.landedOn && !samePlace(observation.route, observation.landedOn)) {
+    const canonical = canonicalisation(observation.route, observation.landedOn);
+    return {
+      route: observation.route,
+      result: canonical ? "canonical-redirect" : "bounced",
+      // Carried only when it is a finding. A parent handing off to its default
+      // child needs no row, so it needs no detail either.
+      ...canonical ? {} : { landed: observation.landedOn }
+    };
+  }
+  if (EMPTY_STATE_PHRASES.some((phrase) => phrase.test(text2))) {
+    return { route: observation.route, result: "empty-state" };
+  }
+  if (text2.length < THIN_TEXT_CHARS) return { route: observation.route, result: "thin" };
+  return { route: observation.route, result: "ok" };
+}
+function crashedBecause(observation, text2) {
+  const uncaught = observation.errors?.[0];
+  if (uncaught) return uncaught;
+  if (observation.status !== void 0 && observation.status >= 500) {
+    return `the server answered ${observation.status}`;
+  }
+  if (BOUNDARY_PHRASES.some((phrase) => phrase.test(text2))) {
+    return observation.consoleErrors?.[0] ?? firstSentence(text2);
+  }
+  return void 0;
+}
+function missingBecause(observation, text2) {
+  const notFoundRequest = observation.failedRequests?.find((request) => request.status === 404);
+  if (notFoundRequest) return notFoundRequest.url;
+  if (observation.status === 404) return observation.route;
+  if (NOT_FOUND_PHRASES.some((phrase) => phrase.test(text2))) return observation.route;
+  return void 0;
+}
+function canonicalisation(asked, landed) {
+  return normalise(asked) === normalise(landed);
+}
+function samePlace(asked, landed) {
+  return stripQuery(asked) === stripQuery(landed);
+}
+function stripQuery(path2) {
+  return path2.split(/[?#]/)[0] ?? path2;
+}
+function normalise(path2) {
+  return stripQuery(path2).toLowerCase().replace(/\/index(\.html?)?$/, "/").replace(/\/+$/, "").replace(/^$/, "/");
+}
+function firstSentence(text2) {
+  const sentence = text2.trim().split(/(?<=[.!?])\s|\n/)[0] ?? text2;
+  return sentence.length > 160 ? `${sentence.slice(0, 157)}\u2026` : sentence;
+}
+function surveyLine(outcomes) {
+  const count = (result) => outcomes.filter((outcome) => outcome.result === result).length;
+  const crashed = count("crashed");
+  const parts = [
+    `${count("ok") + count("empty-state")} screens rendered`,
+    crashed ? `${crashed} crashed` : "",
+    count("not-found") ? `${count("not-found")} need data` : "",
+    count("bounced") ? `${count("bounced")} redirected away` : "",
+    count("thin") ? `${count("thin")} rendered nothing` : "",
+    // Counted apart from "need data" on purpose: the fix is to record the
+    // screen, not to go and create a record in the test environment.
+    count("unrecorded") ? `${count("unrecorded")} not in the recording` : ""
+  ].filter(Boolean);
+  return parts.join(" \xB7 ");
+}
+
+// core/capture/preflight.ts
+var NOT_LIVE = /(^|[.\-/])(localhost|127\.0\.0\.1|0\.0\.0\.0|staging|stage|sandbox|demo|preview|test|qa|dev|develop|development|uat)([.\-:/]|$)/i;
+var NOT_LIVE_SUFFIX = /\.(local|test|localhost|internal|vercel\.app|netlify\.app|ngrok\.io|ngrok-free\.app)$/i;
+function looksLive(baseUrl) {
+  let host;
+  try {
+    host = new URL(baseUrl).hostname;
+  } catch {
+    return true;
+  }
+  if (NOT_LIVE.test(host) || NOT_LIVE_SUFFIX.test(host)) return false;
+  return true;
+}
+function preflight(facts) {
+  const checks = [];
+  const live = looksLive(facts.baseUrl);
+  if (facts.replaying) {
+    checks.push({
+      name: "target",
+      ok: true,
+      blocking: false,
+      detail: `${facts.baseUrl}, reading from ${facts.replaying} \u2014 no live backend is reachable from this run, so nothing on these screens can be a real person's`
+    });
+  } else if (facts.session && live && !facts.productionGranted) {
+    checks.push({
+      name: "target",
+      ok: false,
+      blocking: true,
+      detail: `${facts.baseUrl} does not look like a demo or staging address, and this run has a session. A help article shows the typical state of a screen, not somebody's data \u2014 point this at a demo tenant, or pass --allow-production if that address really is the seeded one.`
+    });
+  } else {
+    checks.push({
+      name: "target",
+      ok: true,
+      blocking: false,
+      detail: facts.session ? `${facts.baseUrl}, signed in${live ? " \u2014 accepted as seeded by --allow-production" : " as a demo tenant"}` : `${facts.baseUrl}, signed in as nobody`
+    });
+  }
+  checks.push({
+    name: "browser",
+    ok: Boolean(facts.browser),
+    blocking: false,
+    detail: facts.browser ? `${facts.browser}, recorded on every frame` : "not identified \u2014 a browser upgrade will look like the product changing"
+  });
+  checks.push({
+    name: "clock",
+    ok: facts.clockPinned,
+    blocking: false,
+    detail: facts.clockPinned ? "pinned, with randomness and generated ids seeded from it" : "running live (--live-clock) \u2014 screens showing a date will differ every run, so nothing here can tell you whether they changed"
+  });
+  checks.push({
+    name: "locale",
+    ok: true,
+    blocking: false,
+    detail: `${facts.locale}, ${facts.timezone} \u2014 set explicitly rather than inherited from this machine`
+  });
+  checks.push({
+    name: "isolation",
+    ok: true,
+    blocking: false,
+    detail: "a fresh browser context per screen, so no frame depends on which frames ran before it"
+  });
+  checks.push({
+    name: "stability",
+    ok: true,
+    blocking: false,
+    detail: "the shutter waits for two identical frames; a screen that never settles is reported, not silently kept"
+  });
+  checks.push({
+    name: "posture",
+    ok: true,
+    blocking: false,
+    detail: "read-only: this navigates and photographs, and activates no control"
+  });
+  if (facts.rebaselineReason) {
+    checks.push({
+      name: "rebaseline",
+      ok: true,
+      blocking: false,
+      detail: `replacing every stored frame \u2014 "${facts.rebaselineReason}"`
+    });
+  }
+  const blocked = checks.filter((check) => check.blocking && !check.ok);
+  const lines = [
+    "Before anything is photographed:",
+    "",
+    ...checks.map((check) => `  ${check.ok ? "\u2713" : "\u2717"} ${check.name.padEnd(10)} ${check.detail}`)
+  ];
+  return { ok: !blocked.length, checks, lines };
+}
+function attestation(run) {
+  const took = run.unchanged ? `${run.captured} new frame(s) and ${run.unchanged} verified unchanged` : `${run.captured} frame(s)`;
+  return [
+    `${took} from ${run.baseUrl}${run.browser ? ` with ${run.browser}` : ""}.`,
+    "Every one was checked before the shutter and again on arrival: no frame in this set showed an email address,",
+    "an account or card number, a national or tax id, a date of birth, a passport number or a named institution.",
+    run.refused ? `${run.refused} screen(s) were refused for showing something that looked real, and no picture of them exists.` : "Nothing was refused.",
+    // Two different claims, and the second is much stronger. "Nothing that
+    // looked real got through" is a gate doing its job on unknown data; "there
+    // was no real data behind any of it" is a fact about where the data came
+    // from, and it is the one a compliance reader actually wants.
+    run.replaying ? `Every screen was served from ${run.replaying}, so no customer data was reachable during this run at all.` : "",
+    run.clockPinned && run.replaying ? "The clock was pinned and the data was fixed, so re-running this reproduces the same bytes." : run.clockPinned ? "The clock was pinned. The backend was live, so any screen showing its data can still move between runs." : "The clock ran live, so these frames are not reproducible."
+  ].filter(Boolean).join("\n");
+}
+
+// core/capture/scrub.ts
+var BRANDS = [
+  "Chase",
+  "JPMorgan",
+  "J.P. Morgan",
+  "Bank of America",
+  "Wells Fargo",
+  "Citibank",
+  "Citigroup",
+  "Goldman Sachs",
+  "Morgan Stanley",
+  "Schwab",
+  "Charles Schwab",
+  "Fidelity",
+  "Vanguard",
+  "BlackRock",
+  "Merrill",
+  "Merrill Lynch",
+  "TD Ameritrade",
+  "E*TRADE",
+  "Robinhood",
+  "Coinbase",
+  "American Express",
+  "Amex",
+  "Capital One",
+  "PNC",
+  "US Bank",
+  "Truist",
+  "HSBC",
+  "Barclays",
+  "Northern Trust",
+  "State Street",
+  "Pershing",
+  "LPL Financial",
+  "Raymond James",
+  "Edward Jones",
+  "Plaid",
+  "Yodlee",
+  "Addepar",
+  "Orion",
+  "Envestnet",
+  "eMoney",
+  "MoneyGuidePro"
+];
+var SAFE_EMAIL_DOMAIN = "example.invalid";
+var ALREADY_SAFE = [
+  // RFC 2606 and RFC 6761 reserve these precisely so they can never resolve.
+  { kind: "email", regex: /@[A-Za-z0-9.-]*\.(invalid|test|example|localhost)$/i },
+  { kind: "email", regex: /@(example\.(com|net|org))$/i },
+  // 555-01xx is reserved for fiction and cannot reach a telephone.
+  { kind: "phone", regex: /^(\+?1[-. ]?)?\(?555\)?[-. ]?01\d{2}$/ },
+  /*
+   * This module's own replacements, which it must not report a second time.
+   *
+   * Without these it is not idempotent, and idempotence is not a nicety here:
+   * a scrubbed fixture is scrubbed AGAIN on the way into a screenshot, and a
+   * zeroed account number matching the long-digit-run rule means the gate
+   * refuses a screen this module already made safe. Nothing is wrong, nothing
+   * can be done about it, and the run stops — which is the precise way a check
+   * teaches people to ignore it.
+   *
+   * No real account, card or identification number is all zeroes.
+   */
+  { kind: "account-number", regex: /^0+$/ },
+  { kind: "account-number", regex: /^XX0+$/ },
+  { kind: "national-id", regex: /^000-00-0000$/ },
+  { kind: "national-id", regex: /^AA0{6}A$/ },
+  { kind: "tax-id", regex: /^00-0000000$/ },
+  { kind: "passport", regex: /^[A-Z]{1,2}0+$/ },
+  { kind: "date-of-birth", regex: /^1970-01-01$/ }
+];
+function alreadySafe(kind, value) {
+  return ALREADY_SAFE.some((entry) => entry.kind === kind && entry.regex.test(value));
+}
+var PATTERNS = [
+  {
+    kind: "email",
+    regex: /\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}\b/g,
+    because: "a real address can receive mail from a fixture",
+    replace: (_match, index) => `person${index + 1}@${SAFE_EMAIL_DOMAIN}`
+  },
+  {
+    kind: "national-id",
+    // US SSN shape. Deliberately narrow: a looser rule matches dates and
+    // phone numbers, and a scrub that cries wolf gets click-throughed.
+    regex: /\b(?!000|666|9\d\d)\d{3}-(?!00)\d{2}-(?!0000)\d{4}\b/g,
+    because: "a national identification number",
+    replace: () => "000-00-0000"
+  },
+  {
+    kind: "tax-id",
+    regex: /\b\d{2}-\d{7}\b/g,
+    because: "an employer or tax identification number",
+    replace: () => "00-0000000"
+  },
+  {
+    kind: "national-id",
+    // UK National Insurance. Two letters, six digits, one suffix letter.
+    // Every product with a UK employee or patient holds one of these, which is
+    // why it sits beside the US shape rather than in a finance-specific list.
+    regex: /\b[A-CEGHJ-PR-TW-Z]{2}\s?\d{2}\s?\d{2}\s?\d{2}\s?[A-D]\b/g,
+    because: "the shape of a UK National Insurance number",
+    replace: () => "AA000000A"
+  },
+  {
+    kind: "account-number",
+    // IBAN. Checked before the bare digit run below, because an IBAN carries
+    // its country and bank in the leading letters and zeroing only the digits
+    // would leave those standing.
+    regex: /\b[A-Z]{2}\d{2}[A-Z0-9]{11,30}\b/g,
+    because: "an international bank account number",
+    replace: (match) => `XX00${"0".repeat(match.length - 4)}`
+  },
+  {
+    kind: "account-number",
+    // Long digit runs. Card numbers, account numbers, routing numbers.
+    regex: /\b\d{9,19}\b/g,
+    because: "long enough to be an account, card or routing number",
+    replace: (match) => "0".repeat(match.length)
+  },
+  {
+    kind: "date-of-birth",
+    regex: /\b(19|20)\d{2}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])\b/g,
+    because: "a full date \u2014 if it is a birth date it identifies somebody",
+    replace: () => "1970-01-01"
+  },
+  {
+    kind: "passport",
+    regex: /\b[A-Z]{1,2}\d{6,9}\b/g,
+    because: "the shape of a passport or licence number",
+    replace: (match) => `${match.slice(0, 1)}${"0".repeat(match.length - 1)}`
+  },
+  {
+    kind: "phone",
+    regex: /\b(?:\+?1[-. ]?)?\(?\d{3}\)?[-. ]\d{3}[-. ]\d{4}\b/g,
+    because: "a telephone number",
+    replace: () => "555-0100"
+  }
+];
+function scrub(text2, options = {}) {
+  const findings = [];
+  const where = options.where ?? "fixture";
+  let output = text2;
+  for (const pattern of PATTERNS) {
+    const seen = /* @__PURE__ */ new Map();
+    output = output.replace(pattern.regex, (match) => {
+      if (alreadySafe(pattern.kind, match)) return match;
+      const already = seen.get(match);
+      if (already) return already;
+      const replacement = pattern.replace(match, seen.size);
+      seen.set(match, replacement);
+      findings.push({ kind: pattern.kind, found: match, replacement, where, because: pattern.because });
+      return replacement;
+    });
+  }
+  for (const brand of [...BRANDS, ...options.brands ?? []]) {
+    const regex = new RegExp(`\\b${escapeRegExp(brand)}\\b`, "gi");
+    if (regex.test(output)) {
+      findings.push({
+        kind: "brand",
+        found: brand,
+        replacement: brand,
+        where,
+        because: "a real institution in a published screenshot implies a partnership \u2014 a legal review item, not a design nit"
+      });
+    }
+  }
+  return { scrubbed: output, findings, needsReview: findings.length > 0 };
+}
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+// core/capture/gate.ts
+function gateFrame(pageText, options = {}) {
+  const result = scrub(pageText, {
+    ...options.brands ? { brands: options.brands } : {},
+    ...options.route ? { where: options.route } : {}
+  });
+  const expected = new Set((options.expected ?? []).map((name) => name.trim().toLowerCase()).filter(Boolean));
+  const findings = result.findings.filter(
+    (finding) => !(finding.kind === "brand" && expected.has(finding.found.trim().toLowerCase()))
+  );
+  if (!findings.length) return { safe: true, findings: [] };
+  const kinds = [...new Set(findings.map((finding) => finding.kind))];
+  const where = options.route ? ` on ${options.route}` : "";
+  const onlyBrands = findings.every((finding) => finding.kind === "brand");
+  const named = [...new Set(findings.filter((finding) => finding.kind === "brand").map((finding) => finding.found))];
+  return {
+    safe: false,
+    findings,
+    reason: onlyBrands ? `Not photographed${where}: the screen names ${named.join(", ")}. A real company in a published screenshot implies a partnership, which is a legal review item rather than a design nit \u2014 so somebody has to say whether it belongs there. If these names are on this screen on purpose, list them on the capture approval and this screen is photographed as it is.` : `Not photographed${where}: the screen showed ${kinds.join(", ")} that looks real. A screenshot cannot be redacted afterwards, so it is refused rather than cleaned \u2014 point the capture at a demo tenant, or fix the seed that produced this.`
+  };
+}
+
+// core/capture/publication/pixels.ts
+import { deflateSync, inflateSync } from "node:zlib";
+var MediaRefused = class extends Error {
+};
+var PUBLICATION_REDACTION = { r: 100, g: 116, b: 139 };
+function decodePng(buffer) {
+  if (buffer.length < 8 || buffer.readUInt32BE(0) !== 2303741511) {
+    throw new MediaRefused("that is not a PNG");
+  }
+  let offset = 8;
+  let width = 0;
+  let height = 0;
+  let colourType = 0;
+  let bitDepth = 0;
+  const data = [];
+  while (offset < buffer.length) {
+    const length = buffer.readUInt32BE(offset);
+    const type = buffer.toString("ascii", offset + 4, offset + 8);
+    const body = buffer.subarray(offset + 8, offset + 8 + length);
+    if (type === "IHDR") {
+      width = body.readUInt32BE(0);
+      height = body.readUInt32BE(4);
+      bitDepth = body.readUInt8(8);
+      colourType = body.readUInt8(9);
+      if (body.readUInt8(12) !== 0) throw new MediaRefused("interlaced PNGs are not supported here");
+    } else if (type === "IDAT") {
+      data.push(body);
+    } else if (type === "IEND") {
+      break;
+    }
+    offset += 12 + length;
+  }
+  if (bitDepth !== 8 || colourType !== 2 && colourType !== 6) {
+    throw new MediaRefused(`only 8-bit RGB and RGBA PNGs are supported here, not colour type ${colourType} at ${bitDepth} bits`);
+  }
+  const channels = colourType === 6 ? 4 : 3;
+  const raw = inflateSync(Buffer.concat(data));
+  const stride = width * channels;
+  const out = Buffer.alloc(width * height * 4);
+  const line = Buffer.alloc(stride);
+  const previous = Buffer.alloc(stride);
+  for (let y = 0; y < height; y += 1) {
+    const filter = raw[y * (stride + 1)];
+    const source = raw.subarray(y * (stride + 1) + 1, y * (stride + 1) + 1 + stride);
+    for (let index = 0; index < stride; index += 1) {
+      const x = source[index];
+      const a = index >= channels ? line[index - channels] : 0;
+      const b = previous[index];
+      const c = index >= channels ? previous[index - channels] : 0;
+      line[index] = filter === 0 ? x : filter === 1 ? x + a & 255 : filter === 2 ? x + b & 255 : filter === 3 ? x + (a + b >> 1) & 255 : x + paeth(a, b, c) & 255;
+    }
+    for (let x = 0; x < width; x += 1) {
+      const from = x * channels;
+      const to = (y * width + x) * 4;
+      out[to] = line[from];
+      out[to + 1] = line[from + 1];
+      out[to + 2] = line[from + 2];
+      out[to + 3] = channels === 4 ? line[from + 3] : 255;
+    }
+    line.copy(previous);
+  }
+  return { width, height, pixels: out };
+}
+function paeth(a, b, c) {
+  const p = a + b - c;
+  const pa = Math.abs(p - a);
+  const pb = Math.abs(p - b);
+  const pc = Math.abs(p - c);
+  return pa <= pb && pa <= pc ? a : pb <= pc ? b : c;
+}
+function coveredFraction(image) {
+  const total = image.width * image.height;
+  if (total === 0) return 0;
+  let covered = 0;
+  for (let index = 0; index < total; index += 1) {
+    const at = index * 4;
+    if (image.pixels[at] === PUBLICATION_REDACTION.r && image.pixels[at + 1] === PUBLICATION_REDACTION.g && image.pixels[at + 2] === PUBLICATION_REDACTION.b) {
+      covered += 1;
+    }
+  }
+  return covered / total;
+}
+var MOSTLY_COVERED = 0.5;
+
+// browser/page-side.ts
+function inPage(fn, arg) {
+  const shim = "(value) => value";
+  const argument = arg === void 0 ? "" : JSON.stringify(arg);
+  return `((__name) => (${fn.toString()}))(${shim})(${argument})`;
+}
+
+// core/transition/comparison.ts
+var RECORD_LAYER_MAY_REACH = Object.freeze({
+  provider: false,
+  registry: true
+});
+
+// browser/media.ts
+async function takeInventory(page, regions) {
+  const found = await page.evaluate(
+    inPage((spec) => {
+      const ignore = /* @__PURE__ */ new Set(["SCRIPT", "STYLE", "TITLE", "NOSCRIPT", "TEMPLATE", "HEAD", "META", "LINK", "OPTION"]);
+      const styleOf = (element, pseudo) => (element.ownerDocument?.defaultView ?? window).getComputedStyle(element, pseudo ?? null);
+      const rendered = (element) => {
+        const style = styleOf(element);
+        if (style.visibility === "hidden" || style.display === "none") return false;
+        for (const box of Array.from(element.getClientRects())) {
+          if (box.width > 0 && box.height > 0) return true;
+        }
+        return false;
+      };
+      const where = (element, prefix) => {
+        const steps = [];
+        for (let node = element; node && node.tagName !== "BODY" && node.tagName !== "HTML"; node = node.parentElement) {
+          if (node.id) {
+            steps.unshift(`#${node.id}`);
+            break;
+          }
+          const tag = node.tagName.toLowerCase();
+          const siblings2 = node.parentElement ? Array.from(node.parentElement.children) : [node];
+          steps.unshift(`${tag}:nth-child(${siblings2.indexOf(node) + 1})`);
+        }
+        return `${prefix}${steps.length === 0 ? "body" : steps.join(" > ")}`;
+      };
+      const accounts = (element, host) => {
+        const holding = [];
+        for (const region of spec.regions) {
+          try {
+            if (element.closest(region) || host?.closest(region)) holding.push(region);
+          } catch {
+          }
+        }
+        return holding;
+      };
+      const quoted = (content) => {
+        if (!content || content === "none" || content === "normal") return "";
+        const pattern = /"((?:[^"\\]|\\.)*)"|'((?:[^'\\]|\\.)*)'/g;
+        const text2 = content.replace(/url\(\s*(['"]?)[^)]*?\1\s*\)/g, " ");
+        const parts = [];
+        for (let match = pattern.exec(text2); match; match = pattern.exec(text2)) {
+          parts.push(match[1] ?? match[2] ?? "");
+        }
+        return parts.join("");
+      };
+      const values = [];
+      const walk = (root, prefix, host, depth2) => {
+        if (depth2 > 8) return;
+        const scope = root instanceof Document ? root.body : root;
+        if (!scope) return;
+        const walker = (scope.ownerDocument ?? document).createTreeWalker(scope, NodeFilter.SHOW_TEXT);
+        for (let node = walker.nextNode(); node; node = walker.nextNode()) {
+          const text2 = (node.textContent ?? "").trim();
+          const parent = node.parentElement;
+          if (text2.length === 0 || !parent) continue;
+          if (ignore.has(parent.tagName) || parent.closest("select") || !rendered(parent)) continue;
+          values.push({ at: where(parent, prefix), length: text2.length, accountedBy: accounts(parent, host) });
+        }
+        for (const element of Array.from(root.querySelectorAll("input, textarea, select"))) {
+          const control = element;
+          const shown = control.tagName === "SELECT" ? control.selectedOptions[0]?.textContent ?? "" : (control.value ?? "") || (control.placeholder ?? "");
+          if (shown.trim().length === 0 || !rendered(control)) continue;
+          values.push({ at: where(control, prefix), length: shown.trim().length, accountedBy: accounts(control, host) });
+        }
+        for (const element of Array.from(root.querySelectorAll("*"))) {
+          if (!rendered(element)) continue;
+          for (const pseudo of ["::before", "::after"]) {
+            const text2 = quoted(styleOf(element, pseudo).content).trim();
+            if (text2.length === 0) continue;
+            values.push({
+              at: `${where(element, prefix)}${pseudo}`,
+              length: text2.length,
+              accountedBy: accounts(element, host)
+            });
+          }
+          if (element.shadowRoot) {
+            walk(element.shadowRoot, `${where(element, prefix)} >> shadow `, element, depth2 + 1);
+          }
+          const tag = element.tagName.toLowerCase();
+          if (tag === "iframe" || tag === "object" || tag === "embed") {
+            let inner = null;
+            try {
+              inner = element.contentDocument;
+            } catch {
+              inner = null;
+            }
+            if (inner) walk(inner, `${where(element, prefix)} >> frame `, element, depth2 + 1);
+          }
+        }
+      };
+      walk(document, "", null, 0);
+      return values;
+    }, { regions: [...regions] })
+  );
+  const unaccounted = found.filter((value) => value.accountedBy.length === 0);
+  return {
+    observed: found.length,
+    accounted: found.length - unaccounted.length,
+    regions: [...regions],
+    unaccounted,
+    because: unaccounted.length === 0 ? `${found.length} value(s) are readable on this screen and every one of them falls inside one of the ${regions.length} region(s) the clearance enumerates` : `${unaccounted.length} of the ${found.length} readable value(s) on this screen fall outside every region the clearance enumerates`
+  };
+}
+
+// core/capture/determinism.ts
+import { createHash } from "node:crypto";
+function freezeScript(pinnedClock, options = {}) {
+  const fixed = Date.parse(pinnedClock);
+  if (Number.isNaN(fixed)) {
+    throw new Error(`freezeScript needs a parsable instant, got ${JSON.stringify(pinnedClock)}`);
+  }
+  const seed = options.seed ?? 2654435769;
+  return `(() => {
+  const FIXED = ${fixed};
+  const RealDate = Date;
+
+  class FrozenDate extends RealDate {
+    constructor(...args) {
+      // Only the no-argument form is the clock. \`new Date(x)\` is arithmetic
+      // on a value the page already had, and rewriting it would corrupt real
+      // data rather than stabilise a render.
+      if (args.length === 0) super(FIXED);
+      else super(...args);
+    }
+    static now() { return FIXED; }
+  }
+
+  // \`parse\` and \`UTC\` come along by static inheritance and must not be
+  // touched: they are pure functions of their arguments already.
+  FrozenDate.prototype.constructor = FrozenDate;
+  globalThis.Date = FrozenDate;
+
+  let state = ${seed} >>> 0;
+  // mulberry32: small, fast, and good enough that a seeded shuffle still looks
+  // shuffled. Cryptographic quality is the opposite of what is wanted here.
+  globalThis.Math.random = () => {
+    state = (state + 0x6d2b79f5) >>> 0;
+    let t = state;
+    t = Math.imul(t ^ (t >>> 15), t | 1);
+    t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+
+  if (globalThis.performance) {
+    let ticks = 0;
+    // Monotonic and deterministic. Frozen would deadlock anything that waits
+    // for time to pass.
+    globalThis.performance.now = () => (ticks += 16);
+  }
+
+  if (globalThis.crypto && globalThis.crypto.randomUUID) {
+    let issued = 0;
+    globalThis.crypto.randomUUID = () => {
+      issued += 1;
+      const n = issued.toString(16).padStart(12, "0");
+      return "00000000-0000-4000-8000-" + n;
+    };
+  }
+})();`;
+}
+function frameHash(bytes) {
+  return createHash("sha256").update(bytes).digest("hex");
+}
+async function settle(options) {
+  const wait = options.wait ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+  const now = options.now ?? (() => Date.now());
+  const deadline = now() + options.timeoutMs;
+  let value = await options.sample();
+  let samples = 1;
+  let matches = 1;
+  while (matches < options.identicalSamples) {
+    if (now() >= deadline) return { value, samples, settled: false };
+    await wait(options.intervalMs);
+    const next = await options.sample();
+    samples += 1;
+    matches = options.same(value, next) ? matches + 1 : 1;
+    value = next;
+  }
+  return { value, samples, settled: true };
+}
+function sameBytes(a, b) {
+  if (a.length !== b.length) return false;
+  for (let index = 0; index < a.length; index += 1) {
+    if (a[index] !== b[index]) return false;
+  }
+  return true;
+}
+
+// core/coverage/normalize.ts
+var CURRENCY = /[$£€¥₹]\s?[\d.,]+(?:\s?[A-Z]{3})?/g;
+var DIGITS = /\d+(?:[.,]\d+)*/g;
+function matchKey(value) {
+  const collapsed = value.normalize("NFKC").replace(/\s+/g, " ").trim();
+  const unpunctuated = collapsed.replace(/\s*(?::|\.{3}|…)$/u, "").trim();
+  return unpunctuated.toLowerCase().replace(CURRENCY, "\xA4").replace(DIGITS, "#").replace(/\s+/g, " ").trim();
+}
+
+// core/coverage/fact.ts
+function fact(parts) {
+  return { ...parts, key: matchKey(parts.value) };
+}
+var CHROME_LANDMARK = /* @__PURE__ */ new Set(["nav", "header", "footer"]);
+function scopeFromLandmark(landmark) {
+  if (CHROME_LANDMARK.has(landmark)) return "application";
+  if (landmark === "aside") return "layout";
+  return "screen";
+}
+var VOLATILE = /(?:[$£€¥₹]\s?[\d.,]+)|(?:\b\d[\d.,]*\s?(?:%|USD|EUR|GBP|items?|results?|days?|hours?|minutes?)\b)|(?:\b\d{1,2}[/-]\d{1,2}[/-]\d{2,4}\b)|(?:\b(?:Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec)[a-z]*\s+\d{1,2}\b)/i;
+function classifyData(value, scope, context) {
+  if (VOLATILE.test(value)) return "volatile-transactional";
+  if (context.inSource) return "product-interface";
+  if (scope !== "screen") return "product-interface";
+  return "example-instance";
+}
+
+// core/discovery/screen-facts.ts
+var LIMITS = {
+  headings: 12,
+  actions: 24,
+  links: 24,
+  fields: 24,
+  notices: 20,
+  warnings: 12,
+  choices: 12,
+  /** Longer than this is a paragraph of copy, not a label. */
+  label: 120,
+  sentence: 300
+};
+
+// core/discovery/aria-facts.ts
+var LANDMARK = {
+  main: "main",
+  navigation: "nav",
+  banner: "header",
+  contentinfo: "footer",
+  complementary: "aside",
+  dialog: "dialog",
+  alertdialog: "dialog",
+  form: "form",
+  search: "form"
+};
+var ACTION = /* @__PURE__ */ new Set(["button", "menuitem", "menuitemcheckbox", "menuitemradio", "tab", "switch"]);
+var FIELD = {
+  textbox: "text",
+  searchbox: "search",
+  combobox: "select",
+  listbox: "select",
+  checkbox: "checkbox",
+  radio: "radio",
+  slider: "range",
+  spinbutton: "number"
+};
+var NOTICE = /* @__PURE__ */ new Set(["status", "alert"]);
+var STATE = /* @__PURE__ */ new Set(["disabled", "checked", "selected", "expanded", "readonly", "required"]);
+function readAriaFactRecords(snapshot, options = {}) {
+  const from = options.url ?? "";
+  const inSource = options.inSource ?? /* @__PURE__ */ new Set();
+  const facts = [];
+  const add = (kind, value, node, extra = {}) => {
+    if (!value) return;
+    const scope = scopeFromLandmark(node.landmark);
+    facts.push(
+      fact({
+        kind,
+        value: trim(value, LIMITS.label),
+        channel: "p3",
+        scope,
+        dataClass: classifyData(value, scope, { inSource: inSource.has(value) }),
+        from,
+        landmark: node.landmark,
+        ...extra
+      })
+    );
+  };
+  for (const node of parse(snapshot)) {
+    const state = controlState(node);
+    if (node.role === "heading") {
+      add("heading", node.name || node.text, node);
+      continue;
+    }
+    if (node.role === "link") {
+      add("link", node.name || node.text || node.url || "", node, {
+        ...node.url ? { href: node.url } : {},
+        ...state
+      });
+      continue;
+    }
+    if (ACTION.has(node.role)) {
+      add("action", node.name || node.text, node, state);
+      continue;
+    }
+    const fieldKind = FIELD[node.role];
+    if (fieldKind) {
+      add("field", node.name || node.text, node, {
+        fieldKind,
+        ...node.choices.length ? { choices: node.choices.slice(0, LIMITS.choices) } : {},
+        ...state
+      });
+      continue;
+    }
+    if (NOTICE.has(node.role)) {
+      add("notice", trim(node.text || node.name, LIMITS.sentence), node);
+    }
+  }
+  return facts;
+}
+var LINE = /^(\s*)-\s+(.*)$/;
+var ENTRY = /^([a-z]+)(?:\s+"((?:[^"\\]|\\.)*)")?((?:\s*\[[^\]]*\])*)\s*(?::\s*(.*))?$/;
+function parse(snapshot) {
+  const out = [];
+  const stack = [];
+  for (const raw of snapshot.split("\n")) {
+    const line = LINE.exec(raw);
+    if (!line) continue;
+    const depth2 = line[1].length;
+    const body = line[2];
+    while (stack.length && stack[stack.length - 1].depth >= depth2) stack.pop();
+    const parent = stack[stack.length - 1]?.node;
+    if (body.startsWith("/")) {
+      const [name, ...rest] = body.split(":");
+      if (parent && name?.trim() === "/url") parent.url = rest.join(":").trim();
+      continue;
+    }
+    const entry = ENTRY.exec(body);
+    if (!entry) continue;
+    const role = entry[1];
+    const node = {
+      role,
+      name: unescape(entry[2] ?? ""),
+      text: (entry[4] ?? "").trim(),
+      attributes: attributesOf(entry[3] ?? ""),
+      landmark: LANDMARK[role] ?? parent?.landmark ?? "none",
+      choices: []
+    };
+    if (role === "option" && parent) {
+      if (node.name || node.text) parent.choices.push(node.name || node.text);
+      continue;
+    }
+    if (role !== "text") out.push(node);
+    stack.push({ depth: depth2, node });
+  }
+  return out;
+}
+function attributesOf(raw) {
+  const attributes = {};
+  for (const match of raw.matchAll(/\[([^\]]*)\]/g)) {
+    const [name, ...rest] = match[1].split("=");
+    const key = name?.trim();
+    if (!key) continue;
+    attributes[key] = rest.length ? rest.join("=").trim() : true;
+  }
+  return attributes;
+}
+function controlState(node) {
+  const state = {};
+  for (const [name, value] of Object.entries(node.attributes)) {
+    if (STATE.has(name)) state[name] = value;
+  }
+  return Object.keys(state).length ? { controlState: state } : {};
+}
+function unescape(value) {
+  return value.replace(/\\(.)/g, "$1");
+}
+function trim(value, limit) {
+  const collapsed = value.replace(/\s+/g, " ").trim();
+  return collapsed.length <= limit ? collapsed : `${collapsed.slice(0, limit - 1).trimEnd()}\u2026`;
+}
+
+// core/discovery/rendered-facts.ts
+var INVISIBLE = /<(script|style|noscript|template|svg|head)\b[^>]*>[\s\S]*?<\/\1>/gi;
+var COMMENT = /<!--[\s\S]*?-->/g;
+var HEADING = /^h[1-4]$/;
+var PRESSABLE = /* @__PURE__ */ new Set(["button", "menuitem", "tab", "switch", "option"]);
+var ANNOUNCEMENT = /* @__PURE__ */ new Set(["alert", "status", "alertdialog"]);
+var LANDMARK_TAG = {
+  main: "main",
+  nav: "nav",
+  header: "header",
+  footer: "footer",
+  aside: "aside",
+  dialog: "dialog",
+  form: "form"
+};
+var LANDMARK_ROLE = {
+  main: "main",
+  navigation: "nav",
+  banner: "header",
+  contentinfo: "footer",
+  complementary: "aside",
+  dialog: "dialog",
+  alertdialog: "dialog",
+  form: "form",
+  search: "form"
+};
+function readRenderedFactRecords(html, options = {}) {
+  const from = options.url ?? "";
+  const inSource = options.inSource ?? /* @__PURE__ */ new Set();
+  const facts = [];
+  const add = (kind, value, landmark, extra = {}) => {
+    if (!value) return;
+    const scope = scopeFromLandmark(landmark);
+    const context = { inSource: inSource.has(value) };
+    facts.push(
+      fact({
+        kind,
+        value,
+        channel: "p3",
+        scope,
+        dataClass: classifyData(value, scope, context),
+        from,
+        landmark,
+        ...extra
+      })
+    );
+  };
+  for (const element of elements(visibleMarkup(html))) {
+    const { tag, attributes, inner, landmark } = element;
+    const role = attributes["role"]?.toLowerCase() ?? "";
+    const label = accessibleName(element);
+    if (HEADING.test(tag) || role === "heading") {
+      add("heading", label, landmark);
+      continue;
+    }
+    if (tag === "button" || PRESSABLE.has(role) || submitLike(element)) {
+      add("action", label, landmark, controlState2(element));
+      continue;
+    }
+    if (tag === "a") {
+      const href = attributes["href"]?.trim();
+      if (href && !href.startsWith("#") && !href.startsWith("javascript:")) {
+        add("link", label || href, landmark, { href });
+      }
+      continue;
+    }
+    if (tag === "input" || tag === "textarea" || tag === "select") {
+      const field = fieldFrom(element, html);
+      if (field) {
+        add("field", field.label, landmark, {
+          fieldKind: field.kind,
+          ...field.choices ? { choices: field.choices } : {},
+          ...controlState2(element)
+        });
+      }
+      continue;
+    }
+    if (ANNOUNCEMENT.has(role) || attributes["aria-live"]) {
+      add("notice", trim2(text(inner), LIMITS.sentence), landmark);
+    }
+  }
+  return facts;
+}
+var OVERLAY_ROLE = {
+  dialog: "dialog",
+  alertdialog: "dialog",
+  menu: "menu",
+  listbox: "listbox",
+  tablist: "tabs"
+};
+function readOverlays(html, options = {}) {
+  const from = options.url ?? "";
+  const found = /* @__PURE__ */ new Map();
+  const all = elements(visibleMarkup(html));
+  const byId = new Map(
+    all.filter((element) => element.attributes["id"]).map((element) => [element.attributes["id"], element])
+  );
+  const remember = (overlay) => {
+    const key = `${overlay.kind}\0${overlay.key || overlay.name}`;
+    const existing = found.get(key);
+    found.set(key, existing ? { ...existing, ...overlay, key: existing.key } : overlay);
+  };
+  for (const element of all) {
+    const { tag, attributes } = element;
+    const role = attributes["role"]?.toLowerCase() ?? "";
+    const kind = OVERLAY_ROLE[role] ?? (tag === "dialog" ? "dialog" : void 0);
+    if (kind) {
+      const name = accessibleName(element) || attributes["aria-label"]?.trim() || "";
+      const open = openState(element);
+      remember({
+        kind,
+        name: name || `an unnamed ${kind}`,
+        key: attributes["id"] ?? name,
+        ...open === void 0 ? {} : { expanded: open },
+        from
+      });
+      continue;
+    }
+    const popup = attributes["aria-haspopup"];
+    const expanded = attributes["aria-expanded"];
+    if (!popup && expanded === void 0) continue;
+    const controls = attributes["aria-controls"];
+    const target = controls ? byId.get(controls) : void 0;
+    const targetRole = target?.attributes["role"]?.toLowerCase() ?? "";
+    const trigger = accessibleName(element);
+    remember({
+      kind: OVERLAY_ROLE[targetRole] ?? OVERLAY_ROLE[popup && popup !== "true" ? popup.toLowerCase() : ""] ?? (popup ? "menu" : "disclosure"),
+      name: (target ? accessibleName(target) : "") || trigger || "an unnamed overlay",
+      key: controls ?? trigger,
+      ...expanded === void 0 ? {} : { expanded: expanded === "true" },
+      ...trigger ? { openedBy: trigger } : {},
+      from
+    });
+  }
+  return [...found.values()].map(({ key: _key, ...overlay }) => overlay);
+}
+function openState(element) {
+  const { attributes } = element;
+  if ("open" in attributes) return attributes["open"] !== "false";
+  if ("hidden" in attributes) return false;
+  if (attributes["aria-hidden"] === "true") return false;
+  return void 0;
+}
+function visibleMarkup(html) {
+  return html.replace(INVISIBLE, " ").replace(COMMENT, " ");
+}
+var TAG = /<(\/?)([a-zA-Z][a-zA-Z0-9-]*)((?:"[^"]*"|'[^']*'|[^>"'])*?)(\/?)>/g;
+var VOID = /* @__PURE__ */ new Set([
+  "area",
+  "base",
+  "br",
+  "col",
+  "embed",
+  "hr",
+  "img",
+  "input",
+  "link",
+  "meta",
+  "param",
+  "source",
+  "track",
+  "wbr"
+]);
+function elements(markup) {
+  TAG.lastIndex = 0;
+  const stack = [];
+  const out = [];
+  let match;
+  const landmarkNow = () => stack[stack.length - 1]?.landmark ?? "none";
+  const close = (frame, endsAt) => {
+    out.push({
+      tag: frame.tag,
+      attributes: frame.attributes,
+      inner: markup.slice(frame.contentAt, endsAt),
+      landmark: frame.landmark,
+      at: frame.at
+    });
+  };
+  while (match = TAG.exec(markup)) {
+    const closing = match[1] === "/";
+    const tag = match[2].toLowerCase();
+    if (closing) {
+      const depth2 = stack.map((frame2) => frame2.tag).lastIndexOf(tag);
+      if (depth2 === -1) continue;
+      for (let index = stack.length - 1; index >= depth2; index -= 1) {
+        close(stack[index], match.index);
+      }
+      stack.length = depth2;
+      continue;
+    }
+    const attributes = attributesOf2(match[3] ?? "");
+    const own = LANDMARK_ROLE[attributes["role"]?.toLowerCase() ?? ""] ?? LANDMARK_TAG[tag];
+    const frame = {
+      tag,
+      attributes,
+      // An element opening a landmark is itself inside it, which is what makes
+      // `<nav aria-label="Main">` classify as navigation rather than as content.
+      landmark: own ?? landmarkNow(),
+      at: match.index,
+      contentAt: match.index + match[0].length
+    };
+    if (match[4] === "/" || VOID.has(tag)) {
+      out.push({ ...frame, inner: "" });
+      continue;
+    }
+    stack.push(frame);
+  }
+  for (const frame of stack) close(frame, markup.length);
+  return out.sort((a, b) => a.at - b.at);
+}
+var ATTRIBUTE = /([a-zA-Z_:][-a-zA-Z0-9_:.]*)(?:\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s"'>]+)))?/g;
+function attributesOf2(raw) {
+  const attributes = {};
+  ATTRIBUTE.lastIndex = 0;
+  let match;
+  while (match = ATTRIBUTE.exec(raw)) {
+    const name = match[1].toLowerCase();
+    const value = match[2] ?? match[3] ?? match[4];
+    attributes[name] = value === void 0 ? "" : decode(value);
+  }
+  return attributes;
+}
+function controlState2(element) {
+  const state = {};
+  const { attributes } = element;
+  const flag = (name) => name in attributes && attributes[name] !== "false";
+  if (flag("disabled") || attributes["aria-disabled"] === "true") state["disabled"] = true;
+  if (flag("required") || attributes["aria-required"] === "true") state["required"] = true;
+  if (flag("checked") || attributes["aria-checked"] === "true") state["checked"] = true;
+  if (flag("selected") || attributes["aria-selected"] === "true") state["selected"] = true;
+  if (attributes["aria-expanded"]) state["expanded"] = attributes["aria-expanded"] === "true";
+  if (attributes["aria-invalid"] === "true") state["invalid"] = true;
+  return Object.keys(state).length ? { controlState: state } : {};
+}
+function accessibleName(element) {
+  const explicit = element.attributes["aria-label"] ?? element.attributes["title"];
+  if (explicit?.trim()) return trim2(explicit.replace(/\s+/g, " ").trim(), LIMITS.label);
+  return trim2(text(element.inner), LIMITS.label);
+}
+function submitLike(element) {
+  if (element.tag !== "input") return false;
+  const type = element.attributes["type"]?.toLowerCase();
+  return type === "submit" || type === "button" || type === "reset";
+}
+function fieldFrom(element, body) {
+  const { tag, attributes } = element;
+  const type = attributes["type"]?.toLowerCase() ?? "text";
+  if (tag === "input" && (type === "hidden" || submitLike(element))) return void 0;
+  const kind = tag === "input" ? type : tag;
+  const label = attributes["aria-label"]?.trim() || attributes["placeholder"]?.trim() || labelFor(body, attributes["id"]) || humanise(attributes["name"] ?? "");
+  if (!label) return void 0;
+  const field = { label: trim2(label.replace(/\s+/g, " "), LIMITS.label), kind };
+  if (tag === "select") {
+    const choices = [...element.inner.matchAll(/<option\b[^>]*>([\s\S]*?)<\/option>/gi)].map((match) => text(match[1] ?? "")).filter(Boolean).slice(0, LIMITS.choices);
+    if (choices.length) field.choices = choices;
+  }
+  return field;
+}
+function labelFor(body, id) {
+  if (!id) return "";
+  const match = new RegExp(
+    `<label\\b[^>]*\\bfor\\s*=\\s*["']?${escape(id)}["']?[^>]*>([\\s\\S]*?)</label>`,
+    "i"
+  ).exec(body);
+  return match ? text(match[1] ?? "") : "";
+}
+function escape(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function humanise(name) {
+  const words = name.replace(/[_-]+/g, " ").replace(/([a-z0-9])([A-Z])/g, "$1 $2").replace(/\s+/g, " ").trim();
+  return words ? `${words.charAt(0).toUpperCase()}${words.slice(1).toLowerCase()}` : "";
+}
+function text(fragment) {
+  return decode(fragment.replace(/<[^>]*>/g, " ")).replace(/\s+/g, " ").trim();
+}
+var ENTITY = {
+  amp: "&",
+  lt: "<",
+  gt: ">",
+  quot: '"',
+  apos: "'",
+  nbsp: " ",
+  "#39": "'",
+  "#x27": "'",
+  "#34": '"',
+  mdash: "\u2014",
+  ndash: "\u2013",
+  hellip: "\u2026"
+};
+function decode(value) {
+  return value.replace(/&(#x?[0-9a-fA-F]+|[a-zA-Z]+);/g, (whole, name) => {
+    const known = ENTITY[name.toLowerCase()];
+    if (known) return known;
+    const numeric = /^#x/i.test(name) ? Number.parseInt(name.slice(2), 16) : /^#/.test(name) ? Number.parseInt(name.slice(1), 10) : NaN;
+    return Number.isFinite(numeric) && numeric > 0 && numeric < 1114112 ? String.fromCodePoint(numeric) : whole;
+  });
+}
+function trim2(value, limit) {
+  return value.length <= limit ? value : `${value.slice(0, limit - 1).trimEnd()}\u2026`;
+}
+
+// core/coverage/stamp.ts
+var RUNTIME = /* @__PURE__ */ new Set(["p3", "p4"]);
+var STATIC = /* @__PURE__ */ new Set(["p1", "p2", "p2-state", "p5"]);
+function isRuntimeChannel(channel) {
+  return RUNTIME.has(channel);
+}
+function isStaticChannel(channel) {
+  return STATIC.has(channel);
+}
+var ROLE_STATES = /* @__PURE__ */ new Set(["present", "unknown", "not-applicable"]);
+function unknownRole() {
+  return { state: "unknown" };
+}
+function noRole(because) {
+  return { state: "not-applicable", because };
+}
+function unknownDeployment(because) {
+  return { state: "unknown", because };
+}
+var PROVENANCE_LINKS = /* @__PURE__ */ new Set([
+  "verified",
+  "asserted",
+  "unknown"
+]);
+var UnstampedObservation = class extends Error {
+};
+var ISO = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$/;
+var RUNTIME_DIMENSIONS = ["url", "captureEnvironment", "session"];
+var BROWSER_SHAPED = /^(?:headless\s*)?(chromium|chrome|firefox|safari|webkit|edge|msedge|playwright)\b[\s/_v-]*\d/i;
+function requireStamp(input) {
+  if (!input) throw new UnstampedObservation("An observation arrived with no stamp at all.");
+  const producer = input.producer?.trim() ?? "";
+  if (!producer) throw new UnstampedObservation("An observation arrived without naming its producer.");
+  if (!isRuntimeChannel(producer) && !isStaticChannel(producer)) {
+    throw new UnstampedObservation(`"${producer}" is not one of the five named producers.`);
+  }
+  const missing = [];
+  if (!input.at?.trim()) missing.push("at");
+  if (isRuntimeChannel(producer)) {
+    for (const dimension of RUNTIME_DIMENSIONS) {
+      if (!input[dimension]?.trim()) missing.push(dimension);
+    }
+    if (!input.target?.repository?.trim()) missing.push("target.repository");
+    if (!input.target?.commit?.trim()) missing.push("target.commit");
+    if (!input.link?.trim()) missing.push("link");
+    const claimed = ["repository", "commit"].filter(
+      (dimension) => input[dimension] !== void 0
+    );
+    if (claimed.length) {
+      throw new UnstampedObservation(
+        `A ${producer} observation carries ${claimed.join(" and ")} directly. A running URL does not tell us which commit built what answered it: name the repository and commit under \`target\`, and say under \`link\` whether the deployment has been verified against them.`
+      );
+    }
+    if (!input.role) missing.push("role");
+    else if (!ROLE_STATES.has(input.role.state)) {
+      throw new UnstampedObservation(
+        `A ${producer} observation gave its role as "${input.role.state}", which is not one of present, unknown or not-applicable.`
+      );
+    }
+    if (!input.deployment) missing.push("deployment");
+    else requireDeployment(producer, input);
+    if (input.link && !PROVENANCE_LINKS.has(input.link.trim())) {
+      throw new UnstampedObservation(
+        `A ${producer} observation gave its link as "${input.link}", which is not one of verified, asserted or unknown.`
+      );
+    }
+    if (input.link?.trim() === "verified" && input.deployment?.state !== "present") {
+      throw new UnstampedObservation(
+        `A ${producer} observation claims its deployment is verified against ${input.target?.commit ?? "a commit"}, and cannot say which deployment. A mapping to a deployment nobody can name is not a verification.`
+      );
+    }
+  } else {
+    if (!input.repository?.trim()) missing.push("repository");
+    if (!input.commit?.trim()) missing.push("commit");
+    const invented = ["url", "captureEnvironment", "session"].filter(
+      (dimension) => input[dimension] !== void 0
+    );
+    for (const dimension of ["role", "deployment", "target", "link"]) {
+      if (input[dimension] !== void 0) invented.push(dimension);
+    }
+    if (invented.length) {
+      throw new UnstampedObservation(
+        `A ${producer} observation carries ${invented.join(", ")}, and a repository read has none of those. Either the producer is wrong or the value was invented.`
+      );
+    }
+  }
+  if (missing.length) {
+    throw new UnstampedObservation(
+      `A ${producer} observation is missing ${missing.join(", ")}. It cannot be stored, because it could never be invalidated.`
+    );
+  }
+  if (!ISO.test(input.at)) {
+    throw new UnstampedObservation(`"${input.at}" is not an ISO-8601 timestamp.`);
+  }
+  return isRuntimeChannel(producer) ? {
+    producer,
+    at: input.at,
+    url: input.url.trim(),
+    deployment: input.deployment,
+    captureEnvironment: input.captureEnvironment.trim(),
+    session: input.session.trim(),
+    role: input.role,
+    target: {
+      repository: input.target.repository.trim(),
+      commit: input.target.commit.trim()
+    },
+    link: input.link.trim()
+  } : {
+    producer,
+    repository: input.repository.trim(),
+    commit: input.commit.trim(),
+    at: input.at
+  };
+}
+function requireDeployment(producer, input) {
+  const deployment = input.deployment;
+  if (deployment.state === "unknown") {
+    if (!deployment.because.trim()) {
+      throw new UnstampedObservation(
+        `A ${producer} observation says its deployment is unknown and does not say why. An unexplained unknown is the blank field this shape exists to abolish.`
+      );
+    }
+    return;
+  }
+  if (deployment.state !== "present" || !deployment.value.trim()) {
+    throw new UnstampedObservation(
+      `A ${producer} observation gave its deployment as "${deployment.state}", which is not one of present or unknown.`
+    );
+  }
+  const value = deployment.value.trim();
+  if (BROWSER_SHAPED.test(value) || value === input.captureEnvironment?.trim()) {
+    throw new UnstampedObservation(
+      `A ${producer} observation gives "${value}" as the deployment that answered it. That names the browser that did the reading, which belongs in captureEnvironment. What is wanted here is what the application was running \u2014 a deployment id, a build id, a release SHA \u2014 or unknownDeployment("why not").`
+    );
+  }
+}
+
+// adapters/capture-cli.ts
+async function runCapture(options) {
+  const outcomes = [];
+  const survey = [];
+  const evidence = [];
+  const build = await options.browser.build?.().catch(() => void 0);
+  for (const [index, shot] of options.shots.entries()) {
+    const { outcome, observed, seen } = await captureOne(options, shot, build);
+    outcomes.push(outcome);
+    if (observed) survey.push(observed);
+    if (seen) evidence.push(seen);
+    options.onProgress?.(outcome, index + 1, options.shots.length);
+  }
+  const count = (status) => outcomes.filter((outcome) => outcome.status === status).length;
+  return {
+    baseUrl: options.baseUrl,
+    outcomes,
+    evidence,
+    survey,
+    ...build ? { browser: build } : {},
+    captured: count("captured"),
+    unchanged: count("unchanged"),
+    skipped: count("skipped"),
+    refused: count("refused"),
+    failed: count("failed")
+  };
+}
+async function captureOne(options, shot, build) {
+  let page;
+  try {
+    page = await options.browser.page();
+    await page.goto(new URL(shot.route, options.baseUrl).toString());
+    if (await page.isSignIn()) {
+      return {
+        outcome: {
+          shotId: shot.id,
+          route: shot.route,
+          status: "skipped",
+          result: "bounced",
+          needsAccount: true,
+          reason: "a signed-out visitor is shown a sign-in here, so this screen needs a demo tenant \u2014 never a real account"
+        },
+        observed: { route: shot.route, result: "bounced" }
+      };
+    }
+    const settledPage = page;
+    const text2 = await settle({
+      sample: () => settledPage.text(),
+      same: (a, b) => a === b,
+      identicalSamples: VISUAL_STABILITY.identicalFrames,
+      intervalMs: VISUAL_STABILITY.intervalMs,
+      timeoutMs: VISUAL_STABILITY.timeoutMs
+    });
+    const pageText = text2.value;
+    const verdict = gateFrame(pageText, {
+      route: shot.route,
+      ...options.brands ? { brands: options.brands } : {},
+      // Read off the clearance the help desk holds, never off a flag. A run
+      // that could name its own expected brands could name any of them, and the
+      // one thing this list does is stop a name being flagged.
+      ...options.clearance?.expectedBrands?.length ? { expected: options.clearance.expectedBrands } : {}
+    });
+    if (!verdict.safe) {
+      return {
+        outcome: { shotId: shot.id, route: shot.route, status: "refused", reason: verdict.reason }
+      };
+    }
+    const seen = await page.observe?.() ?? {};
+    const observed = classifyRoute({ ...seen, route: shot.route, text: pageText });
+    if (!isPublishable(observed.result)) {
+      return {
+        outcome: {
+          shotId: shot.id,
+          route: shot.route,
+          status: "skipped",
+          result: observed.result,
+          reason: actionFor(observed) ?? `the screen came back ${observed.result}`
+        },
+        observed
+      };
+    }
+    const evidence = await readEvidence(settledPage, shot.route, options, build);
+    const reading = options.clearance ? await readScreen(settledPage, options.clearance) : void 0;
+    if (options.clearance && !reading) {
+      return {
+        outcome: {
+          shotId: shot.id,
+          route: shot.route,
+          status: "failed",
+          result: observed.result,
+          reason: "this browser cannot read a screen against a clearance, so nothing it photographed could be checked. Upgrade the capture runner: the help desk refuses a frame that arrives with no reading of what was on it"
+        },
+        observed,
+        ...evidence ? { seen: evidence } : {}
+      };
+    }
+    if (reading) {
+      const unaccounted = reading.inventory.unaccounted;
+      if (unaccounted.length > 0) {
+        return {
+          outcome: {
+            shotId: shot.id,
+            route: shot.route,
+            status: "refused",
+            result: observed.result,
+            // Where and never what: a value nobody has classified is a value
+            // nobody has established is safe to write down, and a reason that
+            // quoted it would put it in this run's log.
+            reason: `${unaccounted.length} value(s) on this screen are outside every region the clearance names (${unaccounted.map((value) => `${value.at} (${value.length} character(s))`).join("; ")}), so it is restricted until somebody classifies them`
+          },
+          observed,
+          ...evidence ? { seen: evidence } : {}
+        };
+      }
+      const clearance = options.clearance;
+      const loose = reading.surfaces.filter(
+        (surface) => !surface.read && !clearance.covers.includes(surface.where) && !clearance.approved.includes(surface.where)
+      );
+      if (loose.length > 0 && !clearance.coverUnnamed) {
+        return {
+          outcome: {
+            shotId: shot.id,
+            route: shot.route,
+            status: "refused",
+            result: observed.result,
+            reason: `${loose.length} surface(s) on this screen are neither approved nor covered (${loose.map((surface) => `${surface.kind} at ${surface.where}`).join("; ")}); a surface nothing can read is approved against what it shows, covered, or it refuses the capture`
+          },
+          observed,
+          ...evidence ? { seen: evidence } : {}
+        };
+      }
+    }
+    const approved = new Set(options.clearance?.approved ?? []);
+    const cover = (reading?.surfaces ?? []).filter((surface) => !surface.read && !approved.has(surface.where)).map((surface) => surface.where);
+    const frame = await settle({
+      sample: () => settledPage.screenshot(cover),
+      same: sameBytes,
+      identicalSamples: VISUAL_STABILITY.identicalFrames,
+      intervalMs: VISUAL_STABILITY.intervalMs,
+      timeoutMs: VISUAL_STABILITY.timeoutMs
+    });
+    const image = frame.value;
+    const size = pngSize(image);
+    if (size && size.width < CAPTURE_CONTRACT.minStillWidth) {
+      return {
+        outcome: {
+          shotId: shot.id,
+          route: shot.route,
+          status: "failed",
+          result: observed.result,
+          reason: `that frame came back ${size.width}px wide; the contract needs at least ${CAPTURE_CONTRACT.minStillWidth}px`
+        },
+        observed,
+        // The picture is unusable; the reading of the screen is not.
+        ...evidence ? { seen: evidence } : {}
+      };
+    }
+    const measured = cover.length > 0 ? coverageOf(image) : 0;
+    if (measured > MOSTLY_COVERED) {
+      return {
+        outcome: {
+          shotId: shot.id,
+          route: shot.route,
+          status: "refused",
+          result: observed.result,
+          reason: `covering the ${cover.length} unreadable surface(s) on this screen took ${Math.round(measured * 100)}% of the picture, so what came back is more cover than screen. Approve what those surfaces show, or document a screen with fewer of them`
+        },
+        observed,
+        ...evidence ? { seen: evidence } : {}
+      };
+    }
+    const sha256 = frameHash(image);
+    if (!options.force && shot.sha256 && shot.sha256 === sha256) {
+      return {
+        outcome: {
+          shotId: shot.id,
+          route: shot.route,
+          status: "unchanged",
+          result: observed.result,
+          sha256,
+          settled: frame.settled,
+          reason: "byte-identical to the last run"
+        },
+        observed,
+        ...evidence ? { seen: evidence } : {}
+      };
+    }
+    const sent = await options.send({
+      shot,
+      pageText,
+      image,
+      capturedFrom: options.baseUrl,
+      sha256,
+      settled: frame.settled,
+      ...reading ? {
+        report: {
+          // A covered surface makes this a redacted frame, which is what it
+          // is: there is a slate rectangle in the picture.
+          disposition: cover.length > 0 ? "publishable-redacted" : "publishable",
+          inventory: reading.inventory,
+          surfaces: reading.surfaces.map((surface) => ({
+            id: surface.id,
+            kind: surface.kind,
+            at: surface.where,
+            // What was actually done to it, which the server checks against
+            // its own clearance. Reporting everything as covered when one
+            // of them was left visible would be the report disagreeing with
+            // the picture it is attached to.
+            disposition: surface.read ? "read" : approved.has(surface.where) ? "approved" : "masked"
+          })),
+          styled: reading.styled
+        }
+      } : {},
+      ...build ? { browser: build } : {},
+      ...size ?? {}
+    });
+    return {
+      outcome: sent.ok ? {
+        shotId: shot.id,
+        route: shot.route,
+        status: "captured",
+        result: observed.result,
+        sha256,
+        settled: frame.settled,
+        ...frame.settled ? {} : {
+          reason: "photographed, but this screen never stopped moving \u2014 its hash will differ every run, so drift on it means nothing"
+        }
+      } : {
+        shotId: shot.id,
+        route: shot.route,
+        status: "failed",
+        result: observed.result,
+        reason: sent.error ?? "the help desk refused it"
+      },
+      observed,
+      ...evidence ? { seen: evidence } : {}
+    };
+  } catch (error) {
+    return {
+      outcome: {
+        shotId: shot.id,
+        route: shot.route,
+        status: "failed",
+        reason: error instanceof Error ? error.message : String(error)
+      }
+    };
+  } finally {
+    await page?.close().catch(() => void 0);
+  }
+}
+async function readEvidence(page, route, options, build) {
+  if (!options.commit || !options.repository || !options.session || !build) return void 0;
+  const url = new URL(route, options.baseUrl).toString();
+  const html = await page.html?.().catch(() => "");
+  const aria = await page.aria?.().catch(() => "");
+  if (!html && !aria) return void 0;
+  const stamp = requireStamp({
+    producer: "p3",
+    at: (/* @__PURE__ */ new Date()).toISOString(),
+    url,
+    /*
+     * `build` is the browser, and goes where the browser goes. What was serving
+     * the URL is a different question, and a run that was not told the answer
+     * says so rather than letting the browser version imply one.
+     */
+    captureEnvironment: build,
+    deployment: options.deployment ?? unknownDeployment("this run was not told which deployment was serving the base URL"),
+    session: options.session,
+    role: options.role ?? unknownRole(),
+    target: { repository: options.repository, commit: options.commit },
+    link: options.link ?? "asserted"
+  });
+  return {
+    route,
+    facts: [
+      ...html ? readRenderedFactRecords(html, { url }) : [],
+      ...aria ? readAriaFactRecords(aria, { url }) : []
+    ],
+    overlays: html ? readOverlays(html, { url }) : [],
+    stamp,
+    channels: { html: Boolean(html), aria: Boolean(aria) }
+  };
+}
+async function playwrightBrowser(options = {}) {
+  const { chromium } = await loadPlaywright();
+  const executablePath = process.env["CAPTURE_CHROME"] ?? void 0;
+  const browser = await chromium.launch({
+    headless: options.headless ?? true,
+    ...executablePath ? { executablePath } : {},
+    args: [
+      "--no-sandbox",
+      "--disable-dev-shm-usage",
+      /**
+       * Software rendering, deliberately, and it is slower.
+       *
+       * Anything drawn through the GPU — canvas, WebGL, most charting
+       * libraries, some CSS filters — rasterises differently on different
+       * drivers and driver versions. Two machines then produce different bytes
+       * for identical input, so a run on a laptop and a run in CI disagree
+       * about a screen that never changed. That failure is invisible until the
+       * day somebody runs it somewhere new, which is the worst time to find it.
+       */
+      "--disable-gpu",
+      "--disable-software-rasterizer",
+      /**
+       * Font rasterisation, pinned as far as a flag can pin it. Subpixel
+       * antialiasing is tuned per display and hinting varies by platform;
+       * both change every pixel of every glyph without changing a word.
+       */
+      "--font-render-hinting=none",
+      "--disable-lcd-text",
+      "--force-color-profile=srgb",
+      // A scrollbar is an overlay on some platforms and consumes layout width
+      // on others, so leaving it visible makes the page a different width
+      // depending on who took the picture.
+      "--hide-scrollbars"
+    ]
+  });
+  const contextOptions = {
+    viewport: CAPTURE_CONTRACT.viewport,
+    deviceScaleFactor: CAPTURE_CONTRACT.stillScale,
+    // Pinned as well as the clock. A date formatted in the runner's own zone
+    // renders differently in London and in Denver, which makes a frame depend
+    // on who took it.
+    timezoneId: "UTC",
+    locale: "en-GB",
+    /**
+     * A session, when one is supplied — and only ever from a file on the
+     * machine running this.
+     *
+     * Signing in was refused outright until now, and the refusal was doing two
+     * jobs. One of them still stands: this tool must never hold a credential,
+     * so the help desk is not told the session exists and it is never sent
+     * anywhere. The other was collateral — it also meant the screens most
+     * worth documenting, which are the ones behind the sign-in, could not be
+     * photographed at all.
+     *
+     * What makes it safe is not the absence of a session but WHOSE session it
+     * is. A demo tenant holds nothing real; a customer's account holds
+     * everything. `gateFrame` is what enforces that, and with a session in
+     * play it stops being a backstop and becomes the load-bearing check: a
+     * screen showing anything that looks real is refused before the shutter,
+     * so pointing this at the wrong account produces no photographs rather
+     * than the wrong ones.
+     */
+    ...options.sessionPath ? { storageState: options.sessionPath } : { storageState: void 0 }
+  };
+  return {
+    async page() {
+      const context = await browser.newContext(contextOptions);
+      if (!options.liveClock) {
+        await context.addInitScript(freezeScript(CAPTURE_CONTRACT.pinnedClock));
+      }
+      await context.addInitScript(CLOSED_SHADOW_WITNESS);
+      const page = await context.newPage();
+      const errors = [];
+      const consoleErrors = [];
+      const failedRequests = [];
+      let status;
+      page.on("pageerror", (error) => errors.push(error.message));
+      page.on("console", (message) => {
+        if (message.type() === "error") consoleErrors.push(message.text());
+      });
+      page.on("response", (response) => {
+        if (response.status() < 400) return;
+        const kind = response.request().resourceType();
+        if (kind !== "document" && kind !== "xhr" && kind !== "fetch") return;
+        failedRequests.push({ url: pathOf(response.url()), status: response.status() });
+      });
+      await page.addStyleTag({ content: CAPTURE_CONTRACT.motionOff }).catch(() => void 0);
+      return {
+        async goto(url) {
+          const response = await page.goto(url, { waitUntil: "networkidle", timeout: 3e4 });
+          status = response?.status();
+          await page.addStyleTag({ content: CAPTURE_CONTRACT.motionOff }).catch(() => void 0);
+          await page.evaluate(() => document.fonts?.ready).catch(() => void 0);
+        },
+        async text() {
+          return page.locator("body").innerText().catch(() => "");
+        },
+        async html() {
+          return page.content().catch(() => "");
+        },
+        async aria() {
+          return page.locator("body").ariaSnapshot().catch(() => "");
+        },
+        async isSignIn() {
+          return await page.locator('input[type="password"]').count() > 0;
+        },
+        async observe() {
+          return {
+            landedOn: pathOf(page.url()),
+            ...status === void 0 ? {} : { status },
+            errors: [...errors],
+            consoleErrors: [...consoleErrors],
+            failedRequests: [...failedRequests]
+          };
+        },
+        async inspect(regions) {
+          const inventory = await takeInventory(page, regions);
+          const surfaces = await readOpaqueSurfaces(page, regions);
+          const styled = await page.evaluate(() => {
+            const fonts = document.fonts;
+            const images = Array.from(document.images);
+            return (fonts?.status ?? "loaded") === "loaded" && images.every((image) => image.complete);
+          }).catch(() => false);
+          return { inventory, surfaces, styled };
+        },
+        async screenshot(cover) {
+          const masks = (cover ?? []).map((selector) => page.locator(selector));
+          return page.screenshot({
+            type: "png",
+            fullPage: false,
+            // The colour is not a caller's to choose here either. A publication
+            // frame gets the neutral profile; the magenta sentinel is an
+            // instrument and never leaves the machine it was taken on.
+            ...masks.length > 0 ? { mask: masks, maskColor: PUBLICATION_REDACTION_CSS } : {}
+          });
+        },
+        async close() {
+          await context.close();
+        }
+      };
+    },
+    async build() {
+      return `chromium ${browser.version()}`;
+    },
+    async close() {
+      await browser.close();
+    }
+  };
+}
+var CLOSED_SHADOW_WITNESS = `(() => {
+  const real = Element.prototype.attachShadow;
+
+  if (!real) return;
+
+  Element.prototype.attachShadow = function (init) {
+    const root = real.call(this, init);
+
+    if (init && init.mode === "closed") {
+      try {
+        this.setAttribute("data-help-closed-shadow", "");
+      } catch {
+        // An element that refuses an attribute is one this cannot mark, and a
+        // failure here must not be a failure of the page. It stays unmarked,
+        // which leaves it exactly as undetectable as it was before.
+      }
+    }
+
+    return root;
+  };
+})()`;
+function coverageOf(image) {
+  try {
+    return coveredFraction(decodePng(Buffer.from(image)));
+  } catch {
+    return 0;
+  }
+}
+var PUBLICATION_REDACTION_CSS = `#${[PUBLICATION_REDACTION.r, PUBLICATION_REDACTION.g, PUBLICATION_REDACTION.b].map((channel) => channel.toString(16).padStart(2, "0")).join("")}`;
+async function readOpaqueSurfaces(page, regions) {
+  return page.evaluate(
+    inPage((spec) => {
+      const where = (element) => {
+        const steps = [];
+        for (let node = element; node && node.tagName !== "BODY" && node.tagName !== "HTML"; node = node.parentElement) {
+          if (node.id) {
+            steps.unshift(`#${node.id}`);
+            break;
+          }
+          const siblings2 = node.parentElement ? Array.from(node.parentElement.children) : [node];
+          steps.unshift(`${node.tagName.toLowerCase()}:nth-child(${siblings2.indexOf(node) + 1})`);
+        }
+        return steps.length === 0 ? "body" : steps.join(" > ");
+      };
+      const painted = (element) => {
+        const style = window.getComputedStyle(element);
+        if (style.visibility === "hidden" || style.display === "none") return false;
+        return Array.from(element.getClientRects()).some((box) => box.width > 0 && box.height > 0);
+      };
+      const found = [];
+      const add = (element, kind) => {
+        if (!painted(element)) return;
+        const at = where(element);
+        found.push({ id: `${kind}@${at}`, kind, where: at });
+      };
+      for (const element of Array.from(document.querySelectorAll("img"))) add(element, "image");
+      for (const element of Array.from(document.querySelectorAll("canvas"))) add(element, "canvas");
+      for (const element of Array.from(document.querySelectorAll("video"))) add(element, "video");
+      for (const element of Array.from(document.querySelectorAll("iframe, object, embed"))) add(element, "frame");
+      for (const element of Array.from(document.querySelectorAll("svg"))) {
+        if (!painted(element)) continue;
+        const at = where(element);
+        const markup = element.outerHTML;
+        const carries = element.querySelector("image, foreignObject, [href], [*|href]") !== null || /url\(/i.test(markup);
+        const held = spec.regions.some((region) => {
+          try {
+            return element.closest(region) !== null;
+          } catch {
+            return false;
+          }
+        });
+        found.push({
+          id: `svg@${at}`,
+          kind: "svg",
+          where: at,
+          // Reported either way. A drawing this resolved by reading is a thing
+          // somebody may want to check, and dropping it from the report would
+          // make "no surfaces on this screen" the answer to two very different
+          // questions.
+          ...carries || !held ? {} : { read: true }
+        });
+      }
+      for (const element of Array.from(document.querySelectorAll("*"))) {
+        if (element.hasAttribute("data-help-closed-shadow") || element.tagName.includes("-") && !element.shadowRoot) {
+          add(element, "shadow-opaque");
+        }
+        const style = window.getComputedStyle(element);
+        for (const property of ["backgroundImage", "listStyleImage", "borderImageSource", "maskImage"]) {
+          const value = style[property];
+          if (value && value !== "none" && value.includes("url(")) {
+            add(element, "css-image");
+            break;
+          }
+        }
+        for (const pseudo of ["::before", "::after"]) {
+          const content = window.getComputedStyle(element, pseudo).content;
+          if (content && content !== "none" && content.includes("url(")) {
+            add(element, "generated-image");
+            break;
+          }
+        }
+      }
+      return [...new Map(found.map((surface) => [surface.id, surface])).values()];
+    }, { regions: [...regions] })
+  ).catch(() => []).then((surfaces) => surfaces.map((surface) => ({ ...surface, kind: surface.kind })));
+}
+async function readScreen(page, clearance) {
+  if (!page.inspect) return void 0;
+  return page.inspect(clearance.regions);
+}
+function pathOf(url) {
+  try {
+    const parsed = new URL(url);
+    return `${parsed.pathname}${parsed.search}`;
+  } catch {
+    return url;
+  }
+}
+async function captureSignIn(options) {
+  const { chromium } = await loadPlaywright();
+  const executablePath = process.env["CAPTURE_CHROME"] ?? void 0;
+  const browser = await chromium.launch({
+    headless: false,
+    ...executablePath ? { executablePath } : {},
+    args: [
+      "--no-sandbox",
+      "--disable-dev-shm-usage",
+      // Offering to remember the password is the one thing this window must
+      // not do. The whole point of signing in here is that the credential is
+      // spent and forgotten; a browser prompt to save it invites the opposite,
+      // in a profile that is thrown away seconds later.
+      "--disable-features=PasswordManagerEnabled,AutofillServerCommunication",
+      "--password-store=basic"
+    ]
+  });
+  try {
+    const context = await browser.newContext({ viewport: CAPTURE_CONTRACT.viewport });
+    const page = await context.newPage();
+    await page.goto(options.baseUrl, { waitUntil: "domcontentloaded", timeout: 6e4 });
+    const deadline = Date.now() + (options.timeoutMs ?? 5 * 6e4);
+    while (Date.now() < deadline) {
+      const stillSigningIn = await page.locator('input[type="password"]').count() > 0;
+      if (!stillSigningIn) {
+        await page.waitForTimeout(1500);
+        await context.storageState({ path: options.sessionPath });
+        return { ok: true };
+      }
+      await page.waitForTimeout(1e3);
+    }
+    return { ok: false, reason: "Nobody finished signing in before the wait ran out." };
+  } finally {
+    await browser.close();
+  }
+}
+async function loadPlaywright() {
+  const specifier = "playwright-core";
+  try {
+    return await import(
+      /* webpackIgnore: true */
+      specifier
+    );
+  } catch {
+    throw new Error(
+      "Capture needs Playwright. Install it beside this command with `npm i -D playwright-core` and make sure a Chrome is available (set CAPTURE_CHROME to its path if it is not on the default one)."
+    );
+  }
+}
+
+// adapters/capture-stage.ts
+import { spawn } from "node:child_process";
+
+// adapters/seed-proxy.ts
+import { createServer, request as httpRequest } from "node:http";
+
+// core/seed/cassette.ts
+var CASSETTE_SCHEMA = "olomon.seed-cassette/1";
+var CACHE_BUSTERS = /* @__PURE__ */ new Set(["_", "cb", "cachebust", "cache_bust", "_t", "__ts", "nocache"]);
+function significantQuery(query) {
+  const kept = Object.entries(query).filter(([name]) => !CACHE_BUSTERS.has(name)).sort(([a], [b]) => a.localeCompare(b));
+  return Object.fromEntries(kept);
+}
+function interactionKey(args) {
+  const query = significantQuery(args.query ?? {});
+  const search = Object.entries(query).map(([name, value]) => `${name}=${value}`).join("&");
+  return `${args.method.toUpperCase()} ${args.path}${search ? `?${search}` : ""}`;
+}
+function looksLikeIdentifier(segment) {
+  if (!segment) return false;
+  if (/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(segment)) return true;
+  if (/^\d+$/.test(segment)) return true;
+  if (/^[0-9a-f]{8,}$/i.test(segment)) return true;
+  if (segment.length >= 20) return true;
+  return /\d/.test(segment) && segment.length >= 3;
+}
+function templatise(paths) {
+  const split = paths.map((path2) => path2.split("/").filter(Boolean));
+  const depth2 = Math.max(0, ...split.map((segments) => segments.length));
+  const parameters = /* @__PURE__ */ new Set();
+  const prefixOf = (segments, upTo) => {
+    const parts = [];
+    for (let index = 0; index < upTo; index += 1) {
+      parts.push(parameters.has(`${parts.join("/")}\0${index}`) ? ":" : segments[index]);
+    }
+    return parts.join("/");
+  };
+  for (let index = 0; index < depth2; index += 1) {
+    const groups = /* @__PURE__ */ new Map();
+    const children = /* @__PURE__ */ new Map();
+    for (const segments of split) {
+      if (segments.length <= index) continue;
+      const prefix = prefixOf(segments, index);
+      const value = segments[index];
+      (groups.get(prefix) ?? groups.set(prefix, /* @__PURE__ */ new Set()).get(prefix)).add(value);
+      const perGroup = children.get(prefix) ?? children.set(prefix, /* @__PURE__ */ new Map()).get(prefix);
+      const seen = perGroup.get(value) ?? perGroup.set(value, /* @__PURE__ */ new Set()).get(value);
+      if (segments.length > index + 1) seen.add(segments[index + 1]);
+    }
+    for (const [prefix, values] of groups) {
+      if (values.size < 2) continue;
+      const identifier = [...values].some(looksLikeIdentifier);
+      const parallel = leadsToTheSamePlaces(children.get(prefix));
+      if (identifier || parallel) parameters.add(`${prefix}\0${index}`);
+    }
+  }
+  const templates = /* @__PURE__ */ new Map();
+  for (const [index, segments] of split.entries()) {
+    const named = [];
+    let templated = false;
+    for (let position = 0; position < segments.length; position += 1) {
+      if (parameters.has(`${prefixOf(segments, position)}\0${position}`)) {
+        named.push(`:${parameterName(segments, position)}`);
+        templated = true;
+      } else {
+        named.push(segments[position]);
+      }
+    }
+    if (templated) templates.set(paths[index], `/${named.join("/")}`);
+  }
+  return templates;
+}
+function leadsToTheSamePlaces(children) {
+  if (!children || children.size < 2) return false;
+  const sets = [...children.values()].map((set) => [...set].sort().join("\0"));
+  return sets.every((set) => set && set === sets[0]);
+}
+function parameterName(segments, depth2) {
+  const parent = depth2 > 0 ? segments[depth2 - 1] : "";
+  const base = parent && !parent.startsWith(":") ? singular(parent) : "id";
+  return base.replace(/[^a-z0-9]+/gi, "") || "id";
+}
+function singular(word) {
+  const lower = word.toLowerCase();
+  if (/(analysis|status|address|series|species)$/.test(lower)) return lower;
+  if (lower.endsWith("ies")) return `${lower.slice(0, -3)}y`;
+  if (/(ch|sh|ss|x|z)es$/.test(lower)) return lower.slice(0, -2);
+  if (lower.endsWith("s") && !lower.endsWith("ss")) return lower.slice(0, -1);
+  return lower;
+}
+function parseCassette(text2) {
+  const parsed = JSON.parse(text2);
+  if (parsed.schema !== CASSETTE_SCHEMA) {
+    throw new Error(`Cassette schema ${JSON.stringify(parsed.schema)} is not one this understands.`);
+  }
+  return parsed;
+}
+var CassetteIndex = class {
+  constructor(cassette) {
+    this.cassette = cassette;
+    for (const interaction of cassette.interactions) {
+      this.exact.set(interactionKey(interaction), interaction);
+      if (interaction.template) {
+        const key = interactionKey({ ...interaction, path: interaction.template });
+        if (!this.byTemplate.has(key)) this.byTemplate.set(key, interaction);
+      }
+    }
+  }
+  exact = /* @__PURE__ */ new Map();
+  byTemplate = /* @__PURE__ */ new Map();
+  get anchor() {
+    return this.cassette.anchor;
+  }
+  get size() {
+    return this.exact.size;
+  }
+  find(args) {
+    const direct = this.exact.get(interactionKey(args));
+    if (direct) return direct;
+    const templates = new Set(
+      this.cassette.interactions.map((interaction) => interaction.template).filter(Boolean)
+    );
+    for (const template of [...templates].sort()) {
+      if (!matchesTemplate(template, args.path)) continue;
+      const found = this.byTemplate.get(interactionKey({ ...args, path: template }));
+      if (found) return found;
+    }
+    return void 0;
+  }
+};
+function matchesTemplate(template, path2) {
+  const wanted = template.split("/").filter(Boolean);
+  const actual = path2.split("/").filter(Boolean);
+  if (wanted.length !== actual.length) return false;
+  return wanted.every((segment, index) => segment.startsWith(":") || segment === actual[index]);
+}
+
+// adapters/seed-proxy.ts
+var MISS_STATUS = RECORDING_MISS_STATUS;
+function bodyOf(message) {
+  return new Promise((resolve, reject) => {
+    const chunks = [];
+    message.on("data", (chunk) => chunks.push(chunk));
+    message.on("end", () => resolve(Buffer.concat(chunks)));
+    message.on("error", reject);
+  });
+}
+function listen(server, port) {
+  return new Promise((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(port, "127.0.0.1", () => {
+      const address = server.address();
+      resolve(typeof address === "object" && address ? address.port : port);
+    });
+  });
+}
+function shut(server) {
+  return new Promise((resolve) => {
+    server.closeAllConnections?.();
+    server.close(() => resolve());
+  });
+}
+function splitUrl(url) {
+  const [path2, search] = url.split("?");
+  const query = {};
+  for (const [name, value] of new URLSearchParams(search ?? "")) query[name] = value;
+  return { path: path2 ?? "/", query };
+}
+async function replayFrom(options) {
+  const index = new CassetteIndex(options.cassette);
+  const misses = [];
+  const served = /* @__PURE__ */ new Set();
+  const server = createServer((incoming, outgoing) => {
+    void (async () => {
+      const { path: path2, query } = splitUrl(incoming.url ?? "/");
+      await bodyOf(incoming);
+      const found = index.find({ method: incoming.method ?? "GET", path: path2, query });
+      if (!found) {
+        const from = incoming.headers["referer"] ?? incoming.headers["x-seed-page"];
+        const miss = {
+          method: incoming.method ?? "GET",
+          path: path2,
+          ...Object.keys(query).length ? { query } : {},
+          ...typeof from === "string" ? { from: pageOf(from) } : {}
+        };
+        misses.push(miss);
+        options.onMiss?.(miss);
+        outgoing.writeHead(MISS_STATUS, { "content-type": "application/json" });
+        outgoing.end(
+          JSON.stringify({
+            error: "not in the recording",
+            method: miss.method,
+            path: miss.path,
+            hint: "Record this endpoint, or the screen that needs it has no data."
+          })
+        );
+        return;
+      }
+      served.add(`${found.method} ${found.path}`);
+      const body = found.encoding === "base64" ? Buffer.from(found.body, "base64") : Buffer.from(found.body, "utf8");
+      outgoing.writeHead(found.status, { ...found.headers, "content-length": String(body.byteLength) });
+      outgoing.end(body);
+    })();
+  });
+  const port = await listen(server, options.port ?? 0);
+  return {
+    url: `http://127.0.0.1:${port}`,
+    port,
+    misses,
+    served,
+    close: () => shut(server)
+  };
+}
+function pageOf(referer) {
+  try {
+    return new URL(referer).pathname;
+  } catch {
+    return referer;
+  }
+}
+
+// core/ci-api.ts
+var CI_SESSION_OUT_ENV = "HELPDESK_SESSION_OUT";
+var CI_BASE_URL_ENV = "HELPDESK_BASE_URL";
+
+// adapters/capture-stage.ts
+var DEFAULT_APP_ENV = "API_BASE_URL";
+async function waitForApp(url, deadline, onLog, gaveUp) {
+  let announced = false;
+  while (Date.now() < deadline) {
+    try {
+      await fetch(url, { signal: AbortSignal.timeout(2e3) });
+      return true;
+    } catch {
+      if (gaveUp?.()) return false;
+      if (!announced) {
+        onLog?.(`Waiting for ${url} to answer\u2026`);
+        announced = true;
+      }
+      await new Promise((resolve) => setTimeout(resolve, 400));
+    }
+  }
+  return false;
+}
+async function stageAgainstRecording(options) {
+  const replay = await replayFrom({
+    cassette: options.cassette,
+    ...options.replayPort ? { port: options.replayPort } : {},
+    onMiss: (miss) => options.onLog?.(`  the recording has no ${miss.method} ${miss.path}${miss.from ? ` (wanted by ${miss.from})` : ""}`)
+  });
+  const variable = options.appEnv ?? DEFAULT_APP_ENV;
+  let app;
+  let died;
+  if (options.appCommand) {
+    options.onLog?.(`Starting your product with ${variable}=${replay.url}`);
+    app = spawn(options.appCommand, {
+      shell: true,
+      // Its own process group, so it can be taken down as one.
+      //
+      // A start command is almost never the server: it is a shell running
+      // `npm start` running `next start`. Killing the pid we hold kills the
+      // shell and leaves the server holding the port, so the next run finds
+      // the address occupied by the last one — and on a build agent, the job
+      // never finishes.
+      detached: true,
+      env: { ...process.env, [variable]: replay.url },
+      stdio: ["ignore", "pipe", "pipe"]
+    });
+    app.stdout?.on("data", (chunk) => options.onLog?.(`  [app] ${chunk.toString().trimEnd()}`));
+    app.stderr?.on("data", (chunk) => options.onLog?.(`  [app] ${chunk.toString().trimEnd()}`));
+    app.on("exit", (code) => {
+      died = code ?? 1;
+    });
+  } else {
+    options.onLog?.(`The recording is at ${replay.url} \u2014 start your product with ${variable} set to it.`);
+  }
+  const up = await waitForApp(options.appUrl, Date.now() + (options.waitMs ?? 6e4), options.onLog, () => died !== void 0);
+  if (app) await new Promise((resolve) => setTimeout(resolve, 250));
+  if (died === void 0 && app?.exitCode !== null && app?.exitCode !== void 0) died = app.exitCode;
+  if (died !== void 0) {
+    await replay.close();
+    stop(app);
+    throw new Error(
+      `The start command exited (${died}) before the product was ready. Its output is above.` + (up ? `
+
+Something else is already answering on ${options.appUrl}. That is almost always a server left behind by an earlier run \u2014 this will not photograph it, because it is not the product this run started.` : "")
+    );
+  }
+  if (!up) {
+    await replay.close();
+    stop(app);
+    throw new Error(
+      `${options.appUrl} never answered. ` + (options.appCommand ? "Check the start command above, and that your product listens on that address." : `Start your product with ${variable}=${replay.url}, then run this again.`)
+    );
+  }
+  return {
+    appUrl: options.appUrl,
+    replayUrl: replay.url,
+    replay,
+    cassette: options.cassette,
+    close: async () => {
+      stop(app);
+      await replay.close();
+    }
+  };
+}
+var SESSION_OUT_ENV = CI_SESSION_OUT_ENV;
+async function stageSeeded(options) {
+  const onLog = options.onLog;
+  const { access, unlink } = await import("node:fs/promises");
+  await unlink(options.sessionOut).catch(() => void 0);
+  onLog?.(`Seeding a demo tenant with ${options.seedCommand}`);
+  const seeded = await runToCompletion(
+    options.seedCommand,
+    options.seedMs ?? 6e5,
+    { [CI_SESSION_OUT_ENV]: options.sessionOut, [CI_BASE_URL_ENV]: options.appUrl },
+    onLog
+  );
+  if (!seeded.ok) {
+    throw new Error(
+      `The seed command ${seeded.timedOut ? "did not finish in time" : `exited ${seeded.code}`}. Its output is above.
+
+Nothing has been photographed. A run that carried on from here would sign in to nothing and photograph the login screen of an empty product.`
+    );
+  }
+  const wrote = await access(options.sessionOut).then(
+    () => true,
+    () => false
+  );
+  const sessionPath = wrote ? options.sessionOut : void 0;
+  onLog?.(
+    sessionPath ? `The seed command left a session at ${sessionPath}, so the screens behind your login can be photographed.` : `The seed command wrote no session to ${SESSION_OUT_ENV}. Only the screens a signed-out visitor can reach will be photographed.`
+  );
+  let app;
+  let died;
+  if (options.appCommand) {
+    onLog?.(`Starting your product with ${options.appCommand}`);
+    app = spawn(options.appCommand, {
+      shell: true,
+      detached: true,
+      env: { ...process.env },
+      stdio: ["ignore", "pipe", "pipe"]
+    });
+    app.stdout?.on("data", (chunk) => onLog?.(`  [app] ${chunk.toString().trimEnd()}`));
+    app.stderr?.on("data", (chunk) => onLog?.(`  [app] ${chunk.toString().trimEnd()}`));
+    app.on("exit", (code) => {
+      died = code ?? 1;
+    });
+  }
+  const up = await waitForApp(options.appUrl, Date.now() + (options.waitMs ?? 6e4), onLog, () => died !== void 0);
+  if (app) await new Promise((resolve) => setTimeout(resolve, 250));
+  if (died === void 0 && app?.exitCode !== null && app?.exitCode !== void 0) died = app.exitCode;
+  if (died !== void 0) {
+    stop(app);
+    throw new Error(
+      `The start command exited (${died}) before the product was ready. Its output is above.` + (up ? `
+
+Something else is already answering on ${options.appUrl}, which is almost always a server left behind by an earlier run. This will not photograph it, because it is not the product this run started.` : "")
+    );
+  }
+  if (!up) {
+    stop(app);
+    throw new Error(
+      `${options.appUrl} never answered. Check the start command above, and that your product listens on that address.`
+    );
+  }
+  return {
+    appUrl: options.appUrl,
+    ...sessionPath ? { sessionPath } : {},
+    close: async () => {
+      stop(app);
+    }
+  };
+}
+async function runToCompletion(command, timeoutMs, env, onLog) {
+  return new Promise((resolve) => {
+    const child = spawn(command, {
+      shell: true,
+      detached: true,
+      env: { ...process.env, ...env },
+      stdio: ["ignore", "pipe", "pipe"]
+    });
+    const timer = setTimeout(() => {
+      stop(child);
+      resolve({ ok: false, timedOut: true });
+    }, timeoutMs);
+    child.stdout?.on("data", (chunk) => onLog?.(`  [seed] ${chunk.toString().trimEnd()}`));
+    child.stderr?.on("data", (chunk) => onLog?.(`  [seed] ${chunk.toString().trimEnd()}`));
+    child.on("error", (error) => {
+      clearTimeout(timer);
+      onLog?.(`  [seed] ${error.message}`);
+      resolve({ ok: false, code: 1, timedOut: false });
+    });
+    child.on("exit", (code) => {
+      clearTimeout(timer);
+      resolve({ ok: code === 0, code: code ?? 1, timedOut: false });
+    });
+  });
+}
+function stop(app) {
+  if (!app?.pid) return;
+  try {
+    process.kill(-app.pid, "SIGTERM");
+  } catch {
+    try {
+      process.kill(app.pid, "SIGTERM");
+    } catch {
+    }
+  }
+}
+
+// core/seed/gaps.ts
+function gapsFrom(misses, cassette) {
+  const known = cassette?.interactions.map((interaction) => interaction.path) ?? [];
+  const templates = templatise([...known, ...misses.map((miss) => miss.path)]);
+  const grouped = /* @__PURE__ */ new Map();
+  for (const miss of misses) {
+    const path2 = templates.get(miss.path) ?? miss.path;
+    const key = interactionKey({ method: miss.method, path: path2, ...miss.query ? { query: miss.query } : {} });
+    const existing = grouped.get(key);
+    if (existing) {
+      existing.asked += 1;
+      if (miss.from && !existing.broke.includes(miss.from)) existing.broke.push(miss.from);
+      continue;
+    }
+    grouped.set(key, {
+      method: miss.method.toUpperCase(),
+      path: path2,
+      asked: 1,
+      broke: miss.from ? [miss.from] : [],
+      example: miss.path
+    });
+  }
+  return [...grouped.values()].sort((a, b) => b.asked - a.asked || a.path.localeCompare(b.path));
+}
+function gapReport(gaps) {
+  if (!gaps.length) return ["The recording answered everything this run asked for."];
+  const lines = [
+    `${gaps.length} endpoint(s) are missing from the recording. Until they are in it, the screens below have no data:`,
+    ""
+  ];
+  for (const gap of gaps) {
+    const broke = gap.broke.length ? ` \u2014 breaks ${gap.broke.join(", ")}` : "";
+    lines.push(`  ${gap.method} ${gap.path}${broke}`);
+    if (gap.path !== gap.example) lines.push(`      for example ${gap.example}`);
+  }
+  lines.push(
+    "",
+    "Record them by running the product against the recording proxy once more and visiting those screens."
+  );
+  return lines;
+}
+function coverage(routes, cassette) {
+  const screens = cassette.screens ?? [];
+  if (!screens.length) return { covered: [], missing: [], known: false };
+  const covered = [];
+  const missing = [];
+  for (const route of routes) {
+    (screens.some((screen) => sameScreen(route, screen)) ? covered : missing).push(route);
+  }
+  return { covered, missing, known: true };
+}
+function sameScreen(route, screen) {
+  const wanted = route.split("/").filter(Boolean);
+  const actual = screen.split("/").filter(Boolean);
+  if (wanted.length !== actual.length) return false;
+  return wanted.every(
+    (segment, index) => /^[[:]/.test(segment) || segment.toLowerCase() === actual[index]?.toLowerCase()
+  );
+}
+function coverageReport(found, total) {
+  if (!found.known) {
+    return [
+      "This recording does not say which screens it was made from, so it cannot be checked",
+      "against your plan before the run. Record again to find out what is missing before",
+      "photographing rather than after."
+    ];
+  }
+  if (!found.missing.length) {
+    return [`All ${total} screen(s) in your plan were visited while recording.`];
+  }
+  return [
+    `Your plan needs ${total} screen(s). This recording was made while visiting ${found.covered.length}.`,
+    "",
+    `${found.missing.length} screen(s) have no data in the recording:`,
+    "",
+    ...found.missing.map((route) => `  ${route}`),
+    "",
+    "They will not be photographed. Record again and visit them, or they stay out of the",
+    "plan \u2014 an empty screen photographed from a gap in the recording looks exactly like an",
+    "empty screen belonging to a customer with nothing, which is how a help article ends up",
+    "showing a product with no content in it."
+  ];
+}
+
+// adapters/capture-bin.ts
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+// adapters/map-cli.ts
+import { execFileSync } from "node:child_process";
+
+// core/discovery/next-app-router.ts
+var PAGE_FILE = /(^|\/)page\.(tsx|ts|jsx|js)$/;
+var LAYOUT_FILE = /(^|\/)layout\.(tsx|ts|jsx|js)$/;
+var STATE_FILE = /(^|\/)(error|global-error|loading|not-found|template|default)\.(tsx|ts|jsx|js)$/;
+var ROUTE_GROUP = /^\((.+)\)$/;
+var DYNAMIC = /^\[{1,2}(\.{3})?(.+?)\]{1,2}$/;
+var PARALLEL = /^@/;
+var INTERCEPTING = /^\(\.+\)/;
+function classify(path2) {
+  if (path2 === "/api" || path2.startsWith("/api/")) {
+    return { skipped: "not-html", note: "an API route, not a screen" };
+  }
+  if (/(^|\/)(admin|internal|debug|_dev)(\/|$)/.test(path2)) {
+    return { skipped: "internal-tooling", note: "internal tooling" };
+  }
+  if (/(^|\/)(login|logout|signin|sign-in|signup|sign-up|auth|verify|reset-password)(\/|$)/.test(path2)) {
+    return { skipped: "unauthenticated-flow", note: "an authentication step" };
+  }
+  return void 0;
+}
+function detectRouterRoot(files) {
+  for (const candidate of ["src/app", "app"]) {
+    if (files.some((file) => file.startsWith(`${candidate}/`) && PAGE_FILE.test(file))) {
+      return candidate;
+    }
+  }
+  return void 0;
+}
+function readNextAppRouter(files, root = "src/app") {
+  const prefix = root.endsWith("/") ? root : `${root}/`;
+  const inRouter = [...new Set(files)].filter((file) => file.startsWith(prefix));
+  const layouts = inRouter.filter((file) => LAYOUT_FILE.test(file));
+  const routes = [];
+  const ignored = [];
+  for (const file of inRouter) {
+    if (!PAGE_FILE.test(file)) continue;
+    const segments = file.slice(prefix.length).split("/").slice(0, -1);
+    const parsed = toPath(segments);
+    if ("reason" in parsed) {
+      ignored.push({ file, reason: parsed.reason });
+      continue;
+    }
+    const classification = classify(parsed.path);
+    routes.push({
+      path: parsed.path,
+      // The page, then what sits beside it, then the layouts that wrap it.
+      //
+      // Co-located files matter as much as the page: a route's server actions
+      // and client components are where its behaviour actually lives, so an
+      // article about the screen goes stale when THEY change. Taking only the
+      // page would leave change detection blind to the part most likely to move.
+      sourceFiles: [file, ...siblings(file, inRouter), ...enclosingLayouts(file, layouts)],
+      params: parsed.params,
+      groups: parsed.groups,
+      states: declaredStates(file, inRouter, prefix),
+      ...classification ?? {}
+    });
+  }
+  routes.sort((a, b) => depth(a.path) - depth(b.path) || a.path.localeCompare(b.path));
+  return { framework: "next-app-router", routes, ignored };
+}
+function declaredStates(pageFile, files, prefix) {
+  const directory = pageFile.slice(0, pageFile.lastIndexOf("/"));
+  const own = new Set(
+    files.filter((file) => file.slice(0, file.lastIndexOf("/")) === directory)
+  );
+  const found = /* @__PURE__ */ new Map();
+  for (let at = directory; at.length >= prefix.length - 1; ) {
+    for (const file of files) {
+      if (file.slice(0, file.lastIndexOf("/")) !== at) continue;
+      const kind = stateKindOf(file);
+      if (!kind || found.has(kind)) continue;
+      found.set(kind, {
+        kind,
+        file,
+        segment: at.slice(prefix.length - 1).replace(/^\//, ""),
+        inherited: !own.has(file)
+      });
+    }
+    const up = at.lastIndexOf("/");
+    if (up < 0 || at.length <= prefix.length - 1) break;
+    at = at.slice(0, up);
+  }
+  return [...found.values()].sort((a, b) => a.kind.localeCompare(b.kind));
+}
+function stateKindOf(file) {
+  const match = /(^|\/)(error|global-error|loading|not-found)\.(tsx|ts|jsx|js)$/.exec(file);
+  return match ? match[2] : void 0;
+}
+function toPath(segments) {
+  const parts = [];
+  const params = [];
+  const groups = [];
+  for (const segment of segments) {
+    if (INTERCEPTING.test(segment)) return { reason: "an intercepting route, not its own URL" };
+    if (PARALLEL.test(segment)) return { reason: "a parallel route slot, not its own URL" };
+    const group = ROUTE_GROUP.exec(segment);
+    if (group) {
+      groups.push(group[1]);
+      continue;
+    }
+    const dynamic = DYNAMIC.exec(segment);
+    if (dynamic) {
+      params.push(dynamic[2]);
+      parts.push(segment);
+      continue;
+    }
+    parts.push(segment);
+  }
+  return { path: `/${parts.join("/")}`.replace(/\/+$/, "") || "/", params, groups };
+}
+function siblings(pageFile, files) {
+  const dir = pageFile.slice(0, pageFile.lastIndexOf("/") + 1);
+  return files.filter((file) => file !== pageFile && file.startsWith(dir) && !file.slice(dir.length).includes("/")).filter((file) => !/(^|\/)(opengraph-image|twitter-image|icon|apple-icon|sitemap|robots)\./.test(file)).filter((file) => !STATE_FILE.test(file)).filter((file) => !LAYOUT_FILE.test(file)).sort();
+}
+function enclosingLayouts(pageFile, layouts) {
+  const dir = pageFile.slice(0, pageFile.lastIndexOf("/"));
+  return layouts.filter((layout) => dir.startsWith(layout.slice(0, layout.lastIndexOf("/")))).sort((a, b) => a.length - b.length);
+}
+function depth(path2) {
+  return path2 === "/" ? 0 : path2.split("/").filter(Boolean).length;
+}
+
+// core/discovery/article-plan.ts
+var MONEY_OR_ACCESS = /* @__PURE__ */ new Set([
+  "billing",
+  "invoice",
+  "invoices",
+  "payment",
+  "payments",
+  "subscription",
+  "subscriptions",
+  "plan",
+  "plans",
+  "pricing",
+  "seat",
+  "seats",
+  "permission",
+  "permissions",
+  "role",
+  "roles",
+  "member",
+  "members"
+]);
+var ENTRY_POINT = /* @__PURE__ */ new Set([
+  "onboard",
+  "onboarding",
+  "setup",
+  "get-started",
+  "getting-started",
+  "welcome",
+  "install",
+  "import",
+  "connect",
+  "integration",
+  "integrations"
+]);
+function hasSegment(path2, vocabulary) {
+  return path2.split("/").filter(Boolean).some((segment) => vocabulary.has(segment.toLowerCase()));
+}
+function score(route, signals) {
+  const because = [];
+  const segments = route.path.split("/").filter(Boolean);
+  let total = 0;
+  const depthPenalty = Math.min(segments.length, 5) * 8;
+  total += 40 - depthPenalty;
+  if (segments.length <= 1) because.push("a top-level destination");
+  if (route.params.length > 0) {
+    total += 10;
+    because.push("a record detail screen");
+  }
+  if (signals.writes && signals.writes > 0) {
+    total += Math.min(signals.writes, 4) * 7;
+    because.push(
+      signals.writes === 1 ? "somewhere a user changes something" : `${signals.writes} actions a user can take here`
+    );
+  }
+  if (signals.fanIn && signals.fanIn > 2) {
+    total += Math.min(signals.fanIn, 8) * 2;
+    because.push("linked to from across the app");
+  }
+  if (hasSegment(route.path, MONEY_OR_ACCESS)) {
+    total += 18;
+    because.push("money or access \u2014 asked about out of proportion to its traffic");
+  }
+  if (hasSegment(route.path, ENTRY_POINT)) {
+    total += 16;
+    because.push("one of the first things a new customer does");
+  }
+  return { score: total, because };
+}
+function tierFor(rank, count) {
+  if (rank <= Math.max(3, Math.ceil(count * 0.1))) return "critical";
+  if (rank <= Math.max(8, Math.ceil(count * 0.3))) return "core";
+  if (rank <= Math.max(16, Math.ceil(count * 0.6))) return "supporting";
+  return "minor";
+}
+function slugFor(path2) {
+  const segments = path2.split("/").filter(Boolean).filter((segment) => !segment.startsWith("["));
+  return segments.length ? segments.join("/") : "overview";
+}
+function titleFor(route) {
+  const segments = route.path.split("/").filter(Boolean).filter((s) => !s.startsWith("["));
+  if (!segments.length) return "Getting around";
+  const words = segments[segments.length - 1].replace(/[-_]/g, " ");
+  const subject = words.charAt(0).toUpperCase() + words.slice(1);
+  if (!route.params.length) return subject;
+  return `Working with ${article(singular2(subject.toLowerCase()))}`;
+}
+function singular2(word) {
+  if (/(sis|ss|us|is)$/.test(word)) return word;
+  if (/(ches|shes|xes|zes)$/.test(word)) return word.slice(0, -2);
+  if (/[^aeiou]ies$/.test(word)) return `${word.slice(0, -3)}y`;
+  if (/s$/.test(word)) return word.slice(0, -1);
+  return word;
+}
+function article(word) {
+  return /^[aeiou]/.test(word) ? `an ${word}` : `a ${word}`;
+}
+function buildArticlePlan(options) {
+  const existing = new Set(options.existingSlugs ?? []);
+  const excluded = [];
+  const scored = [];
+  for (const route of options.routes) {
+    if (route.skipped) {
+      excluded.push({ route: route.path, reason: route.note ?? route.skipped });
+      continue;
+    }
+    scored.push({ route, ...score(route, options.signals?.[route.path] ?? {}) });
+  }
+  scored.sort((a, b) => b.score - a.score || a.route.path.localeCompare(b.route.path));
+  const merged = /* @__PURE__ */ new Map();
+  for (const entry of scored) {
+    const slug = slugFor(entry.route.path);
+    const existingNeed = merged.get(slug);
+    if (!existingNeed) {
+      merged.set(slug, {
+        entry,
+        routes: [entry.route.path],
+        files: [...entry.route.sourceFiles],
+        because: [...entry.because],
+        ...entry.route.title ? { title: entry.route.title } : {}
+      });
+      continue;
+    }
+    if (!existingNeed.title && entry.route.title) existingNeed.title = entry.route.title;
+    existingNeed.routes.push(entry.route.path);
+    for (const file of entry.route.sourceFiles) {
+      if (!existingNeed.files.includes(file)) existingNeed.files.push(file);
+    }
+    for (const reason of entry.because) {
+      if (!existingNeed.because.includes(reason)) existingNeed.because.push(reason);
+    }
+  }
+  let covered = 0;
+  const needs = [...merged.entries()].map(([slug, group], index) => {
+    const rank = index + 1;
+    const claimed = [group.entry.route.path, ...group.routes.slice(1) ?? []].map((path2) => options.documented?.[path2]).find(Boolean);
+    const already = existing.has(slug) || Boolean(claimed);
+    if (already) covered += 1;
+    return {
+      slug,
+      title: group.title ?? titleFor(group.entry.route),
+      route: group.entry.route.path,
+      ...group.routes.length > 1 ? { alsoCovers: group.routes.slice(1) } : {},
+      tier: tierFor(rank, merged.size),
+      rank,
+      sourceRefs: group.files,
+      because: group.because,
+      ...already ? { covered: claimed ?? slug } : {}
+    };
+  });
+  return { needs, excluded, covered };
+}
+
+// adapters/map-cli.ts
+function repositoryFiles(cwd) {
+  return execFileSync("git", ["ls-files"], { cwd, encoding: "utf8", maxBuffer: 64 * 1024 * 1024 }).split("\n").filter(Boolean);
+}
+
+// core/discovery/storyboard.ts
+function shotIdFor(route) {
+  const parts = route.split("/").filter(Boolean).map((segment) => segment.replace(/^\[+\.{0,3}|\]+$/g, ""));
+  return parts.length ? parts.join("-").toLowerCase() : "overview";
+}
+function describe(route, isEntry) {
+  const segments = route.path.split("/").filter(Boolean);
+  const last = segments[segments.length - 1] ?? "";
+  const readable = route.title ?? (last.startsWith("[") ? `a single ${(segments[segments.length - 2] ?? "record").replace(/s$/, "")}` : last.replace(/[-_]/g, " ") || "the home screen");
+  return isEntry ? `The ${readable} screen as someone arrives on it` : `The ${readable} screen, reached from ${segments.slice(0, -1).join("/") || "the top level"}`;
+}
+function kindFor(_route, _isEntry) {
+  return "still";
+}
+function buildStoryboard(options) {
+  const { need } = options;
+  const covered = /* @__PURE__ */ new Set([need.route, ...need.alsoCovers ?? []]);
+  const byPath = new Map(options.routes.map((route) => [route.path, route]));
+  const beneath = options.routes.filter(
+    (route) => !covered.has(route.path) && !route.skipped && [...covered].some((base) => base !== "/" && route.path.startsWith(`${base}/`))
+  );
+  const ordered = [...covered].map((path2) => byPath.get(path2)).filter((route) => Boolean(route) && !route.skipped).sort((a, b) => a.path.length - b.path.length).concat(beneath.sort((a, b) => a.path.length - b.path.length));
+  const limit = options.maxSteps ?? 5;
+  const steps = ordered.slice(0, limit).map((route, index) => ({
+    route: route.path,
+    shotId: shotIdFor(route.path),
+    depicts: describe(route, index === 0),
+    kind: kindFor(route, index === 0),
+    needsExampleFor: route.params
+  }));
+  const dropped = ordered.length - steps.length;
+  return {
+    slug: need.slug,
+    title: need.title,
+    steps,
+    // Named, because an article that quietly stops halfway is worse than one
+    // that says where its edge is.
+    scope: dropped > 0 ? `Covers ${steps.length} screens. ${dropped} deeper screen${dropped === 1 ? "" : "s"} below this belong in their own article rather than making this one longer than anybody reads.` : `Covers ${steps.length} screen${steps.length === 1 ? "" : "s"}, which is the whole of this area.`
+  };
+}
+
+// adapters/capture-bin.ts
+function parseArgs(argv) {
+  const args = {
+    brands: [],
+    only: [],
+    liveClock: false,
+    allowProduction: false
+  };
+  for (let index = 0; index < argv.length; index += 1) {
+    const flag = argv[index];
+    const value = argv[index + 1];
+    if (flag === "--key" && value) args.key = value, index += 1;
+    else if (flag === "--to" && value) args.to = value.replace(/\/+$/, ""), index += 1;
+    else if (flag === "--base-url" && value) args.baseUrl = value.replace(/\/+$/, ""), index += 1;
+    else if (flag === "--brand" && value) args.brands.push(value), index += 1;
+    else if (flag === "--only" && value) args.only.push(value), index += 1;
+    else if (flag === "--session" && value) args.session = value, index += 1;
+    else if (flag === "--rebaseline" && value) args.rebaseline = value, index += 1;
+    else if (flag === "--cassette" && value) args.cassette = value, index += 1;
+    else if (flag === "--app-command" && value) args.appCommand = value, index += 1;
+    else if (flag === "--seed-command" && value) args.seedCommand = value, index += 1;
+    else if (flag === "--app-env" && value) args.appEnv = value, index += 1;
+    else if (flag === "--replay-port" && value) args.replayPort = Number(value), index += 1;
+    else if (flag === "--out" && value) args.out = value, index += 1;
+    else if (flag === "--repo" && value) args.repo = value, index += 1;
+    else if (flag === "--live-clock") args.liveClock = true;
+    else if (flag === "--allow-production") args.allowProduction = true;
+    else if (flag === "--rebaseline" || flag === "--force") {
+      return '--rebaseline needs a reason: `--rebaseline "new brand colours shipped"`. Replacing every stored frame moves every checksum at once, and a re-baseline nobody wrote down is indistinguishable from the product changing.';
+    }
+  }
+  if (args.out) {
+    args.key ??= "";
+    args.to ??= "";
+    if (!args.baseUrl) return "Missing --base-url. That is where your product is running.";
+    return args;
+  }
+  if (!args.key) return "Missing --key, or --out <dir> to keep the frames here instead.";
+  if (!args.to) return "Missing --to. That is the address of your help desk, or use --out <dir>.";
+  return args;
+}
+function shotsFromRepo(repo, previous) {
+  const files = repositoryFiles(repo);
+  const routes = readNextAppRouter(files, detectRouterRoot(files)).routes;
+  return buildArticlePlan({ routes }).needs.flatMap((need) => buildStoryboard({ need, routes }).steps).filter((step) => step.kind === "still").map((step) => ({
+    id: step.shotId,
+    route: step.route,
+    depicts: step.depicts,
+    // Carried so a second run can recognise a frame it already has, which is
+    // what makes "nothing changed" a sentence this can say offline too.
+    ...previous.has(step.shotId) ? { sha256: previous.get(step.shotId) } : {}
+  }));
+}
+async function previousFrames(out) {
+  try {
+    const manifest = JSON.parse(await readFile(path.join(out, "manifest.json"), "utf8"));
+    return new Map((manifest.frames ?? []).map((frame) => [frame.id, frame.sha256]));
+  } catch {
+    return /* @__PURE__ */ new Map();
+  }
+}
+async function main(argv) {
+  if (argv[0] === "sign-in") return signIn(argv.slice(1));
+  const parsed = parseArgs(argv);
+  if (typeof parsed === "string") {
+    console.error(parsed);
+    return 2;
+  }
+  const headers = { authorization: `Bearer ${parsed.key}` };
+  const local = parsed.out;
+  const frames = [];
+  let orders;
+  if (local) {
+    const repo = parsed.repo ?? process.cwd();
+    await mkdir(local, { recursive: true });
+    try {
+      orders = { baseUrl: null, shots: shotsFromRepo(repo, await previousFrames(local)) };
+    } catch (error) {
+      console.error(
+        `Could not read a plan from ${repo}: ${error.message}
+Run this from your repository, or pass --repo <dir>.`
+      );
+      return 1;
+    }
+    console.log(`Read ${orders.shots.length} screen(s) from ${repo}. Frames will be written to ${local}.
+`);
+  } else {
+    const listed = await fetch(`${parsed.to}/api/helpdesk/frames`, { headers });
+    if (!listed.ok) {
+      console.error(`The help desk refused the key (${listed.status}).`);
+      return 1;
+    }
+    orders = await listed.json();
+    if (!orders.capture) {
+      console.error(
+        `This workspace has approved no capture subject, so the help desk will refuse every frame.
+${orders.captureRefused ?? ""}
+Approve one on the plan page, then run this again.`
+      );
+      return 1;
+    }
+  }
+  const baseUrl = parsed.cassette || parsed.seedCommand ? parsed.baseUrl ?? "http://127.0.0.1:3000" : parsed.baseUrl ?? orders.baseUrl;
+  if (!baseUrl) {
+    console.error("No product address. Pass --base-url, or set one on the help desk's plan page.");
+    return 2;
+  }
+  const shots = parsed.only.length ? orders.shots.filter((shot) => parsed.only.includes(shot.id)) : orders.shots;
+  if (!shots.length) {
+    console.log("Nothing to photograph.");
+    return 0;
+  }
+  let stage;
+  let seeded;
+  if (parsed.seedCommand) {
+    try {
+      seeded = await stageSeeded({
+        appUrl: baseUrl,
+        seedCommand: parsed.seedCommand,
+        ...parsed.appCommand ? { appCommand: parsed.appCommand } : {},
+        sessionOut: parsed.session ?? path.join(process.cwd(), "helpdesk-demo-session.json"),
+        onLog: (line) => console.log(line)
+      });
+      if (seeded.sessionPath) parsed.session = seeded.sessionPath;
+      else delete parsed.session;
+      console.log("");
+    } catch (error) {
+      console.error(String(error.message));
+      return 1;
+    }
+  }
+  if (parsed.cassette) {
+    try {
+      stage = await stageAgainstRecording({
+        cassette: parseCassette(await readFile(parsed.cassette, "utf8")),
+        appUrl: baseUrl,
+        ...parsed.appCommand ? { appCommand: parsed.appCommand } : {},
+        ...parsed.appEnv ? { appEnv: parsed.appEnv } : {},
+        ...parsed.replayPort ? { replayPort: parsed.replayPort } : {},
+        onLog: (line) => console.log(line)
+      });
+      console.log("");
+    } catch (error) {
+      console.error(String(error.message));
+      return 1;
+    }
+  }
+  const browser = await playwrightBrowser({
+    ...parsed.session ? { sessionPath: parsed.session } : {},
+    ...parsed.liveClock ? { liveClock: true } : {}
+  });
+  const checks = preflight({
+    baseUrl,
+    browser: await browser.build?.().catch(() => void 0),
+    clockPinned: !parsed.liveClock,
+    locale: "en-GB",
+    timezone: "UTC",
+    session: Boolean(parsed.session),
+    ...stage ? { replaying: parsed.cassette } : {},
+    ...parsed.allowProduction ? { productionGranted: true } : {},
+    ...parsed.rebaseline ? { rebaselineReason: parsed.rebaseline } : {}
+  });
+  console.log(checks.lines.join("\n"));
+  console.log("");
+  if (!checks.ok) {
+    await browser.close();
+    await stage?.close();
+    await seeded?.close();
+    return 2;
+  }
+  if (stage) {
+    const found = coverage(
+      shots.map((shot) => shot.route),
+      stage.cassette
+    );
+    console.log(`${coverageReport(found, shots.length).join("\n")}
+`);
+  }
+  console.log(
+    stage ? `Photographing ${shots.length} screen(s) of ${baseUrl}, served from ${parsed.cassette}.
+` : `Photographing ${shots.length} screen(s) of ${baseUrl}.
+`
+  );
+  const runId = local ? void 0 : await openRun(parsed.to, headers, shots.length);
+  try {
+    const report = await runCapture({
+      baseUrl,
+      shots,
+      browser,
+      ...orders.capture ? {
+        clearance: {
+          subject: orders.capture.subject,
+          routes: orders.capture.routes,
+          regions: orders.capture.regions,
+          // A cover is where to put a rectangle; an approval is where not
+          // to. Both are read off the clearance the help desk holds, and
+          // the second is checked again against that same record when the
+          // frame arrives, so this run cannot approve anything by saying so.
+          covers: (orders.capture.surfaces ?? []).filter((surface) => surface.treatment?.treat === "cover").map((surface) => surface.where),
+          approved: (orders.capture.surfaces ?? []).filter((surface) => surface.treatment?.treat === "approve").map((surface) => surface.where),
+          coverUnnamed: orders.capture.coverUnnamed === true,
+          expectedBrands: orders.capture.expectedBrands ?? []
+        }
+      } : {},
+      brands: parsed.brands,
+      force: Boolean(parsed.rebaseline),
+      /*
+       * Said rather than inferred. A run with no saved session is signed out,
+       * which is a fact about the evidence worth recording; a run with one is
+       * signed in as somebody nobody has told us about, which is a different
+       * fact and not a defect. Neither is an empty string.
+       */
+      session: parsed.session ? "saved-session" : "signed-out",
+      role: parsed.session ? unknownRole() : noRole("this run was signed out"),
+      onProgress: (outcome, index, total) => {
+        const mark = { captured: "\u2713", unchanged: "=", skipped: "\u2013", refused: "\u2717", failed: "!" }[outcome.status];
+        console.log(`${mark} ${index}/${total} ${outcome.route}${outcome.reason ? ` \u2014 ${outcome.reason}` : ""}`);
+        if (runId) {
+          void tellHelpDesk(parsed.to, headers, {
+            action: "progress",
+            jobId: runId,
+            item: outcome.route,
+            status: outcome.status === "captured" || outcome.status === "unchanged" ? "ok" : outcome.status === "failed" ? "failed" : "skipped",
+            ...outcome.reason ? { note: outcome.reason } : {}
+          });
+        }
+      },
+      async send(frame) {
+        if (local) {
+          const file = `${frame.shot.id}.png`;
+          await writeFile(path.join(local, file), frame.image);
+          frames.push({
+            id: frame.shot.id,
+            route: frame.shot.route,
+            depicts: frame.shot.depicts,
+            file,
+            sha256: frame.sha256,
+            settled: frame.settled,
+            ...frame.browser ? { browser: frame.browser } : {},
+            ...frame.width ? { width: frame.width } : {},
+            ...frame.height ? { height: frame.height } : {}
+          });
+          return { ok: true };
+        }
+        const form = new FormData();
+        form.set(
+          "meta",
+          JSON.stringify({
+            shotId: frame.shot.id,
+            route: frame.shot.route,
+            depicts: frame.shot.depicts,
+            pageText: frame.pageText,
+            capturedFrom: frame.capturedFrom,
+            settled: frame.settled,
+            // What this run read off the screen. Absent is a refusal at the
+            // other end rather than a default, which is the point of sending it.
+            ...frame.report ? { report: frame.report } : {},
+            ...frame.browser ? { browser: frame.browser } : {},
+            ...frame.width ? { width: frame.width } : {},
+            ...frame.height ? { height: frame.height } : {}
+          })
+        );
+        form.set("image", new Blob([frame.image], { type: "image/png" }), `${frame.shot.id}.png`);
+        const response = await fetch(`${parsed.to}/api/helpdesk/frames`, {
+          method: "POST",
+          headers,
+          body: form
+        });
+        if (response.ok) return { ok: true };
+        const body = await response.json().catch(() => ({}));
+        return { ok: false, error: body.error ?? `the help desk answered ${response.status}` };
+      }
+    });
+    console.log(
+      `
+${report.captured} photographed, ${report.unchanged} unchanged, ${report.skipped} skipped, ${report.refused} refused, ${report.failed} failed.`
+    );
+    if (local) {
+      const kept = new Map(frames.map((frame) => [frame.id, frame]));
+      for (const shot of shots) {
+        if (kept.has(shot.id) || !shot.sha256) continue;
+        const unchanged = report.outcomes.find((outcome) => outcome.shotId === shot.id);
+        if (unchanged?.status !== "unchanged") continue;
+        kept.set(shot.id, {
+          id: shot.id,
+          route: shot.route,
+          depicts: shot.depicts,
+          file: `${shot.id}.png`,
+          sha256: shot.sha256,
+          settled: unchanged.settled !== false
+        });
+      }
+      await writeFile(
+        path.join(local, "manifest.json"),
+        `${JSON.stringify(
+          {
+            schema: "olomon.capture-manifest/1",
+            capturedFrom: baseUrl,
+            capturedAt: (/* @__PURE__ */ new Date()).toISOString(),
+            ...parsed.cassette ? { recording: parsed.cassette } : {},
+            frames: [...kept.values()].sort((a, b) => a.id.localeCompare(b.id)),
+            survey: report.survey
+          },
+          null,
+          2
+        )}
+`,
+        "utf8"
+      );
+      console.log(`
+Written to ${local}: ${kept.size} frame(s) and manifest.json.`);
+    }
+    if (report.survey.length) {
+      const survey = captureReport(report.survey);
+      console.log(`
+${surveyLine(report.survey)}
+`);
+      if (survey.needData) {
+        console.log("What needs attention:\n");
+        console.log(survey.lines.slice(2).join("\n"));
+      }
+      const unstable = report.outcomes.filter((outcome) => outcome.settled === false);
+      if (unstable.length) {
+        console.log(
+          `
+${unstable.length} screen(s) never stopped moving: ${unstable.map((o) => o.route).join(", ")}.
+Their frames were kept, but they will hash differently every run, so nothing can tell you
+whether they changed. Usually a spinner that never resolves or a looping animation.`
+        );
+      }
+    }
+    const gated = report.outcomes.filter((outcome) => outcome.needsAccount);
+    if (gated.length) {
+      console.log(
+        stage ? "\nSome screens still showed a sign-in. A recording answers the backend, but it cannot\ngive the product a session \u2014 record the sign-in itself, or save one against the replayed\nproduct and pass it with --session." : parsed.session ? "\nSome screens still showed a sign-in. The saved session may have expired \u2014 run `sign-in` again." : `
+Some screens are behind your sign-in. To photograph them, save a session against a
+DEMO tenant and pass it back:
+
+  ${helpdeskCommand("helpdesk-capture", ["sign-in", `--base-url ${baseUrl}`, "--session ./demo-session.json"])}
+  ${helpdeskCommand("helpdesk-capture", [local ? `--out ${local} --base-url ${baseUrl}` : `--key <your key> --to ${parsed.to}`, "--session ./demo-session.json"])}
+
+Never a real customer's account: a help article shows the typical state of a screen,
+not somebody's data. The session file stays on this machine and is sent nowhere.`
+      );
+    }
+    console.log(
+      `
+${attestation({
+        captured: report.captured,
+        unchanged: report.unchanged,
+        refused: report.refused,
+        baseUrl,
+        ...report.browser ? { browser: report.browser } : {},
+        clockPinned: !parsed.liveClock,
+        ...stage ? { replaying: parsed.cassette } : {}
+      })}`
+    );
+    if (stage?.replay.misses.length) {
+      console.log(`
+${gapReport(gapsFrom([...stage.replay.misses])).join("\n")}`);
+    }
+    if (runId) {
+      await tellHelpDesk(parsed.to, headers, {
+        action: "finish",
+        jobId: runId,
+        ...report.survey.length ? { survey: report.survey } : {}
+      });
+    }
+    return report.failed ? 1 : 0;
+  } catch (error) {
+    if (runId) {
+      await tellHelpDesk(parsed.to, headers, {
+        action: "finish",
+        jobId: runId,
+        error: error instanceof Error ? error.message : String(error)
+      });
+    }
+    throw error;
+  } finally {
+    await browser.close();
+    await stage?.close();
+    await seeded?.close();
+  }
+}
+async function openRun(to, headers, total) {
+  try {
+    const response = await fetch(`${to}/api/helpdesk/captures`, {
+      method: "POST",
+      headers: { ...headers, "content-type": "application/json" },
+      body: JSON.stringify({ action: "start", total })
+    });
+    if (!response.ok) return void 0;
+    const body = await response.json();
+    return body.jobId;
+  } catch {
+    return void 0;
+  }
+}
+async function tellHelpDesk(to, headers, body) {
+  await fetch(`${to}/api/helpdesk/captures`, {
+    method: "POST",
+    headers: { ...headers, "content-type": "application/json" },
+    body: JSON.stringify(body)
+  }).catch(() => void 0);
+}
+async function signIn(argv) {
+  let baseUrl = "";
+  let sessionPath = "./demo-session.json";
+  for (let index = 0; index < argv.length; index += 1) {
+    const flag = argv[index];
+    const value = argv[index + 1];
+    if (flag === "--base-url" && value) baseUrl = value.replace(/\/+$/, ""), index += 1;
+    else if (flag === "--session" && value) sessionPath = value, index += 1;
+  }
+  if (!baseUrl) {
+    console.error("Missing --base-url. That is where your product is deployed.");
+    return 2;
+  }
+  console.log(
+    `Opening ${baseUrl}. Sign in as your DEMO tenant \u2014 never a real customer.
+This window is yours: use SSO, a one-time code, whatever you normally do.
+The session will be saved to ${sessionPath} and sent nowhere.
+`
+  );
+  const outcome = await captureSignIn({ baseUrl, sessionPath });
+  if (!outcome.ok) {
+    console.error(outcome.reason ?? "Could not save a session.");
+    return 1;
+  }
+  console.log(`
+Saved ${sessionPath}. Pass it to a capture run with --session ${sessionPath}.`);
+  return 0;
+}
+if (import.meta.url === `file://${process.argv[1]}`) {
+  main(process.argv.slice(2)).then(
+    (code) => process.exit(code),
+    (error) => {
+      console.error(error instanceof Error ? error.message : String(error));
+      process.exit(1);
+    }
+  );
+}
+export {
+  main
+};