@sametalmdr/word-editor 0.2.0-alpha → 0.3.0-alpha

package/dist/io/ooxml/slots.js

@@ -1,581 +1,582 @@
-// Template scan for the fill engine (FR2, ADR-0037): where the `{tag}`s are,
-// which of them may be filled, and every reason one may not. Pure and
-// synchronous — word/document.xml's scanned tree and bytes in, a plain result
-// out. Never calls importDocx: the importer's gate (character styles,
-// wp:inline, group transforms) has nothing to say about filling.
-//
-// THE RULES (ADR-0037 Karar 1–3, 7):
-//   - A tag is the WHOLE text of one `w:t`: `{` + [a-z][a-z0-9_]* + `}`, its
-//     raw bytes equal to that text, covered by a single text node.
-//   - The only context a tag may sit in:
-//     mc:AlternateContent > mc:Choice|mc:Fallback > … > w:txbxContent > w:p >
-//     w:r > w:t, the AlternateContent holding exactly one Choice (with one
-//     wp:anchor), one Fallback and one w:txbxContent per branch, not nested,
-//     in a paragraph with no field.
-//   - The two copies are compared STRUCTURALLY; only bookmark ids may differ.
-//     When they are equal, the k-th tag of the Choice copy is the twin of the
-//     k-th tag of the Fallback copy — no VML id, bookmark name or offset is
-//     ever used to pair them.
-//   - Grammar and context problems are reported from the Choice copy (and the
-//     body) only. A brace in the Fallback copy marks its AlternateContent for
-//     the copy comparison, which is what surfaces a Fallback-only difference.
-
-import { getAttr, findChild, isElement } from "./xml-scan.js";
-import { readSections, pageForAnchor } from "./sections.js";
-import { W_NS, WP_NS, MC_NS, XML_NS } from "./ns.js";
-
-const TAG_TEXT = /^\{([a-z][a-z0-9_]*)\}$/;
-const TAG_ANYWHERE = /\{[a-z][a-z0-9_]*\}/;
-const BRACED = /\{[^{}]*\}/;
-
-// ST_OnOff's false spellings (ECMA-376 §22.9.2.7) — `<w:vanish w:val="0"/>` is not hidden.
-const ON_OFF_FALSE = new Set(["0", "false", "off"]);
-
-const textDecoder = new TextDecoder("utf-8", { fatal: true });
-
-/**
- * @typedef {object} TemplateProblem
- * @property {string} code
- * @property {string} message  never contains a data value
- * @property {string} [tag]
- * @property {number | null} [docPrId]
- * @property {number} [page]
- * @property {string} [part]
- * @property {string} [path]
- */
-
-/**
- * @typedef {object} TagSite  one tag `w:t`, in one copy
- * @property {string} name
- * @property {import("./xml-scan.js").XmlElement} t
- * @property {import("./xml-scan.js").XmlElement} run
- */
-
-/**
- * @typedef {object} TagOccurrence  one tag of a box's Choice copy, with its Fallback twin
- * @property {string} name
- * @property {number | null} docPrId
- * @property {number} page
- * @property {number} acIndex
- * @property {TagSite} choice
- * @property {TagSite} fallback
- */
-
-/**
- * @typedef {object} AlternateContentRecord
- * @property {import("./xml-scan.js").XmlElement} el
- * @property {number} index  document (pre-)order among all AlternateContents
- * @property {boolean} nested
- * @property {import("./xml-scan.js").XmlElement[]} choices
- * @property {import("./xml-scan.js").XmlElement[]} fallbacks
- * @property {import("./xml-scan.js").XmlElement[]} choiceTx
- * @property {import("./xml-scan.js").XmlElement[]} fallbackTx
- * @property {import("./xml-scan.js").XmlElement[]} choiceAnchors  wp:anchor / wp:inline in the Choice, outside any text box
- */
-
-/**
- * @typedef {object} WalkContext
- * @property {AlternateContentRecord | null} ac
- * @property {"choice" | "fallback" | null} branch
- * @property {{el: import("./xml-scan.js").XmlElement, nested: boolean} | null} txbx
- */
-
-/**
- * @param {import("./xml-scan.js").XmlElement} el
- * @returns {string}
- */
-function qname(el) {
-  return el.prefix ? `${el.prefix}:${el.localName}` : el.localName;
-}
-
-/**
- * The decoded text of a `w:t`-like element: every text and CDATA child.
- * @param {import("./xml-scan.js").XmlElement} el
- * @returns {string}
- */
-function elementText(el) {
-  let text = "";
-  for (const c of el.children) {
-    if (c.kind === "text" || c.kind === "cdata") text += c.value;
-  }
-  return text;
-}
-
-/**
- * One document-order walk over the whole tree — Choice AND Fallback, inside
- * text boxes too — building the AlternateContent records and handing every
- * `t` element to `onText` together with its ancestor stack (stack top = its
- * parent), and every `w:br` to `onBreak`. No parent pointers exist in
- * xml-scan's tree; the stack is the parent chain.
- * @param {import("./xml-scan.js").XmlElement} root
- * @param {(t: import("./xml-scan.js").XmlElement, ctx: WalkContext, stack: import("./xml-scan.js").XmlElement[]) => void} onText
- * @param {(br: import("./xml-scan.js").XmlElement) => void} [onBreak]
- * @returns {AlternateContentRecord[]}
- */
-function walk(root, onText, onBreak = () => {}) {
-  /** @type {AlternateContentRecord[]} */
-  const acs = [];
-  /** @type {import("./xml-scan.js").XmlElement[]} */
-  const stack = [];
-  /**
-   * @param {import("./xml-scan.js").XmlElement} el
-   * @param {WalkContext} ctx
-   */
-  function visit(el, ctx) {
-    stack.push(el);
-    for (const child of el.children) {
-      if (child.kind !== "element") continue;
-      if (isElement(child, MC_NS, "AlternateContent")) {
-        /** @type {AlternateContentRecord} */
-        const rec = {
-          el: child,
-          index: acs.length,
-          nested: ctx.ac !== null,
-          choices: [],
-          fallbacks: [],
-          choiceTx: [],
-          fallbackTx: [],
-          choiceAnchors: [],
-        };
-        acs.push(rec);
-        visit(child, { ac: rec, branch: null, txbx: null });
-      } else if (ctx.ac !== null && el === ctx.ac.el && isElement(child, MC_NS, "Choice")) {
-        ctx.ac.choices.push(child);
-        visit(child, { ...ctx, branch: "choice" });
-      } else if (ctx.ac !== null && el === ctx.ac.el && isElement(child, MC_NS, "Fallback")) {
-        ctx.ac.fallbacks.push(child);
-        visit(child, { ...ctx, branch: "fallback" });
-      } else if (
-        ctx.ac !== null &&
-        ctx.branch === "choice" &&
-        ctx.txbx === null &&
-        (isElement(child, WP_NS, "anchor") || isElement(child, WP_NS, "inline"))
-      ) {
-        ctx.ac.choiceAnchors.push(child);
-        visit(child, ctx);
-      } else if (isElement(child, W_NS, "txbxContent")) {
-        const txbx = { el: child, nested: ctx.txbx !== null };
-        if (ctx.ac !== null && ctx.branch !== null && !txbx.nested) {
-          (ctx.branch === "choice" ? ctx.ac.choiceTx : ctx.ac.fallbackTx).push(child);
-        }
-        visit(child, { ...ctx, txbx });
-      } else if (child.localName === "t") {
-        onText(child, ctx, stack);
-      } else if (isElement(child, W_NS, "br")) {
-        onBreak(child);
-      } else {
-        visit(child, ctx);
-      }
-    }
-    stack.pop();
-  }
-  visit(root, { ac: null, branch: null, txbx: null });
-  return acs;
-}
-
-/**
- * Every AlternateContent's structure, in the same order `scanTemplate`
- * numbers them — for checking the copies of a filled output.
- * @param {import("./xml-scan.js").XmlElement} root
- * @returns {AlternateContentRecord[]}
- */
-export function collectAlternateContents(root) {
-  return walk(root, () => {});
-}
-
-/**
- * Every `w:t` of the document, in document order, with its decoded text —
- * body, Choice and Fallback alike.
- * @param {import("./xml-scan.js").XmlElement} root
- * @returns {{el: import("./xml-scan.js").XmlElement, text: string}[]}
- */
-export function textElements(root) {
-  /** @type {{el: import("./xml-scan.js").XmlElement, text: string}[]} */
-  const out = [];
-  walk(root, (t) => {
-    if (t.uri === W_NS) out.push({ el: t, text: elementText(t) });
-  });
-  return out;
-}
-
-/**
- * @typedef {{kind: "t", el: import("./xml-scan.js").XmlElement, text: string} | {kind: "br", el: import("./xml-scan.js").XmlElement}} TextToken
- */
-
-/**
- * Every `w:t` (with its decoded text) and every `w:br` of the document, in
- * document order — body, Choice and Fallback alike. The fill's read-back
- * compares these streams (ADR-0039 Karar 4): a multi-line value is its lines'
- * `w:t`s with a `w:br` between each two, so counting `w:t`s alone would
- * accept an output whose lines were never separated.
- * @param {import("./xml-scan.js").XmlElement} root
- * @returns {TextToken[]}
- */
-export function textTokens(root) {
-  /** @type {TextToken[]} */
-  const out = [];
-  walk(
-    root,
-    (t) => {
-      if (t.uri === W_NS) out.push({ kind: "t", el: t, text: elementText(t) });
-    },
-    (br) => {
-      out.push({ kind: "br", el: br });
-    },
-  );
-  return out;
-}
-
-/**
- * Two `w:txbxContent` subtrees compared structurally: namespace + local name,
- * attributes as a set (with values), decoded text and CDATA, child order.
- * Comments count only by position — xml-scan keeps no comment text, and a
- * processing instruction is not a node at all — so two copies whose comments
- * say different things compare equal; neither is rendered. The one exemption is `w:id` on `w:bookmarkStart`/`w:bookmarkEnd`
- * (29 corpus boxes differ only there). Returns the first difference's path,
- * e.g. `w:p[1]/w:r[2]/w:rPr/w:rFonts@w:hAnsi`.
- * @param {import("./xml-scan.js").XmlElement} a
- * @param {import("./xml-scan.js").XmlElement} b
- * @returns {{equal: true} | {equal: false, path: string}}
- */
-export function compareCopies(a, b) {
-  const path = compareElements(a, b, qname(a));
-  return path === null ? { equal: true } : { equal: false, path };
-}
-
-/**
- * @param {import("./xml-scan.js").XmlElement} el
- * @param {import("./xml-scan.js").XmlAttribute} attr
- * @returns {boolean}
- */
-function isExemptAttribute(el, attr) {
-  return (
-    el.uri === W_NS &&
-    (el.localName === "bookmarkStart" || el.localName === "bookmarkEnd") &&
-    attr.uri === W_NS &&
-    attr.localName === "id"
-  );
-}
-
-/**
- * @param {import("./xml-scan.js").XmlElement} a
- * @param {import("./xml-scan.js").XmlElement} b
- * @param {string} path
- * @returns {string | null}  null when equal
- */
-function compareElements(a, b, path) {
-  if (a.uri !== b.uri || a.localName !== b.localName) return `${path} (${qname(a)} vs ${qname(b)})`;
-  const attrsA = a.attributes.filter((x) => !isExemptAttribute(a, x));
-  const attrsB = b.attributes.filter((x) => !isExemptAttribute(b, x));
-  for (const x of attrsA) {
-    const y = attrsB.find((o) => o.uri === x.uri && o.localName === x.localName);
-    const name = x.prefix ? `${x.prefix}:${x.localName}` : x.localName;
-    if (y === undefined) return `${path}@${name} (missing in the Fallback copy)`;
-    if (y.value !== x.value) return `${path}@${name} (values differ)`;
-  }
-  for (const y of attrsB) {
-    if (!attrsA.some((x) => x.uri === y.uri && x.localName === y.localName)) {
-      const name = y.prefix ? `${y.prefix}:${y.localName}` : y.localName;
-      return `${path}@${name} (missing in the Choice copy)`;
-    }
-  }
-  if (a.children.length !== b.children.length) return `${path} (child count ${a.children.length} vs ${b.children.length})`;
-  /** @type {Map<string, number>} */
-  const seen = new Map();
-  for (let i = 0; i < a.children.length; i += 1) {
-    const ca = a.children[i];
-    const cb = b.children[i];
-    if (ca.kind !== cb.kind) return `${path}/node()[${i + 1}] (${ca.kind} vs ${cb.kind})`;
-    if (ca.kind === "element" && cb.kind === "element") {
-      const key = `${ca.uri} ${ca.localName}`;
-      const n = (seen.get(key) ?? 0) + 1;
-      seen.set(key, n);
-      const diff = compareElements(ca, cb, `${path}/${qname(ca)}[${n}]`);
-      if (diff !== null) return diff;
-    } else if ((ca.kind === "text" || ca.kind === "cdata") && (cb.kind === "text" || cb.kind === "cdata")) {
-      if (ca.value !== cb.value) return `${path}/text()[${i + 1}] (text differs)`;
-    }
-  }
-  return null;
-}
-
-/**
- * @param {import("./xml-scan.js").XmlElement} t
- * @param {Uint8Array} xmlBytes
- * @returns {{kind: "none"} | {kind: "tag", name: string} | {kind: "problem", code: string, detail: string}}
- */
-function classifyText(t, xmlBytes) {
-  const text = elementText(t);
-  if (!text.includes("{") && !text.includes("}")) return { kind: "none" };
-  const only = t.children.length === 1 ? t.children[0] : null;
-  if (only === null || only.kind !== "text" || only.start !== t.contentStart || only.end !== t.contentEnd) {
-    return { kind: "problem", code: "TAG_TEXT_NOT_PLAIN", detail: "its content is not one plain text node (comment, CDATA or processing instruction)" };
-  }
-  const match = TAG_TEXT.exec(text);
-  if (match !== null) {
-    if (textDecoder.decode(xmlBytes.subarray(t.contentStart, t.contentEnd)) !== text) {
-      return { kind: "problem", code: "TAG_ENCODED", detail: "the tag is written with a character reference; write the braces and name as plain text" };
-    }
-    return { kind: "tag", name: match[1] };
-  }
-  if (TAG_ANYWHERE.test(text)) {
-    return { kind: "problem", code: "TAG_NOT_ALONE", detail: "a tag must be the whole text of its w:t, with nothing before or after it" };
-  }
-  if (BRACED.test(text)) {
-    return { kind: "problem", code: "INVALID_TAG_NAME", detail: "a tag name is a lowercase ASCII letter followed by lowercase ASCII letters, digits or _" };
-  }
-  return { kind: "problem", code: "STRAY_BRACE", detail: "a brace that is not part of a whole-w:t tag (a tag split across runs looks like this)" };
-}
-
-/**
- * Why a tag `w:t` sits in a context the engine does not fill, or null.
- * @param {import("./xml-scan.js").XmlElement} t
- * @param {WalkContext} ctx
- * @param {import("./xml-scan.js").XmlElement[]} stack  stack top = the w:t's parent
- * @returns {{code: string, detail: string} | null}
- */
-function contextProblem(t, ctx, stack) {
-  if (t.uri !== W_NS) {
-    return { code: "TAG_CONTEXT_UNSUPPORTED", detail: `a brace in <${qname(t)}> (only w:t is filled)` };
-  }
-  if (ctx.txbx === null) {
-    if (ctx.ac === null) return { code: "TAG_OUTSIDE_TEXT_BOX", detail: "tags are filled only inside text boxes" };
-    return { code: "TAG_CONTEXT_UNSUPPORTED", detail: "a w:t inside mc:AlternateContent but outside any w:txbxContent" };
-  }
-  if (ctx.txbx.nested) return { code: "TAG_CONTEXT_UNSUPPORTED", detail: "a text box nested inside another text box" };
-  if (ctx.ac === null || ctx.branch === null) {
-    return { code: "TAG_CONTEXT_UNSUPPORTED", detail: "a text box outside mc:AlternateContent (VML-only or a bare w:drawing)" };
-  }
-  const run = stack[stack.length - 1];
-  const paragraph = stack[stack.length - 2];
-  const box = stack[stack.length - 3];
-  if (!isElement(run, W_NS, "r")) return { code: "TAG_CONTEXT_UNSUPPORTED", detail: `the w:t sits in <${qname(run)}>, not directly in a w:r` };
-  if (paragraph === undefined || !isElement(paragraph, W_NS, "p")) {
-    return { code: "TAG_CONTEXT_UNSUPPORTED", detail: `the run sits in <${paragraph === undefined ? "?" : qname(paragraph)}>, not directly in a w:p` };
-  }
-  if (box !== ctx.txbx.el) {
-    return { code: "TAG_CONTEXT_UNSUPPORTED", detail: `the paragraph sits in <${box === undefined ? "?" : qname(box)}>, not directly in the w:txbxContent` };
-  }
-  if (hasField(paragraph)) return { code: "TAG_CONTEXT_UNSUPPORTED", detail: "the paragraph holds a field (w:fldChar / w:instrText)" };
-  return null;
-}
-
-/**
- * @param {import("./xml-scan.js").XmlElement} el
- * @returns {boolean}
- */
-function hasField(el) {
-  for (const c of el.children) {
-    if (c.kind !== "element") continue;
-    if (isElement(c, W_NS, "fldChar") || isElement(c, W_NS, "instrText") || isElement(c, W_NS, "fldSimple")) return true;
-    if (hasField(c)) return true;
-  }
-  return false;
-}
-
-/**
- * Null when the tag `w:t`'s start tag can be kept or given `xml:space`, else why not.
- * @param {import("./xml-scan.js").XmlElement} t
- * @returns {string | null}
- */
-function attributeProblem(t) {
-  if (t.attributes.length === 0) return null;
-  const only = t.attributes.length === 1 ? t.attributes[0] : null;
-  if (only !== null && only.uri === XML_NS && only.localName === "space" && only.value === "preserve") return null;
-  return `the tag's w:t carries attributes other than xml:space="preserve" (${t.attributes.map((x) => (x.prefix ? `${x.prefix}:` : "") + x.localName).join(", ")})`;
-}
-
-/**
- * The run's direct `w:rFonts` sets one of the ascii/hAnsi slots but not the
- * other, or sets them to different fonts (FILL-E1: Turkish letters then draw
- * in another font than the rest of the value).
- * @param {import("./xml-scan.js").XmlElement} run
- * @returns {boolean}
- */
-function fontSlotsSplit(run) {
-  const rPr = findChild(run, W_NS, "rPr");
-  const rFonts = rPr && findChild(rPr, W_NS, "rFonts");
-  if (!rFonts) return false;
-  const ascii = getAttr(rFonts, W_NS, "asciiTheme") ?? getAttr(rFonts, W_NS, "ascii");
-  const hAnsi = getAttr(rFonts, W_NS, "hAnsiTheme") ?? getAttr(rFonts, W_NS, "hAnsi");
-  if (ascii === undefined && hAnsi === undefined) return false;
-  return ascii !== hAnsi;
-}
-
-/**
- * @param {import("./xml-scan.js").XmlElement} run
- * @returns {boolean}
- */
-function isHidden(run) {
-  const rPr = findChild(run, W_NS, "rPr");
-  const vanish = rPr && findChild(rPr, W_NS, "vanish");
-  if (!vanish) return false;
-  const val = getAttr(vanish, W_NS, "val");
-  return val === undefined || !ON_OFF_FALSE.has(val);
-}
-
-/**
- * @typedef {object} ScanResult
- * @property {TagOccurrence[]} occurrences  document order (Choice copy)
- * @property {TemplateProblem[]} problems
- * @property {TemplateProblem[]} warnings
- * @property {AlternateContentRecord[]} acs
- */
-
-/**
- * @param {import("./xml-scan.js").XmlElement} root  scanXml(xmlBytes).root
- * @param {Uint8Array} xmlBytes
- * @returns {ScanResult}
- */
-export function scanTemplate(root, xmlBytes) {
-  const { page, sectPrStarts } = readSections(root);
-  /** @type {{t: import("./xml-scan.js").XmlElement, code: string, detail: string, acIndex: number | null, tag?: string}[]} */
-  const pending = [];
-  /** @type {Map<number, {choice: TagSite[], fallback: TagSite[], braces: boolean}>} */
-  const byAc = new Map();
-  /** @param {number} index */
-  const acEntry = (index) => {
-    let entry = byAc.get(index);
-    if (entry === undefined) {
-      entry = { choice: [], fallback: [], braces: false };
-      byAc.set(index, entry);
-    }
-    return entry;
-  };
-
-  const acs = walk(root, (t, ctx, stack) => {
-    const verdict = classifyText(t, xmlBytes);
-    if (verdict.kind === "none") return;
-    const acIndex = ctx.ac === null ? null : ctx.ac.index;
-    if (acIndex !== null) acEntry(acIndex).braces = true;
-    const reportHere = ctx.branch !== "fallback";
-    if (verdict.kind === "problem") {
-      if (reportHere) pending.push({ t, code: verdict.code, detail: verdict.detail, acIndex });
-      return;
-    }
-    const where = contextProblem(t, ctx, stack);
-    if (where !== null) {
-      if (reportHere) pending.push({ t, code: where.code, detail: where.detail, acIndex, tag: verdict.name });
-      return;
-    }
-    const attrs = attributeProblem(t);
-    if (attrs !== null) {
-      if (reportHere) pending.push({ t, code: "TAG_TEXT_ATTRIBUTES", detail: attrs, acIndex, tag: verdict.name });
-      return;
-    }
-    const site = { name: verdict.name, t, run: stack[stack.length - 1] };
-    const entry = acEntry(/** @type {number} */ (acIndex));
-    (ctx.branch === "choice" ? entry.choice : entry.fallback).push(site);
-  });
-
-  /** @type {Map<number, {docPrId: number | null, page: number}>} */
-  const attribution = new Map();
-  /** @type {TemplateProblem[]} */
-  const acProblems = [];
-  /** @type {TemplateProblem[]} */
-  const warnings = [];
-  /** @type {TagOccurrence[]} */
-  const occurrences = [];
-
-  for (const [index, entry] of [...byAc.entries()].sort((x, y) => x[0] - y[0])) {
-    const ac = acs[index];
-    const anchor = ac.choiceAnchors.length === 1 ? ac.choiceAnchors[0] : null;
-    const shapeIssues = [];
-    if (ac.nested) shapeIssues.push("it is nested inside another mc:AlternateContent");
-    if (ac.choices.length !== 1) shapeIssues.push(`${ac.choices.length} mc:Choice`);
-    if (ac.fallbacks.length !== 1) shapeIssues.push(`${ac.fallbacks.length} mc:Fallback`);
-    if (ac.choiceTx.length !== 1) shapeIssues.push(`${ac.choiceTx.length} w:txbxContent in the Choice`);
-    if (ac.fallbackTx.length !== 1) shapeIssues.push(`${ac.fallbackTx.length} w:txbxContent in the Fallback`);
-    if (anchor === null) shapeIssues.push(`${ac.choiceAnchors.length} wp:anchor/wp:inline in the Choice`);
-    else if (!isElement(anchor, WP_NS, "anchor")) shapeIssues.push("the Choice holds wp:inline, not wp:anchor");
-
-    /** @type {number | null} */
-    let docPrId = null;
-    let pageNumber = pageForAnchor(sectPrStarts, ac.el.start, page.count);
-    if (anchor !== null) {
-      pageNumber = pageForAnchor(sectPrStarts, anchor.start, page.count);
-      const docPr = findChild(anchor, WP_NS, "docPr");
-      const id = docPr ? getAttr(docPr, "", "id") : undefined;
-      if (id !== undefined && /^[0-9]+$/.test(id)) docPrId = Number(id);
-    }
-    attribution.set(index, { docPrId, page: pageNumber });
-
-    if (shapeIssues.length > 0) {
-      acProblems.push({
-        code: "ALTERNATE_CONTENT_SHAPE",
-        message: `the text box holding a tag does not have the shape the engine fills: ${shapeIssues.join("; ")}`,
-        docPrId,
-        page: pageNumber,
-      });
-      continue;
-    }
-    const copies = compareCopies(ac.choiceTx[0], ac.fallbackTx[0]);
-    if (!copies.equal) {
-      acProblems.push({
-        code: "COPIES_DIFFER",
-        message: `the box's mc:Choice and mc:Fallback copies differ at ${copies.path}`,
-        docPrId,
-        page: pageNumber,
-        path: copies.path,
-      });
-      continue;
-    }
-    // Structurally equal trees can still spell a tag differently in raw bytes
-    // (a character reference in one copy) — compare the twin lists themselves.
-    const twinsMatch =
-      entry.choice.length === entry.fallback.length && entry.choice.every((site, i) => site.name === entry.fallback[i].name);
-    if (!twinsMatch) {
-      acProblems.push({
-        code: "COPIES_DIFFER",
-        message: "the box's mc:Choice and mc:Fallback copies do not hold the same tags",
-        docPrId,
-        page: pageNumber,
-      });
-      continue;
-    }
-    if (anchor !== null && docPrId === null) {
-      warnings.push({ code: "DOCPR_MISSING", message: "a text box holding a tag has no numeric wp:docPr id", page: pageNumber });
-    }
-    entry.choice.forEach((site, i) => {
-      occurrences.push({ name: site.name, docPrId, page: pageNumber, acIndex: index, choice: site, fallback: entry.fallback[i] });
-    });
-  }
-
-  /** @type {TemplateProblem[]} */
-  const problems = pending.map((p) => {
-    const where = p.acIndex !== null && attribution.has(p.acIndex)
-      ? /** @type {{docPrId: number | null, page: number}} */ (attribution.get(p.acIndex))
-      : { docPrId: null, page: pageForAnchor(sectPrStarts, p.t.start, page.count) };
-    /** @type {TemplateProblem} */
-    const problem = { code: p.code, message: p.detail, docPrId: where.docPrId, page: where.page };
-    if (p.tag !== undefined) problem.tag = p.tag;
-    return problem;
-  });
-  problems.push(...acProblems);
-
-  /** @type {Map<number, number>} */
-  const docPrUse = new Map();
-  for (const index of new Set(occurrences.map((o) => o.acIndex))) {
-    const id = /** @type {{docPrId: number | null}} */ (attribution.get(index)).docPrId;
-    if (id !== null) docPrUse.set(id, (docPrUse.get(id) ?? 0) + 1);
-  }
-  for (const [id, n] of docPrUse) {
-    if (n > 1) warnings.push({ code: "DUPLICATE_DOCPR_ID", message: `${n} text boxes holding tags share wp:docPr id ${id}`, docPrId: id });
-  }
-  for (const o of occurrences) {
-    if (fontSlotsSplit(o.choice.run)) {
-      warnings.push({
-        code: "FONT_SLOTS_SPLIT",
-        message: "the tag's run sets the ascii and hAnsi font slots differently, so Turkish letters may draw in another font",
-        tag: o.name,
-        docPrId: o.docPrId,
-        page: o.page,
-      });
-    }
-    if (isHidden(o.choice.run)) {
-      warnings.push({ code: "HIDDEN_TAG_RUN", message: "the tag's run is hidden (w:vanish)", tag: o.name, docPrId: o.docPrId, page: o.page });
-    }
-  }
-
-  return { occurrences, problems, warnings, acs };
-}
+// Template scan for the fill engine (FR2, ADR-0037): where the `{tag}`s are,
+// which of them may be filled, and every reason one may not. Pure and
+// synchronous — word/document.xml's scanned tree and bytes in, a plain result
+// out. Never calls importDocx: the importer's gate (character styles,
+// wp:inline, group transforms) has nothing to say about filling.
+//
+// THE RULES (ADR-0037 Karar 1–3, 7):
+//   - A tag is the WHOLE text of one `w:t`: `{` + [a-z][a-z0-9_]* + `}`, its
+//     raw bytes equal to that text, covered by a single text node.
+//   - The only context a tag may sit in:
+//     mc:AlternateContent > mc:Choice|mc:Fallback > … > w:txbxContent > w:p >
+//     w:r > w:t, the AlternateContent holding exactly one Choice (with one
+//     wp:anchor), one Fallback and one w:txbxContent per branch, not nested,
+//     in a paragraph with no field.
+//   - The two copies are compared STRUCTURALLY; only bookmark ids may differ.
+//     When they are equal, the k-th tag of the Choice copy is the twin of the
+//     k-th tag of the Fallback copy — no VML id, bookmark name or offset is
+//     ever used to pair them.
+//   - Grammar and context problems are reported from the Choice copy (and the
+//     body) only. A brace in the Fallback copy marks its AlternateContent for
+//     the copy comparison, which is what surfaces a Fallback-only difference.
+
+import { getAttr, findChild, isElement } from "./xml-scan.js";
+import { readSections, pageForAnchor } from "./sections.js";
+import { W_NS, WP_NS, MC_NS, XML_NS } from "./ns.js";
+
+const TAG_TEXT = /^\{([a-z][a-z0-9_]*)\}$/;
+const TAG_ANYWHERE = /\{[a-z][a-z0-9_]*\}/;
+const BRACED = /\{[^{}]*\}/;
+
+// ST_OnOff's false spellings (ECMA-376 §22.9.2.7) — `<w:vanish w:val="0"/>` is not hidden.
+const ON_OFF_FALSE = new Set(["0", "false", "off"]);
+
+const textDecoder = new TextDecoder("utf-8", { fatal: true });
+
+/**
+ * @typedef {object} TemplateProblem
+ * @property {string} code
+ * @property {string} message  never contains a data value
+ * @property {string} [tag]
+ * @property {number | null} [docPrId]
+ * @property {number} [page]
+ * @property {string} [part]
+ * @property {string} [path]
+ */
+
+/**
+ * @typedef {object} TagSite  one tag `w:t`, in one copy
+ * @property {string} name
+ * @property {import("./xml-scan.js").XmlElement} t
+ * @property {import("./xml-scan.js").XmlElement} run
+ * @property {import("./xml-scan.js").XmlElement} paragraph  the w:p holding the run (contextProblem checked it)
+ */
+
+/**
+ * @typedef {object} TagOccurrence  one tag of a box's Choice copy, with its Fallback twin
+ * @property {string} name
+ * @property {number | null} docPrId
+ * @property {number} page
+ * @property {number} acIndex
+ * @property {TagSite} choice
+ * @property {TagSite} fallback
+ */
+
+/**
+ * @typedef {object} AlternateContentRecord
+ * @property {import("./xml-scan.js").XmlElement} el
+ * @property {number} index  document (pre-)order among all AlternateContents
+ * @property {boolean} nested
+ * @property {import("./xml-scan.js").XmlElement[]} choices
+ * @property {import("./xml-scan.js").XmlElement[]} fallbacks
+ * @property {import("./xml-scan.js").XmlElement[]} choiceTx
+ * @property {import("./xml-scan.js").XmlElement[]} fallbackTx
+ * @property {import("./xml-scan.js").XmlElement[]} choiceAnchors  wp:anchor / wp:inline in the Choice, outside any text box
+ */
+
+/**
+ * @typedef {object} WalkContext
+ * @property {AlternateContentRecord | null} ac
+ * @property {"choice" | "fallback" | null} branch
+ * @property {{el: import("./xml-scan.js").XmlElement, nested: boolean} | null} txbx
+ */
+
+/**
+ * @param {import("./xml-scan.js").XmlElement} el
+ * @returns {string}
+ */
+function qname(el) {
+  return el.prefix ? `${el.prefix}:${el.localName}` : el.localName;
+}
+
+/**
+ * The decoded text of a `w:t`-like element: every text and CDATA child.
+ * @param {import("./xml-scan.js").XmlElement} el
+ * @returns {string}
+ */
+function elementText(el) {
+  let text = "";
+  for (const c of el.children) {
+    if (c.kind === "text" || c.kind === "cdata") text += c.value;
+  }
+  return text;
+}
+
+/**
+ * One document-order walk over the whole tree — Choice AND Fallback, inside
+ * text boxes too — building the AlternateContent records and handing every
+ * `t` element to `onText` together with its ancestor stack (stack top = its
+ * parent), and every `w:br` to `onBreak`. No parent pointers exist in
+ * xml-scan's tree; the stack is the parent chain.
+ * @param {import("./xml-scan.js").XmlElement} root
+ * @param {(t: import("./xml-scan.js").XmlElement, ctx: WalkContext, stack: import("./xml-scan.js").XmlElement[]) => void} onText
+ * @param {(br: import("./xml-scan.js").XmlElement) => void} [onBreak]
+ * @returns {AlternateContentRecord[]}
+ */
+function walk(root, onText, onBreak = () => {}) {
+  /** @type {AlternateContentRecord[]} */
+  const acs = [];
+  /** @type {import("./xml-scan.js").XmlElement[]} */
+  const stack = [];
+  /**
+   * @param {import("./xml-scan.js").XmlElement} el
+   * @param {WalkContext} ctx
+   */
+  function visit(el, ctx) {
+    stack.push(el);
+    for (const child of el.children) {
+      if (child.kind !== "element") continue;
+      if (isElement(child, MC_NS, "AlternateContent")) {
+        /** @type {AlternateContentRecord} */
+        const rec = {
+          el: child,
+          index: acs.length,
+          nested: ctx.ac !== null,
+          choices: [],
+          fallbacks: [],
+          choiceTx: [],
+          fallbackTx: [],
+          choiceAnchors: [],
+        };
+        acs.push(rec);
+        visit(child, { ac: rec, branch: null, txbx: null });
+      } else if (ctx.ac !== null && el === ctx.ac.el && isElement(child, MC_NS, "Choice")) {
+        ctx.ac.choices.push(child);
+        visit(child, { ...ctx, branch: "choice" });
+      } else if (ctx.ac !== null && el === ctx.ac.el && isElement(child, MC_NS, "Fallback")) {
+        ctx.ac.fallbacks.push(child);
+        visit(child, { ...ctx, branch: "fallback" });
+      } else if (
+        ctx.ac !== null &&
+        ctx.branch === "choice" &&
+        ctx.txbx === null &&
+        (isElement(child, WP_NS, "anchor") || isElement(child, WP_NS, "inline"))
+      ) {
+        ctx.ac.choiceAnchors.push(child);
+        visit(child, ctx);
+      } else if (isElement(child, W_NS, "txbxContent")) {
+        const txbx = { el: child, nested: ctx.txbx !== null };
+        if (ctx.ac !== null && ctx.branch !== null && !txbx.nested) {
+          (ctx.branch === "choice" ? ctx.ac.choiceTx : ctx.ac.fallbackTx).push(child);
+        }
+        visit(child, { ...ctx, txbx });
+      } else if (child.localName === "t") {
+        onText(child, ctx, stack);
+      } else if (isElement(child, W_NS, "br")) {
+        onBreak(child);
+      } else {
+        visit(child, ctx);
+      }
+    }
+    stack.pop();
+  }
+  visit(root, { ac: null, branch: null, txbx: null });
+  return acs;
+}
+
+/**
+ * Every AlternateContent's structure, in the same order `scanTemplate`
+ * numbers them — for checking the copies of a filled output.
+ * @param {import("./xml-scan.js").XmlElement} root
+ * @returns {AlternateContentRecord[]}
+ */
+export function collectAlternateContents(root) {
+  return walk(root, () => {});
+}
+
+/**
+ * Every `w:t` of the document, in document order, with its decoded text —
+ * body, Choice and Fallback alike.
+ * @param {import("./xml-scan.js").XmlElement} root
+ * @returns {{el: import("./xml-scan.js").XmlElement, text: string}[]}
+ */
+export function textElements(root) {
+  /** @type {{el: import("./xml-scan.js").XmlElement, text: string}[]} */
+  const out = [];
+  walk(root, (t) => {
+    if (t.uri === W_NS) out.push({ el: t, text: elementText(t) });
+  });
+  return out;
+}
+
+/**
+ * @typedef {{kind: "t", el: import("./xml-scan.js").XmlElement, text: string} | {kind: "br", el: import("./xml-scan.js").XmlElement}} TextToken
+ */
+
+/**
+ * Every `w:t` (with its decoded text) and every `w:br` of the document, in
+ * document order — body, Choice and Fallback alike. The fill's read-back
+ * compares these streams (ADR-0039 Karar 4): a multi-line value is its lines'
+ * `w:t`s with a `w:br` between each two, so counting `w:t`s alone would
+ * accept an output whose lines were never separated.
+ * @param {import("./xml-scan.js").XmlElement} root
+ * @returns {TextToken[]}
+ */
+export function textTokens(root) {
+  /** @type {TextToken[]} */
+  const out = [];
+  walk(
+    root,
+    (t) => {
+      if (t.uri === W_NS) out.push({ kind: "t", el: t, text: elementText(t) });
+    },
+    (br) => {
+      out.push({ kind: "br", el: br });
+    },
+  );
+  return out;
+}
+
+/**
+ * Two `w:txbxContent` subtrees compared structurally: namespace + local name,
+ * attributes as a set (with values), decoded text and CDATA, child order.
+ * Comments count only by position — xml-scan keeps no comment text, and a
+ * processing instruction is not a node at all — so two copies whose comments
+ * say different things compare equal; neither is rendered. The one exemption is `w:id` on `w:bookmarkStart`/`w:bookmarkEnd`
+ * (29 corpus boxes differ only there). Returns the first difference's path,
+ * e.g. `w:p[1]/w:r[2]/w:rPr/w:rFonts@w:hAnsi`.
+ * @param {import("./xml-scan.js").XmlElement} a
+ * @param {import("./xml-scan.js").XmlElement} b
+ * @returns {{equal: true} | {equal: false, path: string}}
+ */
+export function compareCopies(a, b) {
+  const path = compareElements(a, b, qname(a));
+  return path === null ? { equal: true } : { equal: false, path };
+}
+
+/**
+ * @param {import("./xml-scan.js").XmlElement} el
+ * @param {import("./xml-scan.js").XmlAttribute} attr
+ * @returns {boolean}
+ */
+function isExemptAttribute(el, attr) {
+  return (
+    el.uri === W_NS &&
+    (el.localName === "bookmarkStart" || el.localName === "bookmarkEnd") &&
+    attr.uri === W_NS &&
+    attr.localName === "id"
+  );
+}
+
+/**
+ * @param {import("./xml-scan.js").XmlElement} a
+ * @param {import("./xml-scan.js").XmlElement} b
+ * @param {string} path
+ * @returns {string | null}  null when equal
+ */
+function compareElements(a, b, path) {
+  if (a.uri !== b.uri || a.localName !== b.localName) return `${path} (${qname(a)} vs ${qname(b)})`;
+  const attrsA = a.attributes.filter((x) => !isExemptAttribute(a, x));
+  const attrsB = b.attributes.filter((x) => !isExemptAttribute(b, x));
+  for (const x of attrsA) {
+    const y = attrsB.find((o) => o.uri === x.uri && o.localName === x.localName);
+    const name = x.prefix ? `${x.prefix}:${x.localName}` : x.localName;
+    if (y === undefined) return `${path}@${name} (missing in the Fallback copy)`;
+    if (y.value !== x.value) return `${path}@${name} (values differ)`;
+  }
+  for (const y of attrsB) {
+    if (!attrsA.some((x) => x.uri === y.uri && x.localName === y.localName)) {
+      const name = y.prefix ? `${y.prefix}:${y.localName}` : y.localName;
+      return `${path}@${name} (missing in the Choice copy)`;
+    }
+  }
+  if (a.children.length !== b.children.length) return `${path} (child count ${a.children.length} vs ${b.children.length})`;
+  /** @type {Map<string, number>} */
+  const seen = new Map();
+  for (let i = 0; i < a.children.length; i += 1) {
+    const ca = a.children[i];
+    const cb = b.children[i];
+    if (ca.kind !== cb.kind) return `${path}/node()[${i + 1}] (${ca.kind} vs ${cb.kind})`;
+    if (ca.kind === "element" && cb.kind === "element") {
+      const key = `${ca.uri} ${ca.localName}`;
+      const n = (seen.get(key) ?? 0) + 1;
+      seen.set(key, n);
+      const diff = compareElements(ca, cb, `${path}/${qname(ca)}[${n}]`);
+      if (diff !== null) return diff;
+    } else if ((ca.kind === "text" || ca.kind === "cdata") && (cb.kind === "text" || cb.kind === "cdata")) {
+      if (ca.value !== cb.value) return `${path}/text()[${i + 1}] (text differs)`;
+    }
+  }
+  return null;
+}
+
+/**
+ * @param {import("./xml-scan.js").XmlElement} t
+ * @param {Uint8Array} xmlBytes
+ * @returns {{kind: "none"} | {kind: "tag", name: string} | {kind: "problem", code: string, detail: string}}
+ */
+function classifyText(t, xmlBytes) {
+  const text = elementText(t);
+  if (!text.includes("{") && !text.includes("}")) return { kind: "none" };
+  const only = t.children.length === 1 ? t.children[0] : null;
+  if (only === null || only.kind !== "text" || only.start !== t.contentStart || only.end !== t.contentEnd) {
+    return { kind: "problem", code: "TAG_TEXT_NOT_PLAIN", detail: "its content is not one plain text node (comment, CDATA or processing instruction)" };
+  }
+  const match = TAG_TEXT.exec(text);
+  if (match !== null) {
+    if (textDecoder.decode(xmlBytes.subarray(t.contentStart, t.contentEnd)) !== text) {
+      return { kind: "problem", code: "TAG_ENCODED", detail: "the tag is written with a character reference; write the braces and name as plain text" };
+    }
+    return { kind: "tag", name: match[1] };
+  }
+  if (TAG_ANYWHERE.test(text)) {
+    return { kind: "problem", code: "TAG_NOT_ALONE", detail: "a tag must be the whole text of its w:t, with nothing before or after it" };
+  }
+  if (BRACED.test(text)) {
+    return { kind: "problem", code: "INVALID_TAG_NAME", detail: "a tag name is a lowercase ASCII letter followed by lowercase ASCII letters, digits or _" };
+  }
+  return { kind: "problem", code: "STRAY_BRACE", detail: "a brace that is not part of a whole-w:t tag (a tag split across runs looks like this)" };
+}
+
+/**
+ * Why a tag `w:t` sits in a context the engine does not fill, or null.
+ * @param {import("./xml-scan.js").XmlElement} t
+ * @param {WalkContext} ctx
+ * @param {import("./xml-scan.js").XmlElement[]} stack  stack top = the w:t's parent
+ * @returns {{code: string, detail: string} | null}
+ */
+function contextProblem(t, ctx, stack) {
+  if (t.uri !== W_NS) {
+    return { code: "TAG_CONTEXT_UNSUPPORTED", detail: `a brace in <${qname(t)}> (only w:t is filled)` };
+  }
+  if (ctx.txbx === null) {
+    if (ctx.ac === null) return { code: "TAG_OUTSIDE_TEXT_BOX", detail: "tags are filled only inside text boxes" };
+    return { code: "TAG_CONTEXT_UNSUPPORTED", detail: "a w:t inside mc:AlternateContent but outside any w:txbxContent" };
+  }
+  if (ctx.txbx.nested) return { code: "TAG_CONTEXT_UNSUPPORTED", detail: "a text box nested inside another text box" };
+  if (ctx.ac === null || ctx.branch === null) {
+    return { code: "TAG_CONTEXT_UNSUPPORTED", detail: "a text box outside mc:AlternateContent (VML-only or a bare w:drawing)" };
+  }
+  const run = stack[stack.length - 1];
+  const paragraph = stack[stack.length - 2];
+  const box = stack[stack.length - 3];
+  if (!isElement(run, W_NS, "r")) return { code: "TAG_CONTEXT_UNSUPPORTED", detail: `the w:t sits in <${qname(run)}>, not directly in a w:r` };
+  if (paragraph === undefined || !isElement(paragraph, W_NS, "p")) {
+    return { code: "TAG_CONTEXT_UNSUPPORTED", detail: `the run sits in <${paragraph === undefined ? "?" : qname(paragraph)}>, not directly in a w:p` };
+  }
+  if (box !== ctx.txbx.el) {
+    return { code: "TAG_CONTEXT_UNSUPPORTED", detail: `the paragraph sits in <${box === undefined ? "?" : qname(box)}>, not directly in the w:txbxContent` };
+  }
+  if (hasField(paragraph)) return { code: "TAG_CONTEXT_UNSUPPORTED", detail: "the paragraph holds a field (w:fldChar / w:instrText)" };
+  return null;
+}
+
+/**
+ * @param {import("./xml-scan.js").XmlElement} el
+ * @returns {boolean}
+ */
+function hasField(el) {
+  for (const c of el.children) {
+    if (c.kind !== "element") continue;
+    if (isElement(c, W_NS, "fldChar") || isElement(c, W_NS, "instrText") || isElement(c, W_NS, "fldSimple")) return true;
+    if (hasField(c)) return true;
+  }
+  return false;
+}
+
+/**
+ * Null when the tag `w:t`'s start tag can be kept or given `xml:space`, else why not.
+ * @param {import("./xml-scan.js").XmlElement} t
+ * @returns {string | null}
+ */
+function attributeProblem(t) {
+  if (t.attributes.length === 0) return null;
+  const only = t.attributes.length === 1 ? t.attributes[0] : null;
+  if (only !== null && only.uri === XML_NS && only.localName === "space" && only.value === "preserve") return null;
+  return `the tag's w:t carries attributes other than xml:space="preserve" (${t.attributes.map((x) => (x.prefix ? `${x.prefix}:` : "") + x.localName).join(", ")})`;
+}
+
+/**
+ * The run's direct `w:rFonts` sets one of the ascii/hAnsi slots but not the
+ * other, or sets them to different fonts (FILL-E1: Turkish letters then draw
+ * in another font than the rest of the value).
+ * @param {import("./xml-scan.js").XmlElement} run
+ * @returns {boolean}
+ */
+function fontSlotsSplit(run) {
+  const rPr = findChild(run, W_NS, "rPr");
+  const rFonts = rPr && findChild(rPr, W_NS, "rFonts");
+  if (!rFonts) return false;
+  const ascii = getAttr(rFonts, W_NS, "asciiTheme") ?? getAttr(rFonts, W_NS, "ascii");
+  const hAnsi = getAttr(rFonts, W_NS, "hAnsiTheme") ?? getAttr(rFonts, W_NS, "hAnsi");
+  if (ascii === undefined && hAnsi === undefined) return false;
+  return ascii !== hAnsi;
+}
+
+/**
+ * @param {import("./xml-scan.js").XmlElement} run
+ * @returns {boolean}
+ */
+function isHidden(run) {
+  const rPr = findChild(run, W_NS, "rPr");
+  const vanish = rPr && findChild(rPr, W_NS, "vanish");
+  if (!vanish) return false;
+  const val = getAttr(vanish, W_NS, "val");
+  return val === undefined || !ON_OFF_FALSE.has(val);
+}
+
+/**
+ * @typedef {object} ScanResult
+ * @property {TagOccurrence[]} occurrences  document order (Choice copy)
+ * @property {TemplateProblem[]} problems
+ * @property {TemplateProblem[]} warnings
+ * @property {AlternateContentRecord[]} acs
+ */
+
+/**
+ * @param {import("./xml-scan.js").XmlElement} root  scanXml(xmlBytes).root
+ * @param {Uint8Array} xmlBytes
+ * @returns {ScanResult}
+ */
+export function scanTemplate(root, xmlBytes) {
+  const { page, sectPrStarts } = readSections(root);
+  /** @type {{t: import("./xml-scan.js").XmlElement, code: string, detail: string, acIndex: number | null, tag?: string}[]} */
+  const pending = [];
+  /** @type {Map<number, {choice: TagSite[], fallback: TagSite[], braces: boolean}>} */
+  const byAc = new Map();
+  /** @param {number} index */
+  const acEntry = (index) => {
+    let entry = byAc.get(index);
+    if (entry === undefined) {
+      entry = { choice: [], fallback: [], braces: false };
+      byAc.set(index, entry);
+    }
+    return entry;
+  };
+
+  const acs = walk(root, (t, ctx, stack) => {
+    const verdict = classifyText(t, xmlBytes);
+    if (verdict.kind === "none") return;
+    const acIndex = ctx.ac === null ? null : ctx.ac.index;
+    if (acIndex !== null) acEntry(acIndex).braces = true;
+    const reportHere = ctx.branch !== "fallback";
+    if (verdict.kind === "problem") {
+      if (reportHere) pending.push({ t, code: verdict.code, detail: verdict.detail, acIndex });
+      return;
+    }
+    const where = contextProblem(t, ctx, stack);
+    if (where !== null) {
+      if (reportHere) pending.push({ t, code: where.code, detail: where.detail, acIndex, tag: verdict.name });
+      return;
+    }
+    const attrs = attributeProblem(t);
+    if (attrs !== null) {
+      if (reportHere) pending.push({ t, code: "TAG_TEXT_ATTRIBUTES", detail: attrs, acIndex, tag: verdict.name });
+      return;
+    }
+    const site = { name: verdict.name, t, run: stack[stack.length - 1], paragraph: stack[stack.length - 2] };
+    const entry = acEntry(/** @type {number} */ (acIndex));
+    (ctx.branch === "choice" ? entry.choice : entry.fallback).push(site);
+  });
+
+  /** @type {Map<number, {docPrId: number | null, page: number}>} */
+  const attribution = new Map();
+  /** @type {TemplateProblem[]} */
+  const acProblems = [];
+  /** @type {TemplateProblem[]} */
+  const warnings = [];
+  /** @type {TagOccurrence[]} */
+  const occurrences = [];
+
+  for (const [index, entry] of [...byAc.entries()].sort((x, y) => x[0] - y[0])) {
+    const ac = acs[index];
+    const anchor = ac.choiceAnchors.length === 1 ? ac.choiceAnchors[0] : null;
+    const shapeIssues = [];
+    if (ac.nested) shapeIssues.push("it is nested inside another mc:AlternateContent");
+    if (ac.choices.length !== 1) shapeIssues.push(`${ac.choices.length} mc:Choice`);
+    if (ac.fallbacks.length !== 1) shapeIssues.push(`${ac.fallbacks.length} mc:Fallback`);
+    if (ac.choiceTx.length !== 1) shapeIssues.push(`${ac.choiceTx.length} w:txbxContent in the Choice`);
+    if (ac.fallbackTx.length !== 1) shapeIssues.push(`${ac.fallbackTx.length} w:txbxContent in the Fallback`);
+    if (anchor === null) shapeIssues.push(`${ac.choiceAnchors.length} wp:anchor/wp:inline in the Choice`);
+    else if (!isElement(anchor, WP_NS, "anchor")) shapeIssues.push("the Choice holds wp:inline, not wp:anchor");
+
+    /** @type {number | null} */
+    let docPrId = null;
+    let pageNumber = pageForAnchor(sectPrStarts, ac.el.start, page.count);
+    if (anchor !== null) {
+      pageNumber = pageForAnchor(sectPrStarts, anchor.start, page.count);
+      const docPr = findChild(anchor, WP_NS, "docPr");
+      const id = docPr ? getAttr(docPr, "", "id") : undefined;
+      if (id !== undefined && /^[0-9]+$/.test(id)) docPrId = Number(id);
+    }
+    attribution.set(index, { docPrId, page: pageNumber });
+
+    if (shapeIssues.length > 0) {
+      acProblems.push({
+        code: "ALTERNATE_CONTENT_SHAPE",
+        message: `the text box holding a tag does not have the shape the engine fills: ${shapeIssues.join("; ")}`,
+        docPrId,
+        page: pageNumber,
+      });
+      continue;
+    }
+    const copies = compareCopies(ac.choiceTx[0], ac.fallbackTx[0]);
+    if (!copies.equal) {
+      acProblems.push({
+        code: "COPIES_DIFFER",
+        message: `the box's mc:Choice and mc:Fallback copies differ at ${copies.path}`,
+        docPrId,
+        page: pageNumber,
+        path: copies.path,
+      });
+      continue;
+    }
+    // Structurally equal trees can still spell a tag differently in raw bytes
+    // (a character reference in one copy) — compare the twin lists themselves.
+    const twinsMatch =
+      entry.choice.length === entry.fallback.length && entry.choice.every((site, i) => site.name === entry.fallback[i].name);
+    if (!twinsMatch) {
+      acProblems.push({
+        code: "COPIES_DIFFER",
+        message: "the box's mc:Choice and mc:Fallback copies do not hold the same tags",
+        docPrId,
+        page: pageNumber,
+      });
+      continue;
+    }
+    if (anchor !== null && docPrId === null) {
+      warnings.push({ code: "DOCPR_MISSING", message: "a text box holding a tag has no numeric wp:docPr id", page: pageNumber });
+    }
+    entry.choice.forEach((site, i) => {
+      occurrences.push({ name: site.name, docPrId, page: pageNumber, acIndex: index, choice: site, fallback: entry.fallback[i] });
+    });
+  }
+
+  /** @type {TemplateProblem[]} */
+  const problems = pending.map((p) => {
+    const where = p.acIndex !== null && attribution.has(p.acIndex)
+      ? /** @type {{docPrId: number | null, page: number}} */ (attribution.get(p.acIndex))
+      : { docPrId: null, page: pageForAnchor(sectPrStarts, p.t.start, page.count) };
+    /** @type {TemplateProblem} */
+    const problem = { code: p.code, message: p.detail, docPrId: where.docPrId, page: where.page };
+    if (p.tag !== undefined) problem.tag = p.tag;
+    return problem;
+  });
+  problems.push(...acProblems);
+
+  /** @type {Map<number, number>} */
+  const docPrUse = new Map();
+  for (const index of new Set(occurrences.map((o) => o.acIndex))) {
+    const id = /** @type {{docPrId: number | null}} */ (attribution.get(index)).docPrId;
+    if (id !== null) docPrUse.set(id, (docPrUse.get(id) ?? 0) + 1);
+  }
+  for (const [id, n] of docPrUse) {
+    if (n > 1) warnings.push({ code: "DUPLICATE_DOCPR_ID", message: `${n} text boxes holding tags share wp:docPr id ${id}`, docPrId: id });
+  }
+  for (const o of occurrences) {
+    if (fontSlotsSplit(o.choice.run)) {
+      warnings.push({
+        code: "FONT_SLOTS_SPLIT",
+        message: "the tag's run sets the ascii and hAnsi font slots differently, so Turkish letters may draw in another font",
+        tag: o.name,
+        docPrId: o.docPrId,
+        page: o.page,
+      });
+    }
+    if (isHidden(o.choice.run)) {
+      warnings.push({ code: "HIDDEN_TAG_RUN", message: "the tag's run is hidden (w:vanish)", tag: o.name, docPrId: o.docPrId, page: o.page });
+    }
+  }
+
+  return { occurrences, problems, warnings, acs };
+}