@olomonhelpdesk2/helpdesk 0.1.9 → 0.1.11

package/helpdesk-capture.mjs

@@ -154,7 +154,20 @@ var CAPTURE_CONTRACT = {
   /**
    * Injected before every shot. Necessary, not sufficient — see above.
    */
-  motionOff: "*,*::before,*::after{animation:none!important;transition:none!important;caret-color:transparent!important}"
+  motionOff: "*,*::before,*::after{animation:none!important;transition:none!important;caret-color:transparent!important}",
+  /**
+   * What an app uses to leave its own floating widgets out of the pictures.
+   *
+   * A feedback button or a chat launcher sits on top of the product on every
+   * screen, and an article about the product should show only the product. The
+   * capture sets `marker` on `<html>` of every page it photographs, so an app
+   * can style a widget away under `html[data-helpdesk-capture]`, and it removes
+   * any element carrying `hide` itself. Removed before the screen is read, so
+   * what is not in the picture is not asked about either.
+   */
+  marker: "data-helpdesk-capture",
+  hide: "data-helpdesk-hide",
+  hideOff: "[data-helpdesk-hide]{display:none!important}"
 };
 var VISUAL_STABILITY = {
   /** Gap between comparison frames. Short enough to be cheap, long enough to differ. */
@@ -963,88 +976,57 @@ async function takeInventory(page, regions) {
   };
 }
 
-// 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;
+// browser/painted.ts
+async function readPaintedMarkup(page, regions) {
+  return page.evaluate(
+    inPage(
+      (spec) => {
+        const painted = (element) => {
+          const style = window.getComputedStyle(element);
+          if (style.display === "none" || style.visibility === "hidden" || style.visibility === "collapse") return false;
+          if (style.display === "contents") return true;
+          for (const box of Array.from(element.getClientRects())) {
+            if (box.width > 0 && box.height > 0) return true;
+          }
+          return false;
+        };
+        const choice = (element) => element.tagName === "OPTION" || element.tagName === "OPTGROUP";
+        const matched = [];
+        for (const region of spec.regions) {
+          let found = [];
+          try {
+            found = Array.from(document.querySelectorAll(region));
+          } catch {
+            continue;
+          }
+          for (const element of found) if (!matched.includes(element)) matched.push(element);
+        }
+        const roots = matched.filter((element) => !matched.some((other) => other !== element && other.contains(element)));
+        const prune = (original, copy) => {
+          const originals = Array.from(original.children);
+          const copies = Array.from(copy.children);
+          for (const [index, child] of originals.entries()) {
+            const twin = copies[index];
+            if (!twin) continue;
+            if (!choice(child) && !painted(child)) {
+              twin.remove();
+              continue;
+            }
+            prune(child, twin);
+          }
+        };
+        const parts = [];
+        for (const root of roots) {
+          if (!painted(root)) continue;
+          const copy = root.cloneNode(true);
+          prune(root, copy);
+          parts.push(copy.outerHTML);
+        }
+        return parts.join("\n");
+      },
+      { regions: [...regions] }
+    )
+  );
 }
 
 // core/coverage/normalize.ts
@@ -1098,152 +1080,52 @@ function isEmptyState(text2) {
   if (sentence.split(" ").length < 2) return false;
   return EMPTY_STATE.test(sentence);
 }
-
-// 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);
-      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") {
-      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)) {
-      const said = trim(node.text || node.name, LIMITS.sentence);
-      add("notice", said, node);
-      if (isEmptyState(said)) add("empty", said, 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;
-    }
-    out.push(node);
-    stack.push({ depth: depth2, node });
+var IRREVERSIBLE = /\b(cannot be undone|can't be undone|permanently|permanent|irreversible|no way back|cannot be recovered|unrecoverable|this cannot be reversed)\b/i;
+var DESTRUCTIVE = /\b(delete|deletes|deleting|remove|removes|revoke|revokes|erase|wipe|discard|destroy|overwrite|overwrites|reset|disconnect|unpublish|cancel subscription)\b/i;
+var PERMISSION = /\b(only (?:an?\s+)?(?:owner|admin|administrator)s?\b|your role|not allowed|do(?:es)? not have permission|don't have permission|permission to|requires? (?:an? )?(?:owner|admin|editing|editor)|admins? only|read[- ]only)\b/i;
+function finishScreenFacts(parts) {
+  const warnings = [];
+  for (const sentence of parts.notices) {
+    if (IRREVERSIBLE.test(sentence) || PERMISSION.test(sentence)) warnings.push(sentence);
   }
-  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;
+  for (const label of parts.actions) {
+    if (DESTRUCTIVE.test(label)) warnings.push(`"${label}" destroys or replaces something.`);
   }
-  return attributes;
+  return {
+    headings: capped(parts.headings, LIMITS.headings),
+    actions: capped(parts.actions, LIMITS.actions),
+    links: cappedBy(parts.links, (link) => `${link.label ?? ""}|${link.href}`, LIMITS.links),
+    fields: cappedBy(parts.fields, (field) => `${field.label}|${field.kind}`, LIMITS.fields),
+    notices: capped(parts.notices, LIMITS.notices),
+    warnings: capped(warnings, LIMITS.warnings),
+    readFrom: parts.readFrom,
+    ...states({ disabled: parts.disabled, empty: parts.empty, gatedBy: parts.gatedBy })
+  };
 }
-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 states(parts) {
+  const disabled = capped(parts.disabled ?? [], LIMITS.disabled);
+  const empty = capped(parts.empty ?? [], LIMITS.empty);
+  const gatedBy = capped(parts.gatedBy ?? [], LIMITS.gatedBy);
+  return {
+    ...disabled.length ? { disabled } : {},
+    ...empty.length ? { empty } : {},
+    ...gatedBy.length ? { gatedBy } : {}
+  };
 }
-function unescape(value) {
-  return value.replace(/\\(.)/g, "$1");
+function capped(values, limit) {
+  return [...new Set(values)].slice(0, limit);
 }
-function trim(value, limit) {
-  const collapsed = value.replace(/\s+/g, " ").trim();
-  return collapsed.length <= limit ? collapsed : `${collapsed.slice(0, limit - 1).trimEnd()}\u2026`;
+function cappedBy(values, key, limit) {
+  const seen = /* @__PURE__ */ new Set();
+  const kept = [];
+  for (const value of values) {
+    const identity = key(value);
+    if (seen.has(identity)) continue;
+    seen.add(identity);
+    kept.push(value);
+    if (kept.length >= limit) break;
+  }
+  return kept;
 }
 
 // core/discovery/rendered-facts.ts
@@ -1303,7 +1185,7 @@ function readRenderedFactRecords(html, options = {}) {
       continue;
     }
     if (tag === "button" || PRESSABLE.has(role) || submitLike(element)) {
-      add("action", label, landmark, controlState2(element));
+      add("action", label, landmark, controlState(element));
       continue;
     }
     if (tag === "a") {
@@ -1319,19 +1201,19 @@ function readRenderedFactRecords(html, options = {}) {
         add("field", field.label, landmark, {
           fieldKind: field.kind,
           ...field.choices ? { choices: field.choices } : {},
-          ...controlState2(element)
+          ...controlState(element)
         });
       }
       continue;
     }
     if (ANNOUNCEMENT.has(role) || attributes["aria-live"]) {
-      const said = trim2(text(inner), LIMITS.sentence);
+      const said = trim(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);
+      const said = trim(text(inner).replace(/\s+([.,;:!])/g, "$1"), LIMITS.sentence);
       if (isEmptyState(said)) add("empty", said, landmark);
     }
   }
@@ -1339,6 +1221,58 @@ function readRenderedFactRecords(html, options = {}) {
 }
 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;
+function readRenderedFacts(html, options = {}) {
+  return toScreenFacts(readRenderedFactRecords(html, options), options.url);
+}
+function toScreenFacts(facts, from) {
+  const headings = [];
+  const actions = [];
+  const links = [];
+  const fields = [];
+  const notices = [];
+  const disabled = [];
+  const empty = [];
+  for (const entry of facts) {
+    if ((entry.kind === "action" || entry.kind === "field") && entry.controlState?.["disabled"]) {
+      disabled.push(entry.value);
+    }
+    switch (entry.kind) {
+      case "heading":
+        headings.push(entry.value);
+        break;
+      case "action":
+        actions.push(entry.value);
+        break;
+      case "link":
+        links.push(entry.href ? { label: entry.value, href: entry.href } : { href: entry.value });
+        break;
+      case "field": {
+        const field = { label: entry.value, kind: entry.fieldKind ?? "text" };
+        if (entry.choices?.length) field.choices = [...entry.choices];
+        fields.push(field);
+        break;
+      }
+      case "notice":
+        notices.push(entry.value);
+        break;
+      case "empty":
+        empty.push(entry.value);
+        break;
+      case "warning":
+        break;
+    }
+  }
+  return finishScreenFacts({
+    headings,
+    actions,
+    links,
+    fields,
+    notices,
+    readFrom: from ? [from] : [],
+    disabled,
+    empty
+  });
+}
 var OVERLAY_ROLE = {
   dialog: "dialog",
   alertdialog: "dialog",
@@ -1446,7 +1380,7 @@ function elements(markup) {
       stack.length = depth2;
       continue;
     }
-    const attributes = attributesOf2(match[3] ?? "");
+    const attributes = attributesOf(match[3] ?? "");
     const own = LANDMARK_ROLE[attributes["role"]?.toLowerCase() ?? ""] ?? LANDMARK_TAG[tag];
     const frame = {
       tag,
@@ -1467,7 +1401,7 @@ function elements(markup) {
   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) {
+function attributesOf(raw) {
   const attributes = {};
   ATTRIBUTE.lastIndex = 0;
   let match;
@@ -1478,7 +1412,7 @@ function attributesOf2(raw) {
   }
   return attributes;
 }
-function controlState2(element) {
+function controlState(element) {
   const state = {};
   const { attributes } = element;
   const flag = (name) => name in attributes && attributes[name] !== "false";
@@ -1492,8 +1426,8 @@ function controlState2(element) {
 }
 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);
+  if (explicit?.trim()) return trim(explicit.replace(/\s+/g, " ").trim(), LIMITS.label);
+  return trim(text(element.inner), LIMITS.label);
 }
 function submitLike(element) {
   if (element.tag !== "input") return false;
@@ -1507,7 +1441,7 @@ function fieldFrom(element, body) {
   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 };
+  const field = { label: trim(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;
@@ -1554,10 +1488,279 @@ function decode(value) {
     return Number.isFinite(numeric) && numeric > 0 && numeric < 1114112 ? String.fromCodePoint(numeric) : whole;
   });
 }
-function trim2(value, limit) {
+function trim(value, limit) {
   return value.length <= limit ? value : `${value.slice(0, limit - 1).trimEnd()}\u2026`;
 }
 
+// core/capture/screen-details.ts
+function screenDetails(markup, context) {
+  const read = readRenderedFacts(markup, { url: context.route });
+  const clean = (text2) => scrub(text2, { where: context.route, ...context.brands?.length ? { brands: context.brands } : {} }).findings.length === 0;
+  const keep = (values) => values.filter(clean);
+  const links = [];
+  for (const link of read.links) {
+    const href = linkTarget(link.href, context);
+    if (!href || link.label && !clean(link.label)) continue;
+    links.push(link.label ? { label: link.label, href } : { href });
+  }
+  const disabled = keep(read.disabled ?? []);
+  const empty = keep(read.empty ?? []);
+  return {
+    headings: keep(read.headings),
+    actions: keep(read.actions),
+    links,
+    fields: read.fields.filter((field) => clean(field.label)).map((field) => field.choices ? { ...field, choices: keep(field.choices) } : field),
+    notices: keep(read.notices),
+    warnings: keep(read.warnings),
+    readFrom: [context.route],
+    read: { how: "rendered", commit: commitOf(context.commit) },
+    ...disabled.length ? { disabled } : {},
+    ...empty.length ? { empty } : {}
+  };
+}
+function commitOf(commit) {
+  return commit && /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/i.test(commit) ? commit.toLowerCase() : null;
+}
+var RECORD_ID = /^(?:[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}|[0-9a-f]{16,}|\d+|[a-z0-9]{24,})$/i;
+function linkTarget(href, context) {
+  let url;
+  try {
+    url = new URL(href, context.origin);
+  } catch {
+    return void 0;
+  }
+  if (url.protocol !== "http:" && url.protocol !== "https:") return void 0;
+  if (url.origin !== context.origin) return `${url.origin}${url.pathname}`;
+  const path3 = url.pathname;
+  const screen = context.patterns.find((pattern) => fillsPattern(pattern, path3));
+  if (screen) return screen;
+  return path3.split("/").map((segment) => RECORD_ID.test(segment) ? "[id]" : segment).join("/");
+}
+
+// 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.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/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: trim2(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 = controlState2(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", trim2(said, LIMITS.sentence), 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)) {
+      const said = trim2(node.text || node.name, LIMITS.sentence);
+      add("notice", said, node);
+      if (isEmptyState(said)) add("empty", said, 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: attributesOf2(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;
+    }
+    out.push(node);
+    stack.push({ depth: depth2, node });
+  }
+  return out;
+}
+function attributesOf2(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 controlState2(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 trim2(value, limit) {
+  const collapsed = value.replace(/\s+/g, " ").trim();
+  return collapsed.length <= limit ? collapsed : `${collapsed.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"]);
@@ -1709,11 +1912,16 @@ async function runCapture(options) {
     options.onProgress?.(outcome, index + 1, options.shots.length);
   }
   const count = (status) => outcomes.filter((outcome) => outcome.status === status).length;
+  const readings = {};
+  for (const outcome of outcomes) {
+    if (outcome.facts && (outcome.status === "captured" || outcome.status === "unchanged")) readings[outcome.route] = outcome.facts;
+  }
   return {
     baseUrl: options.baseUrl,
     outcomes,
     evidence,
     survey,
+    readings,
     ...build ? { browser: build } : {},
     captured: count("captured"),
     unchanged: count("unchanged"),
@@ -1834,6 +2042,7 @@ async function captureOne(options, shot, build) {
         };
       }
     }
+    const facts = await readDetails(settledPage, shot, options);
     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({
@@ -1883,7 +2092,8 @@ async function captureOne(options, shot, build) {
           result: observed.result,
           sha256,
           settled: frame.settled,
-          reason: "byte-identical to the last run"
+          reason: "byte-identical to the last run",
+          ...facts ? { facts } : {}
         },
         observed,
         ...evidence ? { seen: evidence } : {}
@@ -1926,6 +2136,7 @@ async function captureOne(options, shot, build) {
         result: observed.result,
         sha256,
         settled: frame.settled,
+        ...facts ? { facts } : {},
         ...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"
         }
@@ -2077,6 +2288,8 @@ async function playwrightBrowser(options = {}) {
           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.addStyleTag({ content: CAPTURE_CONTRACT.hideOff }).catch(() => void 0);
+          await page.evaluate((name) => document.documentElement.setAttribute(name, ""), CAPTURE_CONTRACT.marker).catch(() => void 0);
           await page.evaluate(() => document.fonts?.ready).catch(() => void 0);
         },
         async text() {
@@ -2120,6 +2333,9 @@ async function playwrightBrowser(options = {}) {
           }).catch(() => false);
           return { inventory, surfaces, styled };
         },
+        async painted(regions) {
+          return readPaintedMarkup(page, regions).catch(() => "");
+        },
         async screenshot(cover) {
           const masks = (cover ?? []).map((selector) => page.locator(selector));
           return page.screenshot({
@@ -2254,6 +2470,18 @@ async function readScreen(page, clearance) {
   if (!page.inspect) return void 0;
   return page.inspect(clearance.regions);
 }
+async function readDetails(page, shot, options) {
+  if (!options.clearance || !page.painted) return void 0;
+  const markup = await page.painted(options.clearance.regions).catch(() => "");
+  if (!markup) return void 0;
+  return screenDetails(markup, {
+    route: shot.route,
+    commit: options.commit,
+    origin: new URL(options.baseUrl).origin,
+    patterns: options.shots.map((each) => each.route),
+    brands: options.brands
+  });
+}
 function pathOf(url) {
   try {
     const parsed = new URL(url);
@@ -3193,7 +3421,8 @@ function buildStoryboard(options) {
   const beneath = options.routes.filter(
     (route) => !covered.has(route.path) && !route.skipped && [...covered].some((base) => base !== "/" && route.path.startsWith(`${base}/`))
   );
-  const ordered = [...covered].map((path3) => byPath.get(path3)).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 own = [...covered].map((path3) => byPath.get(path3)).filter((route) => Boolean(route) && !route.skipped);
+  const ordered = options.inOrder ? own : own.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,
@@ -3432,6 +3661,9 @@ Approve one on the plan page, then run this again.`
       } : {},
       brands: parsed.brands,
       force: Boolean(parsed.rebaseline),
+      // The commit a workflow run checked out, so the screens' details say
+      // which code they describe. Absent anywhere else, and never guessed.
+      .../^[0-9a-f]{40}$/i.test(process.env["GITHUB_SHA"] ?? "") ? { commit: process.env["GITHUB_SHA"] } : {},
       /*
        * 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
@@ -3506,6 +3738,10 @@ Approve one on the plan page, then run this again.`
     });
     console.log(`
 ${runCounts(report)}.`);
+    const read = Object.keys(report.readings).length;
+    if (read && !local) {
+      console.log(`Read what ${read} screen${read === 1 ? "" : "s"} say, as the help desk's screen details: headings, buttons, fields and messages.`);
+    }
     const unclassified = unclassifiedLines(
       groupUnclassified(
         report.outcomes.flatMap((outcome) => outcome.unaccounted?.length ? [{ route: outcome.route, values: outcome.unaccounted }] : [])
@@ -3612,7 +3848,9 @@ ${gapReport(gapsFrom([...stage.replay.misses])).join("\n")}`);
         jobId: runId,
         // What the verdict below prints, so Setup can say what this log says.
         counts,
-        ...report.survey.length ? { survey: report.survey } : {}
+        ...report.survey.length ? { survey: report.survey } : {},
+        // What each photographed screen says, as the screens' details.
+        ...Object.keys(report.readings).length ? { readings: report.readings } : {}
       });
     }
     const verdict = runVerdict(counts);

package/helpdesk-seed.mjs

@@ -1002,7 +1002,20 @@ var CAPTURE_CONTRACT = {
   /**
    * Injected before every shot. Necessary, not sufficient — see above.
    */
-  motionOff: "*,*::before,*::after{animation:none!important;transition:none!important;caret-color:transparent!important}"
+  motionOff: "*,*::before,*::after{animation:none!important;transition:none!important;caret-color:transparent!important}",
+  /**
+   * What an app uses to leave its own floating widgets out of the pictures.
+   *
+   * A feedback button or a chat launcher sits on top of the product on every
+   * screen, and an article about the product should show only the product. The
+   * capture sets `marker` on `<html>` of every page it photographs, so an app
+   * can style a widget away under `html[data-helpdesk-capture]`, and it removes
+   * any element carrying `hide` itself. Removed before the screen is read, so
+   * what is not in the picture is not asked about either.
+   */
+  marker: "data-helpdesk-capture",
+  hide: "data-helpdesk-hide",
+  hideOff: "[data-helpdesk-hide]{display:none!important}"
 };
 var RECORDING_MISS_STATUS = 599;
 

package/helpdesk.mjs

@@ -965,8 +965,13 @@ function hasAnything(facts) {
 }
 function describeReading(routes) {
   const documentable = routes.filter((route) => !route.skipped);
-  const read = documentable.filter((route) => route.facts && hasAnything(route.facts)).length;
-  return { screens: documentable.length, read, pathsOnly: read === 0 };
+  const read = documentable.filter((route) => route.facts && hasAnything(route.facts));
+  return {
+    screens: documentable.length,
+    read: read.length,
+    rendered: read.filter((route) => route.facts?.read?.how === "rendered").length,
+    pathsOnly: read.length === 0
+  };
 }
 
 // core/github/remote.ts

package/package.json

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