@olomonhelpdesk2/helpdesk 0.1.3 → 0.1.5

package/helpdesk-capture.mjs

@@ -1,4 +1,106 @@
 #!/usr/bin/env node
+// core/capture/examples.ts
+var CI_EXAMPLES_OUT_ENV = "HELPDESK_EXAMPLES_OUT";
+var EXAMPLES_SCHEMA = "helpdesk.examples/1";
+var MAX_PATH = 2048;
+var MAX_ROUTES = 500;
+function segmentsOf(path3) {
+  return path3.split("/").filter((part) => part !== "");
+}
+function patternOf(route) {
+  return segmentsOf(route).map((part) => {
+    const optional = /^\[\[\.\.\.([^\]]+)\]\]$/.exec(part);
+    if (optional) return { kind: "any", name: optional[1] };
+    const catchAll = /^\[\.\.\.([^\]]+)\]$/.exec(part);
+    if (catchAll) return { kind: "many", name: catchAll[1] };
+    const one = /^\[([^\]]+)\]$/.exec(part);
+    if (one) return { kind: "one", name: one[1] };
+    return { kind: "static", text: part };
+  });
+}
+function dynamicSegments(route) {
+  return patternOf(route).filter((segment) => segment.kind !== "static").map((segment) => segment.name);
+}
+function fillsPattern(pattern, path3) {
+  const want = patternOf(pattern);
+  const have = segmentsOf(path3);
+  const match = (w, h) => {
+    if (w === want.length) return h === have.length;
+    const segment = want[w];
+    if (segment.kind === "static") return have[h] === segment.text && match(w + 1, h + 1);
+    if (segment.kind === "one") return h < have.length && match(w + 1, h + 1);
+    const least = segment.kind === "many" ? 1 : 0;
+    for (let take = have.length - h; take >= least; take -= 1) {
+      if (match(w + 1, h + take)) return true;
+    }
+    return false;
+  };
+  return match(0, 0);
+}
+function unusablePath(path3) {
+  if (path3.length > MAX_PATH) return "the path is longer than any screen's";
+  if (!path3.startsWith("/") || path3.startsWith("//")) return "the path is not a path inside the product";
+  if (/[?#\\]/.test(path3)) return "the path carries a query, a fragment or a backslash";
+  if (/\s/.test(path3) || [...path3].some((character) => character.charCodeAt(0) < 32)) {
+    return "the path carries whitespace or a control character";
+  }
+  const segments = segmentsOf(path3);
+  if (segments.some((segment) => segment === "." || segment === ".." || /%2e%2e|%2f|%5c/i.test(segment))) {
+    return "the path climbs out of its position";
+  }
+  if (/\[|\]/.test(path3)) return "the path still holds a dynamic segment rather than a record";
+  return void 0;
+}
+function readExampleRoutes(raw) {
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+    return { ok: false, because: "the file is not a JSON object" };
+  }
+  const body = raw;
+  if (body["schema"] !== EXAMPLES_SCHEMA) {
+    return { ok: false, because: `the file does not say "schema": "${EXAMPLES_SCHEMA}"` };
+  }
+  const routes = body["routes"];
+  if (typeof routes !== "object" || routes === null || Array.isArray(routes)) {
+    return { ok: false, because: 'the file has no "routes" object' };
+  }
+  const entries = Object.entries(routes);
+  if (entries.length > MAX_ROUTES) return { ok: false, because: `the file names more than ${MAX_ROUTES} routes` };
+  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" });
+      continue;
+    }
+    if (typeof value !== "string") {
+      refused.push({ route, because: "its example is not a path" });
+      continue;
+    }
+    const path3 = value.trim();
+    const unusable = unusablePath(path3);
+    if (unusable) {
+      refused.push({ route, because: unusable });
+      continue;
+    }
+    if (!fillsPattern(route, path3)) {
+      refused.push({ route, because: `${path3} is not ${route} with its dynamic segments filled in` });
+      continue;
+    }
+    paths.set(route, path3);
+  }
+  return { ok: true, examples: { paths, refused } };
+}
+function resolveVisit(route, examples) {
+  const needs = dynamicSegments(route);
+  if (needs.length === 0) return { visit: route };
+  const path3 = examples.paths.get(route);
+  return path3 ? { visit: path3 } : { needs };
+}
+function describeMissingExample(route, needs) {
+  const named = needs.map((name) => `[${name}]`).join(" and ");
+  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. */
@@ -21,6 +123,16 @@ var CAPTURE_CONTRACT = {
   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.
    */
@@ -52,7 +164,11 @@ function actionFor(outcome) {
     case "canonical-redirect":
       return void 0;
     case "not-found": {
-      const noun = subjectOf(outcome.missingEndpoint ?? outcome.route);
+      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 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":
@@ -72,7 +188,7 @@ function subjectOf(path3) {
   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
+  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);
 }
@@ -122,7 +238,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) {
@@ -132,21 +248,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];
@@ -304,6 +425,82 @@ function attestation(run) {
   ].filter(Boolean).join("\n");
 }
 
+// core/capture/run-verdict.ts
+function runVerdict(run) {
+  const delivered = run.captured + run.unchanged;
+  const missed = run.skipped + run.refused + run.failed;
+  const counts = `${run.captured} photographed, ${run.unchanged} unchanged, ${run.skipped} skipped, ${run.refused} refused, ${run.failed} failed`;
+  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";
@@ -438,7 +635,7 @@ var PATTERNS = [
   {
     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)}`
   },
   {
@@ -504,6 +701,20 @@ function gateFrame(pageText, options = {}) {
   };
 }
 
+// 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 {
@@ -537,7 +748,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));
@@ -1438,10 +1649,14 @@ async function runCapture(options) {
   };
 }
 async function captureOne(options, shot, build) {
+  if (shot.unvisitable) {
+    return { outcome: { shotId: shot.id, route: shot.route, status: "skipped", reason: shot.unvisitable } };
+  }
+  const visit = shot.visit ?? shot.route;
   let page;
   try {
     page = await options.browser.page();
-    await page.goto(new URL(shot.route, options.baseUrl).toString());
+    await page.goto(new URL(visit, options.baseUrl).toString());
     if (await page.isSignIn()) {
       return {
         outcome: {
@@ -1478,7 +1693,9 @@ async function captureOne(options, shot, build) {
       };
     }
     const seen = await page.observe?.() ?? {};
-    const observed = classifyRoute({ ...seen, route: shot.route, text: pageText });
+    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: {
@@ -1491,7 +1708,7 @@ async function captureOne(options, shot, build) {
         observed
       };
     }
-    const evidence = await readEvidence(settledPage, shot.route, options, build);
+    const evidence = await readEvidence(settledPage, shot.route, options, build, visit);
     const reading = options.clearance ? await readScreen(settledPage, options.clearance) : void 0;
     if (options.clearance && !reading) {
       return {
@@ -1518,7 +1735,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 } : {}
@@ -1634,7 +1852,7 @@ async function captureOne(options, shot, build) {
         result: observed.result,
         sha256,
         settled: frame.settled,
-        ...frame.settled ? {} : {
+        ...frame.settled ? observed.landed ? { reason: `followed its redirect to ${observed.landed}` } : {} : {
           reason: "photographed, but this screen never stopped moving \u2014 its hash will differ every run, so drift on it means nothing"
         }
       } : {
@@ -1660,9 +1878,9 @@ async function captureOne(options, shot, build) {
     await page?.close().catch(() => void 0);
   }
 }
-async function readEvidence(page, route, options, build) {
+async function readEvidence(page, route, options, build, visited = route) {
   if (!options.commit || !options.repository || !options.session || !build) return void 0;
-  const url = new URL(route, options.baseUrl).toString();
+  const url = new URL(visited, options.baseUrl).toString();
   const html = await page.html?.().catch(() => "");
   const aria = await page.aria?.().catch(() => "");
   if (!html && !aria) return void 0;
@@ -1734,8 +1952,8 @@ async function playwrightBrowser(options = {}) {
     // 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",
+    timezoneId: CAPTURE_CONTRACT.timezone,
+    locale: CAPTURE_CONTRACT.locale,
     /**
      * A session, when one is supplied — and only ever from a file on the
      * machine running this.
@@ -1797,11 +2015,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],
@@ -2351,15 +2579,21 @@ Something else is already answering on ${options.appUrl}. That is almost always
   };
 }
 var SESSION_OUT_ENV = CI_SESSION_OUT_ENV;
+var EXAMPLES_OUT_ENV = CI_EXAMPLES_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);
+  if (options.examplesOut) await unlink(options.examplesOut).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 },
+    {
+      [CI_SESSION_OUT_ENV]: options.sessionOut,
+      [CI_BASE_URL_ENV]: options.appUrl,
+      ...options.examplesOut ? { [CI_EXAMPLES_OUT_ENV]: options.examplesOut } : {}
+    },
     onLog
   );
   if (!seeded.ok) {
@@ -2377,6 +2611,7 @@ Nothing has been photographed. A run that carried on from here would sign in to
   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.`
   );
+  const examples = options.examplesOut ? await examplesFrom(options.examplesOut, onLog) : void 0;
   let app;
   let died;
   if (options.appCommand) {
@@ -2413,11 +2648,38 @@ Something else is already answering on ${options.appUrl}, which is almost always
   return {
     appUrl: options.appUrl,
     ...sessionPath ? { sessionPath } : {},
+    ...examples ? { examples } : {},
     close: async () => {
       stop(app);
     }
   };
 }
+async function examplesFrom(path3, onLog) {
+  const { readFile: readFile2 } = await import("node:fs/promises");
+  let text2;
+  try {
+    text2 = await readFile2(path3, "utf8");
+  } catch {
+    return void 0;
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(text2);
+  } catch {
+    onLog?.(`The seed command wrote ${EXAMPLES_OUT_ENV}, but it is not JSON, so no screen with an id in its address will be opened.`);
+    return void 0;
+  }
+  const reading = readExampleRoutes(parsed);
+  if (!reading.ok) {
+    onLog?.(`The seed command wrote ${EXAMPLES_OUT_ENV}, but ${reading.because}, so no screen with an id in its address will be opened.`);
+    return void 0;
+  }
+  onLog?.(
+    `The seed command named a record for ${reading.examples.paths.size} screen(s) with an id in the address.`
+  );
+  for (const refused of reading.examples.refused) onLog?.(`  not using ${refused.route}: ${refused.because}`);
+  return reading.examples;
+}
 async function runToCompletion(command, timeoutMs, env, onLog) {
   return new Promise((resolve) => {
     const child = spawn(command, {
@@ -2895,7 +3157,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) {
@@ -2920,6 +3182,13 @@ function shotsFromRepo(repo, previous) {
     ...previous.has(step.shotId) ? { sha256: previous.get(step.shotId) } : {}
   }));
 }
+function withExamples(shots, examples) {
+  return shots.map((shot) => {
+    const resolved = resolveVisit(shot.route, examples);
+    if ("needs" in resolved) return { ...shot, unvisitable: describeMissingExample(shot.route, resolved.needs) };
+    return resolved.visit === shot.route ? shot : { ...shot, visit: resolved.visit };
+  });
+}
 async function previousFrames(out) {
   try {
     const manifest = JSON.parse(await readFile(path2.join(out, "manifest.json"), "utf8"));
@@ -2988,6 +3257,7 @@ Approve one on the plan page, then run this again.`
         seedCommand: parsed.seedCommand,
         ...parsed.appCommand ? { appCommand: parsed.appCommand } : {},
         sessionOut: parsed.session ?? path2.join(process.cwd(), "helpdesk-demo-session.json"),
+        examplesOut: path2.join(process.cwd(), "helpdesk-examples.json"),
         onLog: (line) => console.log(line)
       });
       if (seeded.sessionPath) parsed.session = seeded.sessionPath;
@@ -2998,6 +3268,7 @@ Approve one on the plan page, then run this again.`
       return 1;
     }
   }
+  const planned = seeded?.examples ? withExamples(shots, seeded.examples) : shots;
   if (parsed.cassette) {
     try {
       stage = await stageAgainstRecording({
@@ -3022,8 +3293,8 @@ Approve one on the plan page, then run this again.`
     baseUrl,
     browser: await browser.build?.().catch(() => void 0),
     clockPinned: !parsed.liveClock,
-    locale: "en-GB",
-    timezone: "UTC",
+    locale: CAPTURE_CONTRACT.locale,
+    timezone: CAPTURE_CONTRACT.timezone,
     session: Boolean(parsed.session),
     ...stage ? { replaying: parsed.cassette } : {},
     ...parsed.allowProduction ? { productionGranted: true } : {},
@@ -3054,7 +3325,7 @@ Approve one on the plan page, then run this again.`
   try {
     const report = await runCapture({
       baseUrl,
-      shots,
+      shots: planned,
       browser,
       ...orders.capture ? {
         clearance: {
@@ -3090,7 +3361,9 @@ Approve one on the plan page, then run this again.`
             jobId: runId,
             item: outcome.route,
             status: outcome.status === "captured" || outcome.status === "unchanged" ? "ok" : outcome.status === "failed" ? "failed" : "skipped",
-            ...outcome.reason ? { note: outcome.reason } : {}
+            ...outcome.reason ? { note: outcome.reason } : {},
+            // So Setup can ask about them, once each. See `core/capture/unclassified.ts`.
+            ...outcome.unaccounted?.length ? { unaccounted: outcome.unaccounted } : {}
           });
         }
       },
@@ -3144,6 +3417,13 @@ Approve one on the plan page, then run this again.`
       `
 ${report.captured} photographed, ${report.unchanged} unchanged, ${report.skipped} skipped, ${report.refused} refused, ${report.failed} failed.`
     );
+    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) {
@@ -3235,7 +3515,18 @@ ${gapReport(gapsFrom([...stage.replay.misses])).join("\n")}`);
         ...report.survey.length ? { survey: report.survey } : {}
       });
     }
-    return report.failed ? 1 : 0;
+    const verdict = runVerdict({
+      screens: shots.length,
+      captured: report.captured,
+      unchanged: report.unchanged,
+      skipped: report.skipped,
+      refused: report.refused,
+      failed: report.failed
+    });
+    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 tellHelpDesk(parsed.to, headers, {
@@ -3310,5 +3601,6 @@ if (runningAsCommand(import.meta.url)) {
   );
 }
 export {
-  main
+  main,
+  withExamples
 };

package/helpdesk-seed.mjs

@@ -788,7 +788,7 @@ var PATTERNS = [
   {
     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)}`
   },
   {
@@ -981,6 +981,16 @@ var CAPTURE_CONTRACT = {
   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.
    */
@@ -1260,7 +1270,7 @@ ${carriedReport(sealed.carried, args.cassette).join("\n")}`);
     console.log(`
 ${describeScrub({ scrubbed: "", findings: sealed.findings, needsReview: true })}`);
     console.log(
-      "\nThese survived the field pass, which means they were in free text or under a key nothing\nrecognised. Read them before you commit this."
+      "\nThese survived the field pass, which means they were in free text or under a key nothing\nrecognized. Read them before you commit this."
     );
     return 1;
   }
@@ -1268,7 +1278,7 @@ ${describeScrub({ scrubbed: "", findings: sealed.findings, needsReview: true })}
   return 0;
 }
 function carriedReport(carried, cassette) {
-  if (!carried.length) return ["Every key in the recording was recognised and rewritten."];
+  if (!carried.length) return ["Every key in the recording was recognized and rewritten."];
   const ranked = [...carried].sort((a, b) => score(b) - score(a) || b.count - a.count);
   const width = Math.max(...ranked.map((field) => field.key.length));
   const worth = ranked.filter((field) => score(field) > 0);
@@ -1370,7 +1380,7 @@ async function routes(args) {
   const cassette = parseCassette(await readFile(args.cassette, "utf8"));
   const found = exampleRoutes(cassette);
   if (!found.length) {
-    console.log("The recording holds no parameterised routes, so there are no example ids to offer.");
+    console.log("The recording holds no parameterized routes, so there are no example ids to offer.");
     return 0;
   }
   console.log("Routes the recording can answer, with an identifier it has already served:\n");

package/helpdesk.mjs

@@ -519,8 +519,17 @@ function baseUrlFromTsconfig(tsconfig) {
 }
 
 // core/discovery/screen-facts.ts
-function noScreenFacts() {
-  return { headings: [], actions: [], links: [], fields: [], notices: [], warnings: [], readFrom: [] };
+function noScreenFacts(read) {
+  return {
+    headings: [],
+    actions: [],
+    links: [],
+    fields: [],
+    notices: [],
+    warnings: [],
+    readFrom: [],
+    ...read ? { read } : {}
+  };
 }
 var LIMITS = {
   headings: 12,
@@ -784,6 +793,7 @@ function readProduct(routes, options) {
   };
   const documentable = routes.filter((route) => !route.skipped);
   const total = Math.min(documentable.length, maxScreens);
+  const reading = { how: "source", commit: options.commit ?? null };
   let done = 0;
   let withFacts = 0;
   const out = routes.map((route) => {
@@ -794,12 +804,15 @@ function readProduct(routes, options) {
       const source = read(reached.path);
       if (source !== void 0) files.push({ path: reached.path, contents: source, depth: reached.depth });
     }
-    const facts = readScreenFacts(files);
     done += 1;
     options.onScreen?.(route, done, total);
-    if (!hasAnything(facts)) return route;
+    if (files.length === 0) return route;
+    const facts = readScreenFacts(files);
+    if (!hasAnything(facts)) {
+      return { ...route, facts: noScreenFacts(reading) };
+    }
     withFacts += 1;
-    return { ...route, facts };
+    return { ...route, facts: { ...facts, read: reading } };
   });
   return { routes: out, read: withFacts, filesOpened: opened.size };
 }
@@ -928,7 +941,7 @@ function markersPullRequestBody(result) {
   const lines = [
     "This adds one-line comments that link screens in this repository to the help articles that describe them.",
     "",
-    "**Nothing here changes behaviour.** Each line is a comment. Once merged, a change to one of these files tells our help desk which article may now be out of date, so somebody can check it before a customer does.",
+    "**Nothing here changes behavior.** Each line is a comment. Once merged, a change to one of these files tells our help desk which article may now be out of date, so somebody can check it before a customer does.",
     "",
     `${result.proposals.length} marker${result.proposals.length === 1 ? "" : "s"} proposed.`
   ];
@@ -991,7 +1004,10 @@ async function runMap(options) {
         }
       },
       aliases: aliasesFromTsconfig(tsconfig),
-      baseUrl: baseUrlFromTsconfig(tsconfig)
+      baseUrl: baseUrlFromTsconfig(tsconfig),
+      // Stamped onto every reading, so a map carries the commit its labels and
+      // controls were read at and a later one can tell fresh from stale.
+      commit: headCommit(options.cwd)
     });
     routes = read.routes;
     const reading = describeReading(routes);
@@ -1066,6 +1082,13 @@ function originOf(cwd) {
     return void 0;
   }
 }
+function headCommit(cwd) {
+  try {
+    return execFileSync("git", ["rev-parse", "HEAD"], { cwd, encoding: "utf8" }).trim() || null;
+  } catch {
+    return null;
+  }
+}
 
 // adapters/invoked-as-command.ts
 import { realpathSync } from "node:fs";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@olomonhelpdesk2/helpdesk",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "Reads a product's screens, plans its help articles, and photographs them.",
   "type": "module",
   "engines": {