@olomonhelpdesk2/helpdesk 0.1.4 → 0.1.9

package/helpdesk-capture.mjs

@@ -1,102 +1,4 @@
 #!/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",
-  /**
-   * And in this locale and this zone, set on the browser rather than inherited
-   * from whoever runs it, so a date on a screen reads the same from any machine.
-   *
-   * American English, because the products this documents are read in it: a
-   * frame showing "15/01/2026" beside an article written for an American
-   * reader is a screenshot of a product nobody uses.
-   */
-  locale: "en-US",
-  timezone: "UTC",
-  /**
-   * 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(path3) {
-  const segments = path3.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/capture/examples.ts
 var CI_EXAMPLES_OUT_ENV = "HELPDESK_EXAMPLES_OUT";
 var EXAMPLES_SCHEMA = "helpdesk.examples/1";
@@ -149,6 +51,18 @@ function unusablePath(path3) {
   if (/\[|\]/.test(path3)) return "the path still holds a dynamic segment rather than a record";
   return void 0;
 }
+var PLAIN_QUERY = /^[\w.~%:+,-]+=[\w.~%:+,-]*(?:&[\w.~%:+,-]+=[\w.~%:+,-]*)*$/;
+function queryFor(route, named) {
+  const mark = named.indexOf("?");
+  const path3 = mark < 0 ? named : named.slice(0, mark);
+  const query = mark < 0 ? "" : named.slice(mark + 1);
+  if (!query) return { because: "it has no dynamic segment, so the only thing to name for it is the query it opens with" };
+  if (path3 !== route) return { because: `${named} is not ${route} with a query` };
+  const unusable = unusablePath(route);
+  if (unusable) return { because: unusable };
+  if (named.length > MAX_PATH || !PLAIN_QUERY.test(query)) return { because: "the query is not a plain list of names and values" };
+  return { visit: named };
+}
 function readExampleRoutes(raw) {
   if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
     return { ok: false, because: "the file is not a JSON object" };
@@ -166,14 +80,20 @@ function readExampleRoutes(raw) {
   const paths = /* @__PURE__ */ new Map();
   const refused = [];
   for (const [route, value] of entries) {
-    if (!route.startsWith("/") || dynamicSegments(route).length === 0) {
-      refused.push({ route, because: "it is not a route with a dynamic segment" });
+    if (!route.startsWith("/")) {
+      refused.push({ route, because: "it is not a route" });
       continue;
     }
     if (typeof value !== "string") {
       refused.push({ route, because: "its example is not a path" });
       continue;
     }
+    if (dynamicSegments(route).length === 0) {
+      const opened = queryFor(route, value.trim());
+      if ("because" in opened) refused.push({ route, because: opened.because });
+      else paths.set(route, opened.visit);
+      continue;
+    }
     const path3 = value.trim();
     const unusable = unusablePath(path3);
     if (unusable) {
@@ -190,8 +110,8 @@ function readExampleRoutes(raw) {
 }
 function resolveVisit(route, examples) {
   const needs = dynamicSegments(route);
-  if (needs.length === 0) return { visit: route };
   const path3 = examples.paths.get(route);
+  if (needs.length === 0) return { visit: path3 ?? route };
   return path3 ? { visit: path3 } : { needs };
 }
 function describeMissingExample(route, needs) {
@@ -199,6 +119,108 @@ function describeMissingExample(route, needs) {
   return `the seed command named no record for ${named} on ${route}, so there is nothing real to open. Add one to the file it writes at ${CI_EXAMPLES_OUT_ENV}`;
 }
 
+// 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",
+  /**
+   * And in this locale and this zone, set on the browser rather than inherited
+   * from whoever runs it, so a date on a screen reads the same from any machine.
+   *
+   * American English, because the products this documents are read in it: a
+   * frame showing "15/01/2026" beside an article written for an American
+   * reader is a screenshot of a product nobody uses.
+   */
+  locale: "en-US",
+  timezone: "UTC",
+  /**
+   * 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": {
+      if ((!outcome.missingEndpoint || outcome.missingEndpoint === outcome.route) && !outcome.route.includes("[")) {
+        return `${outcome.route} answered Not Found here, and its address names no record to create. If it is behind a feature flag, turn the flag on where the run happens. If it opens only from a record, as a form started from one does, name the address it opens at in the file the seed command writes at ${CI_EXAMPLES_OUT_ENV}. If it is gone, it will drop out of the plan.`;
+      }
+      const asked = outcome.missingEndpoint ?? outcome.route;
+      const noun = subjectOf(fillsPattern(outcome.route, asked) ? outcome.route : asked);
+      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(path3) {
+  const segments = path3.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 /^\[{1,2}[^\]]+\]{1,2}$/.test(segment) || /^\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 = []) {
@@ -234,7 +256,7 @@ var EMPTY_STATE_PHRASES = [
   /\bno results\b/i,
   /\bthis (list|table) is empty\b/i
 ];
-function classifyRoute(observation) {
+function classifyRoute(observation, options = {}) {
   const text2 = observation.text.trim();
   const unrecorded = observation.failedRequests?.find((request) => request.status === RECORDING_MISS_STATUS);
   if (unrecorded) {
@@ -244,21 +266,26 @@ function classifyRoute(observation) {
   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 };
+  let followed;
   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 (!canonical && options.follow?.(observation.landedOn)) {
+      followed = { landed: observation.landedOn };
+    } else {
+      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" };
+    return { route: observation.route, result: "empty-state", ...followed };
   }
-  if (text2.length < THIN_TEXT_CHARS) return { route: observation.route, result: "thin" };
-  return { route: observation.route, result: "ok" };
+  if (text2.length < THIN_TEXT_CHARS) return { route: observation.route, result: "thin", ...followed };
+  return { route: observation.route, result: "ok", ...followed };
 }
 function crashedBecause(observation, text2) {
   const uncaught = observation.errors?.[0];
@@ -331,40 +358,40 @@ function preflight(facts) {
       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`
+      detail: `${facts.baseUrl}, reading from ${facts.replaying}. 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.`
+      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. 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`
+      detail: facts.session ? `${facts.baseUrl}, signed in${live ? ", 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"
+    detail: facts.browser ? `${facts.browser}, recorded on every frame` : "not identified. 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"
+    detail: facts.clockPinned ? "pinned, with randomness and generated ids seeded from it" : "running live (--live-clock). 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`
+    detail: `${facts.locale}, ${facts.timezone}, set explicitly rather than inherited from this machine`
   });
   checks.push({
     name: "isolation",
@@ -389,7 +416,7 @@ function preflight(facts) {
       name: "rebaseline",
       ok: true,
       blocking: false,
-      detail: `replacing every stored frame \u2014 "${facts.rebaselineReason}"`
+      detail: `replacing every stored frame: "${facts.rebaselineReason}"`
     });
   }
   const blocked = checks.filter((check) => check.blocking && !check.ok);
@@ -416,6 +443,101 @@ function attestation(run) {
   ].filter(Boolean).join("\n");
 }
 
+// core/capture/run-record.ts
+function runIdentityFromEnv(env) {
+  if (env["GITHUB_ACTIONS"] !== "true" || !env["GITHUB_RUN_NUMBER"]) return void 0;
+  const said = { number: env["GITHUB_RUN_NUMBER"] };
+  for (const [key, name] of [
+    ["id", "GITHUB_RUN_ID"],
+    ["attempt", "GITHUB_RUN_ATTEMPT"],
+    ["repository", "GITHUB_REPOSITORY"],
+    ["server", "GITHUB_SERVER_URL"]
+  ]) {
+    const value = env[name];
+    if (value) said[key] = value;
+  }
+  return said;
+}
+
+// core/capture/run-verdict.ts
+function runCounts(run) {
+  return `${run.captured} photographed, ${run.unchanged} unchanged, ${run.skipped} skipped, ${run.refused} refused, ${run.failed} failed`;
+}
+function runVerdict(run) {
+  const delivered = run.captured + run.unchanged;
+  const missed = run.skipped + run.refused + run.failed;
+  const counts = runCounts(run);
+  if (run.screens > 0 && delivered === 0) {
+    return {
+      exit: 1,
+      annotation: `::error title=No screenshots were delivered::None of the ${run.screens} screens was photographed (${counts}). The step log says why for each one.`,
+      sentence: `Nothing was delivered, so this run fails rather than passing with no screenshots: ${counts}.`
+    };
+  }
+  if (missed > 0) {
+    return {
+      exit: run.failed > 0 ? 1 : 0,
+      annotation: `::warning title=${missed} of ${run.screens} screens were not photographed::${counts}. The step log says why for each one.`
+    };
+  }
+  return { exit: 0 };
+}
+
+// core/capture/unclassified.ts
+var SEPARATOR = " > ";
+function commonRegion(selectors) {
+  const parts = selectors.map((selector) => selector.split(SEPARATOR));
+  const first = parts[0] ?? [];
+  let shared = 0;
+  while (shared < first.length && parts.every((steps) => steps[shared] === first[shared])) shared += 1;
+  return shared >= 3 ? first.slice(0, shared).join(SEPARATOR) : "";
+}
+function groupUnclassified(refused) {
+  const enough = Math.max(2, Math.ceil(new Set(refused.map((screen) => screen.route)).size / 2));
+  const where = /* @__PURE__ */ new Map();
+  for (const screen of refused) {
+    for (const value of screen.values) {
+      const seen = where.get(value.at) ?? { screens: /* @__PURE__ */ new Set(), lengths: /* @__PURE__ */ new Set() };
+      seen.screens.add(screen.route);
+      seen.lengths.add(value.length);
+      where.set(value.at, seen);
+    }
+  }
+  const shared = [...where.entries()].filter(([, seen]) => seen.screens.size >= enough).map(([at, seen]) => ({ at, screens: [...seen.screens].sort(), lengths: [...seen.lengths].sort((a, b) => a - b) })).sort((a, b) => b.screens.length - a.screens.length || a.at.localeCompare(b.at));
+  const isShared = new Set(shared.map((element) => element.at));
+  const screens = [];
+  const onlyShared = [];
+  for (const screen of refused) {
+    const rest = screen.values.filter((value) => !isShared.has(value.at));
+    if (rest.length) {
+      screens.push({ route: screen.route, count: rest.length, within: commonRegion(rest.map((value) => value.at)) });
+    } else if (screen.values.length) {
+      onlyShared.push(screen.route);
+    }
+  }
+  return { shared, screens, onlyShared: [...new Set(onlyShared)].sort() };
+}
+function describeLengths(lengths) {
+  const low = lengths[0] ?? 0;
+  const high = lengths[lengths.length - 1] ?? low;
+  return low === high ? `${low} character${low === 1 ? "" : "s"}` : `${low} to ${high} characters`;
+}
+function describeShared(element, summary) {
+  const unblocks = summary.onlyShared.filter((route) => element.screens.includes(route)).length;
+  return `One element sits outside every part of the page the clearance names, in the same place on ${element.screens.length} screens: ${element.at} (${describeLengths(element.lengths)}). Something in the same place on every screen is part of the app's own layout, such as a feedback or help button, so it is classified once. Say what it is on Setup` + (unblocks ? `, and the ${unblocks} screen${unblocks === 1 ? "" : "s"} held back only by it can be photographed.` : ".");
+}
+function describeRemainder(screen) {
+  return `${screen.route}: ${screen.count} value${screen.count === 1 ? "" : "s"} outside every part of the page the clearance names` + (screen.within ? `, all inside ${screen.within}.` : ", spread across the page.");
+}
+function unclassifiedLines(summary) {
+  if (!summary.shared.length && !summary.screens.length) return [];
+  return [
+    "Not photographed until somebody says what is there:",
+    ...summary.shared.map((element) => `  ${describeShared(element, summary)}`),
+    ...summary.screens.map((screen) => `  ${describeRemainder(screen)}`)
+  ];
+}
+
 // adapters/capture-cli.ts
 import { createRequire } from "node:module";
 import path from "node:path";
@@ -495,6 +617,8 @@ var ALREADY_SAFE = [
 function alreadySafe(kind, value) {
   return ALREADY_SAFE.some((entry) => entry.kind === kind && entry.regex.test(value));
 }
+var BIRTH_LABEL = /(?:\bdate[\s_-]*of[\s_-]*birth|\bbirth[\s_-]*(?:date|day)|\bdob\b|\bd\.o\.b\b|\bborn\b)/i;
+var LABEL_REACH = 48;
 var PATTERNS = [
   {
     kind: "email",
@@ -544,13 +668,14 @@ var PATTERNS = [
   {
     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"
+    because: "a date labeled as a birth date, which identifies somebody",
+    replace: () => "1970-01-01",
+    labelled: BIRTH_LABEL
   },
   {
     kind: "passport",
     regex: /\b[A-Z]{1,2}\d{6,9}\b/g,
-    because: "the shape of a passport or licence number",
+    because: "the shape of a passport or license number",
     replace: (match) => `${match.slice(0, 1)}${"0".repeat(match.length - 1)}`
   },
   {
@@ -566,8 +691,13 @@ function scrub(text2, options = {}) {
   let output = text2;
   for (const pattern of PATTERNS) {
     const seen = /* @__PURE__ */ new Map();
-    output = output.replace(pattern.regex, (match) => {
+    output = output.replace(pattern.regex, (...args) => {
+      const match = args[0];
+      const named = typeof args[args.length - 1] === "object";
+      const offset = args[args.length - (named ? 3 : 2)];
+      const whole = args[args.length - (named ? 2 : 1)];
       if (alreadySafe(pattern.kind, match)) return match;
+      if (pattern.labelled && !pattern.labelled.test(whole.slice(Math.max(0, offset - LABEL_REACH), offset))) return match;
       const already = seen.get(match);
       if (already) return already;
       const replacement = pattern.replace(match, seen.size);
@@ -584,7 +714,7 @@ function scrub(text2, options = {}) {
         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"
+        because: "a real institution in a published screenshot implies a partnership: a legal review item, not a design nit"
       });
     }
   }
@@ -612,10 +742,24 @@ function gateFrame(pageText, options = {}) {
   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.`
+    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, 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. Point the capture at a demo tenant, or fix the seed that produced this.`
   };
 }
 
+// core/capture/sign-in.ts
+var IDENTIFIER_HINT = /\b(username|email)\b/;
+var IDENTIFIER_NAME = /user|login|e-?mail/;
+function identifies(field) {
+  if (field.type === "email") return true;
+  if (IDENTIFIER_HINT.test(field.autocomplete)) return true;
+  return (field.type === "text" || field.type === "") && IDENTIFIER_NAME.test(field.name);
+}
+function looksLikeSignIn(fields) {
+  const secrets = fields.filter((field) => field.type === "password");
+  if (secrets.some((field) => field.autocomplete.split(/\s+/).includes("current-password"))) return true;
+  return secrets.some((secret) => fields.some((field) => field.form === secret.form && identifies(field)));
+}
+
 // core/capture/publication/pixels.ts
 import { deflateSync, inflateSync } from "node:zlib";
 var MediaRefused = class extends Error {
@@ -649,7 +793,7 @@ function decodePng(buffer) {
     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`);
+    throw new MediaRefused(`only 8-bit RGB and RGBA PNGs are supported here, not color type ${colourType} at ${bitDepth} bits`);
   }
   const channels = colourType === 6 ? 4 : 3;
   const raw = inflateSync(Buffer.concat(data));
@@ -938,11 +1082,22 @@ var LIMITS = {
   fields: 24,
   notices: 20,
   warnings: 12,
+  disabled: 24,
+  empty: 12,
+  gatedBy: 8,
   choices: 12,
   /** Longer than this is a paragraph of copy, not a label. */
   label: 120,
   sentence: 300
 };
+var EMPTY_STATE = /^(?:no\s+(?!(?:longer|need|problem|worries|matter|one|way|thanks)\b)[a-z]|nothing\b|none\s|you (?:have|haven't|don't have|do not have)\s+(?:no|any|not)\b|there(?:'s| (?:are|is|were))\s+(?:no|nothing)\b|there aren't any\b|(?:you|we) haven't\b.*\byet\b)/i;
+function isEmptyState(text2) {
+  const sentence = text2.replace(/[\u2018\u2019]/g, "'").replace(/\s+/g, " ").trim();
+  if (!sentence || sentence.length > LIMITS.sentence || sentence.includes("?")) return false;
+  if (/\b(?:until|unless)\b/i.test(sentence)) return false;
+  if (sentence.split(" ").length < 2) return false;
+  return EMPTY_STATE.test(sentence);
+}
 
 // core/discovery/aria-facts.ts
 var LANDMARK = {
@@ -993,6 +1148,12 @@ function readAriaFactRecords(snapshot, options = {}) {
     const state = controlState(node);
     if (node.role === "heading") {
       add("heading", node.name || node.text, node);
+      if (isEmptyState(node.name || node.text)) add("empty", node.name || node.text, node);
+      continue;
+    }
+    if (node.role === "paragraph" || node.role === "text") {
+      const said = node.text || node.name;
+      if (isEmptyState(said)) add("empty", trim(said, LIMITS.sentence), node);
       continue;
     }
     if (node.role === "link") {
@@ -1016,7 +1177,9 @@ function readAriaFactRecords(snapshot, options = {}) {
       continue;
     }
     if (NOTICE.has(node.role)) {
-      add("notice", trim(node.text || node.name, LIMITS.sentence), node);
+      const said = trim(node.text || node.name, LIMITS.sentence);
+      add("notice", said, node);
+      if (isEmptyState(said)) add("empty", said, node);
     }
   }
   return facts;
@@ -1053,7 +1216,7 @@ function parse(snapshot) {
       if (node.name || node.text) parent.choices.push(node.name || node.text);
       continue;
     }
-    if (role !== "text") out.push(node);
+    out.push(node);
     stack.push({ depth: depth2, node });
   }
   return out;
@@ -1136,6 +1299,7 @@ function readRenderedFactRecords(html, options = {}) {
     const label = accessibleName(element);
     if (HEADING.test(tag) || role === "heading") {
       add("heading", label, landmark);
+      if (isEmptyState(label)) add("empty", label, landmark);
       continue;
     }
     if (tag === "button" || PRESSABLE.has(role) || submitLike(element)) {
@@ -1161,11 +1325,20 @@ function readRenderedFactRecords(html, options = {}) {
       continue;
     }
     if (ANNOUNCEMENT.has(role) || attributes["aria-live"]) {
-      add("notice", trim2(text(inner), LIMITS.sentence), landmark);
+      const said = trim2(text(inner), LIMITS.sentence);
+      add("notice", said, landmark);
+      if (isEmptyState(said)) add("empty", said, landmark);
+      continue;
+    }
+    if (TEXT_HOLDER.has(tag) && !BLOCK_INSIDE.test(inner)) {
+      const said = trim2(text(inner).replace(/\s+([.,;:!])/g, "$1"), LIMITS.sentence);
+      if (isEmptyState(said)) add("empty", said, landmark);
     }
   }
   return facts;
 }
+var TEXT_HOLDER = /* @__PURE__ */ new Set(["p", "span", "small", "td", "li", "div"]);
+var BLOCK_INSIDE = /<(?!\/?(?:strong|em|b|i|a|code|br|span|small)\b)[a-z]/i;
 var OVERLAY_ROLE = {
   dialog: "dialog",
   alertdialog: "dialog",
@@ -1517,7 +1690,7 @@ function requireDeployment(producer, input) {
   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").`
+      `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 (a deployment id, a build id, a release SHA) or unknownDeployment("why not").`
     );
   }
 }
@@ -1566,7 +1739,7 @@ async function captureOne(options, shot, build) {
           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"
+          reason: "a signed-out visitor is shown a sign-in here, so this screen needs a demo tenant, never a real account"
         },
         observed: { route: shot.route, result: "bounced" }
       };
@@ -1594,7 +1767,9 @@ async function captureOne(options, shot, build) {
       };
     }
     const seen = await page.observe?.() ?? {};
-    const observed = { ...classifyRoute({ ...seen, route: visit, text: pageText }), route: shot.route };
+    const origin = new URL(options.baseUrl).origin;
+    const follow = (landed) => seen.landedOrigin === origin && options.shots.some((other) => fillsPattern(other.route, landed.split(/[?#]/)[0] ?? landed));
+    const observed = { ...classifyRoute({ ...seen, route: visit, text: pageText }, { follow }), route: shot.route };
     if (!isPublishable(observed.result)) {
       return {
         outcome: {
@@ -1634,7 +1809,8 @@ async function captureOne(options, shot, build) {
             // 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`
+            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`,
+            unaccounted: unaccounted.map((value) => ({ at: value.at, length: value.length }))
           },
           observed,
           ...evidence ? { seen: evidence } : {}
@@ -1750,8 +1926,8 @@ async function captureOne(options, shot, build) {
         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"
+        ...frame.settled ? observed.landed ? { reason: `followed its redirect to ${observed.landed}` } : {} : {
+          reason: "photographed, but this screen never stopped moving. Its hash will differ every run, so drift on it means nothing"
         }
       } : {
         shotId: shot.id,
@@ -1913,11 +2089,21 @@ async function playwrightBrowser(options = {}) {
           return page.locator("body").ariaSnapshot().catch(() => "");
         },
         async isSignIn() {
-          return await page.locator('input[type="password"]').count() > 0;
+          const fields = await page.evaluate(() => {
+            const forms = Array.from(document.forms);
+            return Array.from(document.querySelectorAll("input")).map((input) => ({
+              type: (input.getAttribute("type") ?? "text").toLowerCase(),
+              autocomplete: (input.getAttribute("autocomplete") ?? "").toLowerCase(),
+              name: `${input.name} ${input.id}`.toLowerCase(),
+              form: input.form ? forms.indexOf(input.form) : -1
+            }));
+          }).catch(() => []);
+          return looksLikeSignIn(fields);
         },
         async observe() {
           return {
             landedOn: pathOf(page.url()),
+            landedOrigin: new URL(page.url()).origin,
             ...status === void 0 ? {} : { status },
             errors: [...errors],
             consoleErrors: [...consoleErrors],
@@ -2434,7 +2620,7 @@ async function stageAgainstRecording(options) {
       died = code ?? 1;
     });
   } else {
-    options.onLog?.(`The recording is at ${replay.url} \u2014 start your product with ${variable} set to it.`);
+    options.onLog?.(`The recording is at ${replay.url}. 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));
@@ -2445,7 +2631,7 @@ async function stageAgainstRecording(options) {
     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.` : "")
+Something else is already answering on ${options.appUrl}. That 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) {
@@ -2636,7 +2822,7 @@ function gapReport(gaps) {
     ""
   ];
   for (const gap of gaps) {
-    const broke = gap.broke.length ? ` \u2014 breaks ${gap.broke.join(", ")}` : "";
+    const broke = gap.broke.length ? ` (breaks ${gap.broke.join(", ")})` : "";
     lines.push(`  ${gap.method} ${gap.path}${broke}`);
     if (gap.path !== gap.example) lines.push(`      for example ${gap.example}`);
   }
@@ -2683,7 +2869,7 @@ function coverageReport(found, total) {
     ...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",
+    "plan: 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."
   ];
@@ -2879,7 +3065,7 @@ function score(route, signals) {
   }
   if (hasSegment(route.path, MONEY_OR_ACCESS)) {
     total += 18;
-    because.push("money or access \u2014 asked about out of proportion to its traffic");
+    because.push("money or access: asked about out of proportion to its traffic");
   }
   if (hasSegment(route.path, ENTRY_POINT)) {
     total += 16;
@@ -2975,6 +3161,16 @@ function buildArticlePlan(options) {
 function repositoryFiles(cwd) {
   return execFileSync("git", ["ls-files"], { cwd, encoding: "utf8", maxBuffer: 64 * 1024 * 1024 }).split("\n").filter(Boolean);
 }
+var WORKFLOW_ACTIONS = {
+  checkout: "actions/checkout@v7",
+  setupNode: "actions/setup-node@v7"
+};
+var SETUP_STEPS = `      - uses: ${WORKFLOW_ACTIONS.checkout}
+      - uses: ${WORKFLOW_ACTIONS.setupNode}
+        with:
+          node-version: "22"
+          package-manager-cache: false
+`;
 
 // core/discovery/storyboard.ts
 function shotIdFor(route) {
@@ -3045,7 +3241,7 @@ function parseArgs(argv) {
     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.';
+      return '--rebaseline needs a reason: `--rebaseline "new brand colors 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) {
@@ -3210,6 +3406,10 @@ Approve one on the plan page, then run this again.`
 `
   );
   const runId = local ? void 0 : await openRun(parsed.to, headers, shots.length);
+  let told = Promise.resolve();
+  const tell = (body) => {
+    told = told.then(() => tellHelpDesk(parsed.to, headers, body));
+  };
   try {
     const report = await runCapture({
       baseUrl,
@@ -3242,14 +3442,19 @@ Approve one on the plan page, then run this again.`
       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}` : ""}`);
+        console.log(`${mark} ${index}/${total} ${outcome.route}${outcome.reason ? `: ${outcome.reason}` : ""}`);
         if (runId) {
-          void tellHelpDesk(parsed.to, headers, {
+          tell({
             action: "progress",
             jobId: runId,
             item: outcome.route,
+            // Kept for a help desk that predates `outcome`, which folds the
+            // five into three and cannot tell a refusal from a skip.
             status: outcome.status === "captured" || outcome.status === "unchanged" ? "ok" : outcome.status === "failed" ? "failed" : "skipped",
-            ...outcome.reason ? { note: outcome.reason } : {}
+            outcome: outcome.status,
+            ...outcome.reason ? { note: outcome.reason } : {},
+            // So Setup can ask about them, once each. See `core/capture/unclassified.ts`.
+            ...outcome.unaccounted?.length ? { unaccounted: outcome.unaccounted } : {}
           });
         }
       },
@@ -3299,10 +3504,15 @@ Approve one on the plan page, then run this again.`
         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.`
+    console.log(`
+${runCounts(report)}.`);
+    const unclassified = unclassifiedLines(
+      groupUnclassified(
+        report.outcomes.flatMap((outcome) => outcome.unaccounted?.length ? [{ route: outcome.route, values: outcome.unaccounted }] : [])
+      )
     );
+    if (unclassified.length) console.log(`
+${unclassified.join("\n")}`);
     if (local) {
       const kept = new Map(frames.map((frame) => [frame.id, frame]));
       for (const shot of shots) {
@@ -3360,7 +3570,7 @@ whether they changed. Usually a spinner that never resolves or a looping animati
     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." : `
+        stage ? "\nSome screens still showed a sign-in. A recording answers the backend, but it cannot\ngive the product a session: 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. 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:
 
@@ -3387,16 +3597,32 @@ ${attestation({
       console.log(`
 ${gapReport(gapsFrom([...stage.replay.misses])).join("\n")}`);
     }
+    const counts = {
+      screens: shots.length,
+      captured: report.captured,
+      unchanged: report.unchanged,
+      skipped: report.skipped,
+      refused: report.refused,
+      failed: report.failed
+    };
     if (runId) {
+      await told;
       await tellHelpDesk(parsed.to, headers, {
         action: "finish",
         jobId: runId,
+        // What the verdict below prints, so Setup can say what this log says.
+        counts,
         ...report.survey.length ? { survey: report.survey } : {}
       });
     }
-    return report.failed ? 1 : 0;
+    const verdict = runVerdict(counts);
+    if (verdict.sentence) console.log(`
+${verdict.sentence}`);
+    if (verdict.annotation && process.env["GITHUB_ACTIONS"] === "true") console.log(verdict.annotation);
+    return verdict.exit;
   } catch (error) {
     if (runId) {
+      await told;
       await tellHelpDesk(parsed.to, headers, {
         action: "finish",
         jobId: runId,
@@ -3411,11 +3637,12 @@ ${gapReport(gapsFrom([...stage.replay.misses])).join("\n")}`);
   }
 }
 async function openRun(to, headers, total) {
+  const run = runIdentityFromEnv(process.env);
   try {
     const response = await fetch(`${to}/api/helpdesk/captures`, {
       method: "POST",
       headers: { ...headers, "content-type": "application/json" },
-      body: JSON.stringify({ action: "start", total })
+      body: JSON.stringify({ action: "start", total, ...run ? { run } : {} })
     });
     if (!response.ok) return void 0;
     const body = await response.json();
@@ -3445,7 +3672,7 @@ async function signIn(argv) {
     return 2;
   }
   console.log(
-    `Opening ${baseUrl}. Sign in as your DEMO tenant \u2014 never a real customer.
+    `Opening ${baseUrl}. Sign in as your DEMO tenant, never as 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.
 `