@json-to-office/jto-ops 3.3.0 → 4.1.0

package/dist/index.js

@@ -1742,24 +1742,41 @@ function decodeEntities(value) {
   );
 }
 var PAGE_PATTERN = /<page\s+width="([\d.]+)"\s+height="([\d.]+)">([\s\S]*?)<\/page>/g;
-var WORD_PATTERN = /<word\s+xMin="(-?[\d.]+)"\s+yMin="(-?[\d.]+)"\s+xMax="(-?[\d.]+)"\s+yMax="(-?[\d.]+)">([\s\S]*?)<\/word>/g;
+var LINE_OR_WORD_PATTERN = /<line\s+xMin="(-?[\d.]+)"\s+yMin="(-?[\d.]+)"\s+xMax="(-?[\d.]+)"\s+yMax="(-?[\d.]+)">|<\/line>|<word\s+xMin="(-?[\d.]+)"\s+yMin="(-?[\d.]+)"\s+xMax="(-?[\d.]+)"\s+yMax="(-?[\d.]+)">([\s\S]*?)<\/word>/g;
 function parsePdfTextBbox(bboxXml) {
   const pages = [];
   for (const pageMatch of bboxXml.matchAll(PAGE_PATTERN)) {
     const words = [];
-    for (const wordMatch of pageMatch[3].matchAll(WORD_PATTERN)) {
-      words.push({
-        xMin: Number(wordMatch[1]),
-        yMin: Number(wordMatch[2]),
-        xMax: Number(wordMatch[3]),
-        yMax: Number(wordMatch[4]),
-        text: decodeEntities(wordMatch[5])
-      });
+    const lines = [];
+    let open;
+    for (const token of pageMatch[3].matchAll(LINE_OR_WORD_PATTERN)) {
+      if (token[0] === "</line>") {
+        if (open) lines.push(open);
+        open = void 0;
+      } else if (token[1] !== void 0) {
+        open = {
+          xMin: Number(token[1]),
+          yMin: Number(token[2]),
+          xMax: Number(token[3]),
+          yMax: Number(token[4]),
+          words: []
+        };
+      } else {
+        open?.words.push(words.length);
+        words.push({
+          xMin: Number(token[5]),
+          yMin: Number(token[6]),
+          xMax: Number(token[7]),
+          yMax: Number(token[8]),
+          text: decodeEntities(token[9])
+        });
+      }
     }
     pages.push({
       widthPt: Number(pageMatch[1]),
       heightPt: Number(pageMatch[2]),
-      words
+      words,
+      lines
     });
   }
   return pages;
@@ -1827,27 +1844,773 @@ async function extractPdfTextGeometry(pdfPath, options = {}) {
   const binary = await resolvePdftotext();
   const stdout = await run(
     binary,
-    ["-bbox", pdfPath, "-"],
+    [options.layout ? "-bbox-layout" : "-bbox", pdfPath, "-"],
     options.timeoutMs ?? 6e4
   );
   return parsePdfTextBbox(stdout);
 }
+
+// src/pdf-fonts.ts
+import { execFile as execFile3 } from "child_process";
+import * as path7 from "path";
+var ROW_PATTERN = /^(\S+)\s+(.+?)\s+(\S+)\s+(yes|no)\s+(yes|no)\s+(yes|no)\s+/;
+function parsePdfFonts(stdout) {
+  const fonts = [];
+  for (const line of stdout.split(/\r?\n/)) {
+    if (line.startsWith("name ") || line.startsWith("---") || !line.trim()) {
+      continue;
+    }
+    const match = ROW_PATTERN.exec(line);
+    if (!match) continue;
+    const name = match[1];
+    fonts.push({
+      name,
+      baseName: name.replace(/^[A-Z]{6}\+/, ""),
+      type: match[2].trim(),
+      embedded: match[4] === "yes"
+    });
+  }
+  return fonts;
+}
+function foldFontName(value) {
+  return value.toLowerCase().replace(/[^a-z0-9]/g, "");
+}
+function familyRendered(family, fonts) {
+  const folded = foldFontName(family);
+  if (folded === "") return true;
+  return fonts.some((font) => foldFontName(font.baseName).startsWith(folded));
+}
+function pdffontsCandidates() {
+  const candidates = [];
+  const configured = process.env.PDFFONTS_PATH?.trim();
+  if (configured) candidates.push(configured);
+  const sibling = process.env.PDFTOTEXT_PATH?.trim();
+  if (sibling) {
+    candidates.push(
+      path7.join(
+        path7.dirname(sibling),
+        process.platform === "win32" ? "pdffonts.exe" : "pdffonts"
+      )
+    );
+  }
+  candidates.push("pdffonts");
+  return [...new Set(candidates)];
+}
+async function run2(binary, args, timeoutMs) {
+  return new Promise((resolve2, reject) => {
+    execFile3(
+      binary,
+      args,
+      { timeout: timeoutMs, maxBuffer: 16 * 1024 * 1024 },
+      (error, stdout) => {
+        if (error) reject(error);
+        else resolve2(stdout);
+      }
+    );
+  });
+}
+var pdffontsPromise;
+async function resolvePdffonts() {
+  if (!pdffontsPromise) {
+    pdffontsPromise = (async () => {
+      for (const candidate of pdffontsCandidates()) {
+        try {
+          await run2(candidate, ["-v"], 1e4);
+          return candidate;
+        } catch (error) {
+          const code = error.code;
+          if (code !== "ENOENT" && code !== "EACCES") return candidate;
+        }
+      }
+      throw new Error(
+        `Font inspection needs pdffonts (poppler), which was not found. Install poppler-utils or set PDFFONTS_PATH (searched: ${pdffontsCandidates().join(", ")}).`
+      );
+    })().catch((error) => {
+      pdffontsPromise = void 0;
+      throw error;
+    });
+  }
+  return pdffontsPromise;
+}
+async function pdffontsAvailable() {
+  try {
+    await resolvePdffonts();
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function extractPdfFonts(pdfPath, options = {}) {
+  const binary = await resolvePdffonts();
+  const stdout = await run2(binary, [pdfPath], options.timeoutMs ?? 3e4);
+  return parsePdfFonts(stdout);
+}
+
+// src/rendered-analysis.ts
+import {
+  QUALITY_CODES
+} from "@json-to-office/quality";
+
+// src/rendered-text-match.ts
+function normalizeForMatch(value) {
+  return value.normalize("NFKC").toLowerCase().replace(/[^a-z0-9]/g, "");
+}
+var FIELD = "";
+function authoredTextForMatch(text) {
+  return text.replace(/\{[^}\s]+\}/g, FIELD).replace(/\[\^[^\]\s]+\]/g, FIELD).replace(/\[@[^\]\s]+\]/g, FIELD).replace(/\[([^\]]*)\]\([^)]*\)/g, "$1").replace(/[*_`]+/g, "");
+}
+function needleSegments(text) {
+  return authoredTextForMatch(text).split(FIELD).map(normalizeForMatch).filter((segment) => segment !== "");
+}
+function indexDocument(pages, exclude = /* @__PURE__ */ new Set()) {
+  const refs = [];
+  const fragments = [];
+  const positions = [];
+  let cursor = 0;
+  pages.forEach((page, pageIndex) => {
+    page.words.forEach((word, index) => {
+      const key = `${pageIndex}:${index}`;
+      const fragment = exclude.has(key) ? "" : normalizeForMatch(word.text);
+      refs.push({ pageIndex, word: index });
+      fragments.push(fragment);
+      positions.push(cursor);
+      cursor += fragment.length;
+    });
+  });
+  return { pages, refs, fragments, positions, stream: fragments.join("") };
+}
+function fragmentAt(index, offset) {
+  let low = 0;
+  let high = index.positions.length - 1;
+  while (low < high) {
+    const mid = Math.ceil((low + high) / 2);
+    if (index.positions[mid] <= offset) low = mid;
+    else high = mid - 1;
+  }
+  while (low < index.fragments.length && index.fragments[low] === "") low++;
+  return low;
+}
+function alignedToFragments(index, at, end) {
+  const first = fragmentAt(index, at);
+  if (first >= index.fragments.length || index.positions[first] !== at) {
+    return false;
+  }
+  let i = first;
+  while (i < index.fragments.length && index.positions[i] + index.fragments[i].length < end) {
+    i++;
+  }
+  return i < index.fragments.length && index.positions[i] + index.fragments[i].length === end;
+}
+function partsOf(index, at, end) {
+  const parts = [];
+  for (let i = fragmentAt(index, at); i < index.fragments.length; i++) {
+    const start = index.positions[i];
+    if (start >= end) break;
+    if (index.fragments[i] === "") continue;
+    const ref = index.refs[i];
+    const w = index.pages[ref.pageIndex].words[ref.word];
+    let part = parts[parts.length - 1];
+    if (!part || part.pageIndex !== ref.pageIndex) {
+      part = {
+        pageIndex: ref.pageIndex,
+        words: [],
+        xMin: Infinity,
+        yMin: Infinity,
+        xMax: -Infinity,
+        yMax: -Infinity
+      };
+      parts.push(part);
+    }
+    part.words.push(ref.word);
+    part.xMin = Math.min(part.xMin, w.xMin);
+    part.yMin = Math.min(part.yMin, w.yMin);
+    part.xMax = Math.max(part.xMax, w.xMax);
+    part.yMax = Math.max(part.yMax, w.yMax);
+  }
+  return parts;
+}
+function occurrence(index, at, end) {
+  const parts = partsOf(index, at, end);
+  return {
+    at,
+    pageIndex: parts[0].pageIndex,
+    endPageIndex: parts[parts.length - 1].pageIndex,
+    parts
+  };
+}
+var MAX_FIELD_GAP = 24;
+function findOccurrences(index, segments) {
+  if (segments.length === 0 || segments[0] === "") return [];
+  const hits = [];
+  let searchFrom = 0;
+  for (; ; ) {
+    const at = index.stream.indexOf(segments[0], searchFrom);
+    if (at === -1) break;
+    searchFrom = at + 1;
+    let end = at + segments[0].length;
+    let complete = true;
+    for (let s = 1; s < segments.length; s++) {
+      const next = index.stream.indexOf(segments[s], end);
+      if (next === -1 || next - end > MAX_FIELD_GAP) {
+        complete = false;
+        break;
+      }
+      end = next + segments[s].length;
+    }
+    if (!complete || !alignedToFragments(index, at, end)) continue;
+    hits.push(occurrence(index, at, end));
+    searchFrom = end;
+  }
+  return hits;
+}
+var MIN_NEEDLE_LENGTH = 3;
+var MIN_PARTIAL_PREFIX = 16;
+var CHROME_BAND = 0.2;
+function longestRenderedPrefix(index, needle) {
+  if (needle.length < MIN_PARTIAL_PREFIX) return void 0;
+  const anchor = needle.slice(0, MIN_PARTIAL_PREFIX);
+  let best;
+  let searchFrom = 0;
+  for (; ; ) {
+    const at = index.stream.indexOf(anchor, searchFrom);
+    if (at === -1) break;
+    searchFrom = at + 1;
+    const first = fragmentAt(index, at);
+    if (first >= index.fragments.length || index.positions[first] !== at) {
+      continue;
+    }
+    let length = MIN_PARTIAL_PREFIX;
+    while (length < needle.length && index.stream.charCodeAt(at + length) === needle.charCodeAt(length)) {
+      length++;
+    }
+    if (!best || length > best.length) best = { length, at };
+  }
+  return best;
+}
+function sameRow(a, b) {
+  const overlap = Math.min(a.yMax, b.yMax) - Math.max(a.yMin, b.yMin);
+  const shorter = Math.min(a.yMax - a.yMin, b.yMax - b.yMin);
+  return shorter > 0 && overlap > shorter / 2;
+}
+function inChromeBand(page, box) {
+  return box.yMax <= page.heightPt * CHROME_BAND || box.yMin >= page.heightPt * (1 - CHROME_BAND);
+}
+var PAGE_NUMBER_ROW = /^[0-9\s./|-]*$/;
+function assignInventory(pages, inventory) {
+  const results = /* @__PURE__ */ new Map();
+  const chromeWords = /* @__PURE__ */ new Set();
+  const claimRow = (pageIndex, box) => {
+    pages[pageIndex].words.forEach((w, i) => {
+      if (sameRow(w, box)) chromeWords.add(`${pageIndex}:${i}`);
+    });
+  };
+  const repeating = inventory.filter((entry) => entry.repeats);
+  if (repeating.length > 0) {
+    const full = indexDocument(pages);
+    for (const entry of repeating) {
+      const segments = needleSegments(entry.text);
+      const needle = segments.join("");
+      if (needle.length < MIN_NEEDLE_LENGTH) {
+        results.set(entry, {
+          entry,
+          needle,
+          status: "skipped",
+          occurrences: []
+        });
+        continue;
+      }
+      const occurrences = findOccurrences(full, segments).filter(
+        (o) => o.pageIndex === o.endPageIndex && inChromeBand(pages[o.pageIndex], o.parts[0])
+      );
+      for (const o of occurrences) claimRow(o.pageIndex, o.parts[0]);
+      results.set(entry, {
+        entry,
+        needle,
+        status: occurrences.length > 0 ? "mapped" : "missing",
+        occurrences
+      });
+    }
+  }
+  pages.forEach((page, pageIndex) => {
+    page.words.forEach((word, i) => {
+      if (chromeWords.has(`${pageIndex}:${i}`)) return;
+      if (!inChromeBand(page, word)) return;
+      const row = page.words.filter((w) => sameRow(w, word));
+      if (row.every((w) => PAGE_NUMBER_ROW.test(w.text))) {
+        claimRow(pageIndex, word);
+      }
+    });
+  });
+  const body = indexDocument(pages, chromeWords);
+  const claimed = /* @__PURE__ */ new Set();
+  let cursor = 0;
+  for (const entry of inventory) {
+    if (entry.repeats) continue;
+    const segments = needleSegments(entry.text);
+    const needle = segments.join("");
+    if (needle.length < MIN_NEEDLE_LENGTH) {
+      results.set(entry, { entry, needle, status: "skipped", occurrences: [] });
+      continue;
+    }
+    let all = findOccurrences(body, segments);
+    let partial;
+    if (all.length === 0 && segments.length === 1) {
+      const prefix = longestRenderedPrefix(body, needle);
+      if (prefix) {
+        all = [occurrence(body, prefix.at, prefix.at + prefix.length)];
+        partial = { matchedChars: prefix.length, totalChars: needle.length };
+      }
+    }
+    if (all.length === 0) {
+      results.set(entry, { entry, needle, status: "missing", occurrences: [] });
+      continue;
+    }
+    const free = all.filter((o) => !claimed.has(o.at));
+    if (free.length === 0) {
+      results.set(entry, {
+        entry,
+        needle,
+        status: "ambiguous",
+        occurrences: all
+      });
+      continue;
+    }
+    const chosen = free.find((o) => o.at >= cursor) ?? free[0];
+    claimed.add(chosen.at);
+    cursor = chosen.at;
+    results.set(entry, {
+      entry,
+      needle,
+      status: "mapped",
+      occurrences: [chosen],
+      ...partial && { partial }
+    });
+  }
+  return {
+    matches: inventory.map((entry) => results.get(entry)),
+    chromeWords
+  };
+}
+
+// src/rendered-analysis.ts
+var VISIBLE_SPILL_PT = 2;
+var OVERLAP_FRACTION = 0.3;
+function finding(draft) {
+  const { ruleId, mapping, page, context, ...rest } = draft;
+  return {
+    source: "quality",
+    ruleId,
+    certainty: "rendered",
+    blocking: false,
+    ...rest,
+    context: {
+      ...context,
+      mapping,
+      ...page !== void 0 && { page }
+    }
+  };
+}
+function round(value) {
+  return Math.round(value * 10) / 10;
+}
+function intersects(a, b) {
+  const w = Math.min(a.xMax, b.xMax) - Math.max(a.xMin, b.xMin);
+  const h = Math.min(a.yMax, b.yMax) - Math.max(a.yMin, b.yMin);
+  return w > 0 && h > 0 ? w * h : 0;
+}
+function area(w) {
+  return Math.max(0, w.xMax - w.xMin) * Math.max(0, w.yMax - w.yMin);
+}
+function excerpt(text, max = 60) {
+  const flat = text.replace(/\s+/g, " ").trim();
+  return flat.length > max ? `${flat.slice(0, max - 1)}\u2026` : flat;
+}
+function wordOwners(matches) {
+  const owners = /* @__PURE__ */ new Map();
+  for (const match of matches) {
+    if (match.status !== "mapped") continue;
+    for (const o of match.occurrences) {
+      for (const part of o.parts) {
+        for (const w of part.words) owners.set(`${part.pageIndex}:${w}`, match);
+      }
+    }
+  }
+  return owners;
+}
+var lineMaps = /* @__PURE__ */ new WeakMap();
+function lineOfWord(page) {
+  const cached2 = lineMaps.get(page);
+  if (cached2) return cached2;
+  const lines = /* @__PURE__ */ new Map();
+  page.lines.forEach((line, index) => {
+    for (const w of line.words) lines.set(w, index);
+  });
+  lineMaps.set(page, lines);
+  return lines;
+}
+function unionBox(parts) {
+  return parts.reduce(
+    (box, part) => ({
+      xMin: Math.min(box.xMin, part.xMin),
+      yMin: Math.min(box.yMin, part.yMin),
+      xMax: Math.max(box.xMax, part.xMax),
+      yMax: Math.max(box.yMax, part.yMax)
+    }),
+    { xMin: Infinity, yMin: Infinity, xMax: -Infinity, yMax: -Infinity }
+  );
+}
+function analyzeRenderedDocument(input) {
+  const { pages, format } = input;
+  const { matches, chromeWords } = assignInventory(pages, input.inventory);
+  const owners = wordOwners(matches);
+  const findings = [];
+  const ownerOf = (pageIndex, word) => owners.get(`${pageIndex}:${word}`);
+  const clipped = /* @__PURE__ */ new Map();
+  pages.forEach((page, pageIndex) => {
+    page.words.forEach((word, index) => {
+      const beyond = Math.max(
+        -word.xMin,
+        word.xMax - page.widthPt,
+        -word.yMin,
+        word.yMax - page.heightPt
+      );
+      if (beyond <= VISIBLE_SPILL_PT) return;
+      const owner = ownerOf(pageIndex, index);
+      const key = owner ? `entry:${owner.entry.path}` : `page:${pageIndex}`;
+      const bucket = clipped.get(key) ?? {
+        match: owner,
+        words: [],
+        page: pageIndex + 1,
+        maxPt: 0
+      };
+      bucket.words.push(word);
+      bucket.maxPt = Math.max(bucket.maxPt, beyond);
+      clipped.set(key, bucket);
+    });
+  });
+  for (const bucket of clipped.values()) {
+    const sample = excerpt(bucket.words.map((w) => w.text).join(" "));
+    findings.push(
+      finding({
+        ruleId: "rendered/clip",
+        code: QUALITY_CODES.RENDERED_CLIP,
+        category: "integrity",
+        severity: "warning",
+        mapping: bucket.match ? "mapped" : "unmapped",
+        page: bucket.page,
+        path: bucket.match?.entry.path ?? "",
+        message: `${bucket.words.length} word${bucket.words.length === 1 ? "" : "s"} rendered past the page edge on page ${bucket.page} by up to ${round(bucket.maxPt)} pt: "${sample}".`,
+        suggestion: "Shorten the text, allow it to wrap, or widen the column or frame that holds it; text outside the page is cut off in print and in Word.",
+        evidence: {
+          summary: "Word boxes beyond the page bounds",
+          actual: round(bucket.maxPt),
+          expected: 0,
+          unit: "pt",
+          values: { words: bucket.words.length }
+        }
+      })
+    );
+  }
+  for (const match of matches) {
+    if (!match.partial || match.status !== "mapped") continue;
+    const o = match.occurrences[0];
+    const shown = Math.round(
+      100 * match.partial.matchedChars / match.partial.totalChars
+    );
+    findings.push(
+      finding({
+        ruleId: "rendered/clip",
+        code: QUALITY_CODES.RENDERED_CLIP,
+        category: "integrity",
+        severity: "warning",
+        mapping: "mapped",
+        page: o.endPageIndex + 1,
+        path: match.entry.path,
+        message: `"${excerpt(match.entry.text)}" is cut off: about ${shown}% of it rendered on page ${o.endPageIndex + 1} and the rest is nowhere on the page.`,
+        suggestion: "Shorten the text or enlarge the frame, box or cell that holds it; what did not render here will not print either.",
+        evidence: {
+          summary: "Share of the authored text found in the PDF",
+          actual: shown,
+          expected: 100,
+          unit: "%",
+          values: match.partial
+        },
+        context: { kind: "truncated" }
+      })
+    );
+  }
+  for (const match of matches) {
+    const box = match.entry.box;
+    if (!box || match.status !== "mapped") continue;
+    for (const o of match.occurrences) {
+      const extent = unionBox(o.parts);
+      const rendered = {
+        heightPt: extent.yMax - extent.yMin,
+        widthPt: extent.xMax - extent.xMin
+      };
+      const worst = ["heightPt", "widthPt"].filter((axis) => box[axis] !== void 0).map((axis) => ({
+        axis,
+        declared: box[axis],
+        rendered: rendered[axis],
+        over: rendered[axis] - box[axis]
+      })).sort((a, b) => b.over - a.over)[0];
+      if (!worst || worst.over <= VISIBLE_SPILL_PT) continue;
+      const word = worst.axis === "heightPt" ? "taller" : "wider";
+      findings.push(
+        finding({
+          ruleId: "rendered/spill",
+          code: QUALITY_CODES.RENDERED_SPILL,
+          category: "integrity",
+          severity: "warning",
+          mapping: "mapped",
+          page: o.pageIndex + 1,
+          path: match.entry.path,
+          message: `"${excerpt(match.entry.text)}" rendered ${round(worst.over)} pt ${word} than its ${round(worst.declared)} pt box on page ${o.pageIndex + 1}.`,
+          suggestion: "Shorten the text, reduce its size, or enlarge the box; the renderer let it spill past the edge the author drew.",
+          evidence: {
+            summary: "Rendered extent against the declared box",
+            actual: round(worst.rendered),
+            expected: round(worst.declared),
+            unit: "pt",
+            values: { marginPt: round(-worst.over) }
+          }
+        })
+      );
+    }
+  }
+  pages.forEach((page, pageIndex) => {
+    const lines = lineOfWord(page);
+    const seen = /* @__PURE__ */ new Set();
+    const words = page.words;
+    const byTop = words.map((_, i) => i).sort((a, b) => words[a].yMin - words[b].yMin);
+    for (let p = 0; p < byTop.length; p++) {
+      const i = byTop[p];
+      const a = words[i];
+      for (let q = p + 1; q < byTop.length; q++) {
+        const j = byTop[q];
+        const b = words[j];
+        if (b.yMin >= a.yMax) break;
+        const shared = intersects(a, b);
+        if (shared <= 0) continue;
+        const lineA = lines.get(i);
+        if (lineA !== void 0 && lineA === lines.get(j)) continue;
+        const smaller = Math.min(area(a), area(b));
+        if (smaller <= 0 || shared / smaller < OVERLAP_FRACTION) continue;
+        const ownerA = ownerOf(pageIndex, i);
+        const ownerB = ownerOf(pageIndex, j);
+        const pathA = ownerA?.entry.path ?? "";
+        const pathB = ownerB?.entry.path ?? "";
+        const key = pathA && pathB ? [pathA, pathB].sort().join("|") : `${Math.min(i, j)}:${Math.max(i, j)}`;
+        if (seen.has(key)) continue;
+        seen.add(key);
+        const mapping = ownerA && ownerB ? "mapped" : ownerA || ownerB ? "ambiguous" : "unmapped";
+        findings.push(
+          finding({
+            ruleId: "rendered/overlap",
+            code: QUALITY_CODES.RENDERED_OVERLAP,
+            category: "integrity",
+            severity: "warning",
+            mapping,
+            page: pageIndex + 1,
+            path: pathA || pathB,
+            ...pathA && pathB && pathA !== pathB && { relatedPaths: [pathB] },
+            message: `"${a.text}" and "${b.text}" are drawn over each other on page ${pageIndex + 1}.`,
+            suggestion: "Give the two elements separate room: move one, reduce the text, or increase the spacing between them.",
+            evidence: {
+              summary: "Word boxes intersect",
+              actual: round(100 * shared / smaller),
+              expected: 0,
+              unit: "% of the smaller word"
+            }
+          })
+        );
+      }
+    }
+  });
+  for (const match of matches) {
+    if (match.status !== "missing") continue;
+    findings.push(
+      finding({
+        ruleId: "rendered/text-missing",
+        code: QUALITY_CODES.RENDERED_TEXT_MISSING,
+        category: "integrity",
+        severity: "warning",
+        mapping: "mapped",
+        path: match.entry.path,
+        message: `"${excerpt(match.entry.text)}" does not appear anywhere in the rendered pages.`,
+        suggestion: "The text was fully clipped, hidden behind another element, or set somewhere the renderer could not place it; preview the page it belongs to.",
+        evidence: { summary: "No rendered occurrence of the authored text" },
+        context: { role: match.entry.role }
+      })
+    );
+  }
+  let substituted = 0;
+  if (input.fonts && input.fonts.length > 0 && input.requestedFonts) {
+    const seen = /* @__PURE__ */ new Set();
+    for (const requested of input.requestedFonts) {
+      const family = requested.family.trim();
+      if (family === "" || seen.has(family.toLowerCase())) continue;
+      seen.add(family.toLowerCase());
+      if (familyRendered(family, input.fonts)) continue;
+      substituted += 1;
+      findings.push(
+        finding({
+          ruleId: "rendered/font-substituted",
+          code: QUALITY_CODES.RENDERED_FONT_SUBSTITUTED,
+          category: "brand",
+          severity: requested.declared ? "warning" : "info",
+          mapping: requested.path ? "mapped" : "unmapped",
+          path: requested.path ?? "",
+          message: requested.declared ? `"${family}" was declared with a source but the rendered PDF embeds no face of it; the renderer substituted another family.` : `"${family}" is not installed on this host, so the preview substituted another family; a recipient with the font sees the intended face.`,
+          suggestion: requested.declared ? "Check the font source: the file or URL must resolve to a face LibreOffice can load, or the recipient will see the same substitution." : "Install the family on the host for a faithful preview, or declare a source for it in the document fonts so every renderer has it.",
+          context: { declared: requested.declared === true },
+          evidence: {
+            summary: "Requested family against embedded PDF fonts",
+            expected: family,
+            actual: [...new Set(input.fonts.map((f) => f.baseName))].join(", ")
+          }
+        })
+      );
+    }
+  }
+  pages.forEach((page, pageIndex) => {
+    if (page.words.length > 0) return;
+    findings.push(
+      finding({
+        ruleId: "rendered/empty-page",
+        code: QUALITY_CODES.RENDERED_EMPTY_PAGE,
+        category: "integrity",
+        severity: "info",
+        mapping: "unmapped",
+        page: pageIndex + 1,
+        path: "",
+        message: `Page ${pageIndex + 1} carries no text. A full-page figure is fine; a blank page from a stray break is not.`,
+        suggestion: "Preview the page; remove the page break or the empty section if nothing was meant to be there."
+      })
+    );
+  });
+  if (format === "docx") {
+    for (const match of matches) {
+      if (match.entry.role !== "heading" || match.status !== "mapped") continue;
+      const o = match.occurrences[0];
+      const part = o.parts[o.parts.length - 1];
+      if (part.pageIndex >= pages.length - 1) continue;
+      const page = pages[part.pageIndex];
+      const below = page.words.some(
+        (w, i) => !chromeWords.has(`${part.pageIndex}:${i}`) && !part.words.includes(i) && w.yMin >= part.yMax - 1
+      );
+      if (below) continue;
+      findings.push(
+        finding({
+          ruleId: "rendered/heading-stranded",
+          code: QUALITY_CODES.RENDERED_HEADING_STRANDED,
+          category: "composition",
+          severity: "warning",
+          mapping: "mapped",
+          page: part.pageIndex + 1,
+          path: match.entry.path,
+          message: `Heading "${excerpt(match.entry.text)}" is the last line on page ${part.pageIndex + 1}; its content starts on the next page.`,
+          suggestion: "Keep the heading with its first paragraph (keep-with-next), or move a page break so they land together."
+        })
+      );
+    }
+    for (const match of matches) {
+      const role = match.entry.role;
+      if (role !== "body" && role !== "list-item" || match.status !== "mapped")
+        continue;
+      const o = match.occurrences[0];
+      if (o.pageIndex === o.endPageIndex) continue;
+      const first = o.parts[0];
+      const last = o.parts[o.parts.length - 1];
+      const linesOn = (part) => {
+        const lines = lineOfWord(pages[part.pageIndex]);
+        const set = /* @__PURE__ */ new Set();
+        for (const w of part.words) {
+          const line = lines.get(w);
+          if (line !== void 0) set.add(line);
+        }
+        return set.size;
+      };
+      const before = linesOn(first);
+      const after = linesOn(last);
+      if (before === 0 || after === 0) continue;
+      if (before > 1 && after > 1) continue;
+      const which = before === 1 ? "orphan" : "widow";
+      findings.push(
+        finding({
+          ruleId: "rendered/paragraph-split",
+          code: QUALITY_CODES.RENDERED_PARAGRAPH_SPLIT,
+          category: "composition",
+          severity: "info",
+          mapping: "mapped",
+          page: (which === "orphan" ? first.pageIndex : last.pageIndex) + 1,
+          path: match.entry.path,
+          message: which === "orphan" ? `"${excerpt(match.entry.text)}" leaves one line alone at the foot of page ${first.pageIndex + 1}.` : `"${excerpt(match.entry.text)}" leaves one line alone at the top of page ${last.pageIndex + 1}.`,
+          suggestion: "Edit the paragraph a few words shorter or longer, or set widow/orphan control on the style.",
+          evidence: {
+            summary: "Lines on each side of the page break",
+            values: { linesBefore: before, linesAfter: after }
+          },
+          context: { kind: which }
+        })
+      );
+    }
+  }
+  const inventory = {
+    mapped: 0,
+    ambiguous: 0,
+    missing: 0,
+    skipped: 0
+  };
+  for (const match of matches) inventory[match.status] += 1;
+  const byMapping = {
+    mapped: 0,
+    ambiguous: 0,
+    unmapped: 0
+  };
+  for (const f of findings) {
+    byMapping[f.context?.mapping ?? "unmapped"] += 1;
+  }
+  return {
+    findings,
+    summary: {
+      pages: pages.length,
+      words: pages.reduce((n, p) => n + p.words.length, 0),
+      inventory,
+      findings: byMapping,
+      // The same gate the check itself runs under: an empty font list
+      // verified nothing, and must not read as "nothing was substituted".
+      ...input.fonts && input.fonts.length > 0 && input.requestedFonts && {
+        fonts: { requested: input.requestedFonts.length, substituted }
+      }
+    }
+  };
+}
 export {
   DocxFormatAdapter,
   FontconfigStager,
   MacOSCoreTextStager,
   NoopFontStager,
   PptxFormatAdapter,
+  VISIBLE_SPILL_PT,
   WindowsFontStager,
+  analyzeRenderedDocument,
+  assignInventory,
+  authoredTextForMatch,
   clearRasterizerCache,
   createAdapter,
   createLibreOfficePptxBatchRasterizer,
   createLibreOfficePptxRasterizer,
   emitDiagnostic,
+  extractPdfFonts,
   extractPdfTextGeometry,
+  familyRendered,
   getFontStager,
   getRasterizerCacheStats,
+  normalizeForMatch,
+  parsePdfFonts,
   parsePdfTextBbox,
+  pdffontsAvailable,
   pdftotextAvailable,
   runWithDiagnosticSink,
   stderrDiagnosticSink