// WHAT THE ADJUDICATOR IS SHOWN — the subjects, and the content classes they collapse to.
//
// A criterion the engine cannot decide is handed to an agent with the evidence it must rule
// against. Two properties decide whether that verdict is worth anything, and this module owns
// both.
//
// 1. AIM. Evidence used to be the union of the harvesters of a criterion's mapped success
//    criteria, taken in `pc.wcag` order and then cut to a fixed cap. Measured on a real audit:
//    RGAA 11.1 (are form fields labelled?) maps [1.3.1, 2.4.6, 3.3.2, 4.1.2], the 1.3.1
//    harvest filled every slot with headings and lists, and the control harvest — the actual
//    SUBJECT of 11.1 — never appeared. 9.2 (landmarks) and 5.8 (layout tables) received the
//    very same thirty headings. Those three are exactly the criteria a real run had refused
//    for a "fabricated" citation: the agent had opened the right file and cited the right
//    element, and the evidence set simply did not contain the subject. So a criterion names
//    its SUBJECTS, and a pack criterion may name its own (`PACK_SUBJECTS`) rather than
//    inherit a union that is aimed elsewhere.
//
// 2. COMPLETENESS. A cap over raw anchors is a sample, and a `C` over a sample is a claim
//    about a population nobody looked at — measured, 30 of 2652 anchors for 11.1, and not one
//    of them from a rendered page. But a population is only large when counted as
//    occurrences: 887 links across 38 captured pages are 97 distinct (text, href) pairs, and
//    47 images are 8 distinct (alt, src) pairs. So every subject declares the CONTENT CLASS
//    an anchor belongs to, the harvest collapses to one representative per class, and the
//    occurrence count travels with it. What the agent reads is then the whole population,
//    expressed once per distinct thing.
import { type Doc, type El, ancestors, attr, elementsByTag, snippet as elSnippet, textContent } from "./parse/html.js";
import { parseInlineStyle } from "./color.js";
import type { Evidence } from "./adjudicate.js";

/** Mask the parts of a text that change between runs without the code changing.
 *
 *  Only the class IDENTITY is masked — the note and the snippet keep the real text, so the
 *  adjudicator still reads what the page says. What this decides is whether two anchors are
 *  "the same thing": a row rendered at 13:04 and the same row rendered at 14:12 are one
 *  decision about accessibility, not two.
 *
 *  It matters beyond tidiness. The verdict ledger fingerprints the evidence a criterion was
 *  ruled against, and a fingerprint that moves every run makes a stored verdict stale on
 *  arrival — the criterion returns to « to assess » and the ledger stops paying for itself.
 *  Measured on a real capture set: four criteria carried a run timestamp in their evidence.
 *
 *  Deliberately narrow. Generated ids that are stable for a given tree (React `useId`) and
 *  content hashes that are stable for given source are NOT masked: when those move, the code
 *  moved, and a verdict about it SHOULD be re-examined. */
const VOLATILE: [RegExp, string][] = [
  [/\b\d{1,2}[/-]\d{1,2}[/-]\d{2,4}\b/g, "<date>"],
  [/\b\d{4}-\d{2}-\d{2}\b/g, "<date>"],
  [/\b\d{1,2}:\d{2}(?::\d{2})?\b/g, "<time>"],
  [/\b\d{6,}\b/g, "<num>"],
];
const stable = (s: string): string => VOLATILE.reduce((acc, [re, to]) => acc.replace(re, to), s);

/** One harvested anchor, plus the content class it belongs to. Two anchors sharing a class
 *  are the same thing rendered twice — a header link on 38 pages, not 38 link problems. */
export interface Harvested {
  ev: Evidence;
  cls: string;
  /** THE MARKUP THIS ANCHOR ACTUALLY CARRIES — its tag, the attributes it sets to a non-empty
   *  value, and the value itself for the two attributes a standard writes tests about by
   *  value (`role`, `type`). Derived from the parsed element, never from the note's prose.
   *
   *  It exists so a brief can say WHICH of a criterion's numbered tests the harvest actually
   *  touches. RGAA 11.2 asks the same question six times over six different labelling
   *  mechanisms — `<label>`, `title`, `aria-label`, `aria-labelledby`, a visible label, an
   *  adjacent button — and every one of them harvests under the same subject (`controls`),
   *  so subject granularity separates none of them. What separates them is the markup on the
   *  element, and that is a fact about the source rather than a judgement about the test. */
  markup?: string[];
  /** Source offset of the anchor. Identity, not output: `file:line:selector` is NOT unique —
   *  forty links minified onto one line share all three — so de-duplicating on it silently
   *  collapsed distinct elements into one and undercounted every population that came from a
   *  single-line document. */
  at: number;
}

export type Subject = (docs: Doc[]) => Harvested[];

const selectorFor = (el: El): string => {
  const id = el.attribs.id ? `#${el.attribs.id}` : "";
  const cls = el.attribs.class ? `.${el.attribs.class.trim().split(/\s+/)[0]}` : "";
  return `${el.tag}${id}${cls}`;
};

/** An anchor on an element. `cls` is the content identity; when omitted the note is used,
 *  which is right for every subject whose note already spells out what makes it distinct. */
/** Attributes whose VALUE is normative vocabulary a standard writes tests against — RGAA 1.1
 *  distinguishes `role="img"` from any other role, and `<input type="image">` from any other
 *  input. Every other attribute contributes its NAME only: `aria-label` is the mechanism, its
 *  text is what the agent judges. */
const VALUE_BEARING_ATTRS = new Set(["role", "type"]);

/** The markup an element carries, as flat tokens — see `Harvested.markup`.
 *
 *  Generic on purpose: computed from the parsed element for EVERY subject, so no harvester
 *  has to be taught about it and no per-test table has to be curated. An attribute set to the
 *  empty string contributes nothing, which is the whole point — `aria-label=""` is the
 *  absence of that mechanism, not its presence. */
function markupOf(el: El, extra?: string[]): string[] {
  const out = new Set<string>([el.tag.toLowerCase(), ...(extra ?? [])]);
  for (const [name, value] of Object.entries(el.attribs)) {
    if (typeof value !== "string" || value.trim() === "") continue;
    const key = name.toLowerCase();
    out.add(key);
    if (VALUE_BEARING_ATTRS.has(key)) out.add(`${key}=${value.trim().toLowerCase()}`);
  }
  return [...out];
}

function h(doc: Doc, el: El, note: string, cls?: string, markupExtra?: string[]): Harvested {
  return {
    ev: { file: doc.file, line: el.line, selector: selectorFor(el), snippet: elSnippet(doc, el, 160), note },
    cls: stable(cls ?? `${el.tag}|${note}`),
    at: el.start,
    markup: markupOf(el, markupExtra),
  };
}

/** A document-level anchor, for signals that have no element to hang on (a source import, a
 *  stylesheet rule, a doctype). Anchored at a real line so grounding can still resolve it. */
function hAt(doc: Doc, line: number, selector: string, note: string, cls: string): Harvested {
  return {
    ev: { file: doc.file, line, selector, snippet: (doc.source.split("\n")[line - 1] ?? "").trim().slice(0, 160), note },
    cls: stable(cls),
    at: line,
  };
}

/** A stylesheet rule's declarations as one readable line — the agent judges the rule, so it
 *  must see what the rule actually says. */
const declsText = (decls: Record<string, string>): string =>
  Object.entries(decls)
    .map(([k, v]) => `${k}: ${v}`)
    .join("; ")
    .slice(0, 100);

const t = (el: El, n = 60): string => textContent(el).trim().replace(/\s+/g, " ").slice(0, n);

/** Nearest preceding heading text — the context a link/control is read in. */
function nearestHeading(doc: Doc, el: El): string | undefined {
  const headings = elementsByTag(doc, "h1", "h2", "h3", "h4", "h5", "h6").filter((x) => x.start < el.start);
  const last = headings[headings.length - 1];
  return last ? t(last, 80) : undefined;
}

/** First source line matching `re`, or undefined. Used by the source-signal subjects, whose
 *  subject matter is an API call rather than an element. */
function lineOf(doc: Doc, re: RegExp): number | undefined {
  const m = re.exec(doc.source);
  return m ? doc.source.slice(0, m.index).split("\n").length : undefined;
}

/** Every source line matching `re` (global), capped so one minified bundle cannot flood a
 *  worklist. The cap is on ANCHORS, never on classes — see the module header. */
function linesOf(doc: Doc, re: RegExp, cap = 200): { line: number; text: string }[] {
  const out: { line: number; text: string }[] = [];
  const g = new RegExp(re.source, re.flags.includes("g") ? re.flags : `${re.flags}g`);
  let m: RegExpExecArray | null;
  while ((m = g.exec(doc.source)) && out.length < cap) {
    const line = doc.source.slice(0, m.index).split("\n").length;
    out.push({ line, text: (doc.source.split("\n")[line - 1] ?? "").trim().slice(0, 120) });
    if (m.index === g.lastIndex) g.lastIndex++;
  }
  return out;
}

// Key/value display patterns (RGAA 8.9 div-presented fields / 9.3 <dl> semantics).
const LABEL_LIKE = /(^|[-_ ])(field-label|field-key|label|key|term)([-_ ]|$)/i;
const VALUE_LIKE = /(^|[-_ ])(field-value|field-data|value|data)([-_ ]|$)/i;
function keyValuePairs(doc: Doc): { key: El; label: string; value: string }[] {
  const out: { key: El; label: string; value: string }[] = [];
  for (const el of doc.elements) {
    const isDt = el.tag === "dt";
    const isLabelDiv = el.tag !== "label" && el.tag !== "dt" && LABEL_LIKE.test(attr(el, "class") ?? "");
    if (!isDt && !isLabelDiv) continue;
    const parent = el.parent;
    if (!parent) continue;
    const sibs = parent.children.filter((c): c is El => c.type === "element");
    const next = sibs[sibs.indexOf(el) + 1];
    if (!next) continue;
    const paired = isDt ? next.tag === "dd" : VALUE_LIKE.test(attr(next, "class") ?? "");
    if (!paired) continue;
    out.push({ key: el, label: t(el, 40), value: t(next, 40) });
  }
  return out;
}

// The RGAA's own closed lists (glossary « Présentation de l'information »), kept here only to
// SURFACE candidates for a reader; the verdict comes from src/rules/presentation.ts, which
// applies the conditional parts (width/height, size, the <u> caveat) that this does not.
const PRESENTATIONAL_MARKUP_TAGS = new Set(["basefont", "big", "blink", "center", "font", "marquee", "s", "strike", "tt"]);
const PRESENTATIONAL_MARKUP_ATTRS = new Set([
  "align",
  "alink",
  "background",
  "bgcolor",
  "border",
  "cellpadding",
  "cellspacing",
  "char",
  "charoff",
  "clear",
  "compact",
  "color",
  "frameborder",
  "hspace",
  "link",
  "marginheight",
  "marginwidth",
  "text",
  "valign",
  "vlink",
  "vspace",
]);

const DOWNLOAD_HREF = /\.(pdf|docx?|xlsx?)(?:[?#]|$)/i;
const STATUS_CLASS = /(error|status|message|alert|notif|toast|feedback|live)/i;
const TEMPORAL_MEDIA_VALUE = /(?:^|[/.?=&_-])(?:audio|video|player|podcast|mp[34]|webm|ogg|ogv|wav|m4a|mov|avi|mpeg)(?:$|[/.?=&_-])/i;
const ROUTER_IMPORT =
  /['"](?:react-router(?:-dom)?|next\/(?:router|navigation)|vue-router|@remix-run\/[\w-]+|@tanstack\/[\w-]*router|@sveltejs\/kit|\$app\/(?:navigation|stores))['"]/;

// Words that MIGHT signal a passage in another language on a French-language interface. A
// lead for the agent, never a finding: the decision protocol exempts proper nouns, technical
// terms and borrowings in common use, and half of these are all three.
const FOREIGN_LEXICON =
  /\b(?:the|and|with|your|about|please|download|settings|welcome|dashboard|overview|read more|learn more|sign in|sign up|log in|get started|coming soon|powered by)\b/i;

const CONTROL_TAGS = ["input", "select", "textarea"] as const;
const INTERACTIVE_TAGS = ["a", "button", "input", "select", "textarea", "summary", "details", "label"];

/** An object/embed is ambiguous until its declared type or resource says what it carries.
 * Unknown plug-in content stays in BOTH multimedia populations: narrowing uncertainty to one
 * side can hide the exact temporal/non-temporal player the criterion was meant to inspect. */
function embeddedMediaKind(el: El): "temporal" | "non-temporal" | "unknown" {
  const type = (attr(el, "type") ?? "").toLowerCase();
  const resource = `${attr(el, "src") ?? ""} ${attr(el, "data") ?? ""}`.toLowerCase();
  if (/^(?:audio|video)\//.test(type) || TEMPORAL_MEDIA_VALUE.test(`${type} ${resource}`)) return "temporal";
  if (/^image\//.test(type) || /\.(?:svg|png|jpe?g|webp|avif)(?:[?#]|$)/i.test(resource)) return "non-temporal";
  return "unknown";
}

function labelFor(doc: Doc, el: El): string {
  const id = attr(el, "id");
  const lbl = id ? elementsByTag(doc, "label").find((l) => attr(l, "for") === id) : undefined;
  if (lbl) return t(lbl, 40);
  const wrapping = ancestors(el).find((a) => a.tag === "label");
  return wrapping ? t(wrapping, 40) : "";
}

/** `<label>` as a MARKUP TOKEN on the labelled control.
 *
 *  A `<label for=…>` is a different element from the field it names, so the field's own
 *  attributes never mention it — and RGAA 11.2.1 is written about exactly that element. This
 *  is the one place a token has to be attributed across a relationship rather than read off
 *  the element, so it is stated here rather than smuggled into the generic `markupOf`. */
function labelElementTokens(doc: Doc, el: El): string[] {
  const id = attr(el, "id");
  if (id && elementsByTag(doc, "label").some((l) => attr(l, "for") === id)) return ["label"];
  return ancestors(el).some((a) => a.tag === "label") ? ["label"] : [];
}

/** The page a snapshot document belongs to (`.ultra11y/pages/<id>/dom.html`), else undefined
 *  for a source file. Carried on the evidence so a class can say WHERE it appears. */
export function pageOfDoc(file: string): string | undefined {
  const m = /(?:^|\/)\.ultra11y\/pages\/([^/]+)\//.exec(file.replace(/\\/g, "/"));
  return m ? m[1] : undefined;
}

export const isSnapshotFile = (file: string): boolean => pageOfDoc(file) !== undefined;

// ---- the subjects -------------------------------------------------------------------------

export const SUBJECTS: Record<string, Subject> = {
  // Every image-like element and the alternative it carries. Class = (alt, src): the same
  // logo on 38 pages is one decision, not 38.
  images: (docs) =>
    docs.flatMap((d) =>
      elementsByTag(d, "img", "svg", "area", "object", "embed", "canvas")
        .concat(d.elements.filter((e) => attr(e, "role") === "img"))
        .filter((e, i, a) => a.indexOf(e) === i)
        .map((e) =>
          h(
            d,
            e,
            `<${e.tag}> alt="${attr(e, "alt") ?? ""}" aria-label="${attr(e, "aria-label") ?? ""}" src="${(attr(e, "src") ?? "").slice(0, 80)}"`,
            `image|${e.tag}|${attr(e, "alt") ?? ""}|${attr(e, "aria-label") ?? ""}|${attr(e, "src") ?? ""}`,
          ),
        ),
    ),

  // Links: text + destination + the heading they are read under. Class = (text, href).
  links: (docs) =>
    docs.flatMap((d) =>
      elementsByTag(d, "a")
        .filter((e) => attr(e, "href") !== undefined)
        .map((e) => {
          const href = attr(e, "href") ?? "";
          const dl = DOWNLOAD_HREF.exec(href);
          const note = dl ? ` download-format=${dl[1]!.toLowerCase()} (naming the format, e.g. "(PDF)", is a recommendation — not an NC)` : "";
          return h(d, e, `text="${t(e)}" href="${href}" under="${nearestHeading(d, e) ?? ""}"${note}`, `link|${t(e)}|${href}`);
        }),
    ),

  // Literal inline colour pairs — the statically visible subset of contrast.
  colourPairs: (docs) =>
    docs.flatMap((d) =>
      d.elements
        .filter((e) => {
          const st = parseInlineStyle(attr(e, "style") ?? "");
          return st.has("color") || st.has("background-color") || st.has("background");
        })
        .map((e) => {
          const st = parseInlineStyle(attr(e, "style") ?? "");
          const fg = st.get("color") ?? "?";
          const bg = st.get("background-color") ?? st.get("background") ?? "?";
          return h(d, e, `color=${fg} background=${bg}`, `colour|${fg}|${bg}`);
        }),
    ),

  // Headings, labels, legends and captions — the text judged for descriptiveness.
  headings: (docs) =>
    docs.flatMap((d) =>
      elementsByTag(d, "h1", "h2", "h3", "h4", "h5", "h6", "label", "legend", "caption").map((e) =>
        h(d, e, `<${e.tag}> text="${t(e)}"`, `heading|${e.tag}|${t(e)}`),
      ),
    ),

  // Form controls and the label/placeholder/instruction attached to them.
  controls: (docs) =>
    docs.flatMap((d) =>
      elementsByTag(d, ...CONTROL_TAGS).map((e) =>
        h(
          d,
          e,
          `<${e.tag}${attr(e, "type") ? ` type="${attr(e, "type")}"` : ""}> label="${labelFor(d, e)}" placeholder="${attr(e, "placeholder") ?? ""}" aria-label="${attr(e, "aria-label") ?? ""}" required=${attr(e, "required") !== undefined} describedby="${attr(e, "aria-describedby") ?? ""}"`,
          `control|${e.tag}|${attr(e, "type") ?? ""}|${labelFor(d, e)}|${attr(e, "name") ?? ""}`,
          labelElementTokens(d, e),
        ),
      ),
    ),

  // The `autocomplete` token a field carries — the subject of "identify input purpose".
  autocomplete: (docs) =>
    docs.flatMap((d) =>
      elementsByTag(d, ...CONTROL_TAGS).map((e) =>
        h(
          d,
          e,
          `<${e.tag} type="${attr(e, "type") ?? ""}" name="${attr(e, "name") ?? ""}"> autocomplete="${attr(e, "autocomplete") ?? ""}" — does this field collect data ABOUT THE USER?`,
          `autocomplete|${attr(e, "type") ?? ""}|${attr(e, "name") ?? ""}|${attr(e, "autocomplete") ?? ""}`,
        ),
      ),
    ),

  // Error messaging and its association with the offending field.
  errors: (docs) =>
    docs.flatMap((d) => [
      ...d.elements
        .filter((e) => attr(e, "aria-invalid") !== undefined || attr(e, "aria-errormessage") !== undefined)
        .map((e) =>
          h(
            d,
            e,
            `aria-invalid="${attr(e, "aria-invalid") ?? ""}" aria-errormessage="${attr(e, "aria-errormessage") ?? ""}" aria-describedby="${attr(e, "aria-describedby") ?? ""}"`,
            `errorstate|${attr(e, "aria-invalid") ?? ""}|${attr(e, "aria-errormessage") ?? ""}`,
          ),
        ),
      ...d.elements
        .filter((e) => STATUS_CLASS.test(attr(e, "class") ?? "") && ancestors(e).some((a) => a.tag === "form"))
        .map((e) => h(d, e, `error/status text in a form: "${t(e, 60)}"`, `errortext|${t(e, 60)}`)),
    ]),

  // Structure conveyed by markup: the outline, tables, lists, and div-presented pairs.
  structure: (docs) =>
    docs.flatMap((d) => [
      ...elementsByTag(d, "h1", "h2", "h3", "h4", "h5", "h6", "table", "ul", "ol", "dl").map((e) =>
        h(d, e, `<${e.tag}> "${t(e, 50)}"`, `structure|${e.tag}|${t(e, 50)}`),
      ),
      ...keyValuePairs(d).map((p) =>
        h(
          d,
          p.key,
          `key/value pair — label="${p.label}" value="${p.value}" (div-presented field? verify the relationship isn't only visual — RGAA 8.9/9.3)`,
          `kv|${p.label}|${p.value}`,
        ),
      ),
    ]),

  // Tables, with the parts that decide whether they are data or layout.
  tables: (docs) =>
    docs.flatMap((d) =>
      elementsByTag(d, "table").map((e) => {
        const caption = elementsByTag(d, "caption").find((c) => ancestors(c)[0] === e);
        const ths = elementsByTag(d, "th").filter((x) => ancestors(x).includes(e));
        return h(
          d,
          e,
          `<table> caption="${caption ? t(caption, 40) : ""}" role="${attr(e, "role") ?? ""}" th=${ths.length} summary="${attr(e, "summary") ?? ""}" — data table or layout?`,
          `table|${caption ? t(caption, 40) : ""}|${ths.length}|${attr(e, "role") ?? ""}`,
        );
      }),
    ),

  // Lists and definition lists, for the technique-consistency question.
  lists: (docs) =>
    docs.flatMap((d) =>
      elementsByTag(d, "ul", "ol", "dl").map((e) => {
        const items = e.children.filter((c): c is El => c.type === "element").length;
        return h(d, e, `<${e.tag}> items=${items} first="${t(e, 40)}"`, `list|${e.tag}|${items}|${t(e, 40)}`);
      }),
    ),

  // Landmarks and the navigation structure that lets a user bypass repeated blocks.
  landmarks: (docs) =>
    docs.flatMap((d) => [
      ...elementsByTag(d, "header", "nav", "main", "footer", "aside", "form", "section")
        .concat(d.elements.filter((e) => ["banner", "navigation", "main", "contentinfo", "complementary", "search", "region"].includes(attr(e, "role") ?? "")))
        .filter((e, i, a) => a.indexOf(e) === i)
        .map((e) =>
          h(
            d,
            e,
            `<${e.tag}> role="${attr(e, "role") ?? ""}" aria-label="${attr(e, "aria-label") ?? ""}" aria-labelledby="${attr(e, "aria-labelledby") ?? ""}"`,
            `landmark|${e.tag}|${attr(e, "role") ?? ""}|${attr(e, "aria-label") ?? ""}`,
          ),
        ),
      ...elementsByTag(d, "a")
        .filter((e) => (attr(e, "href") ?? "").startsWith("#"))
        .map((e) => h(d, e, `in-page link (skip link?) text="${t(e, 40)}" href="${attr(e, "href")}"`, `skiplink|${t(e, 40)}|${attr(e, "href")}`)),
    ]),

  // Every mechanism that leads to a page — the subject of "multiple ways".
  navMechanisms: (docs) =>
    docs.flatMap((d) => [
      ...elementsByTag(d, "nav").map((e) =>
        h(
          d,
          e,
          `<nav> aria-label="${attr(e, "aria-label") ?? ""}" links=${elementsByTag(d, "a").filter((a) => ancestors(a).includes(e)).length}`,
          `nav|${attr(e, "aria-label") ?? ""}`,
        ),
      ),
      ...elementsByTag(d, ...CONTROL_TAGS)
        .filter(
          (e) => (attr(e, "type") ?? "") === "search" || /search|recherch/i.test(`${attr(e, "name") ?? ""} ${attr(e, "id") ?? ""} ${attr(e, "class") ?? ""}`),
        )
        .map((e) => h(d, e, `search field — one of the "multiple ways" mechanisms`, `search|${attr(e, "name") ?? ""}`)),
      ...elementsByTag(d, "a")
        .filter((e) => /plan-du-site|sitemap|site-map|index/i.test(attr(e, "href") ?? ""))
        .map((e) => h(d, e, `site map / index link text="${t(e, 40)}" href="${attr(e, "href")}"`, `sitemap|${attr(e, "href")}`)),
    ]),

  // The repeated blocks whose ORDER must not change from page to page. One class per page so
  // "same relative order everywhere" is answerable from the evidence itself.
  repeatedBlocks: (docs) =>
    docs.flatMap((d) => {
      const page = pageOfDoc(d.file) ?? "source";
      return elementsByTag(d, "header", "nav", "footer").map((e) => {
        const order = elementsByTag(d, "a")
          .filter((a) => ancestors(a).includes(e))
          .map((a) => t(a, 24))
          .slice(0, 20)
          .join(" › ");
        return h(d, e, `page="${page}" <${e.tag}> order: ${order}`, `repeated|${page}|${e.tag}`);
      });
    }),

  // Elements whose ARIA name, role or state is authored rather than native.
  aria: (docs) =>
    docs.flatMap((d) =>
      d.elements
        .filter((e) => attr(e, "role") !== undefined || Object.keys(e.attribs).some((k) => k.startsWith("aria-")))
        .map((e) => {
          const ariaKeys = Object.keys(e.attribs)
            .filter((k) => k.startsWith("aria-"))
            .sort()
            .join(",");
          return h(d, e, `<${e.tag}> role="${attr(e, "role") ?? ""}" ${ariaKeys}`, `aria|${e.tag}|${attr(e, "role") ?? ""}|${ariaKeys}`);
        }),
    ),

  // Live regions and the async feedback that must reach them.
  liveRegions: (docs) =>
    docs.flatMap((d) => {
      const isRegion = (e: El) => attr(e, "aria-live") !== undefined || ["status", "alert", "log"].includes((attr(e, "role") ?? "").trim().toLowerCase());
      return [
        ...d.elements
          .filter(isRegion)
          .map((e) =>
            h(d, e, `aria-live="${attr(e, "aria-live") ?? ""}" role="${attr(e, "role") ?? ""}"`, `live|${attr(e, "aria-live") ?? ""}|${attr(e, "role") ?? ""}`),
          ),
        ...d.elements
          .filter((e) => !isRegion(e) && STATUS_CLASS.test(attr(e, "class") ?? "") && ancestors(e).some((a) => a.tag === "form"))
          .map((e) =>
            h(
              d,
              e,
              `status-like class="${(attr(e, "class") ?? "").slice(0, 40)}" in a form — verify async feedback is announced (role=status/alert or aria-live)`,
              `statusclass|${(attr(e, "class") ?? "").slice(0, 40)}`,
            ),
          ),
      ];
    }),

  // Explicit tab order, dialogs, and the SPA signals that decide focus restitution.
  focusOrder: (docs) =>
    docs.flatMap((d) => {
      const out: Harvested[] = [
        ...d.elements
          .filter((e) => attr(e, "tabindex") !== undefined)
          .map((e) => h(d, e, `tabindex="${attr(e, "tabindex")}"`, `tabindex|${attr(e, "tabindex")}`)),
        ...elementsByTag(d, "dialog")
          .concat(d.elements.filter((e) => attr(e, "role") === "dialog"))
          .filter((e, i, a) => a.indexOf(e) === i)
          .map((e) =>
            h(d, e, `<${e.tag} role="${attr(e, "role") ?? ""}"> — verify focus moves in on open and is restored to the trigger on close`, `dialog|${e.tag}`),
          ),
      ];
      const rl = lineOf(d, ROUTER_IMPORT);
      if (rl !== undefined)
        out.push(hAt(d, rl, "import", "client-router import — verify page title + focus are restored on partial (SPA) navigation", "router"));
      return out;
    }),

  // Focusable inventory plus the handlers that can hold focus — the keyboard-trap subject.
  focusables: (docs) =>
    docs.flatMap((d) => [
      ...elementsByTag(d, "iframe", "object", "embed").map((e) =>
        h(
          d,
          e,
          `<${e.tag}> title="${attr(e, "title") ?? ""}" src="${(attr(e, "src") ?? "").slice(0, 60)}" — can focus LEAVE this embedded content with the keyboard alone?`,
          `embed|${e.tag}|${attr(e, "src") ?? ""}`,
        ),
      ),
      ...elementsByTag(d, "dialog")
        .concat(d.elements.filter((e) => attr(e, "role") === "dialog" || attr(e, "aria-modal") === "true"))
        .filter((e, i, a) => a.indexOf(e) === i)
        .map((e) => h(d, e, `modal container <${e.tag}> aria-modal="${attr(e, "aria-modal") ?? ""}" — does Escape hand control back?`, `modal|${e.tag}`)),
      ...linesOf(d, /preventDefault\(\)/).map((l) => hAt(d, l.line, "handler", `preventDefault in a handler: ${l.text}`, `preventDefault|${l.text}`)),
    ]),

  // Language changes inside a page.
  //
  // The absence of a `lang` attribute proves NOTHING here, which is why this criterion has no
  // applicability predicate: a page with no `lang` anywhere is either a page with no change of
  // language (conforming) or a page whose foreign passages are all unmarked (failing), and
  // those are opposite verdicts. So the harvest cannot just list `lang` attributes — it has to
  // hand over the CANDIDATES too, or the agent is asked to rule on an empty set.
  //
  // Three things go in: the language each page declares, every element-level override, and
  // every text run carrying a word from a foreign lexicon. The lexicon is a lead, never a
  // verdict — "email", "test" and "sprint" are French usage now, and the decision protocol
  // already exempts proper nouns, technical terms and words that entered the vernacular.
  langParts: (docs) =>
    docs.flatMap((d) => [
      ...elementsByTag(d, "html").map((e) =>
        h(
          d,
          e,
          `page="${pageOfDoc(d.file) ?? "source"}" declares lang="${attr(e, "lang") ?? ""}" — passages in another language must override it`,
          `declaredlang|${attr(e, "lang") ?? ""}`,
        ),
      ),
      ...d.elements
        .filter((e) => e.tag !== "html" && attr(e, "lang") !== undefined)
        .map((e) => h(d, e, `lang="${attr(e, "lang")}" text="${t(e, 40)}"`, `lang|${attr(e, "lang")}|${t(e, 40)}`)),
      ...d.elements
        .filter((e) => e.children.some((c) => c.type === "text") && FOREIGN_LEXICON.test(textContent(e)) && attr(e, "lang") === undefined)
        .map((e) =>
          h(
            d,
            e,
            `candidate foreign passage, NOT marked with lang: "${t(e, 60)}" — a proper noun, a technical term or a word in common use is exempt`,
            `foreign|${t(e, 60)}`,
          ),
        ),
    ]),

  // The document's own language declaration.
  // THE LANGUAGE CODE THAT IS ACTUALLY THERE — RGAA 8.4's own subject, and NOT `docLang`.
  //
  // 8.3 and 8.4 read the same element and ask opposite questions. 8.3 (« la page a-t-elle une
  // langue par défaut ? ») is about the `<html>` element, and its subject must be present even
  // when the attribute is missing — that absence IS its non-conformity. 8.4 (« POUR CHAQUE PAGE
  // AYANT UNE LANGUE PAR DÉFAUT, le code est-il pertinent ? ») is about the code, and on a page
  // that declares none the criterion has, in the referential's own words, nothing to be about.
  //
  // Sharing `docLang` made 8.4 unclosable exactly there: the subject was seen (the `<html>`
  // element is always seen), so absence could never be concluded, and 8.4 is `judgment: true`
  // so silence never earned it a `C` either. Measured on tests/fixtures/realworld: one page
  // declares no language — that is its seeded 8.3 defect — and 8.4 stayed « à évaluer » on it
  // for ever, on every run, with nothing any adjudicator could read.
  //
  // Same correction as 13.2 and 7.4 further down: the refusal was right about the rule and
  // wrong about the SUBJECT.
  declaredLang: (docs) =>
    docs.flatMap((d) =>
      elementsByTag(d, "html")
        .filter((e) => (attr(e, "lang") ?? attr(e, "xml:lang") ?? "").trim() !== "")
        .map((e) =>
          h(
            d,
            e,
            `<html lang="${attr(e, "lang") ?? attr(e, "xml:lang")}"> — is this code the language the content is actually written in?`,
            `declaredlang|${attr(e, "lang") ?? attr(e, "xml:lang")}`,
          ),
        ),
    ),

  docLang: (docs) =>
    docs.flatMap((d) =>
      elementsByTag(d, "html").map((e) =>
        h(d, e, `<html lang="${attr(e, "lang") ?? ""}"> — is it present, valid, and the language of the content?`, `doclang|${attr(e, "lang") ?? ""}`),
      ),
    ),

  // Frames, and the title each one carries. RGAA theme 2 is about nothing else: 2.1 asks
  // whether every frame HAS a title, 2.2 whether that title is pertinent. Both used to inherit
  // `aria` from WCAG 4.1.2 and be handed every ARIA attribute in the application — measured on
  // a real run, the adjudicator answered `undecidable` on both, correctly, because nothing it
  // had been shown could settle a question about `<iframe title>`.
  frames: (docs) =>
    docs.flatMap((d) =>
      elementsByTag(d, "iframe", "frame").map((e) =>
        h(
          d,
          e,
          `<${e.tag}> title="${attr(e, "title") ?? ""}" name="${attr(e, "name") ?? ""}" src="${(attr(e, "src") ?? "").slice(0, 60)}" — un titre de cadre est-il présent, et décrit-il le contenu du cadre ?`,
          `frame|${attr(e, "title") ?? ""}|${attr(e, "src") ?? ""}`,
        ),
      ),
    ),

  // The document's title, with the page it belongs to, so "is it pertinent?" is answerable.
  docTitle: (docs) =>
    docs.flatMap((d) =>
      elementsByTag(d, "title").map((e) => h(d, e, `page="${pageOfDoc(d.file) ?? "source"}" <title>${t(e, 80)}</title>`, `doctitle|${t(e, 80)}`)),
    ),

  // The doctype — the subject of RGAA 8.1, which maps onto no WCAG 2.2 criterion, so the pack
  // is the only place it can be named.
  //
  // Three states, deliberately kept apart. A capture's `dom.html` is documentElement.outerHTML
  // and never contains a doctype, so reading the DOM for one would report "absent" on every
  // page in the world. The capture records it beside the DOM (SnapshotMeta.doctype): present
  // is the declaration, empty is a page that genuinely had none, and ABSENT is a capture taken
  // before the field existed — which is not evidence of anything and must not read as one.
  doctype: (docs) =>
    docs.flatMap((d) => {
      const page = pageOfDoc(d.file);
      if (page !== undefined) {
        const dt = d.signals?.doctype;
        if (dt === undefined) {
          return [
            hAt(
              d,
              1,
              "doctype",
              `page="${page}" — this capture predates doctype recording, so the declaration was NOT captured. That is not evidence the page lacks one: re-record the snapshots to decide this criterion.`,
              `doctype|unrecorded`,
            ),
          ];
        }
        return [hAt(d, 1, "doctype", `page="${page}" doctype=${dt === "" ? "(none on the page)" : dt}`, `doctype|${dt}`)];
      }
      const line = lineOf(d, /<!DOCTYPE/i);
      if (line === undefined) return [];
      const decl = (d.source.split("\n")[line - 1] ?? "").trim().slice(0, 80);
      return [hAt(d, line, "doctype", `source file ${decl}`, `doctype|${decl}`)];
    }),

  // A visible text label alongside an accessible name that replaces it.
  nameVsAccName: (docs) =>
    docs.flatMap((d) =>
      d.elements
        .filter((e) => INTERACTIVE_TAGS.includes(e.tag) && attr(e, "aria-label") !== undefined && t(e, 40).length > 0)
        .map((e) =>
          h(
            d,
            e,
            `visible="${t(e, 40)}" aria-label="${attr(e, "aria-label")}" — is the visible text CONTAINED in the accessible name?`,
            `namevs|${t(e, 40)}|${attr(e, "aria-label")}`,
          ),
        ),
    ),

  // Pointer, touch, gesture and drag handlers — everything a keyboard may not reach.
  pointerHandlers: (docs) =>
    docs.flatMap((d) => [
      ...d.elements
        .filter(
          (e) =>
            !INTERACTIVE_TAGS.includes(e.tag) && Object.keys(e.attribs).some((k) => /^on(click|mousedown|mouseup|mouseenter|pointerdown|touchstart)$/i.test(k)),
        )
        .map((e) => h(d, e, `<${e.tag}> carries a pointer handler but is not natively interactive — keyboard equivalent?`, `clickable|${e.tag}|${t(e, 40)}`)),
      ...linesOf(d, /\bon(?:MouseDown|PointerDown|TouchStart)\s*=/).map((l) =>
        hAt(d, l.line, "handler", `down-event handler (action must not fire on DOWN, or must be abortable): ${l.text}`, `downevent|${l.text}`),
      ),
      ...linesOf(d, /\b(?:draggable|onDragStart|useDrag|DndContext|react-beautiful-dnd|@dnd-kit)\b/).map((l) =>
        hAt(d, l.line, "drag", `drag interaction: ${l.text}`, `drag|${l.text}`),
      ),
      ...linesOf(d, /\bon(?:TouchMove|GestureStart)\s*=|\b(?:pinch|swipe|hammerjs)\b/i).map((l) =>
        hAt(d, l.line, "gesture", `gesture interaction: ${l.text}`, `gesture|${l.text}`),
      ),
    ]),

  // Single-character keyboard shortcuts.
  shortcuts: (docs) =>
    docs.flatMap((d) =>
      linesOf(d, /\b(?:key|code|charCode)\s*===?\s*["'][a-zA-Z0-9]["']/).map((l) =>
        hAt(d, l.line, "shortcut", `single-character key comparison: ${l.text}`, `shortcut|${l.text}`),
      ),
    ),

  // Instructions that lean on a sensory characteristic alone.
  sensoryText: (docs) =>
    docs.flatMap((d) =>
      linesOf(
        d,
        /\b(?:ci-dessus|ci-dessous|à droite|a droite|à gauche|a gauche|bouton (?:vert|rouge|bleu)|en rouge|en vert|le carré|la case de droite|above|below|to the right|to the left|green button|red button|round button)\b/i,
      ).map((l) => hAt(d, l.line, "text", `sensory-sounding instruction: ${l.text}`, `sensory|${l.text}`)),
    ),

  // Time limits: session expiry, meta refresh, timed redirects.
  timers: (docs) =>
    docs.flatMap((d) => [
      ...d.elements
        .filter((e) => e.tag === "meta" && (attr(e, "http-equiv") ?? "").toLowerCase() === "refresh")
        .map((e) => h(d, e, `<meta http-equiv="refresh" content="${attr(e, "content") ?? ""}">`, `metarefresh|${attr(e, "content") ?? ""}`)),
      ...linesOf(d, /\b(?:setTimeout|setInterval)\s*\(/).map((l) => hAt(d, l.line, "timer", `timer: ${l.text}`, `timer|${l.text}`)),
      ...linesOf(d, /\b(?:sessionTimeout|maxAge|expiresIn|session_max|idleTimeout)\b/i).map((l) =>
        hAt(d, l.line, "session", `session/expiry config: ${l.text}`, `session|${l.text}`),
      ),
    ]),

  // Moving, blinking or auto-updating content, and how it can be stopped.
  motion: (docs) =>
    docs.flatMap((d) => [
      ...elementsByTag(d, "marquee", "blink").map((e) => h(d, e, `<${e.tag}> — moving content with no native control`, `marquee|${e.tag}`)),
      ...d.elements
        .filter((e) => /animation|transition/.test(attr(e, "style") ?? ""))
        .map((e) => h(d, e, `inline animation: ${(attr(e, "style") ?? "").slice(0, 80)}`, `inlineanim|${(attr(e, "style") ?? "").slice(0, 80)}`)),
      ...linesOf(d, /\b(?:carousel|slider|autoplay|animation-iteration-count\s*:\s*infinite|requestAnimationFrame)\b/i).map((l) =>
        hAt(d, l.line, "motion", `moving/auto-updating content: ${l.text}`, `motion|${l.text}`),
      ),
      ...elementsByTag(d, "video", "audio").map((e) =>
        h(d, e, `<${e.tag} autoplay=${attr(e, "autoplay") !== undefined} controls=${attr(e, "controls") !== undefined}>`, `media|${e.tag}`),
      ),
    ]),

  // RGAA 4.11 — temporal players and the code that controls their consultation. This must
  // not inherit WCAG 2.1.1/2.1.2's page-wide union of pointer handlers and focusables: an
  // unrelated clickable card says nothing about whether an <audio> can be paused.
  temporalMediaControls: (docs) =>
    docs.flatMap((d) => [
      ...d.elements
        .filter((e) => e.tag === "audio" || e.tag === "video" || (["object", "embed"].includes(e.tag) && embeddedMediaKind(e) !== "non-temporal"))
        .map((e) =>
          h(
            d,
            e,
            `<${e.tag}> temporal media — controls=${attr(e, "controls") !== undefined}, autoplay=${attr(e, "autoplay") !== undefined}; can play/pause/stop and sound be operated by keyboard and pointer?`,
            `temporal-media|${e.tag}|${attr(e, "src") ?? attr(e, "data") ?? ""}|controls=${attr(e, "controls") !== undefined}`,
          ),
        ),
      ...linesOf(d, /\.(?:play|pause)\s*\(|\b(?:currentTime|muted|volume|playbackRate)\s*=|\bHTMLMediaElement\b/).map((l) =>
        hAt(d, l.line, "media-control", `custom temporal-media control: ${l.text}`, `temporal-control|${l.text}`),
      ),
    ]),

  // RGAA 4.12 — non-temporal plug-in/SVG/canvas media. Static instances are included too:
  // the adjudicator must first establish whether they expose consultation controls before it
  // can legitimately answer NA. Temporal players and generic event handlers stay out.
  nonTemporalMediaControls: (docs) =>
    docs.flatMap((d) => [
      ...d.elements
        .filter((e) => e.tag === "svg" || e.tag === "canvas" || (["object", "embed"].includes(e.tag) && embeddedMediaKind(e) !== "temporal"))
        .map((e) =>
          h(
            d,
            e,
            `<${e.tag}> non-temporal media — inspect any pan/zoom/navigation/control function for keyboard and pointer operation`,
            `non-temporal-media|${e.tag}|${attr(e, "src") ?? attr(e, "data") ?? attr(e, "id") ?? ""}`,
          ),
        ),
      ...linesOf(d, /\b(?:svgPanZoom|panzoom|zoomIn|zoomOut|getContext)\b/i).map((l) =>
        hAt(d, l.line, "media-control", `non-temporal media/control code: ${l.text}`, `non-temporal-control|${l.text}`),
      ),
    ]),

  // WCAG 2.3.1 / RGAA 13.7 — only things capable of a luminance flash. The old `motion`
  // subject mixed autoplay audio and <marquee> into this criterion while omitting ordinary
  // images, canvas, scripts and stylesheet animation rules. That gave the adjudicator lots of
  // evidence and none of the evidence the three-flash test actually asks for.
  flashes: (docs) =>
    docs.flatMap((d) => [
      ...d.elements
        .filter((e) => ["video", "img", "svg", "canvas", "embed", "object", "blink"].includes(e.tag))
        .map((e) =>
          h(
            d,
            e,
            `<${e.tag}> visual/animated content — does it flash, and if so is it at most 3 flashes/s or below the area threshold?`,
            `flash-media|${e.tag}|${attr(e, "src") ?? attr(e, "data") ?? attr(e, "id") ?? ""}`,
          ),
        ),
      ...elementsByTag(d, "script").map((e) =>
        h(d, e, `<script> — inspect for luminance/colour states toggled rapidly`, `flash-script|${attr(e, "src") ?? t(e, 80)}`),
      ),
      ...d.elements
        .filter((e) => /animation|transition/i.test(attr(e, "style") ?? ""))
        .map((e) => h(d, e, `inline visual animation: ${(attr(e, "style") ?? "").slice(0, 100)}`, `flash-inline|${attr(e, "style") ?? ""}`)),
      ...(d.signals?.css?.rules ?? [])
        .filter((r) => r.decls.animation !== undefined || r.decls.animationName !== undefined)
        .map((r) =>
          hAt(
            d,
            1,
            `css:${r.selector}`,
            `stylesheet animation: ${r.selector.slice(0, 60)} { ${declsText(r.decls)} } — inspect keyframes for rapid opposing luminance changes`,
            `flash-css|${r.selector}|${declsText(r.decls)}`,
          ),
        ),
      ...linesOf(d, /\b(?:flash|flashing|strobe|setInterval|requestAnimationFrame|classList\.(?:add|remove|replace|toggle))\b|animation(?:-name)?\s*:/i)
        .filter((l) => !/^\s*(?:<!--|\/\/|\/\*)/.test(l.text))
        .map((l) => hAt(d, l.line, "flash-code", `possible scripted/CSS flash mechanism: ${l.text}`, `flash-code|${l.text}`)),
    ]),

  // RGAA 7.2 — the script AND the alternative whose relevance must be judged. Inheriting
  // WCAG 4.1.2 used to hand this criterion every ARIA-bearing element in the repository while
  // omitting inline handlers entirely. On the realworld fixture that meant 33 unrelated
  // anchors and none of its three scripts; Haiku correctly refused to invent an association.
  // Keep the population narrow: scripts/handlers establish applicability, while noscript and
  // non-text fallbacks are the concrete alternatives covered by tests 7.2.1 and 7.2.2.
  scriptAlternatives: (docs) =>
    docs.flatMap((d) => [
      ...elementsByTag(d, "script").map((e) =>
        h(
          d,
          e,
          `<script${attr(e, "src") ? ` src="${attr(e, "src")}"` : ""}> — identify its alternative and compare the information or function`,
          `script|${attr(e, "src") ?? t(e, 100)}`,
        ),
      ),
      ...linesOf(d, /\bon[A-Z][A-Za-z]*\s*=|\son[a-z]+\s*=\s*["']/).map((l) =>
        hAt(d, l.line, "handler", `script handler — identify any alternative offering the same information or function: ${l.text}`, `handler|${l.text}`),
      ),
      ...elementsByTag(d, "noscript").map((e) =>
        h(d, e, `<noscript> alternative — does it provide content and functions similar to the associated script?`, `noscript|${t(e, 120)}`),
      ),
      ...d.elements
        .filter((e) => ["canvas", "object", "embed"].includes(e.tag) && (t(e, 120) !== "" || e.children.some((child) => child.type === "element")))
        .map((e) =>
          h(
            d,
            e,
            `<${e.tag}> fallback — if a script updates this non-text element, is its alternative updated and relevant?`,
            `script-fallback|${e.tag}|${t(e, 120)}`,
          ),
        ),
    ]),

  // A change of context initiated by a script. RGAA 7.4 / WCAG 3.2.1-3.2.2.
  //
  // THE SUBJECT IS THE SCRIPT, and getting that wrong cost a release. This used to be a list of
  // CONSEQUENCES — onFocus/onBlur/onChange, `.submit(`, `location`, `router.push`,
  // `window.open` — on the theory that a context change is one of them. It is, but the list can
  // only ever be the ways we have already seen a script change context, and a criterion whose
  // subject is « each script » cannot be answered from a catalogue of endings.
  //
  // Measured on tests/fixtures/realworld, which ships LoginForm.tsx whose form carries
  // `onSubmit={(e) => { e.preventDefault(); … }}`: 7.4 reached the adjudicator with population
  // ZERO. A script was right there, doing the thing the criterion asks about, and the harvest
  // walked past it because `onSubmit` was not on the list. The adjudicator was told « no
  // evidence » and billed to guess between NA and manual — on a page it should have been handed
  // twenty lines of React to read.
  //
  // So it collects the script FIRST: any `<script>`, any `on*` binding whatever the event, and
  // then the consequences it always looked for, which stay because they are what an adjudicator
  // most needs pointed out. Two things follow. A page with a script always arrives with it, so
  // the verdict is made on the code rather than on its absence. And a page with no script at all
  // harvests nothing — which is now a FACT about the code, not a gap in a pattern list, so 7.4
  // and 3.2.1/3.2.2 close as « not applicable » with no model in the loop (EXISTENCE_SUBJECTS).
  contextChange: (docs) =>
    docs.flatMap((d) => [
      // The script itself — the subject, before anything it goes on to do.
      ...elementsByTag(d, "script").map((e) =>
        h(
          d,
          e,
          `<script${attr(e, "src") ? ` src="${attr(e, "src")}"` : ""}> — does anything it runs change context, and is the user warned or in control?`,
          `script|${attr(e, "src") ?? "inline"}`,
        ),
      ),
      // Any handler binding, whatever the event: `onSubmit` and `onClick` change context as
      // readily as `onChange`, and a criterion about scripts has no business enumerating events.
      ...linesOf(d, /\bon[A-Z][A-Za-z]*\s*=|\son[a-z]+\s*=\s*["']/).map((l) =>
        hAt(d, l.line, "handler", `handler — does it change context (navigate, submit, open a window, move focus)? ${l.text}`, `handler|${l.text}`),
      ),
      ...linesOf(d, /\bon(?:Focus|Blur)\s*=/).map((l) =>
        hAt(d, l.line, "handler", `focus handler — does it change context (navigate, submit, move focus)? ${l.text}`, `onfocus|${l.text}`),
      ),
      ...linesOf(d, /\bonChange\s*=/).map((l) =>
        hAt(d, l.line, "handler", `change handler — does changing the value itself change context? ${l.text}`, `onchange|${l.text}`),
      ),
      ...linesOf(d, /\.submit\s*\(|\brequestSubmit\s*\(/).map((l) =>
        hAt(d, l.line, "submit", `script submits a form — is the user warned, or is it a button they pressed? ${l.text}`, `submit|${l.text}`),
      ),
      ...linesOf(d, /\blocation\s*\.\s*(?:href|assign|replace)\b|\blocation\s*=|\brouter\s*\.\s*(?:push|replace|navigate)\s*\(/).map((l) =>
        hAt(d, l.line, "navigate", `script navigates — is the change announced before it happens? ${l.text}`, `navigate|${l.text}`),
      ),
      ...linesOf(d, /\bwindow\s*\.\s*open\s*\(/).map((l) =>
        hAt(d, l.line, "open", `script opens a window — is it the user's action? ${l.text}`, `open|${l.text}`),
      ),
    ]),

  // RGAA 10.1 — the markup the standard forbids outright. The ENGINE decides this criterion
  // (src/rules/presentation.ts), so the adjudicator normally never sees it; this exists so the
  // criterion is never handed over with nothing to read, and so a reader asking « what is this
  // criterion about here? » gets the elements rather than the page's layout order.
  presentationalMarkup: (docs) =>
    docs.flatMap((d) =>
      d.elements
        .filter((e) => PRESENTATIONAL_MARKUP_TAGS.has(e.tag) || Object.keys(e.attribs).some((a) => PRESENTATIONAL_MARKUP_ATTRS.has(a.toLowerCase())))
        .map((e) =>
          h(
            d,
            e,
            `presentational markup: <${e.tag}> — styling belongs in the stylesheet (RGAA tests 10.1.1 / 10.1.2)`,
            `presentational|${e.tag}|${Object.keys(e.attribs).sort().join(",")}`,
          ),
        ),
    ),

  // RGAA 13.2 — « l'ouverture d'une nouvelle fenêtre ne doit pas être déclenchée sans action de
  // l'utilisateur ». Its own subject, because inheriting `contextChange` through WCAG 3.2.1
  // handed it focus and change handlers: a real question, and a DIFFERENT one. Measured on run
  // 32508717451: 13.2 reached the adjudicator with nothing to read, the gate refused its `C`
  // twice for citing nothing, and it took a third pass to close.
  //
  // Three ways a window opens: a `target` that is not the current browsing context, a script
  // calling `window.open`, and a meta refresh. The first and third are markup; the second is a
  // literal API call that survives minification.
  newWindow: (docs) =>
    docs.flatMap((d) => [
      ...d.elements
        .filter((e) => {
          const t = (attr(e, "target") ?? "").toLowerCase();
          return t !== "" && t !== "_self" && t !== "_parent" && t !== "_top";
        })
        .map((e) =>
          h(d, e, `target="${attr(e, "target")}" — opens outside this context; is it the user's action, and is it announced?`, `target|${attr(e, "target")}`),
        ),
      ...d.elements
        .filter((e) => e.tag === "meta" && (attr(e, "http-equiv") ?? "").toLowerCase() === "refresh")
        .map((e) => h(d, e, `meta refresh: content="${attr(e, "content")}" — a navigation nobody asked for`, `metarefresh|${attr(e, "content")}`)),
      ...linesOf(d, /\bwindow\s*\.\s*open\s*\(/).map((l) =>
        hAt(d, l.line, "open", `window.open — is it reached only from a user action? ${l.text}`, `open|${l.text}`),
      ),
    ]),

  // Reading order: anything that moves meaning-bearing content away from DOM order.
  readingOrder: (docs) =>
    docs.flatMap((d) => [
      ...d.elements
        .filter((e) => /(?:^|;)\s*order\s*:|flex-direction\s*:\s*\w+-reverse|position\s*:\s*absolute/.test(attr(e, "style") ?? ""))
        .map((e) =>
          h(
            d,
            e,
            `inline layout override: ${(attr(e, "style") ?? "").slice(0, 80)} — does it move meaning?`,
            `orderinline|${(attr(e, "style") ?? "").slice(0, 80)}`,
          ),
        ),
      ...(d.signals?.css?.rules ?? [])
        .filter((r) => r.decls.order !== undefined || /-reverse/.test(r.decls.flexDirection ?? "") || /reverse/.test(r.decls.flexFlow ?? ""))
        .slice(0, 60)
        .map((r) =>
          hAt(
            d,
            1,
            `css:${r.selector}`,
            `stylesheet reorders layout: ${r.selector.slice(0, 60)} { ${declsText(r.decls)} } — does it move meaning-bearing content?`,
            `ordercss|${r.selector}`,
          ),
        ),
    ]),

  // Office documents offered for download — the subject of "is there an accessible version?".
  downloadDocs: (docs) =>
    docs.flatMap((d) =>
      elementsByTag(d, "a")
        .filter((e) => DOWNLOAD_HREF.test(attr(e, "href") ?? ""))
        .map((e) =>
          h(
            d,
            e,
            `downloadable document: text="${t(e, 50)}" href="${attr(e, "href")}" — is an accessible version offered, and is it pertinent?`,
            `download|${t(e, 50)}|${attr(e, "href")}`,
          ),
        ),
    ),

  // Content deliberately hidden from one rendering or the other — the subject of "is what is
  // hidden from assistive technology genuinely meant to be ignored?".
  hiddenContent: (docs) =>
    docs.flatMap((d) =>
      d.elements
        .filter(
          (e) =>
            attr(e, "aria-hidden") !== undefined ||
            attr(e, "hidden") !== undefined ||
            /(?:^|[-_ ])(sr-only|visually-hidden|screen-reader|fr-sr-only)(?:[-_ ]|$)/i.test(attr(e, "class") ?? ""),
        )
        .map((e) =>
          h(
            d,
            e,
            `<${e.tag}> aria-hidden="${attr(e, "aria-hidden") ?? ""}" hidden=${attr(e, "hidden") !== undefined} class="${(attr(e, "class") ?? "").slice(0, 40)}" text="${t(e, 40)}"`,
            `hidden|${e.tag}|${attr(e, "aria-hidden") ?? ""}|${t(e, 40)}`,
          ),
        ),
    ),

  // ADDITIONAL CONTENT — the thing that appears when a component is hovered, focused or
  // activated, and the subject RGAA 10.14 and 12.11 are entirely about.
  //
  // It had no harvester at all, and the two criteria were mapped onto `focusables` +
  // `pointerHandlers` instead. On a page whose tooltip is pure CSS that harvests exactly
  // nothing to do with the question: measured on tests/fixtures/realworld, both criteria
  // reached a paid adjudicator carrying one anchor between them — `e.preventDefault();` from a
  // React submit handler — and were asked whether the site's hover content is keyboard
  // reachable. No model can answer that, and the honest verdict (`undecidable`) leaves the
  // criterion « à évaluer » forever.
  //
  // So harvest the CANDIDATES, from the four shapes additional content actually takes, and let
  // the adjudicator read the rendered page for the rest:
  //   - an explicit `role="tooltip"`, and whatever describes a control (`aria-describedby`,
  //     `aria-details`) — the trigger/target pair `probeHover` also keys on;
  //   - a disclosure: `aria-expanded` on the trigger, `aria-controls` naming the panel;
  //   - the native pair, `<details>`/`<summary>`;
  //   - the popover API (`popover`, `popovertarget`).
  // The TRIGGER goes in beside its target, because 12.11 asks whether the component can be
  // reached at all and 10.14 asks whether activating it reveals the content — both questions
  // about the trigger, neither answerable from the panel alone.
  additionalContent: (docs) =>
    docs.flatMap((d) => {
      const byId = new Map<string, El>();
      for (const e of d.elements) {
        const id = attr(e, "id");
        if (id && !byId.has(id)) byId.set(id, e);
      }
      const out: Harvested[] = [];
      const seen = new Set<number>();
      const push = (e: El, note: string, cls: string): void => {
        if (seen.has(e.start)) return;
        seen.add(e.start);
        out.push(h(d, e, note, cls));
      };
      // The panels, named by what points at them.
      for (const e of d.elements) {
        if (attr(e, "role") === "tooltip")
          push(e, `<${e.tag}> role="tooltip" text="${t(e, 60)}" — revealed how, and reachable with the keyboard?`, `tooltip|${t(e, 40)}`);
        if (attr(e, "popover") !== undefined) push(e, `<${e.tag}> popover="${attr(e, "popover") ?? ""}" text="${t(e, 60)}"`, `popover|${t(e, 40)}`);
      }
      // The triggers, and the panel each one points at.
      for (const e of d.elements) {
        for (const rel of ["aria-describedby", "aria-details", "aria-controls", "popovertarget"]) {
          const ref = (attr(e, rel) ?? "").trim().split(/\s+/)[0];
          if (!ref) continue;
          const target = byId.get(ref);
          if (!target) continue;
          // `aria-expanded` goes on the SAME line rather than into a second anchor: the element
          // is reported once (dedup by offset), so a trigger that is both a disclosure and a
          // describedby owner would otherwise lose whichever relation came second.
          const expanded = attr(e, "aria-expanded");
          push(
            e,
            `<${e.tag}> ${rel}="${ref}"${expanded !== undefined ? ` aria-expanded="${expanded}"` : ""} text="${t(e, 40)}" — the component whose hover/focus/activation reveals #${ref}`,
            `trigger|${e.tag}|${rel}|${ref}`,
          );
          push(
            target,
            `<${target.tag}> #${ref} — additional content pointed at by a ${rel} on <${e.tag}>: visible on hover only, or on focus too?`,
            `revealed|${ref}`,
          );
        }
        if (attr(e, "aria-expanded") !== undefined) {
          push(e, `<${e.tag}> aria-expanded="${attr(e, "aria-expanded") ?? ""}" text="${t(e, 40)}" — disclosure trigger`, `disclosure|${e.tag}|${t(e, 40)}`);
        }
      }
      for (const e of elementsByTag(d, "details", "summary")) {
        push(e, `<${e.tag}> text="${t(e, 60)}" — native disclosure`, `details|${e.tag}|${t(e, 40)}`);
      }
      // AND THE STYLESHEET RULE THAT DOES IT, which is what makes 10.14 « via les styles CSS
      // uniquement » a question about CSS rather than about markup. A `:hover` rule with no
      // `:focus`/`:focus-within` twin is the non-conformity itself; both together are the
      // conformity. Neither is visible in the DOM, and the adjudicator has to be shown the rule.
      out.push(
        ...linesOf(d, /:(?:hover|focus|focus-within|focus-visible)\b/).map((l) =>
          hAt(d, l.line, "css", `CSS rule keyed on a pointer/keyboard state — does the hover half have a focus twin? ${l.text}`, `cssstate|${l.text}`),
        ),
      );
      // …AND WHERE TO GO WHEN THE RULE IS NOT IN THIS FILE. An external stylesheet is not a
      // document this engine parses (`.css` is absent from glob.ts DEFAULT_EXT — engine scope is
      // markup), so a site whose tooltip lives in `styles.css` hands the adjudicator the trigger
      // and the panel and NOTHING about how either becomes visible. It has Read and Grep; what
      // it lacked was the address. Only emitted when this document really carries additional
      // content, so a page with a stylesheet and no tooltip stays silent.
      if (out.length) {
        for (const link of elementsByTag(d, "link")) {
          const rel = (attr(link, "rel") ?? "").toLowerCase();
          if (!rel.split(/\s+/).includes("stylesheet")) continue;
          const href = attr(link, "href") ?? "";
          out.push(
            h(
              d,
              link,
              `stylesheet "${href}" — this page reveals additional content and the rule that does it is NOT in this file. Open the stylesheet and check the \`:hover\` selectors for a \`:focus\`/\`:focus-within\` twin.`,
              `stylesheet|${href}`,
            ),
          );
        }
      }
      return out;
    }),

  // Content pinned over the page — what can obscure a focused element.
  stickies: (docs) =>
    docs.flatMap((d) => [
      ...d.elements
        .filter((e) => /position\s*:\s*(?:fixed|sticky)/.test(attr(e, "style") ?? ""))
        .map((e) => h(d, e, `pinned element (inline): ${(attr(e, "style") ?? "").slice(0, 60)} — can it cover a focused element?`, `sticky|${selectorFor(e)}`)),
      ...(d.signals?.css?.rules ?? [])
        .filter((r) => /^(?:fixed|sticky)$/.test((r.decls.position ?? "").trim()))
        .slice(0, 60)
        .map((r) =>
          hAt(
            d,
            1,
            `css:${r.selector}`,
            `pinned by stylesheet: ${r.selector.slice(0, 60)} { position: ${r.decls.position} } — can it cover a focused element?`,
            `stickycss|${r.selector}`,
          ),
        ),
    ]),
};

// ---- which subjects serve which criterion ------------------------------------------------
//
// EVERY success criterion the static engine cannot decide names its subjects. The integrity
// test (tests/harvest-coverage.test.ts) fails if one is missing, for the same reason the
// adjudication protocol has one: a criterion handed to the agent with nothing to look at is
// where an audit quietly becomes an opinion.

export const SC_SUBJECTS: Record<string, string[]> = {
  "1.1.1": ["images"],
  "1.2.1": ["motion"],
  "1.2.2": ["motion"],
  "1.2.3": ["motion"],
  "1.2.4": ["motion"],
  "1.2.5": ["motion"],
  "1.3.1": ["structure", "tables", "lists", "headings"],
  "1.3.2": ["readingOrder", "structure"],
  "1.3.3": ["sensoryText"],
  "1.3.4": ["readingOrder"],
  "1.3.5": ["autocomplete"],
  "1.4.1": ["colourPairs", "links"],
  "1.4.3": ["colourPairs"],
  "1.4.4": ["readingOrder"],
  "1.4.5": ["images"],
  "1.4.10": ["readingOrder"],
  "1.4.11": ["colourPairs"],
  "1.4.12": ["readingOrder"],
  // Content on Hover or Focus. Its subject IS the additional content — `aria` and `stickies`
  // were standing in for a harvester that did not exist yet.
  "1.4.13": ["additionalContent", "aria", "stickies"],
  "2.1.1": ["pointerHandlers", "focusables"],
  "2.1.2": ["focusables", "pointerHandlers"],
  "2.1.4": ["shortcuts"],
  "2.2.1": ["timers"],
  "2.2.2": ["motion", "timers"],
  "2.3.1": ["flashes"],
  "2.4.1": ["landmarks"],
  "2.4.3": ["focusOrder"],
  "2.4.4": ["links"],
  "2.4.5": ["navMechanisms", "links"],
  "2.4.6": ["headings"],
  "2.4.7": ["colourPairs"],
  "2.4.11": ["stickies"],
  "2.5.1": ["pointerHandlers"],
  "2.5.2": ["pointerHandlers"],
  "2.5.3": ["nameVsAccName"],
  "2.5.4": ["pointerHandlers"],
  "2.5.7": ["pointerHandlers"],
  "2.5.8": ["stickies", "links"],
  "3.1.2": ["langParts"],
  "3.2.1": ["contextChange"],
  "3.2.2": ["contextChange"],
  "3.2.3": ["repeatedBlocks"],
  "3.2.4": ["repeatedBlocks", "nameVsAccName"],
  "3.2.6": ["repeatedBlocks", "links"],
  "3.3.1": ["errors", "controls"],
  "3.3.2": ["controls"],
  "3.3.3": ["errors", "controls"],
  "3.3.4": ["controls", "errors"],
  "3.3.7": ["controls"],
  "3.3.8": ["controls"],
  "4.1.2": ["aria"],
  "4.1.3": ["liveRegions"],
};

/** Pack criteria whose subject is NARROWER than the union of their mapped success criteria.
 *
 *  This table is why it exists: RGAA 11.1 asks whether each form field is labelled, and maps
 *  onto [1.3.1, 2.4.6, 3.3.2, 4.1.2]. Inheriting that union hands it the whole heading
 *  outline before it ever reaches a control. A pack criterion that names its own subjects
 *  gets exactly them. Absent from this table ⇒ the union, which is right for the majority. */
export const PACK_SUBJECTS: Record<string, Record<string, string[]>> = {
  rgaa: {
    // Theme 5 — tables. The question is about the table, never about the page outline.
    "5.1": ["tables"],
    "5.2": ["tables"],
    "5.3": ["tables"],
    "5.4": ["tables"],
    "5.5": ["tables"],
    "5.6": ["tables"],
    "5.7": ["tables"],
    "5.8": ["tables"],
    // Theme 6 — links.
    "6.1": ["links"],
    "6.2": ["links"],
    // Theme 2 — frames. Both criteria are about the frame and its title, and nothing else.
    "2.1": ["frames"],
    "2.2": ["frames"],
    // Theme 8 — the document itself. 8.1 maps onto no WCAG 2.2 criterion at all, so the pack
    // is the ONLY place its subject can be named.
    "8.1": ["doctype"],
    "8.3": ["docLang"],
    // 8.4 asks about the CODE, 8.3 about the element — see `declaredLang`.
    "8.4": ["declaredLang"],
    "8.5": ["docTitle"],
    "8.6": ["docTitle"],
    "8.7": ["langParts"],
    "8.8": ["langParts"],
    "8.9": ["structure"],
    "8.10": ["readingOrder", "langParts"],
    // Theme 9 — structure.
    "9.1": ["headings"],
    "9.2": ["landmarks"],
    "9.3": ["lists"],
    "9.4": ["structure"],
    // Theme 11 — forms.
    "11.1": ["controls"],
    "11.2": ["controls"],
    "11.3": ["controls", "nameVsAccName"],
    "11.4": ["controls"],
    "11.5": ["controls"],
    "11.6": ["controls", "landmarks"],
    "11.7": ["controls", "landmarks"],
    "11.8": ["controls"],
    "11.9": ["controls"],
    "11.10": ["controls", "errors"],
    "11.11": ["errors", "controls"],
    "11.12": ["controls", "errors"],
    "11.13": ["autocomplete"],
    // Theme 12 — navigation.
    "12.1": ["navMechanisms"],
    "12.2": ["repeatedBlocks"],
    "12.3": ["navMechanisms"],
    "12.4": ["repeatedBlocks", "navMechanisms"],
    "12.5": ["repeatedBlocks"],
    "12.6": ["landmarks"],
    "12.7": ["landmarks"],
    "12.8": ["focusOrder"],
    "12.9": ["focusables", "pointerHandlers"],
    "12.10": ["shortcuts"],
    "12.11": ["additionalContent", "pointerHandlers", "focusables"],
    // Theme 4 — multimedia. 4.10 (is automatically-triggered sound controllable?) maps onto
    // WCAG 1.4.2, which is `static` and therefore has no subject of its own — but the pack
    // flags 4.10 `judgment`, so judgmentGuard reopens it and it would arrive with nothing.
    "4.10": ["motion"],
    // 4.11/4.12 map to the same keyboard SCs but ask about disjoint media populations.
    // Inheriting the union handed both criteria every pointer handler and focusable in scope.
    "4.11": ["temporalMediaControls"],
    "4.12": ["nonTemporalMediaControls"],
    // Theme 3 — colour. The question is about what colour alone conveys, not the outline.
    "3.1": ["colourPairs", "links"],
    "3.2": ["colourPairs"],
    "3.3": ["colourPairs"],
    // Theme 7 — scripts. "Is each script operable by keyboard AND pointer?" is about the
    // handlers and the focusable surface, never about the page's headings and lists.
    "7.1": ["aria", "pointerHandlers"],
    "7.2": ["scriptAlternatives"],
    "7.3": ["pointerHandlers", "focusables"],
    "7.4": ["contextChange"],
    "7.5": ["liveRegions"],
    // Theme 10 — presentation. These ask what survives when CSS is off, what the stylesheet
    // reorders, and what is hidden on purpose.
    //
    // 10.1 is the exception, and it was mis-pointed: its three tests are the closed list of
    // forbidden presentational ELEMENTS and ATTRIBUTES plus spaces used as layout, which is
    // markup — not reading order. `readingOrder` harvested nothing for it, so the criterion
    // reached the adjudicator with an empty brief and could not be ruled on at all. The engine
    // decides it now (src/rules/presentation.ts); this names what a reader would look at.
    "10.1": ["presentationalMarkup"],
    "10.2": ["hiddenContent", "structure"],
    "10.3": ["readingOrder", "structure"],
    "10.4": ["readingOrder"],
    "10.8": ["hiddenContent", "aria"],
    "10.9": ["sensoryText"],
    "10.10": ["sensoryText"],
    "10.11": ["readingOrder"],
    "10.12": ["readingOrder"],
    "10.13": ["aria", "stickies"],
    "10.14": ["additionalContent", "focusables", "pointerHandlers"],
    // Theme 13 — consultation.
    "13.1": ["timers"],
    // 13.2 asks about a window OPENING, which is not the context-change question it inherited
    // from WCAG 3.2.1. See `newWindow`.
    "13.2": ["newWindow"],
    "13.3": ["downloadDocs"],
    "13.4": ["downloadDocs"],
    "13.7": ["flashes"],
    "13.8": ["motion", "timers"],
    "13.9": ["readingOrder"],
    "13.10": ["pointerHandlers"],
    "13.11": ["pointerHandlers"],
  },
};

// ---- WHOSE EMPTINESS PROVES ABSENCE ------------------------------------------------------
//
// A subject that harvested nothing across the whole scope means one of two very different
// things, and the whole value of this table is telling them apart.
//
//   « No <table> anywhere in what was audited » is a FACT ABOUT THE CODE. Every RGAA theme-5
//   criterion then has nothing to answer, and « non applicable » is the normative verdict —
//   not « à évaluer », which claims only that nobody has looked yet.
//
//   « No heading outline harvested » is a fact about the SCOPE: it usually means no full
//   document was parsed. Concluding NA from it would clear a criterion nobody measured.
//
// Worse than useless, some absences are the non-conformity itself. `langParts` harvests
// marked-up language changes; a page that fails RGAA 8.7 has exactly zero of them.
// `liveRegions` harvests status containers; a status message nobody marked up is what 4.1.3
// exists to catch. Those must never read as "not applicable", so they are not here.
//
// The rule for adding one: could a page that FAILS this criterion harvest nothing? If yes, it
// does not belong. Uncertainty resolves towards applicable — the same direction the
// applicability predicates in src/audit.ts resolve, and for the same reason: a wrong NA is a
// non-conformity hidden inside a report someone signs, while a needless « à évaluer » only
// costs somebody the work of writing "nothing here".
//
// In practice that rule admits exactly one kind of subject: the ones that collect an ELEMENT
// SPECIES by tag or role. "No <table> in this markup" is a fact; a reader can check it. The
// subjects built on a vocabulary — `sensoryText` matches « ci-dessous » and « to the right »,
// `shortcuts` matches a single-character key comparison, `timers` matches `setTimeout` — are
// heuristics aimed at SURFACING candidates, and their silence is precisely what a page that
// fails the criterion looks like: an instruction saying « cliquez sur l'icône en forme de
// loupe » matches no word on the list. Those stay out, however tempting the criteria they
// would close.
//
// Several are also simply redundant: 1.2.x, 1.3.5, 2.1.4, 2.2.x, 2.3.1 and 2.5.x already have
// hand-written applicability predicates in src/audit.ts, which are more careful than any
// subject here and which win outright where they exist. The pack criteria that map onto them
// inherit the NA through the derivation, so nothing is lost by leaving them out.
// `downloadDocs` earns its place by the same test as the rest: it collects an element species
// by tag and attribute — `a[href]` whose target is an office document — so « no office document
// is linked anywhere in scope » is a fact a reader can check, not a heuristic's silence. It
// closes RGAA 13.3 and 13.4, whose question (« is there an accessible version? ») is a question
// about nothing when there is nothing to download. Its recall is not perfect — a document
// served from an extensionless URL is missed — which is true of every subject here and is why
// absence is only ever read as « nothing of that kind is in scope », never as conformance.
//
// `newWindow` earns its place the same way, and it is worth spelling out because the criterion
// it closes has a single test. RGAA 13.2.1 asks one thing — « vérifier qu'à l'ouverture du
// document, aucune nouvelle fenêtre n'est ouverte » — and a browser has exactly three ways to
// do it: a `target` that leaves this browsing context, a `<meta http-equiv="refresh">`, and a
// literal `window.open(`. Two are markup and the third survives minification, so a page that
// FAILS 13.2 cannot harvest nothing. Its recall is imperfect in the same way every subject here
// is — `open` reached through an alias is missed — which is why the absence still reads only as
// « nothing of that kind is in scope », never as conformance.
//
// Measured on tests/fixtures/realworld, crawled and scanned, engine v5.25.0: 13.2 was one of
// only two criteria still reaching the adjudicator with `evidenceComplete` and a population of
// zero. The engine already knew the answer and was billing a model to restate it — on the run
// this comment was written from, both were ruled NA on the first pass with no gate refusal,
// which is the definition of a paid turn that decided nothing.
//
// `contextChange` is here too NOW, and it was not before — the earlier refusal was right about
// the rule and wrong about the subject, so it is worth writing down which changed.
//
// It used to enumerate CONSEQUENCES: `.submit(`, `location.href`, `router.push`, a handful of
// handler attributes. Read that way it is a heuristic, its silence is what a failing page looks
// like, and admitting it would have bought a cheap NA at the price of a hidden non-conformity.
// That refusal stood, and it also let a real defect stand: on tests/fixtures/realworld, 7.4
// arrived with population ZERO from a page shipping `onSubmit={(e) => …}` — a script the harvest
// simply did not look for.
//
// The subject is the SCRIPT now, not the endings: any `<script>`, any `on*` binding. RGAA 7.4
// asks about « chaque script qui initie un changement de contexte », so a page that FAILS it runs
// a script, and a scope with no script anywhere has nothing for the criterion to be about. That
// is an element species, and its silence is a fact a reader can check — the same test
// `downloadDocs` and `newWindow` pass. The heuristics stay in the harvest as POINTERS for
// whoever reads it; they are no longer what decides whether the subject exists.
export const EXISTENCE_SUBJECTS: ReadonlySet<string> = new Set([
  "images",
  "tables",
  "lists",
  "links",
  "controls",
  "autocomplete",
  "errors",
  "frames",
  "downloadDocs",
  "newWindow",
  "contextChange",
  "scriptAlternatives",
  // A page that declares no default language has no language code for 8.4 to be about. The
  // `<html>` element is always there; the attribute is what this subject looks for.
  "declaredLang",
]);

/** The subjects that decide a success criterion. Empty ⇒ the criterion has none declared,
 *  which `tests/harvest-coverage.test.ts` refuses for any criterion the engine hands over. */
export const subjectsForSc = (sc: string): string[] => SC_SUBJECTS[sc] ?? [];

/** The subjects that decide a PACK criterion: its own when it declares them, else the union
 *  of its mapped success criteria's. The override is what stops RGAA 11.1 (are the fields
 *  labelled?) from being handed the page's heading outline because 1.3.1 happens to come
 *  first in its `wcag` list. */
/** The subjects a pack criterion declares FOR ITSELF, as opposed to the union it inherits from
 *  its WCAG mapping. Undefined when it declares none.
 *
 *  The distinction decides whether an INHERITED absence may close the criterion. RGAA 13.2 maps
 *  onto WCAG 3.2.1, whose subject is a script; 13.2's own subject is a window opening. On a page
 *  carrying `target="_blank"` and no script at all, 3.2.1 is legitimately « nothing of that kind
 *  in scope » — and 13.2 inherited that closure and published a conformity over an element
 *  nobody had looked at. Its own subject was right there in the harvest. */
export const ownPackSubjects = (standard: string, id: string): string[] | undefined => PACK_SUBJECTS[standard]?.[id];

export function subjectsForPackCriterion(standard: string, id: string, scs: string[]): string[] {
  const own = PACK_SUBJECTS[standard]?.[id];
  if (own) return own;
  const out: string[] = [];
  for (const sc of scs) for (const subject of subjectsForSc(sc)) if (!out.includes(subject)) out.push(subject);
  return out;
}

/** Did EVERY subject of this criterion look, across the whole scope, and find nothing — and is
 *  every one of them a subject whose emptiness proves absence?
 *
 *  `seen` is the set of subject ids that harvested at least one anchor anywhere in the audited
 *  scope, so this is an AND over the criterion's subjects and an OR over the scope. A criterion
 *  with no declared subject answers false: nothing was looked for, so nothing was proved. */
export function subjectsAbsent(ids: string[], seen: ReadonlySet<string>): boolean {
  if (!ids.length) return false;
  return ids.every((id) => EXISTENCE_SUBJECTS.has(id) && !seen.has(id));
}

/** Which subjects a document carries at least one anchor for. Used to fold absence across a
 *  scope one document at a time — the audit reads files in a stream and never holds them all,
 *  so the accounting has to be a growing set of subject ids rather than a list of anchors.
 *
 *  `skip` is what keeps this cheap: a subject already seen is never evaluated again, so after
 *  the first few documents this costs almost nothing. */
export function subjectsPresentIn(doc: Doc, skip: ReadonlySet<string>): string[] {
  const out: string[] = [];
  for (const id of EXISTENCE_SUBJECTS) {
    if (skip.has(id)) continue;
    const run = SUBJECTS[id];
    if (!run) continue;
    try {
      if (run([doc]).length) out.push(id);
    } catch {
      // A subject that throws on an odd document has looked and found nothing here; the next
      // document still gets its chance. It must never take the audit down with it.
    }
  }
  return out;
}

/** The union of the named subjects, de-duplicated by anchor. Order is the subject order, so a
 *  criterion's own subject always comes before anything it merely inherits. */
export function harvestSubjects(ids: string[], docs: Doc[]): Harvested[] {
  const out: Harvested[] = [];
  const seen = new Set<string>();
  for (const id of ids) {
    for (const item of SUBJECTS[id]?.(docs) ?? []) {
      // Keyed on the anchor's OFFSET and its class, not on `file:line:selector`: the latter
      // is shared by every element on a line, so it deduplicated forty distinct links into
      // one. Two subjects reporting the same element with the same class is the real
      // duplicate this guards against.
      const key = `${item.ev.file}:${item.at}:${item.cls}`;
      if (seen.has(key)) continue;
      seen.add(key);
      out.push(item);
    }
  }
  return out;
}