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

package/dist/io/ooxml/fill.js

@@ -1,562 +1,618 @@
-// The template fill engine (FR2, ADR-0037, ADR-0038): a pure core
-// (word/document.xml bytes + data in, filled bytes + a report out) and the
-// package layer the public /docx functions use (zip in, zip out — only
-// word/document.xml is rewritten, every other part is copied verbatim).
-//
-// Strict (ADR-0037 Karar 5): every problem — the template's, the expected
-// tag set's and the data's — is collected first and thrown together in ONE
-// TemplateError; nothing is written while any remains. A missing tag stops
-// the fill; an empty value (null, "" or whitespace) does not, it is reported.
-//
-// Each tag `w:t` is replaced whole, in both copies, by its start tag (given
-// `xml:space="preserve"` when it has no attribute), the encoded value and its
-// own end tag; every other byte of the document stays where it was, applied
-// in one `applyEdits` pass. A tag the caller names in `multiline` (ADR-0039)
-// takes LFs: each line gets that same start and end tag, with a `w:br` between
-// two lines inside the tag's own run. The output is then READ BACK —
-// re-scanned, every `w:t`'s text and every `w:br` compared with what must now
-// be there, and every written box's two copies compared again (ADR-0038). A
-// read-back failure is a bug in this code, not in the template, so it throws
-// a plain Error and no output.
-//
-// Nothing here — report, problem, error message — ever carries a data value.
-
-import { scanXml } from "./xml-scan.js";
-import { scanTemplate, compareCopies, collectAlternateContents, textTokens } from "./slots.js";
-import { checkValue, encodeTextValue } from "./value.js";
-import { applyEdits } from "./edits.js";
-import { parseZipContainer, resolveMainDocumentPart } from "./zip-container.js";
-import { inflateEntry } from "./inflate.js";
-import { writePackage } from "./opc-write.js";
-import { devFreeze } from "../../dev.js";
-
-/** The package version this engine ships in; a test holds it equal to package.json. */
-export const ENGINE_VERSION = "0.2.0-alpha";
-
-const encoder = new TextEncoder();
-const PRESERVE_ATTRIBUTE = encoder.encode(' xml:space="preserve">');
-
-/**
- * @typedef {import("./slots.js").TemplateProblem & {index?: number, codePoint?: number, count?: number, type?: string}} Problem
- */
-
-/**
- * @typedef {object} TagInfo
- * @property {string} name
- * @property {{docPrId: number | null, page: number}[]} occurrences  document order
- */
-
-/**
- * @typedef {object} FillOptions
- * @property {readonly string[]} [expectedTags]  the binding manifest's exact tag set (SK10)
- * @property {readonly string[]} [multiline]  tags whose values may hold LF line breaks (ADR-0039)
- */
-
-/**
- * Tag name -> value. A string is written as given; null, "" and whitespace
- * are empty (allowed, reported); an absent key or undefined is MISSING_VALUE.
- * @typedef {Record<string, string | null | undefined>} FillData
- */
-
-/**
- * @typedef {object} FillReport
- * @property {TagInfo[]} tags  sorted by name
- * @property {string[]} empty  tags filled with an empty value (null, "" or whitespace), sorted
- * @property {string[]} unused  data keys no tag uses, sorted
- * @property {Problem[]} warnings
- * @property {{tags: number, occurrences: number, textElementsWritten: number}} counts
- *   `textElementsWritten`: tag w:t elements rewritten — one per occurrence per copy. A
- *   multi-line value writes more w:t than that; its extra lines are not counted (ADR-0039).
- * @property {{version: string}} engine
- */
-
-/**
- * Thrown for every problem a caller can fix — the template's, the expected
- * tag set's, the data's — all of them at once in `problems`. A deliberate
- * exception to this codebase's plain-Error convention (import-gate.js): a
- * public API's caller must tell these apart from a bug (ADR-0037 Karar 9).
- */
-export class TemplateError extends Error {
-  /**
-   * @param {string} message
-   * @param {Problem[]} problems
-   * @param {{cause?: unknown}} [options]
-   */
-  constructor(message, problems, options) {
-    super(message, options);
-    this.name = "TemplateError";
-    /** @type {Problem[]} */
-    this.problems = problems;
-  }
-}
-
-/**
- * @param {string} where  the public function's name, for the message
- * @param {Problem[]} problems
- * @returns {TemplateError}
- */
-export function templateError(where, problems) {
-  const shown = problems
-    .slice(0, 5)
-    .map((p) => (p.tag === undefined ? p.code : `${p.code} {${p.tag}}`))
-    .join("; ");
-  const more = problems.length > 5 ? `; and ${problems.length - 5} more` : "";
-  return new TemplateError(`${where}: ${problems.length} problem(s) — ${shown}${more}`, problems);
-}
-
-/**
- * The tags of a scan, sorted by name, each with its occurrences in document order.
- * @param {import("./slots.js").ScanResult} scan
- * @returns {TagInfo[]}
- */
-export function tagInfo(scan) {
-  /** @type {Map<string, {docPrId: number | null, page: number}[]>} */
-  const byName = new Map();
-  for (const o of scan.occurrences) {
-    let list = byName.get(o.name);
-    if (list === undefined) {
-      list = [];
-      byName.set(o.name, list);
-    }
-    list.push({ docPrId: o.docPrId, page: o.page });
-  }
-  return [...byName.keys()].sort().map((name) => ({ name, occurrences: /** @type {{docPrId: number | null, page: number}[]} */ (byName.get(name)) }));
-}
-
-/**
- * Exact-set comparison with a binding manifest (SK10): every expected tag
- * must be in the template, and the template may hold no other.
- * @param {TagInfo[]} tags
- * @param {readonly string[]} expectedTags
- * @returns {Problem[]}
- */
-export function expectedTagProblems(tags, expectedTags) {
-  const present = new Set(tags.map((t) => t.name));
-  const expected = new Set(expectedTags);
-  /** @type {Problem[]} */
-  const problems = [];
-  for (const name of [...expected].sort()) {
-    if (!present.has(name)) problems.push({ code: "EXPECTED_TAG_ABSENT", message: "an expected tag is not in the template", tag: name });
-  }
-  for (const t of tags) {
-    if (!expected.has(t.name)) problems.push({ code: "UNEXPECTED_TAG", message: "the template holds a tag the expected set does not", tag: t.name });
-  }
-  return problems;
-}
-
-/**
- * Every name the `multiline` option lists that the template does not hold
- * (ADR-0039 Karar 1) — a misspelled name would otherwise leave its tag
- * refusing line breaks, or a stale manifest go unnoticed.
- * @param {TagInfo[]} tags
- * @param {readonly string[]} multiline
- * @returns {Problem[]}
- */
-export function multilineProblems(tags, multiline) {
-  const present = new Set(tags.map((t) => t.name));
-  /** @type {Problem[]} */
-  const problems = [];
-  for (const name of [...new Set(multiline)].sort()) {
-    if (!present.has(name)) problems.push({ code: "UNKNOWN_MULTILINE_TAG", message: "a tag the multiline option names is not in the template", tag: name });
-  }
-  return problems;
-}
-
-/**
- * @param {string} where
- * @param {string} key
- * @param {unknown} value
- * @returns {string[] | undefined}
- */
-function stringList(where, key, value) {
-  if (value === undefined) return undefined;
-  if (!Array.isArray(value) || !value.every((t) => typeof t === "string")) {
-    throw new TypeError(`${where}: options.${key} must be an array of strings`);
-  }
-  return [...value];
-}
-
-/**
- * Validates the options object: `expectedTags` and `multiline`, each an
- * array of strings.
- * @param {string} where
- * @param {unknown} options
- * @returns {{expectedTags: string[] | undefined, multiline: string[] | undefined, problems: Problem[]}}
- */
-export function readOptions(where, options) {
-  if (options === undefined) return { expectedTags: undefined, multiline: undefined, problems: [] };
-  if (options === null || typeof options !== "object" || Array.isArray(options)) {
-    throw new TypeError(`${where}: options must be an object`);
-  }
-  /** @type {Problem[]} */
-  const problems = [];
-  for (const key of Object.keys(options)) {
-    if (key !== "expectedTags" && key !== "multiline") {
-      problems.push({ code: "UNKNOWN_OPTION", message: `unknown option "${key}" (only expectedTags and multiline are accepted)` });
-    }
-  }
-  const { expectedTags, multiline } = /** @type {{expectedTags?: unknown, multiline?: unknown}} */ (options);
-  return {
-    expectedTags: stringList(where, "expectedTags", expectedTags),
-    multiline: stringList(where, "multiline", multiline),
-    problems,
-  };
-}
-
-/**
- * @param {unknown} data
- * @returns {Record<string, unknown>}
- */
-function requireData(data) {
-  const proto = data !== null && typeof data === "object" ? Object.getPrototypeOf(data) : undefined;
-  if (proto !== Object.prototype && proto !== null) {
-    throw new TypeError("fillTemplate: data must be a plain object (or one created with Object.create(null))");
-  }
-  return /** @type {Record<string, unknown>} */ (data);
-}
-
-/**
- * The replacement for one tag `w:t`: for each line of the value its own start
- * tag (with `xml:space="preserve"` added when it has no attribute — the scan
- * refused every other attribute), the encoded line and its own end tag, and a
- * `w:br` between two lines (ADR-0039 Karar 3). The break carries the RUN's
- * prefix: that one is bound where the break goes, an `xmlns:` declared on the
- * `w:t` itself would not reach its sibling. One line is the single-line bytes.
- * @param {import("./xml-scan.js").XmlElement} t
- * @param {import("./xml-scan.js").XmlElement} run
- * @param {Uint8Array} xmlBytes
- * @param {Uint8Array[]} lines  the value's encoded lines (one unless multi-line)
- * @returns {Uint8Array}
- */
-function rewriteTag(t, run, xmlBytes, lines) {
-  const start = t.attributes.length === 0
-    ? [xmlBytes.subarray(t.start, t.contentStart - 1), PRESERVE_ATTRIBUTE]
-    : [xmlBytes.subarray(t.start, t.contentStart)];
-  const end = xmlBytes.subarray(t.contentEnd, t.end);
-  const br = encoder.encode(`<${run.prefix ? `${run.prefix}:` : ""}br/>`);
-  /** @type {Uint8Array[]} */
-  const parts = [];
-  lines.forEach((line, i) => {
-    if (i > 0) parts.push(br);
-    parts.push(...start, line, end);
-  });
-  const out = new Uint8Array(parts.reduce((n, p) => n + p.length, 0));
-  let at = 0;
-  for (const p of parts) {
-    out.set(p, at);
-    at += p.length;
-  }
-  return out;
-}
-
-/**
- * @param {{kind: string}[]} tokens
- * @returns {string}  "N w:t and M w:br"
- */
-function tokenCounts(tokens) {
-  const breaks = tokens.filter((k) => k.kind === "br").length;
-  return `${tokens.length - breaks} w:t and ${breaks} w:br`;
-}
-
-/**
- * Reads the filled output back. Throws a plain Error — a failure here is a
- * bug in the engine, never in the template or the data. Exported for its own
- * tests, which hand it deliberately wrong outputs.
- *
- * It compares the whole document's `w:t` + `w:br` token stream (ADR-0039
- * Karar 4): the template's stream with every tag site replaced by its value's
- * lines — `t(L1) (br t(Li))*`, one line unless the tag is multi-line. Kind
- * and text are compared token by token; a count alone would accept lines that
- * were never separated.
- * @param {import("./xml-scan.js").XmlElement} inputRoot
- * @param {Uint8Array} out
- * @param {import("./slots.js").ScanResult} scan
- * @param {Map<string, string>} valueOf
- * @param {ReadonlySet<string>} [multilineSet]  tags whose values were split at LF
- * @returns {void}
- */
-export function readBack(inputRoot, out, scan, valueOf, multilineSet = new Set()) {
-  /** @type {import("./xml-scan.js").XmlElement} */
-  let outRoot;
-  try {
-    outRoot = scanXml(out).root;
-  } catch (err) {
-    throw new Error(`fill: the filled document.xml does not parse — ${/** @type {Error} */ (err).message}`, { cause: err });
-  }
-  /** @type {Map<number, string>} */
-  const filledAt = new Map();
-  for (const o of scan.occurrences) {
-    filledAt.set(o.choice.t.start, o.name);
-    filledAt.set(o.fallback.t.start, o.name);
-  }
-  /** @type {{kind: "t" | "br", text?: string, name?: string}[]} */
-  const expected = [];
-  for (const token of textTokens(inputRoot)) {
-    const name = token.kind === "t" ? filledAt.get(token.el.start) : undefined;
-    if (name === undefined) {
-      expected.push(token.kind === "t" ? { kind: "t", text: token.text } : { kind: "br" });
-      continue;
-    }
-    const value = /** @type {string} */ (valueOf.get(name));
-    (multilineSet.has(name) ? value.split("\n") : [value]).forEach((line, i) => {
-      if (i > 0) expected.push({ kind: "br", name });
-      expected.push({ kind: "t", text: line, name });
-    });
-  }
-  const after = textTokens(outRoot);
-  if (after.length !== expected.length) {
-    throw new Error(`fill: the filled document.xml holds ${tokenCounts(after)}, the filled template must hold ${tokenCounts(expected)}`);
-  }
-  for (let i = 0; i < expected.length; i += 1) {
-    const e = expected[i];
-    const a = after[i];
-    if (a.kind !== e.kind) {
-      throw new Error(`fill: token #${i + 1} is a w:${a.kind} where a w:${e.kind} belongs${e.name === undefined ? "" : ` (the value of {${e.name}})`}`);
-    }
-    if (a.kind === "t" && a.text !== e.text) {
-      throw new Error(`fill: w:t #${i + 1} does not read back as ${e.name === undefined ? "the template's text" : `the value of {${e.name}}`}`);
-    }
-  }
-  const acs = collectAlternateContents(outRoot);
-  for (const index of new Set(scan.occurrences.map((o) => o.acIndex))) {
-    const ac = acs[index];
-    if (ac === undefined || ac.choiceTx.length !== 1 || ac.fallbackTx.length !== 1) {
-      throw new Error(`fill: AlternateContent #${index} lost its shape while filling`);
-    }
-    const copies = compareCopies(ac.choiceTx[0], ac.fallbackTx[0]);
-    if (!copies.equal) throw new Error(`fill: the two copies of AlternateContent #${index} differ after filling, at ${copies.path}`);
-  }
-}
-
-/**
- * Fills word/document.xml. Every problem is collected and thrown together
- * (the package layer adds its other-part findings to the same list).
- * @param {Uint8Array} xmlBytes
- * @param {FillData} data
- * @param {FillOptions} [options]
- * @returns {{xml: Uint8Array, report: FillReport}}
- */
-export function fillDocumentXml(xmlBytes, data, options) {
-  return fillParsed(scanXml(xmlBytes).root, xmlBytes, data, options, []);
-}
-
-/**
- * @param {import("./xml-scan.js").XmlElement} root
- * @param {Uint8Array} xmlBytes
- * @param {unknown} data
- * @param {unknown} options
- * @param {Problem[]} extraProblems
- * @returns {{xml: Uint8Array, report: FillReport}}
- */
-function fillParsed(root, xmlBytes, data, options, extraProblems) {
-  const record = requireData(data);
-  const { expectedTags, multiline, problems: optionProblems } = readOptions("fillTemplate", options);
-  const scan = scanTemplate(root, xmlBytes);
-  const tags = tagInfo(scan);
-  const multilineSet = new Set(multiline ?? []);
-
-  /** @type {Problem[]} */
-  const problems = [...scan.problems, ...extraProblems, ...optionProblems];
-  if (tags.length === 0 && scan.problems.length === 0) {
-    problems.push({ code: "NO_TAGS", message: "the template holds no tag to fill" });
-  }
-  if (expectedTags !== undefined) problems.push(...expectedTagProblems(tags, expectedTags));
-  if (multiline !== undefined) problems.push(...multilineProblems(tags, multiline));
-
-  /** @type {Problem[]} */
-  const warnings = [...scan.warnings];
-  /** @type {Map<string, string>} */
-  const valueOf = new Map();
-  /** @type {string[]} */
-  const empty = [];
-  // Data problems in document order of each tag's first occurrence.
-  const order = [...new Set(scan.occurrences.map((o) => o.name))];
-  for (const name of order) {
-    const value = Object.prototype.hasOwnProperty.call(record, name) ? record[name] : undefined;
-    if (value === undefined) {
-      problems.push({ code: "MISSING_VALUE", message: "the data holds no value for this tag", tag: name });
-      continue;
-    }
-    const check = checkValue(value, { multiline: multilineSet.has(name) });
-    for (const issue of check.errors) {
-      problems.push({ ...issue, message: `the value for this tag is refused (${issue.code})`, tag: name });
-    }
-    for (const issue of check.warnings) {
-      warnings.push({ ...issue, message: "the value for this tag is not in Unicode NFC; it is written as given", tag: name });
-    }
-    if (check.errors.length === 0) {
-      valueOf.set(name, value === null ? "" : /** @type {string} */ (value));
-      if (check.empty) empty.push(name);
-    }
-  }
-  if (problems.length > 0) throw templateError("fillTemplate", problems);
-
-  /** @type {Map<string, Uint8Array[]>} */
-  const encoded = new Map(
-    [...valueOf].map(([name, value]) => [name, (multilineSet.has(name) ? value.split("\n") : [value]).map(encodeTextValue)]),
-  );
-  /** @type {{start: number, end: number, bytes: Uint8Array}[]} */
-  const edits = [];
-  for (const o of scan.occurrences) {
-    const lines = /** @type {Uint8Array[]} */ (encoded.get(o.name));
-    for (const site of [o.choice, o.fallback]) {
-      edits.push({ start: site.t.start, end: site.t.end, bytes: rewriteTag(site.t, site.run, xmlBytes, lines) });
-    }
-  }
-  const xml = applyEdits(xmlBytes, edits);
-  readBack(root, xml, scan, valueOf, multilineSet);
-
-  const used = new Set(order);
-  /** @type {FillReport} */
-  const report = {
-    tags,
-    empty: [...empty].sort(),
-    unused: Object.keys(record).filter((key) => !used.has(key)).sort(),
-    warnings,
-    counts: { tags: tags.length, occurrences: scan.occurrences.length, textElementsWritten: edits.length },
-    engine: { version: ENGINE_VERSION },
-  };
-  return { xml, report: devFreeze(report) };
-}
-
-// --- package layer ------------------------------------------------------------
-
-/**
- * @typedef {object} TemplatePackage
- * @property {import("./zip-container.js").ZipEntry[]} entries
- * @property {import("./zip-container.js").ZipEntry} main
- * @property {Uint8Array} xml  word/document.xml, inflated
- * @property {import("./xml-scan.js").XmlElement} root
- * @property {Problem[]} otherPartProblems
- */
-
-/**
- * @param {string} where
- * @param {unknown} err
- * @returns {TemplateError}
- */
-function unreadable(where, err) {
-  const reason = err instanceof Error ? err.message : String(err);
-  return new TemplateError(`${where}: the package cannot be read — ${reason}`, [{ code: "PACKAGE_UNREADABLE", message: reason }], { cause: err });
-}
-
-/**
- * Whether `el` holds a brace in text a reader shows: in a docProps part every
- * text node (docxtemplater fills those), elsewhere the text of every element
- * named `t` (w:t, a:t, m:t). Attributes never count — docProps/custom.xml
- * carries `fmtid="{…}"` GUIDs in all 46 corpus documents.
- * @param {import("./xml-scan.js").XmlElement} el
- * @param {boolean} allText
- * @returns {boolean}
- */
-function holdsBrace(el, allText) {
-  for (const c of el.children) {
-    if (c.kind === "element") {
-      if (!allText && c.localName === "t") {
-        for (const x of c.children) {
-          if ((x.kind === "text" || x.kind === "cdata") && (x.value.includes("{") || x.value.includes("}"))) return true;
-        }
-      } else if (holdsBrace(c, allText)) {
-        return true;
-      }
-    } else if (allText && (c.kind === "text" || c.kind === "cdata") && (c.value.includes("{") || c.value.includes("}"))) {
-      return true;
-    }
-  }
-  return false;
-}
-
-/**
- * Reads the package: word/document.xml parsed, and every other XML part
- * checked for braces (ADR-0037 Karar 6 — the engine fills only the main
- * document, so a tag anywhere else would ship unfilled). An unreadable zip
- * or XML part is PACKAGE_UNREADABLE.
- * @param {string} where
- * @param {unknown} bytes
- * @returns {Promise<TemplatePackage>}
- */
-async function readTemplatePackage(where, bytes) {
-  if (!(bytes instanceof Uint8Array)) throw new TypeError(`${where}: bytes must be a Uint8Array (a .docx file's bytes)`);
-  try {
-    const entries = parseZipContainer(bytes);
-    const main = resolveMainDocumentPart(entries);
-    const xml = await inflateEntry(bytes, main);
-    const { root } = scanXml(xml);
-    /** @type {Problem[]} */
-    const otherPartProblems = [];
-    for (const entry of entries) {
-      if (entry === main || entry.name === "[Content_Types].xml" || !entry.name.toLowerCase().endsWith(".xml")) continue;
-      const part = scanXml(await inflateEntry(bytes, entry)).root;
-      if (holdsBrace(part, entry.name.startsWith("docProps/"))) {
-        otherPartProblems.push({
-          code: "TAG_IN_OTHER_PART",
-          message: "a brace in a part the engine does not fill (only word/document.xml is filled)",
-          part: entry.name,
-        });
-      }
-    }
-    return { entries, main, xml, root, otherPartProblems };
-  } catch (err) {
-    throw unreadable(where, err);
-  }
-}
-
-/**
- * What a template holds: its tags with their boxes and pages, every problem
- * that would stop a fill, and the warnings. Template problems are reported,
- * not thrown; an unreadable package is a TemplateError (PACKAGE_UNREADABLE).
- * @param {Uint8Array} bytes  a .docx file
- * @returns {Promise<{tags: TagInfo[], problems: Problem[], warnings: Problem[]}>}
- */
-export async function inspectTemplate(bytes) {
-  const pkg = await readTemplatePackage("inspectTemplate", bytes);
-  const scan = scanTemplate(pkg.root, pkg.xml);
-  const tags = tagInfo(scan);
-  /** @type {Problem[]} */
-  const warnings = [...scan.warnings];
-  if (tags.length === 0 && scan.problems.length === 0) {
-    warnings.push({ code: "NO_TAGS", message: "the template holds no tag to fill" });
-  }
-  return devFreeze({ tags, problems: [...scan.problems, ...pkg.otherPartProblems], warnings });
-}
-
-/**
- * `inspectTemplate` plus the binding manifest's exact tag set (SK10). `ok` is
- * true when nothing would stop a fill with complete data — so a template
- * without tags, only a warning to `inspectTemplate`, is a problem here, as it
- * is to `fillTemplate` (the FR2 review found the two disagreeing).
- * @param {Uint8Array} bytes
- * @param {FillOptions} [options]
- * @returns {Promise<{ok: boolean, tags: TagInfo[], problems: Problem[], warnings: Problem[]}>}
- */
-export async function validateTemplate(bytes, options) {
-  const { expectedTags, multiline, problems: optionProblems } = readOptions("validateTemplate", options);
-  const info = await inspectTemplate(bytes);
-  /** @type {Problem[]} */
-  const problems = [...info.problems, ...optionProblems];
-  const noTags = info.warnings.find((w) => w.code === "NO_TAGS");
-  if (noTags !== undefined) problems.push({ ...noTags });
-  if (expectedTags !== undefined) problems.push(...expectedTagProblems(info.tags, expectedTags));
-  if (multiline !== undefined) problems.push(...multilineProblems(info.tags, multiline));
-  const warnings = info.warnings.filter((w) => w.code !== "NO_TAGS");
-  return devFreeze({ ok: problems.length === 0, tags: [...info.tags], problems, warnings });
-}
-
-/**
- * Fills a .docx template. Strict: every problem — the package's other parts,
- * the template, the options, the data — arrives in ONE TemplateError and
- * nothing is written. Otherwise only word/document.xml is rewritten; every
- * other part's bytes are copied verbatim (invariant #10).
- * @param {Uint8Array} bytes  a .docx file
- * @param {FillData} data  a plain object (or one made with Object.create(null))
- * @param {FillOptions} [options]
- * @returns {Promise<{bytes: Uint8Array, documentXml: Uint8Array, report: FillReport}>}
- *   `documentXml` is the filled part uncompressed — hash it to compare
- *   runtimes (zip bytes depend on the runtime's CompressionStream; FR1-DENO)
- */
-export async function fillTemplate(bytes, data, options) {
-  const pkg = await readTemplatePackage("fillTemplate", bytes);
-  const { xml, report } = fillParsed(pkg.root, pkg.xml, data, options, pkg.otherPartProblems);
-  const out = await writePackage(/** @type {Uint8Array} */ (bytes), pkg.entries, { [pkg.main.name]: xml });
-  return { bytes: out, documentXml: xml, report };
-}
+// The template fill engine (FR2, ADR-0037, ADR-0038): a pure core
+// (word/document.xml bytes + data in, filled bytes + a report out) and the
+// package layer the public /docx functions use (zip in, zip out — only
+// word/document.xml is rewritten, every other part is copied verbatim).
+//
+// Strict (ADR-0037 Karar 5): every problem — the template's, the expected
+// tag set's and the data's — is collected first and thrown together in ONE
+// TemplateError; nothing is written while any remains. A missing tag stops
+// the fill; an empty value (null, "" or whitespace) does not, it is reported.
+//
+// Each tag `w:t` is replaced whole, in both copies, by its start tag (given
+// `xml:space="preserve"` when it has no attribute), the encoded value and its
+// own end tag; every other byte of the document stays where it was, applied
+// in one `applyEdits` pass. A tag the caller names in `multiline` (ADR-0039)
+// takes LFs: each line gets that same start and end tag, with a `w:br` between
+// two lines inside the tag's own run. The output is then READ BACK —
+// re-scanned, every `w:t`'s text and every `w:br` compared with what must now
+// be there, and every written box's two copies compared again (ADR-0038). A
+// read-back failure is a bug in this code, not in the template, so it throws
+// a plain Error and no output.
+//
+// Nothing here — report, problem, error message — ever carries a data value.
+
+import { scanXml } from "./xml-scan.js";
+import { scanTemplate, compareCopies, collectAlternateContents, textTokens } from "./slots.js";
+import { checkValue, encodeTextValue } from "./value.js";
+import { applyEdits } from "./edits.js";
+import { parseZipContainer, resolveMainDocumentPart } from "./zip-container.js";
+import { inflateEntry } from "./inflate.js";
+import { writePackage } from "./opc-write.js";
+import { devFreeze } from "../../dev.js";
+
+/** The package version this engine ships in; a test holds it equal to package.json. */
+export const ENGINE_VERSION = "0.3.0-alpha";
+
+const encoder = new TextEncoder();
+const PRESERVE_ATTRIBUTE = encoder.encode(' xml:space="preserve">');
+
+/**
+ * @typedef {import("./slots.js").TemplateProblem & {index?: number, codePoint?: number, count?: number, type?: string}} Problem
+ */
+
+/**
+ * @typedef {object} TagInfo
+ * @property {string} name
+ * @property {{docPrId: number | null, page: number}[]} occurrences  document order
+ */
+
+/**
+ * @typedef {object} FillOptions
+ * @property {readonly string[]} [expectedTags]  the binding manifest's exact tag set (SK10)
+ * @property {readonly string[]} [multiline]  tags whose values may hold LF line breaks (ADR-0039)
+ */
+
+/**
+ * Tag name -> value. A string is written as given; null, "" and whitespace
+ * are empty (allowed, reported); an absent key or undefined is MISSING_VALUE.
+ * @typedef {Record<string, string | null | undefined>} FillData
+ */
+
+/**
+ * @typedef {object} FillReport
+ * @property {TagInfo[]} tags  sorted by name
+ * @property {string[]} empty  tags filled with an empty value (null, "" or whitespace), sorted
+ * @property {string[]} unused  data keys no tag uses, sorted
+ * @property {Problem[]} warnings
+ * @property {{tags: number, occurrences: number, textElementsWritten: number}} counts
+ *   `textElementsWritten`: tag w:t elements rewritten — one per occurrence per copy. A
+ *   multi-line value writes more w:t than that; its extra lines are not counted (ADR-0039).
+ * @property {{version: string}} engine
+ */
+
+/**
+ * Thrown for every problem a caller can fix — the template's, the expected
+ * tag set's, the data's — all of them at once in `problems`. A deliberate
+ * exception to this codebase's plain-Error convention (import-gate.js): a
+ * public API's caller must tell these apart from a bug (ADR-0037 Karar 9).
+ */
+export class TemplateError extends Error {
+  /**
+   * @param {string} message
+   * @param {Problem[]} problems
+   * @param {{cause?: unknown}} [options]
+   */
+  constructor(message, problems, options) {
+    super(message, options);
+    this.name = "TemplateError";
+    /** @type {Problem[]} */
+    this.problems = problems;
+  }
+}
+
+/**
+ * @param {string} where  the public function's name, for the message
+ * @param {Problem[]} problems
+ * @returns {TemplateError}
+ */
+export function templateError(where, problems) {
+  const shown = problems
+    .slice(0, 5)
+    .map((p) => (p.tag === undefined ? p.code : `${p.code} {${p.tag}}`))
+    .join("; ");
+  const more = problems.length > 5 ? `; and ${problems.length - 5} more` : "";
+  return new TemplateError(`${where}: ${problems.length} problem(s) — ${shown}${more}`, problems);
+}
+
+/**
+ * The tags of a scan, sorted by name, each with its occurrences in document order.
+ * @param {import("./slots.js").ScanResult} scan
+ * @returns {TagInfo[]}
+ */
+export function tagInfo(scan) {
+  /** @type {Map<string, {docPrId: number | null, page: number}[]>} */
+  const byName = new Map();
+  for (const o of scan.occurrences) {
+    let list = byName.get(o.name);
+    if (list === undefined) {
+      list = [];
+      byName.set(o.name, list);
+    }
+    list.push({ docPrId: o.docPrId, page: o.page });
+  }
+  return [...byName.keys()].sort().map((name) => ({ name, occurrences: /** @type {{docPrId: number | null, page: number}[]} */ (byName.get(name)) }));
+}
+
+/**
+ * Exact-set comparison with a binding manifest (SK10): every expected tag
+ * must be in the template, and the template may hold no other.
+ * @param {TagInfo[]} tags
+ * @param {readonly string[]} expectedTags
+ * @returns {Problem[]}
+ */
+export function expectedTagProblems(tags, expectedTags) {
+  const present = new Set(tags.map((t) => t.name));
+  const expected = new Set(expectedTags);
+  /** @type {Problem[]} */
+  const problems = [];
+  for (const name of [...expected].sort()) {
+    if (!present.has(name)) problems.push({ code: "EXPECTED_TAG_ABSENT", message: "an expected tag is not in the template", tag: name });
+  }
+  for (const t of tags) {
+    if (!expected.has(t.name)) problems.push({ code: "UNEXPECTED_TAG", message: "the template holds a tag the expected set does not", tag: t.name });
+  }
+  return problems;
+}
+
+/**
+ * Every name the `multiline` option lists that the template does not hold
+ * (ADR-0039 Karar 1) — a misspelled name would otherwise leave its tag
+ * refusing line breaks, or a stale manifest go unnoticed.
+ * @param {TagInfo[]} tags
+ * @param {readonly string[]} multiline
+ * @returns {Problem[]}
+ */
+export function multilineProblems(tags, multiline) {
+  const present = new Set(tags.map((t) => t.name));
+  /** @type {Problem[]} */
+  const problems = [];
+  for (const name of [...new Set(multiline)].sort()) {
+    if (!present.has(name)) problems.push({ code: "UNKNOWN_MULTILINE_TAG", message: "a tag the multiline option names is not in the template", tag: name });
+  }
+  return problems;
+}
+
+/**
+ * @param {string} where
+ * @param {string} key
+ * @param {unknown} value
+ * @returns {string[] | undefined}
+ */
+function stringList(where, key, value) {
+  if (value === undefined) return undefined;
+  if (!Array.isArray(value) || !value.every((t) => typeof t === "string")) {
+    throw new TypeError(`${where}: options.${key} must be an array of strings`);
+  }
+  return [...value];
+}
+
+/**
+ * @typedef {object} ReadOptions
+ * @property {string[] | undefined} expectedTags
+ * @property {string[] | undefined} multiline
+ * @property {Record<string, unknown>} given  the options object as passed ({} when undefined), for keys a caller adds
+ * @property {Problem[]} problems
+ */
+
+/**
+ * Validates the options object: `expectedTags` and `multiline`, each an
+ * array of strings, plus whatever other keys the caller accepts (checkFit's
+ * `capacity`, which it reads itself); any other key is UNKNOWN_OPTION.
+ * @param {string} where
+ * @param {unknown} options
+ * @param {readonly string[]} [accepted]
+ * @returns {ReadOptions}
+ */
+export function readOptions(where, options, accepted = ["expectedTags", "multiline"]) {
+  if (options === undefined) return { expectedTags: undefined, multiline: undefined, given: {}, problems: [] };
+  if (options === null || typeof options !== "object" || Array.isArray(options)) {
+    throw new TypeError(`${where}: options must be an object`);
+  }
+  const list = `${accepted.slice(0, -1).join(", ")} and ${accepted[accepted.length - 1]}`;
+  /** @type {Problem[]} */
+  const problems = [];
+  for (const key of Object.keys(options)) {
+    if (!accepted.includes(key)) {
+      problems.push({ code: "UNKNOWN_OPTION", message: `unknown option "${key}" (only ${list} are accepted)` });
+    }
+  }
+  const given = /** @type {Record<string, unknown>} */ (options);
+  return {
+    expectedTags: stringList(where, "expectedTags", given.expectedTags),
+    multiline: stringList(where, "multiline", given.multiline),
+    given,
+    problems,
+  };
+}
+
+/**
+ * @param {string} where
+ * @param {unknown} data
+ * @returns {Record<string, unknown>}
+ */
+function requireData(where, data) {
+  const proto = data !== null && typeof data === "object" ? Object.getPrototypeOf(data) : undefined;
+  if (proto !== Object.prototype && proto !== null) {
+    throw new TypeError(`${where}: data must be a plain object (or one created with Object.create(null))`);
+  }
+  return /** @type {Record<string, unknown>} */ (data);
+}
+
+/**
+ * The replacement for one tag `w:t`: for each line of the value its own start
+ * tag (with `xml:space="preserve"` added when it has no attribute — the scan
+ * refused every other attribute), the encoded line and its own end tag, and a
+ * `w:br` between two lines (ADR-0039 Karar 3). The break carries the RUN's
+ * prefix: that one is bound where the break goes, an `xmlns:` declared on the
+ * `w:t` itself would not reach its sibling. One line is the single-line bytes.
+ * @param {import("./xml-scan.js").XmlElement} t
+ * @param {import("./xml-scan.js").XmlElement} run
+ * @param {Uint8Array} xmlBytes
+ * @param {Uint8Array[]} lines  the value's encoded lines (one unless multi-line)
+ * @returns {Uint8Array}
+ */
+function rewriteTag(t, run, xmlBytes, lines) {
+  const start = t.attributes.length === 0
+    ? [xmlBytes.subarray(t.start, t.contentStart - 1), PRESERVE_ATTRIBUTE]
+    : [xmlBytes.subarray(t.start, t.contentStart)];
+  const end = xmlBytes.subarray(t.contentEnd, t.end);
+  const br = encoder.encode(`<${run.prefix ? `${run.prefix}:` : ""}br/>`);
+  /** @type {Uint8Array[]} */
+  const parts = [];
+  lines.forEach((line, i) => {
+    if (i > 0) parts.push(br);
+    parts.push(...start, line, end);
+  });
+  const out = new Uint8Array(parts.reduce((n, p) => n + p.length, 0));
+  let at = 0;
+  for (const p of parts) {
+    out.set(p, at);
+    at += p.length;
+  }
+  return out;
+}
+
+/**
+ * @param {{kind: string}[]} tokens
+ * @returns {string}  "N w:t and M w:br"
+ */
+function tokenCounts(tokens) {
+  const breaks = tokens.filter((k) => k.kind === "br").length;
+  return `${tokens.length - breaks} w:t and ${breaks} w:br`;
+}
+
+/**
+ * Reads the filled output back. Throws a plain Error — a failure here is a
+ * bug in the engine, never in the template or the data. Exported for its own
+ * tests, which hand it deliberately wrong outputs.
+ *
+ * It compares the whole document's `w:t` + `w:br` token stream (ADR-0039
+ * Karar 4): the template's stream with every tag site replaced by its value's
+ * lines — `t(L1) (br t(Li))*`, one line unless the tag is multi-line. Kind
+ * and text are compared token by token; a count alone would accept lines that
+ * were never separated.
+ * @param {import("./xml-scan.js").XmlElement} inputRoot
+ * @param {Uint8Array} out
+ * @param {import("./slots.js").ScanResult} scan
+ * @param {Map<string, string>} valueOf
+ * @param {ReadonlySet<string>} [multilineSet]  tags whose values were split at LF
+ * @returns {void}
+ */
+export function readBack(inputRoot, out, scan, valueOf, multilineSet = new Set()) {
+  /** @type {import("./xml-scan.js").XmlElement} */
+  let outRoot;
+  try {
+    outRoot = scanXml(out).root;
+  } catch (err) {
+    throw new Error(`fill: the filled document.xml does not parse — ${/** @type {Error} */ (err).message}`, { cause: err });
+  }
+  /** @type {Map<number, string>} */
+  const filledAt = new Map();
+  for (const o of scan.occurrences) {
+    filledAt.set(o.choice.t.start, o.name);
+    filledAt.set(o.fallback.t.start, o.name);
+  }
+  /** @type {{kind: "t" | "br", text?: string, name?: string}[]} */
+  const expected = [];
+  for (const token of textTokens(inputRoot)) {
+    const name = token.kind === "t" ? filledAt.get(token.el.start) : undefined;
+    if (name === undefined) {
+      expected.push(token.kind === "t" ? { kind: "t", text: token.text } : { kind: "br" });
+      continue;
+    }
+    const value = /** @type {string} */ (valueOf.get(name));
+    (multilineSet.has(name) ? value.split("\n") : [value]).forEach((line, i) => {
+      if (i > 0) expected.push({ kind: "br", name });
+      expected.push({ kind: "t", text: line, name });
+    });
+  }
+  const after = textTokens(outRoot);
+  if (after.length !== expected.length) {
+    throw new Error(`fill: the filled document.xml holds ${tokenCounts(after)}, the filled template must hold ${tokenCounts(expected)}`);
+  }
+  for (let i = 0; i < expected.length; i += 1) {
+    const e = expected[i];
+    const a = after[i];
+    if (a.kind !== e.kind) {
+      throw new Error(`fill: token #${i + 1} is a w:${a.kind} where a w:${e.kind} belongs${e.name === undefined ? "" : ` (the value of {${e.name}})`}`);
+    }
+    if (a.kind === "t" && a.text !== e.text) {
+      throw new Error(`fill: w:t #${i + 1} does not read back as ${e.name === undefined ? "the template's text" : `the value of {${e.name}}`}`);
+    }
+  }
+  const acs = collectAlternateContents(outRoot);
+  for (const index of new Set(scan.occurrences.map((o) => o.acIndex))) {
+    const ac = acs[index];
+    if (ac === undefined || ac.choiceTx.length !== 1 || ac.fallbackTx.length !== 1) {
+      throw new Error(`fill: AlternateContent #${index} lost its shape while filling`);
+    }
+    const copies = compareCopies(ac.choiceTx[0], ac.fallbackTx[0]);
+    if (!copies.equal) throw new Error(`fill: the two copies of AlternateContent #${index} differ after filling, at ${copies.path}`);
+  }
+}
+
+/**
+ * Fills word/document.xml. Every problem is collected and thrown together
+ * (the package layer adds its other-part findings to the same list).
+ * @param {Uint8Array} xmlBytes
+ * @param {FillData} data
+ * @param {FillOptions} [options]
+ * @returns {{xml: Uint8Array, report: FillReport}}
+ */
+export function fillDocumentXml(xmlBytes, data, options) {
+  return fillParsed(scanXml(xmlBytes).root, xmlBytes, data, options, []);
+}
+
+/**
+ * @typedef {object} PreparedFill  everything a fill decides before it writes a byte
+ * @property {Record<string, unknown>} record  the data
+ * @property {import("./slots.js").ScanResult} scan
+ * @property {TagInfo[]} tags
+ * @property {Set<string>} multilineSet
+ * @property {Map<string, string>} valueOf  tag -> value as written ("" for null)
+ * @property {string[]} empty  tags with an empty value, in document order
+ * @property {string[]} order  tag names in document order of their first occurrence
+ * @property {Problem[]} warnings
+ * @property {ReadOptions} options
+ */
+
+/**
+ * Every check a fill makes before writing: the data's shape, the template's
+ * problems, the options', the expected tag set's, each value's. Throws ONE
+ * TemplateError (named for `where`) with all of them. fillTemplate and
+ * checkFit both go through here, so they refuse exactly the same inputs
+ * (ADR-0042 Karar 2).
+ * @param {string} where  the public function's name
+ * @param {import("./xml-scan.js").XmlElement} root
+ * @param {Uint8Array} xmlBytes
+ * @param {unknown} data
+ * @param {unknown} rawOptions
+ * @param {Problem[]} extraProblems  the package layer's other-part findings
+ * @param {readonly string[]} [accepted]  option keys the caller accepts (readOptions)
+ * @param {(options: ReadOptions) => Problem[]} [ownOptionProblems]  the caller's check of its own keys, run
+ *   right after the shared ones so its problems join the same TemplateError
+ * @returns {PreparedFill}
+ */
+export function prepareFill(where, root, xmlBytes, data, rawOptions, extraProblems, accepted, ownOptionProblems) {
+  const record = requireData(where, data);
+  const options = readOptions(where, rawOptions, accepted);
+  const { expectedTags, multiline } = options;
+  const optionProblems = [...options.problems, ...(ownOptionProblems ? ownOptionProblems(options) : [])];
+  const scan = scanTemplate(root, xmlBytes);
+  const tags = tagInfo(scan);
+  const multilineSet = new Set(multiline ?? []);
+
+  /** @type {Problem[]} */
+  const problems = [...scan.problems, ...extraProblems, ...optionProblems];
+  if (tags.length === 0 && scan.problems.length === 0) {
+    problems.push({ code: "NO_TAGS", message: "the template holds no tag to fill" });
+  }
+  if (expectedTags !== undefined) problems.push(...expectedTagProblems(tags, expectedTags));
+  if (multiline !== undefined) problems.push(...multilineProblems(tags, multiline));
+
+  /** @type {Problem[]} */
+  const warnings = [...scan.warnings];
+  /** @type {Map<string, string>} */
+  const valueOf = new Map();
+  /** @type {string[]} */
+  const empty = [];
+  // Data problems in document order of each tag's first occurrence.
+  const order = [...new Set(scan.occurrences.map((o) => o.name))];
+  for (const name of order) {
+    const value = Object.prototype.hasOwnProperty.call(record, name) ? record[name] : undefined;
+    if (value === undefined) {
+      problems.push({ code: "MISSING_VALUE", message: "the data holds no value for this tag", tag: name });
+      continue;
+    }
+    const check = checkValue(value, { multiline: multilineSet.has(name) });
+    for (const issue of check.errors) {
+      problems.push({ ...issue, message: `the value for this tag is refused (${issue.code})`, tag: name });
+    }
+    for (const issue of check.warnings) {
+      warnings.push({ ...issue, message: "the value for this tag is not in Unicode NFC; it is written as given", tag: name });
+    }
+    if (check.errors.length === 0) {
+      valueOf.set(name, value === null ? "" : /** @type {string} */ (value));
+      if (check.empty) empty.push(name);
+    }
+  }
+  if (problems.length > 0) throw templateError(where, problems);
+  return { record, scan, tags, multilineSet, valueOf, empty, order, warnings, options };
+}
+
+/**
+ * @param {import("./xml-scan.js").XmlElement} root
+ * @param {Uint8Array} xmlBytes
+ * @param {unknown} data
+ * @param {unknown} options
+ * @param {Problem[]} extraProblems
+ * @returns {{xml: Uint8Array, report: FillReport}}
+ */
+function fillParsed(root, xmlBytes, data, options, extraProblems) {
+  const { record, scan, tags, multilineSet, valueOf, empty, order, warnings } = prepareFill("fillTemplate", root, xmlBytes, data, options, extraProblems);
+
+  /** @type {Map<string, Uint8Array[]>} */
+  const encoded = new Map(
+    [...valueOf].map(([name, value]) => [name, (multilineSet.has(name) ? value.split("\n") : [value]).map(encodeTextValue)]),
+  );
+  /** @type {{start: number, end: number, bytes: Uint8Array}[]} */
+  const edits = [];
+  for (const o of scan.occurrences) {
+    const lines = /** @type {Uint8Array[]} */ (encoded.get(o.name));
+    for (const site of [o.choice, o.fallback]) {
+      edits.push({ start: site.t.start, end: site.t.end, bytes: rewriteTag(site.t, site.run, xmlBytes, lines) });
+    }
+  }
+  const xml = applyEdits(xmlBytes, edits);
+  readBack(root, xml, scan, valueOf, multilineSet);
+
+  const used = new Set(order);
+  /** @type {FillReport} */
+  const report = {
+    tags,
+    empty: [...empty].sort(),
+    unused: Object.keys(record).filter((key) => !used.has(key)).sort(),
+    warnings,
+    counts: { tags: tags.length, occurrences: scan.occurrences.length, textElementsWritten: edits.length },
+    engine: { version: ENGINE_VERSION },
+  };
+  return { xml, report: devFreeze(report) };
+}
+
+// --- package layer ------------------------------------------------------------
+
+/**
+ * @typedef {object} TemplatePackage
+ * @property {import("./zip-container.js").ZipEntry[]} entries
+ * @property {import("./zip-container.js").ZipEntry} main
+ * @property {Uint8Array} xml  word/document.xml, inflated
+ * @property {import("./xml-scan.js").XmlElement} root
+ * @property {Problem[]} otherPartProblems
+ * @property {Map<string, Uint8Array>} parts  the inflated XML parts the caller asked to keep
+ */
+
+/**
+ * @param {string} where
+ * @param {unknown} err
+ * @returns {TemplateError}
+ */
+function unreadable(where, err) {
+  const reason = err instanceof Error ? err.message : String(err);
+  return new TemplateError(`${where}: the package cannot be read — ${reason}`, [{ code: "PACKAGE_UNREADABLE", message: reason }], { cause: err });
+}
+
+/**
+ * Whether `el` holds a brace in text a reader shows: in a docProps part every
+ * text node (docxtemplater fills those), elsewhere the text of every element
+ * named `t` (w:t, a:t, m:t). Attributes never count — docProps/custom.xml
+ * carries `fmtid="{…}"` GUIDs in all 46 corpus documents.
+ * @param {import("./xml-scan.js").XmlElement} el
+ * @param {boolean} allText
+ * @returns {boolean}
+ */
+function holdsBrace(el, allText) {
+  for (const c of el.children) {
+    if (c.kind === "element") {
+      if (!allText && c.localName === "t") {
+        for (const x of c.children) {
+          if ((x.kind === "text" || x.kind === "cdata") && (x.value.includes("{") || x.value.includes("}"))) return true;
+        }
+      } else if (holdsBrace(c, allText)) {
+        return true;
+      }
+    } else if (allText && (c.kind === "text" || c.kind === "cdata") && (c.value.includes("{") || c.value.includes("}"))) {
+      return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * Reads the package: word/document.xml parsed, and every other XML part
+ * checked for braces (ADR-0037 Karar 6 — the engine fills only the main
+ * document, so a tag anywhere else would ship unfilled). An unreadable zip
+ * or XML part is PACKAGE_UNREADABLE.
+ * @param {string} where
+ * @param {unknown} bytes
+ * @param {readonly string[]} [keep]  part names whose inflated bytes the caller needs (checkFit: styles, settings, theme)
+ * @returns {Promise<TemplatePackage>}
+ */
+export async function readTemplatePackage(where, bytes, keep = []) {
+  if (!(bytes instanceof Uint8Array)) throw new TypeError(`${where}: bytes must be a Uint8Array (a .docx file's bytes)`);
+  try {
+    const entries = parseZipContainer(bytes);
+    const main = resolveMainDocumentPart(entries);
+    const xml = await inflateEntry(bytes, main);
+    const { root } = scanXml(xml);
+    /** @type {Problem[]} */
+    const otherPartProblems = [];
+    /** @type {Map<string, Uint8Array>} */
+    const parts = new Map();
+    for (const entry of entries) {
+      if (entry === main || entry.name === "[Content_Types].xml" || !entry.name.toLowerCase().endsWith(".xml")) continue;
+      const partBytes = await inflateEntry(bytes, entry);
+      if (keep.includes(entry.name)) parts.set(entry.name, partBytes);
+      const part = scanXml(partBytes).root;
+      if (holdsBrace(part, entry.name.startsWith("docProps/"))) {
+        otherPartProblems.push({
+          code: "TAG_IN_OTHER_PART",
+          message: "a brace in a part the engine does not fill (only word/document.xml is filled)",
+          part: entry.name,
+        });
+      }
+    }
+    return { entries, main, xml, root, otherPartProblems, parts };
+  } catch (err) {
+    throw unreadable(where, err);
+  }
+}
+
+/**
+ * What a template holds: its tags with their boxes and pages, every problem
+ * that would stop a fill, and the warnings. Template problems are reported,
+ * not thrown; an unreadable package is a TemplateError (PACKAGE_UNREADABLE).
+ * @param {Uint8Array} bytes  a .docx file
+ * @returns {Promise<{tags: TagInfo[], problems: Problem[], warnings: Problem[]}>}
+ */
+export async function inspectTemplate(bytes) {
+  const pkg = await readTemplatePackage("inspectTemplate", bytes);
+  const scan = scanTemplate(pkg.root, pkg.xml);
+  const tags = tagInfo(scan);
+  /** @type {Problem[]} */
+  const warnings = [...scan.warnings];
+  if (tags.length === 0 && scan.problems.length === 0) {
+    warnings.push({ code: "NO_TAGS", message: "the template holds no tag to fill" });
+  }
+  return devFreeze({ tags, problems: [...scan.problems, ...pkg.otherPartProblems], warnings });
+}
+
+/**
+ * `inspectTemplate` plus the binding manifest's exact tag set (SK10). `ok` is
+ * true when nothing would stop a fill with complete data — so a template
+ * without tags, only a warning to `inspectTemplate`, is a problem here, as it
+ * is to `fillTemplate` (the FR2 review found the two disagreeing).
+ * @param {Uint8Array} bytes
+ * @param {FillOptions} [options]
+ * @returns {Promise<{ok: boolean, tags: TagInfo[], problems: Problem[], warnings: Problem[]}>}
+ */
+export async function validateTemplate(bytes, options) {
+  const { expectedTags, multiline, problems: optionProblems } = readOptions("validateTemplate", options);
+  const info = await inspectTemplate(bytes);
+  /** @type {Problem[]} */
+  const problems = [...info.problems, ...optionProblems];
+  const noTags = info.warnings.find((w) => w.code === "NO_TAGS");
+  if (noTags !== undefined) problems.push({ ...noTags });
+  if (expectedTags !== undefined) problems.push(...expectedTagProblems(info.tags, expectedTags));
+  if (multiline !== undefined) problems.push(...multilineProblems(info.tags, multiline));
+  const warnings = info.warnings.filter((w) => w.code !== "NO_TAGS");
+  return devFreeze({ ok: problems.length === 0, tags: [...info.tags], problems, warnings });
+}
+
+/**
+ * Fills a .docx template. Strict: every problem — the package's other parts,
+ * the template, the options, the data — arrives in ONE TemplateError and
+ * nothing is written. Otherwise only word/document.xml is rewritten; every
+ * other part's bytes are copied verbatim (invariant #10).
+ * @param {Uint8Array} bytes  a .docx file
+ * @param {FillData} data  a plain object (or one made with Object.create(null))
+ * @param {FillOptions} [options]
+ * @returns {Promise<{bytes: Uint8Array, documentXml: Uint8Array, report: FillReport}>}
+ *   `documentXml` is the filled part uncompressed — hash it to compare
+ *   runtimes (zip bytes depend on the runtime's CompressionStream; FR1-DENO)
+ */
+export async function fillTemplate(bytes, data, options) {
+  const pkg = await readTemplatePackage("fillTemplate", bytes);
+  const { xml, report } = fillParsed(pkg.root, pkg.xml, data, options, pkg.otherPartProblems);
+  const out = await writePackage(/** @type {Uint8Array} */ (bytes), pkg.entries, { [pkg.main.name]: xml });
+  return { bytes: out, documentXml: xml, report };
+}