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

package/dist/io/ooxml/fit.js

@@ -0,0 +1,598 @@
+// checkFit (FR4a, ADR-0042): whether each filled value stays on the lines its
+// box gives it — the width a text box gives its text, the width a filled line
+// takes, and the decision between them. Integer arithmetic throughout (EMU,
+// 1 pt = 12700, 1 twip = 635, and u = EMU × 2048 for sums of advances);
+// points appear only in the report. No break point is ever chosen
+// (invariant #9): a line is measured whole.
+//
+// A box is measured only in the shape the evidence covers (ADR-0042 Karar 3):
+// one rectangular wps:wsp of its own, unrotated, unframed, its extent the
+// same in wp:extent and a:ext, the body wrapping in one horizontal column.
+// Anything else is a reason — "unknown" — never a guess.
+
+import { scanXml, findChild, getAttr } from "./xml-scan.js";
+import { W_NS, WP_NS, A_NS, WPS_NS, WPG_NS, WP14_NS, WORD_COMPAT_URI, XML_NS } from "./ns.js";
+import { paragraphStyleOf, layoutResolver } from "./run-fonts.js";
+import { readTemplatePackage, prepareFill, tagInfo, ENGINE_VERSION } from "./fill.js";
+import { CALIBRI_METRICS } from "../../fonts/calibri-metrics.js";
+import { devFreeze } from "../../dev.js";
+
+/** DrawingML's default left and right inset (ECMA-376 §21.1.2.1.1 bodyPr: 91440 EMU, 0.1 in). */
+export const DEFAULT_INSET_EMU = 91440;
+const NON_NEGATIVE = /^[0-9]+$/;
+const ON = new Set(["1", "true", "on"]);
+
+// Widths are summed in u = EMU × 2048, so a Calibri advance at a size in half-points is an
+// integer: adv/2048 em × hps/2 pt × 12700 EMU/pt × 2048 = adv × hps × 6350.
+/** u per EMU */
+export const U_PER_EMU = 2048;
+const U_PER_TWIP = 635 * U_PER_EMU;
+const U_PER_ADVANCE_HALF_POINT = (6350 * 2048) / CALIBRI_METRICS.unitsPerEm;
+// Spaces at a line's end: whether Word lets them hang past the edge is not known — FR4-WORD-FIT2 laid out no
+// line that ended in one, U+0020 included (ADR-0042 H3) — so a line is decided both with them and without.
+const SPACE_AT_END = (/** @type {number} */ cp) => cp === 0x20 || cp === 0xa0 || (cp >= 0x2000 && cp <= 0x200a) || cp === 0x202f || cp === 0x205f || cp === 0x3000;
+const EAST_ASIAN_LANGUAGE = /^(zh|ja|ko)(-|$)/i;
+// Paragraph and run children checkFit reads (text, tabs, breaks) or that draw nothing; any other one is a reason.
+const PARAGRAPH_MARKERS = new Set(["pPr", "r", "bookmarkStart", "bookmarkEnd", "proofErr", "commentRangeStart", "commentRangeEnd", "permStart", "permEnd"]);
+const RUN_MARKERS = new Set(["rPr", "t", "tab", "br", "lastRenderedPageBreak"]);
+
+/**
+ * @typedef {import("./xml-scan.js").XmlElement} XmlElement
+ * @typedef {import("./run-fonts.js").Unknown} Unknown
+ * @typedef {{widthEmu: number, lInsEmu: number, rInsEmu: number, textWidthEmu: number}} BoxGeometry
+ *   `textWidthEmu`: the width between the insets, where a paragraph's indents start
+ * @typedef {object} LineMeasure  one line of a filled paragraph
+ * @property {number} startEmu  where it starts, from the box's inner left edge: the indents
+ * @property {number} limitEmu  where it must end: the text width less the right indent
+ * @property {number} widthU  its natural width, every character counted — trailing spaces too (u = EMU × 2048)
+ * @property {number} widthWithoutTrailingU  the same with the trailing spaces left out, as if Word hung them (H3)
+ * @property {number} glyphs  characters in `widthU` since its last exact place — the line start or a tab stop — whose
+ *   deviations τ covers
+ */
+
+/** @type {Map<string, Map<number, number>> | null} */
+let advances = null;
+/**
+ * The metrics table as a code point -> advance map per style, built on first use.
+ * @param {"regular" | "bold" | "italic" | "boldItalic"} style
+ * @returns {Map<number, number>}
+ */
+function advancesOf(style) {
+  if (advances === null) {
+    advances = new Map();
+    for (const [name, runs] of Object.entries(CALIBRI_METRICS.styles)) {
+      /** @type {Map<number, number>} */
+      const map = new Map();
+      for (const [first, list] of runs) list.forEach((adv, i) => map.set(first + i, adv));
+      advances.set(name, map);
+    }
+  }
+  return /** @type {Map<number, number>} */ (advances.get(style));
+}
+
+/**
+ * @param {XmlElement} el
+ * @returns {XmlElement[]}
+ */
+const elementChildren = (el) => /** @type {XmlElement[]} */ (el.children.filter((c) => c.kind === "element"));
+
+/**
+ * The width a scanned text box gives its text, or why it cannot be known.
+ * @param {import("./slots.js").AlternateContentRecord} ac  a box the slot scan accepted
+ * @returns {{box: BoxGeometry} | {unknown: Unknown}}
+ */
+export function boxGeometry(ac) {
+  /** @param {string} code @param {string} [property] @returns {{unknown: Unknown}} */
+  const no = (code, property) => ({ unknown: property === undefined ? { code } : { code, property } });
+  const anchor = ac.choiceAnchors[0];
+  // Word writes wp14:sizeRelH with pctWidth 0 on boxes of absolute size; any other width is a share of the page.
+  const sizeRelH = findChild(anchor, WP14_NS, "sizeRelH");
+  const pctWidth = sizeRelH && findChild(sizeRelH, WP14_NS, "pctWidth");
+  const pct = pctWidth ? pctWidth.children.map((c) => (c.kind === "text" ? c.value : "")).join("").trim() : undefined;
+  if (sizeRelH && pct !== "0") return no("BOX_RELATIVE_SIZE");
+  const extent = findChild(anchor, WP_NS, "extent");
+  const cx = extent && getAttr(extent, "", "cx");
+  if (cx === undefined || !NON_NEGATIVE.test(cx)) return no("BOX_EXTENT_UNREADABLE");
+
+  const graphic = findChild(anchor, A_NS, "graphic");
+  const data = graphic && findChild(graphic, A_NS, "graphicData");
+  if (data && findChild(data, WPG_NS, "wgp")) return no("BOX_GROUP");
+  const wsp = data && findChild(data, WPS_NS, "wsp");
+  const txbx = wsp && findChild(wsp, WPS_NS, "txbx");
+  if (!wsp || !txbx || findChild(txbx, W_NS, "txbxContent") !== ac.choiceTx[0]) return no("BOX_SHAPE");
+  // A text box Word links into a chain carries an id; its overflow continues in the next box.
+  if (getAttr(txbx, "", "id") !== undefined) return no("BOX_LINKED");
+
+  const spPr = findChild(wsp, WPS_NS, "spPr");
+  const xfrm = spPr && findChild(spPr, A_NS, "xfrm");
+  if (xfrm) {
+    const rot = getAttr(xfrm, "", "rot");
+    if (rot !== undefined && rot !== "0") return no("BOX_ROTATED", "rot");
+    for (const flip of ["flipH", "flipV"]) {
+      const v = getAttr(xfrm, "", flip);
+      if (v !== undefined && ON.has(v)) return no("BOX_ROTATED", flip);
+    }
+  }
+  const ext = xfrm && findChild(xfrm, A_NS, "ext");
+  if (!ext || getAttr(ext, "", "cx") !== cx) return no("BOX_EXTENT_MISMATCH");
+  const geometry = spPr && findChild(spPr, A_NS, "prstGeom");
+  if (!geometry || getAttr(geometry, "", "prst") !== "rect") return no("BOX_GEOMETRY");
+  const ln = spPr && findChild(spPr, A_NS, "ln");
+  if (ln) {
+    if (!findChild(ln, A_NS, "noFill")) return no("BOX_OUTLINE");
+  } else {
+    // No line of its own: the shape style's line reference draws one unless it is 0.
+    const style = findChild(wsp, WPS_NS, "style");
+    const lnRef = style && findChild(style, A_NS, "lnRef");
+    if (lnRef && getAttr(lnRef, "", "idx") !== "0") return no("BOX_OUTLINE");
+  }
+
+  const bodyPr = findChild(wsp, WPS_NS, "bodyPr");
+  let lIns = DEFAULT_INSET_EMU;
+  let rIns = DEFAULT_INSET_EMU;
+  if (bodyPr) {
+    /** @type {[string, (v: string) => boolean][]} */
+    const rules = [
+      ["wrap", (v) => v === "square"],
+      ["vert", (v) => v === "horz"],
+      ["numCol", (v) => v === "1"],
+      ["rot", (v) => v === "0"],
+      ["fromWordArt", (v) => !ON.has(v)],
+    ];
+    for (const [name, ok] of rules) {
+      const v = getAttr(bodyPr, "", name);
+      if (v !== undefined && !ok(v)) return no("BOX_BODY", name);
+    }
+    for (const c of elementChildren(bodyPr)) {
+      if (c.uri === A_NS && c.localName === "normAutofit") return no("BOX_AUTOFIT");
+      if (!(c.uri === A_NS && (c.localName === "noAutofit" || c.localName === "spAutoFit"))) return no("BOX_BODY", c.localName);
+    }
+    const l = getAttr(bodyPr, "", "lIns");
+    const r = getAttr(bodyPr, "", "rIns");
+    if ((l !== undefined && !NON_NEGATIVE.test(l)) || (r !== undefined && !NON_NEGATIVE.test(r))) return no("BOX_INSET_UNREADABLE");
+    if (l !== undefined) lIns = Number(l);
+    if (r !== undefined) rIns = Number(r);
+  }
+  const widthEmu = Number(cx);
+  const textWidthEmu = widthEmu - lIns - rIns;
+  if (textWidthEmu <= 0) return no("BOX_NO_ROOM");
+  return { box: { widthEmu, lInsEmu: lIns, rInsEmu: rIns, textWidthEmu } };
+}
+
+/**
+ * @typedef {{cp: number, u: number, sp: number, tab?: true}} Item  a character, or a tab's jump to its stop
+ * @typedef {{lines: LineMeasure[], stops: number[]}} Laid  the lines, and the stop each tab reached (u)
+ * @typedef {{unknown: Unknown & {codePoint?: number}} | {overflow: {code: "TAB_STOP_PASSED"}}} NotLaid
+ */
+
+/**
+ * The lines a paragraph holds once its tags are filled, each measured: where it
+ * starts, where it must end, how wide it is (ADR-0042 Karar 5). A line ends at a
+ * w:br — the template's, or one a multi-line value's LF becomes. No break point is
+ * ever chosen (invariant #9): a line is measured whole, as the template and the
+ * values give it.
+ *
+ * A tab jumps to the first left stop past the pen, stops measured from the box's
+ * inner left edge (H6). The paragraph is laid out once with its tags empty: that
+ * fixes the stop each tab reaches. Filled, a tab whose text has passed that stop
+ * has broken the column the template aligned — an overflow, TAB_STOP_PASSED, even
+ * if the line itself still fits.
+ * @param {object} input
+ * @param {XmlElement} input.paragraph
+ * @param {BoxGeometry} input.box
+ * @param {ReturnType<typeof import("./run-fonts.js").layoutResolver>} input.layout
+ * @param {Map<XmlElement, string>} input.values  tag run -> the value written into it
+ * @param {boolean} [input.preserve]  every w:t inherits xml:space="preserve" (inheritsPreserve);
+ *   otherwise a template text with edge whitespace and no preserve of its own is unknown —
+ *   Word may drop that whitespace
+ * @returns {{lines: LineMeasure[]} | NotLaid}
+ */
+export function measureParagraph({ paragraph, box, layout, values, preserve = false }) {
+  const styleId = paragraphStyleOf(paragraph);
+  const p = layout.paragraph(styleId, findChild(paragraph, W_NS, "pPr"));
+  if (p.unknown.length > 0) return { unknown: p.unknown[0] };
+  if (p.leftTwips < 0 || p.rightTwips < 0 || p.leftTwips + p.firstLineTwips < 0) return { unknown: { code: "INDENT_OUTSIDE" } };
+  const limitEmu = box.textWidthEmu - p.rightTwips * 635;
+  const limitU = limitEmu * U_PER_EMU;
+  /** @param {number} line @returns {number} EMU */
+  const startOf = (line) => (p.leftTwips + (line === 0 ? p.firstLineTwips : 0)) * 635;
+
+  /**
+   * @param {Map<XmlElement, string>} vals
+   * @param {number[] | null} expected  the stops the blank layout's tabs reached; null for that layout itself
+   * @returns {Laid | NotLaid}
+   */
+  const layOut = (vals, expected) => {
+    /** @type {Item[][]} */
+    const lines = [[]];
+    /** @type {number[]} */
+    const stops = [];
+    let x = startOf(0) * U_PER_EMU;
+    let sinceExact = 0;
+    for (const child of paragraph.children) {
+      if (child.kind !== "element") continue;
+      if (child.uri !== W_NS || !PARAGRAPH_MARKERS.has(child.localName)) return { unknown: { code: "PARAGRAPH_CONTENT", property: child.localName } };
+      if (child.localName !== "r") continue;
+      const run = layout.run(styleId, findChild(child, W_NS, "rPr"));
+      if (run.unknown.length > 0) return { unknown: run.unknown[0] };
+      const hps = run.sizeHalfPoints;
+      if (hps === null) return { unknown: { code: "SIZE_UNKNOWN" } };
+      const style = run.bold ? (run.italic ? "boldItalic" : "bold") : run.italic ? "italic" : "regular";
+      const table = advancesOf(style);
+      const value = vals.get(child);
+      /** @param {string} text @returns {Unknown & {codePoint?: number} | null} */
+      const add = (text) => {
+        for (const ch of text) {
+          const cp = /** @type {number} */ (ch.codePointAt(0));
+          const font = cp <= 0x7f ? run.font.ascii : run.font.hAnsi;
+          if (font === null || font.toLowerCase() !== CALIBRI_METRICS.family.toLowerCase()) return { code: "FONT_NOT_SUPPORTED" };
+          if (cp > 0x7f && run.hint !== null && run.hint !== "default") return { code: "FONT_HINT" };
+          if (cp > 0x7f && run.eastAsiaLanguage !== null && EAST_ASIAN_LANGUAGE.test(run.eastAsiaLanguage)) return { code: "EAST_ASIAN_LANGUAGE" };
+          const adv = table.get(cp);
+          if (adv === undefined) return { code: "UNKNOWN_CHARACTER", codePoint: cp };
+          // Letter spacing follows every character, the last included (ADR-0042 H5).
+          const sp = run.spacingTwips * U_PER_TWIP;
+          const u = adv * hps * U_PER_ADVANCE_HALF_POINT + sp;
+          lines[lines.length - 1].push({ cp, u, sp });
+          x += u;
+          sinceExact += 1;
+        }
+        return null;
+      };
+      const newLine = () => {
+        lines.push([]);
+        x = startOf(lines.length - 1) * U_PER_EMU;
+        sinceExact = 0;
+      };
+      /** @returns {Unknown | {overflow: {code: "TAB_STOP_PASSED"}} | null} */
+      const tab = () => {
+        // A hanging first line gets an implicit stop at the left indent: not modelled.
+        if (p.firstLineTwips < 0) return { code: "TAB_HANGING" };
+        // Measured in Word only on left-aligned lines in boxes without a left inset (FR4-WORD-FIT2):
+        // a centred or right line moves its stops, and an inset leaves "the inner edge" untested (H6).
+        if (p.jc !== "left" && p.jc !== "start") return { code: "TAB_ALIGNMENT" };
+        if (box.lInsEmu !== 0) return { code: "TAB_INSET" };
+        // The pen's place is exact at a line start or a stop; τ grows with the glyphs since.
+        const tau = TAU_BASE_U + TAU_PER_GLYPH_U * sinceExact;
+        let stop;
+        if (expected !== null) {
+          stop = expected[stops.length];
+          if (x > stop + tau) return { overflow: { code: "TAB_STOP_PASSED" } };
+          if (x >= stop - tau) return { code: "TAB_BORDERLINE" };
+        } else {
+          const at = p.tabs.map((t) => ({ ...t, u: t.posTwips * 635 * U_PER_EMU }));
+          const next = at.find((t) => t.u > x);
+          const previous = at.filter((t) => t.u <= x).pop();
+          if (next === undefined) return { code: "TAB_DEFAULT" };
+          if (!next.left) return { code: "TAB_STOP_KIND" };
+          if (next.u - x <= tau || (previous !== undefined && x - previous.u <= tau)) return { code: "TAB_BORDERLINE" };
+          if (next.u > limitU) return { code: "TAB_BEYOND" };
+          stop = next.u;
+        }
+        lines[lines.length - 1].push({ cp: 0x09, u: stop - x, sp: 0, tab: true });
+        stops.push(stop);
+        x = stop;
+        sinceExact = 0;
+        return null;
+      };
+      if (value !== undefined) {
+        // A tag run holds its one w:t and nothing else that draws (the slot scan's grammar); the value
+        // replaces it, a multi-line value's LFs becoming w:br inside the run (ADR-0039).
+        for (const [i, line] of value.split("\n").entries()) {
+          if (i > 0) newLine();
+          const bad = add(line);
+          if (bad !== null) return { unknown: bad };
+        }
+        continue;
+      }
+      for (const c of child.children) {
+        if (c.kind !== "element") continue;
+        if (c.uri !== W_NS || !RUN_MARKERS.has(c.localName)) return { unknown: { code: "RUN_CONTENT", property: c.localName } };
+        if (c.localName === "t") {
+          const text = c.children.map((y) => (y.kind === "text" || y.kind === "cdata" ? y.value : "")).join("");
+          if (!preserve && getAttr(c, XML_NS, "space") !== "preserve" && /^\s|\s$/.test(text)) return { unknown: { code: "WHITESPACE_UNPRESERVED" } };
+          const bad = add(text);
+          if (bad !== null) return { unknown: bad };
+        } else if (c.localName === "tab") {
+          const bad = tab();
+          if (bad !== null) return "overflow" in bad ? bad : { unknown: bad };
+        } else if (c.localName === "br") {
+          const type = getAttr(c, W_NS, "type");
+          if (type !== undefined && type !== "textWrapping") return { unknown: { code: "RUN_CONTENT", property: `br ${type}` } };
+          newLine();
+        }
+      }
+    }
+    return {
+      stops,
+      lines: lines.map((items, i) => {
+        let end = items.length;
+        while (end > 0 && SPACE_AT_END(items[end - 1].cp)) end -= 1;
+        const sum = (/** @type {number} */ n) => items.slice(0, n).reduce((u, c) => u + c.u, 0);
+        const lastTab = items.map((c) => c.tab === true).lastIndexOf(true);
+        return {
+          startEmu: startOf(i),
+          limitEmu,
+          widthU: sum(items.length),
+          widthWithoutTrailingU: sum(end),
+          glyphs: items.length - lastTab - 1,
+        };
+      }),
+    };
+  };
+
+  const tabbed = paragraph.children.some((r) => r.kind === "element" && r.uri === W_NS && r.localName === "r" && !values.has(r) && findChild(r, W_NS, "tab") !== undefined);
+  if (!tabbed) {
+    const laid = layOut(values, null);
+    return "lines" in laid ? { lines: laid.lines } : laid;
+  }
+  const blank = layOut(new Map([...values.keys()].map((run) => [run, ""])), null);
+  if (!("lines" in blank)) return blank;
+  const laid = layOut(values, blank.stops);
+  return "lines" in laid ? { lines: laid.lines } : laid;
+}
+
+// --- the decision and the public function --------------------------------------------------------
+
+const STYLES_PART = "word/styles.xml";
+const SETTINGS_PART = "word/settings.xml";
+const THEME_PART = "word/theme/theme1.xml";
+// w:compat children the FR4-WORD-FIT gate measures with (KR09 carries them); one turned off is no change.
+const COMPAT_OPTIONS = new Set(["ulTrailSpace", "shapeLayoutLikeWW8", "useFELayout"]);
+// Word 2010's compatibility settings next to mode 14; the others touch tables, mirrored indents or
+// OpenType features a run asks for (w14, itself unknown).
+const COMPAT_SETTINGS = new Set(["compatibilityMode", "overrideTableStyleFontSizeAndJustification", "enableOpenTypeFeatures", "doNotFlipMirrorIndents", "differentiateMultirowTableHeaders"]);
+const OFF = new Set(["0", "false", "off"]);
+/** τ = 0.05 pt + 0.025 pt a glyph (ADR-0042 Karar 6), in u. */
+export const TAU_BASE_U = 635 * U_PER_EMU;
+export const TAU_PER_GLYPH_U = 317.5 * U_PER_EMU;
+/** @type {Record<FitStatus, number>} */
+const SEVERITY = { empty: 0, fits: 1, unknown: 2, overflows: 3 };
+
+/**
+ * @typedef {"fits" | "overflows" | "unknown" | "empty"} FitStatus
+ * @typedef {{status: "fits" | "overflows"} | {status: "unknown", reason: Unknown}} LineVerdict
+ * @typedef {object} FitOccurrence
+ * @property {number | null} docPrId
+ * @property {number} page
+ * @property {FitStatus} status
+ * @property {string} [reason]  from a closed list (ADR-0042)
+ * @property {string} [property]  the property or element the reason names
+ * @property {number} [codePoint]  the character the table lacks
+ * @property {number} [widthPt]  the tightest line's width
+ * @property {number} [availablePt]  the room it has
+ * @property {number} [marginPt]  room less width; negative when it overflows
+ * @property {number} [lines]  a multi-line value's line count
+ * @property {number} [capacity]
+ * @property {string[]} [paragraphTags]  the other tags measured on the same line
+ * @typedef {{name: string, status: FitStatus, occurrences: FitOccurrence[]}} FitTag
+ * @typedef {object} FitReport
+ * @property {boolean} ok  no occurrence overflows or is unknown — the caller's approval rule
+ * @property {FitTag[]} tags  sorted by name
+ * @property {{tags: number, occurrences: number, fits: number, overflows: number, unknown: number, empty: number}} counts
+ * @property {{version: string, metrics: {family: string, carlito: string | null, calibri: string | null}}} engine
+ */
+
+/**
+ * One line against its room: fits when even with its trailing spaces counted and τ more it would
+ * fit, overflows when even with them hanging and τ less it would not; between, unknown (ADR-0042
+ * Karar 6) — TRAILING_SPACE when the trailing spaces alone decide.
+ * @param {LineMeasure} line
+ * @returns {LineVerdict}
+ */
+export function decideLine(line) {
+  const available = (line.limitEmu - line.startEmu) * U_PER_EMU;
+  const tau = TAU_BASE_U + TAU_PER_GLYPH_U * line.glyphs;
+  if (line.widthU <= available - tau) return { status: "fits" };
+  if (line.widthWithoutTrailingU > available + tau) return { status: "overflows" };
+  const trailing = line.widthWithoutTrailingU !== line.widthU && (line.widthWithoutTrailingU <= available - tau || line.widthU > available + tau);
+  return { status: "unknown", reason: { code: trailing ? "TRAILING_SPACE" : "BORDERLINE" } };
+}
+
+/**
+ * Whether every w:t of the document inherits xml:space="preserve": the root sets it and no element
+ * below sets anything else (Word writes the root's; all 46 corpus documents carry it).
+ * @param {XmlElement} root
+ * @returns {boolean}
+ */
+export function inheritsPreserve(root) {
+  if (getAttr(root, XML_NS, "space") !== "preserve") return false;
+  /** @param {XmlElement} el @returns {boolean} */
+  const overrides = (el) => elementChildren(el).some((c) => {
+    const v = getAttr(c, XML_NS, "space");
+    return (v !== undefined && v !== "preserve") || overrides(c);
+  });
+  return !overrides(root);
+}
+
+/**
+ * Settings that change every line, or that the evidence does not cover: the compatibility mode
+ * (14 only), the w:compat options, East Asian punctuation compression, a character grid.
+ * @param {Uint8Array | undefined} settingsXml
+ * @param {XmlElement} documentRoot
+ * @returns {Unknown | null}
+ */
+export function documentUnknown(settingsXml, documentRoot) {
+  if (settingsXml === undefined) return { code: "COMPAT_MODE" };
+  const settings = scanXml(settingsXml).root;
+  const control = findChild(settings, W_NS, "characterSpacingControl");
+  if (control && getAttr(control, W_NS, "val") !== "doNotCompress") return { code: "SETTING", property: "characterSpacingControl" };
+  const compat = findChild(settings, W_NS, "compat");
+  /** @type {string | undefined} */
+  let mode;
+  for (const c of compat ? elementChildren(compat) : []) {
+    if (c.uri === W_NS && c.localName === "compatSetting") {
+      const name = getAttr(c, W_NS, "name");
+      if (getAttr(c, W_NS, "uri") !== WORD_COMPAT_URI || name === undefined || !COMPAT_SETTINGS.has(name)) return { code: "COMPAT_OPTION", property: name ?? "compatSetting" };
+      if (name === "compatibilityMode") mode = getAttr(c, W_NS, "val");
+    } else if (!(c.uri === W_NS && COMPAT_OPTIONS.has(c.localName)) && !OFF.has(getAttr(c, W_NS, "val") ?? "")) {
+      return { code: "COMPAT_OPTION", property: c.localName };
+    }
+  }
+  if (mode !== "14") return { code: "COMPAT_MODE" };
+  /** @param {XmlElement} el @returns {boolean} */
+  const charGrid = (el) =>
+    elementChildren(el).some((c) => {
+      if (c.uri === W_NS && c.localName === "docGrid") {
+        const type = getAttr(c, W_NS, "type");
+        return type !== undefined && type !== "default" && type !== "lines";
+      }
+      return charGrid(c);
+    });
+  return charGrid(documentRoot) ? { code: "DOCUMENT_GRID" } : null;
+}
+
+/**
+ * checkFit's own option: `capacity`, tag -> the lines a multi-line tag's box shows.
+ * @param {unknown} value
+ * @param {readonly string[]} multiline
+ * @returns {{capacity: Map<string, number>, problems: import("./fill.js").Problem[]}}
+ */
+function readCapacity(value, multiline) {
+  /** @type {Map<string, number>} */
+  const capacity = new Map();
+  if (value === undefined) return { capacity, problems: [] };
+  const proto = value !== null && typeof value === "object" ? Object.getPrototypeOf(value) : undefined;
+  const entries = proto === Object.prototype || proto === null ? Object.entries(/** @type {object} */ (value)) : null;
+  if (entries === null || !entries.every(([, n]) => Number.isSafeInteger(n) && /** @type {number} */ (n) > 0)) {
+    throw new TypeError("checkFit: options.capacity must be a plain object of positive integers (tag -> lines)");
+  }
+  /** @type {import("./fill.js").Problem[]} */
+  const problems = [];
+  for (const [name, n] of entries.sort((x, y) => (x[0] < y[0] ? -1 : 1))) {
+    if (multiline.includes(name)) capacity.set(name, /** @type {number} */ (n));
+    else problems.push({ code: "CAPACITY_NOT_MULTILINE", message: "capacity names a tag the multiline option does not", tag: name });
+  }
+  return { capacity, problems };
+}
+
+/** @param {number} u @returns {number} */
+const ptOf = (u) => Math.round((u / U_PER_EMU / 12700) * 100) / 100;
+
+/**
+ * Whether each value of `data` stays on the lines its box gives it, as Word lays the filled
+ * template out (ADR-0042). Validates exactly as fillTemplate does — the same TemplateError for
+ * the same input — and writes nothing. The report carries no value: widths, reasons, code points.
+ * @param {Uint8Array} bytes  a .docx template
+ * @param {import("./fill.js").FillData} data
+ * @param {{expectedTags?: readonly string[], multiline?: readonly string[], capacity?: Record<string, number>}} [options]
+ *   `capacity`: tag -> lines, for multi-line tags only; a binding manifest carries it as `fit`
+ * @returns {Promise<FitReport>}
+ */
+export async function checkFit(bytes, data, options) {
+  const pkg = await readTemplatePackage("checkFit", bytes, [STYLES_PART, SETTINGS_PART, THEME_PART]);
+  /** @type {Map<string, number>} */
+  let capacity = new Map();
+  const prepared = prepareFill("checkFit", pkg.root, pkg.xml, data, options, pkg.otherPartProblems, ["expectedTags", "multiline", "capacity"], (o) => {
+    const read = readCapacity(o.given.capacity, o.multiline ?? []);
+    capacity = read.capacity;
+    return read.problems;
+  });
+  const { scan, valueOf, multilineSet } = prepared;
+  const styles = pkg.parts.get(STYLES_PART);
+  const everywhere = styles === undefined ? { code: "STYLES_MISSING" } : documentUnknown(pkg.parts.get(SETTINGS_PART), pkg.root);
+  const layout = styles === undefined ? null : layoutResolver(styles, pkg.parts.get(THEME_PART) ?? null);
+  const preserve = inheritsPreserve(pkg.root);
+
+  /** @type {Map<XmlElement, string>} */
+  const values = new Map(scan.occurrences.map((o) => [o.choice.run, /** @type {string} */ (valueOf.get(o.name))]));
+  /** @type {Map<XmlElement, string[]>} */
+  const tagsOf = new Map();
+  for (const o of scan.occurrences) tagsOf.set(o.choice.paragraph, [...(tagsOf.get(o.choice.paragraph) ?? []), o.name]);
+  /** @type {Map<XmlElement, ReturnType<typeof measureParagraph>>} */
+  const measured = new Map();
+
+  /** @type {Map<string, FitOccurrence[]>} */
+  const byName = new Map();
+  for (const o of scan.occurrences) {
+    const paragraph = o.choice.paragraph;
+    const runs = paragraph.children.filter((c) => c.kind === "element" && c.uri === W_NS && c.localName === "r").length;
+    const others = [...new Set((tagsOf.get(paragraph) ?? []).filter((n) => n !== o.name))].sort();
+    /** @type {FitOccurrence} */
+    const out = { docPrId: o.docPrId, page: o.page, status: "unknown" };
+    /** @param {Unknown & {codePoint?: number}} u */
+    const unknown = (u) => {
+      out.status = "unknown";
+      out.reason = u.code;
+      if (u.property !== undefined) out.property = u.property;
+      if (u.codePoint !== undefined) out.codePoint = u.codePoint;
+    };
+    /**
+     * @param {string} name
+     * @param {LineMeasure[]} lines
+     * @param {boolean} lone  the tag's run is the paragraph's only one
+     */
+    const decide = (name, lines, lone) => {
+      const verdicts = lines.map(decideLine);
+      const roomOf = (/** @type {LineMeasure} */ l) => (l.limitEmu - l.startEmu) * U_PER_EMU;
+      const tightest = lines.reduce((best, l) => (roomOf(l) - l.widthU < roomOf(best) - best.widthU ? l : best));
+      out.widthPt = ptOf(tightest.widthU);
+      out.availablePt = ptOf(roomOf(tightest));
+      out.marginPt = ptOf(roomOf(tightest) - tightest.widthU);
+      const firstUnknown = verdicts.find((v) => v.status === "unknown");
+      if (!multilineSet.has(name)) {
+        if (verdicts.some((v) => v.status === "overflows")) out.status = "overflows";
+        else if (firstUnknown !== undefined && firstUnknown.status === "unknown") unknown(firstUnknown.reason);
+        else out.status = "fits";
+        return;
+      }
+      // A multi-line value: n lines the caller broke, m of them too wide — each of those takes at
+      // least one more line; how many more is the browser's to say (FR4b).
+      out.lines = lines.length;
+      if (!lone) return unknown({ code: "SHARED_MULTILINE" });
+      const c = capacity.get(name);
+      if (c === undefined) return unknown({ code: "NO_CAPACITY" });
+      out.capacity = c;
+      const m = verdicts.filter((v) => v.status === "overflows").length;
+      if (lines.length + m > c) out.status = "overflows";
+      else if (m === 0 && firstUnknown === undefined) out.status = "fits";
+      else if (m > 0) unknown({ code: "WRAPS" });
+      else if (firstUnknown !== undefined && firstUnknown.status === "unknown") unknown(firstUnknown.reason);
+    };
+
+    const value = /** @type {string} */ (valueOf.get(o.name));
+    // Empty is nothing written: whitespace still takes width, and a multi-line value's LFs take lines.
+    if (value === "" && runs === 1) {
+      out.status = "empty";
+    } else if (everywhere !== null) {
+      unknown(everywhere);
+    } else {
+      const geometry = boxGeometry(scan.acs[o.acIndex]);
+      if ("unknown" in geometry) unknown(geometry.unknown);
+      else {
+        let m = measured.get(paragraph);
+        if (m === undefined) {
+          m = measureParagraph({ paragraph, box: geometry.box, layout: /** @type {ReturnType<typeof layoutResolver>} */ (layout), values, preserve });
+          measured.set(paragraph, m);
+        }
+        if ("unknown" in m) unknown(m.unknown);
+        else if ("overflow" in m) {
+          out.status = "overflows";
+          out.reason = m.overflow.code;
+        } else decide(o.name, m.lines, runs === 1);
+      }
+    }
+    if (others.length > 0) out.paragraphTags = others;
+    byName.set(o.name, [...(byName.get(o.name) ?? []), out]);
+  }
+
+  /** @type {FitTag[]} */
+  const tags = tagInfo(scan).map(({ name }) => {
+    const occurrences = /** @type {FitOccurrence[]} */ (byName.get(name));
+    const status = occurrences.reduce((worst, x) => (SEVERITY[x.status] > SEVERITY[worst] ? x.status : worst), /** @type {FitStatus} */ ("empty"));
+    return { name, status, occurrences };
+  });
+  const all = tags.flatMap((t) => t.occurrences);
+  /** @param {FitStatus} s */
+  const count = (s) => all.filter((x) => x.status === s).length;
+  const counts = { tags: tags.length, occurrences: all.length, fits: count("fits"), overflows: count("overflows"), unknown: count("unknown"), empty: count("empty") };
+  const source = CALIBRI_METRICS.source.regular;
+  /** @type {FitReport} */
+  const report = {
+    ok: counts.overflows === 0 && counts.unknown === 0,
+    tags,
+    counts,
+    engine: { version: ENGINE_VERSION, metrics: { family: CALIBRI_METRICS.family, carlito: source.carlito.version, calibri: source.calibri.version } },
+  };
+  return devFreeze(report);
+}