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

package/dist/io/ooxml/recipe.js

@@ -1,708 +1,708 @@
-// Template recipes (FR3, ADR-0040): a form becomes a `{tag}` template only
-// through a recipe — a JSON pinned to the SHA-256 of the parts it reads —
-// applied as ONE byte patch of word/document.xml, the same edit in both copies
-// of every box (ADR-0038). Never by saving in Word: Word 2010+ writes a
-// w14:paraId into every paragraph and the copies would part (ADR-0037
-// DOĞRULANMALI 5).
-//
-// Four ops, each addressed by its box's wp:docPr id and, where it matters, a
-// paragraph and a run index, each carrying an expectation that catches an
-// authoring mistake and keeps the recipe readable:
-//   setTag         the box's one empty value paragraph gets a tag run at its end
-//   replaceRuns    a contiguous run range becomes one tag run, a named run's rPr kept
-//   tagText        a substring of one run's text becomes a tag run, the run split
-//   fillParagraph  the paragraph `expect` names, byte for byte (empty or not), is
-//                  replaced by a literal, validated paragraph
-//
-// Problems are collected stage by stage — the recipe's shape, the pins, every op
-// and their overlaps, the written template's scan — and each stage's are thrown
-// together; a later stage does not run when an earlier one failed. Nothing is written
-// while any remains. The output is then READ BACK: its w:t + w:br token stream
-// must be the input's with exactly each op's declared change, every touched box's
-// copies are compared again, and the template scan must find exactly the
-// recipe's tags — no problem, no warning. A read-back failure is a bug here, a
-// plain Error; a scan finding is the recipe's, a problem.
-//
-// Internal: not exported from /docx (ADR-0040 Karar 2). It imports neither the
-// importer's entry (import.js) nor the exporter, the style resolver or the model —
-// their gates can refuse a form that templates fine. slots.js's section count
-// reaches the importer's helpers (sections.js -> drawingml.js -> import-gate.js),
-// but no gate is called on that path.
-
-import { scanXml, getAttr, isElement, findChild } from "./xml-scan.js";
-import { scanTemplate, compareCopies, collectAlternateContents, textTokens } from "./slots.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 { tagInfo } from "./fill.js";
-import { W_NS, WP_NS, XML_NS } from "./ns.js";
-
-const encoder = new TextEncoder();
-const decoder = new TextDecoder("utf-8", { fatal: true });
-const TAG_NAME = /^[a-z][a-z0-9_]*$/;
-const TAG_TEXT = /^\{([a-z][a-z0-9_]*)\}$/;
-const SHA256_HEX = /^[0-9a-f]{64}$/;
-
-/** Elements a fillParagraph fragment may hold (WordprocessingML, local names). */
-const FRAGMENT_ELEMENTS = new Set([
-  "p", "pPr", "pStyle", "spacing", "ind", "jc", "tabs", "tab", "rPr", "rFonts", "sz", "szCs", "b", "bCs", "i", "iCs", "color", "position", "r", "t",
-]);
-
-const RECIPE_KEYS = new Set(["recipe", "id", "title", "source", "constants", "ops"]);
-/** @type {Record<string, string[]>} */
-const OP_KEYS = {
-  setTag: ["op", "docPrId", "tag", "label"],
-  replaceRuns: ["op", "docPrId", "paragraph", "runs", "expectTexts", "keepRPrOf", "tag"],
-  tagText: ["op", "docPrId", "paragraph", "run", "find", "tag"],
-  fillParagraph: ["op", "docPrId", "paragraph", "expect", "paragraphXml"],
-};
-
-/**
- * @typedef {object} RecipeProblem
- * @property {string} code
- * @property {string} message
- * @property {number} [op]  index of the op in `ops`
- * @property {number} [docPrId]
- * @property {string} [tag]
- * @property {string} [part]
- */
-
-/**
- * @typedef {object} Recipe
- * @property {1} recipe
- * @property {string} id
- * @property {string} [title]
- * @property {{parts: Record<string, string>}} source  part name -> SHA-256 (hex)
- * @property {{emptyValueParagraph?: string, valueRunRPr?: string}} [constants]
- * @property {any[]} ops
- */
-
-/**
- * @typedef {object} RecipeReport
- * @property {{id: string, sha256: string}} recipe  sha256 of the recipe's canonical JSON
- * @property {import("./fill.js").TagInfo[]} tags  the template's tags, as the fill engine sees them
- * @property {Record<string, number>} ops  how many of each op
- * @property {{input: string, output: string}} documentXml  SHA-256 of word/document.xml before and after
- */
-
-/**
- * @param {string} message
- * @param {RecipeProblem[]} problems
- * @returns {Error & {problems: RecipeProblem[]}}
- */
-function recipeError(message, problems) {
-  const shown = problems.slice(0, 5).map((p) => (p.op === undefined ? p.code : `${p.code} (op ${p.op})`)).join("; ");
-  const more = problems.length > 5 ? `; and ${problems.length - 5} more` : "";
-  return Object.assign(new Error(`${message}: ${problems.length} problem(s) — ${shown}${more}`), { problems });
-}
-
-/**
- * JSON with every object's keys sorted, arrays in order — the recipe's identity
- * does not depend on key order or on the line endings a checkout gives the file.
- * @param {unknown} value
- * @returns {string}
- */
-export function canonicalJson(value) {
-  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`;
-  if (value !== null && typeof value === "object") {
-    const obj = /** @type {Record<string, unknown>} */ (value);
-    return `{${Object.keys(obj).sort().map((k) => `${JSON.stringify(k)}:${canonicalJson(obj[k])}`).join(",")}}`;
-  }
-  return JSON.stringify(value);
-}
-
-/**
- * SHA-256 of `bytes` as lowercase hex, through Web Crypto — touched only when
- * called (invariant #5). Node 20+, Deno and browsers on a secure context
- * (127.0.0.1 is one) all have it.
- * @param {Uint8Array} bytes
- * @returns {Promise<string>}
- */
-export async function sha256Hex(bytes) {
-  const subtle = globalThis.crypto?.subtle;
-  if (subtle === undefined) throw new Error("recipe: Web Crypto (crypto.subtle) is not available here");
-  const digest = new Uint8Array(await subtle.digest("SHA-256", /** @type {BufferSource} */ (bytes)));
-  return [...digest].map((b) => b.toString(16).padStart(2, "0")).join("");
-}
-
-/**
- * @param {Recipe} recipe
- * @returns {Promise<string>}  the recipe's identity: SHA-256 of its canonical JSON
- */
-export function recipeSha256(recipe) {
-  return sha256Hex(encoder.encode(canonicalJson(recipe)));
-}
-
-// --- the recipe's shape ---------------------------------------------------------------
-
-/**
- * @param {unknown} v
- * @returns {v is number}
- */
-const isIndex = (v) => typeof v === "number" && Number.isInteger(v) && v >= 0;
-
-/**
- * Every shape problem of a recipe, in one list (strict: an unknown key is one).
- * @param {unknown} recipe
- * @returns {RecipeProblem[]}
- */
-export function recipeShapeProblems(recipe) {
-  /** @type {RecipeProblem[]} */
-  const problems = [];
-  /**
-   * @param {string} message
-   * @param {number} [op]
-   */
-  const bad = (message, op) => {
-    /** @type {RecipeProblem} */
-    const p = { code: "RECIPE_SHAPE", message };
-    if (op !== undefined) p.op = op;
-    problems.push(p);
-  };
-  if (recipe === null || typeof recipe !== "object" || Array.isArray(recipe)) {
-    bad("a recipe is a JSON object");
-    return problems;
-  }
-  const r = /** @type {Record<string, any>} */ (recipe);
-  for (const key of Object.keys(r)) if (!RECIPE_KEYS.has(key)) bad(`unknown key "${key}"`);
-  if (r.recipe !== 1) bad("recipe must be 1 (the format version)");
-  if (typeof r.id !== "string" || !/^[a-z0-9][a-z0-9-]*$/.test(r.id)) bad("id must be a lowercase name");
-  if (r.title !== undefined && typeof r.title !== "string") bad("title must be a string");
-  const parts = r.source?.parts;
-  if (r.source === null || typeof r.source !== "object" || Object.keys(r.source).some((k) => k !== "parts")) bad("source must be {parts}");
-  if (parts === null || typeof parts !== "object" || !("word/document.xml" in parts)) bad("source.parts must pin word/document.xml");
-  else for (const [name, sha] of Object.entries(parts)) if (typeof sha !== "string" || !SHA256_HEX.test(sha)) bad(`source.parts["${name}"] must be a SHA-256 in lowercase hex`);
-  if (r.constants !== undefined) {
-    if (r.constants === null || typeof r.constants !== "object") bad("constants must be an object");
-    else {
-      for (const key of Object.keys(r.constants)) if (key !== "emptyValueParagraph" && key !== "valueRunRPr") bad(`unknown constant "${key}"`);
-      for (const [key, v] of Object.entries(r.constants)) if (typeof v !== "string" || v === "") bad(`constants.${key} must be a non-empty string`);
-    }
-  }
-  if (!Array.isArray(r.ops) || r.ops.length === 0) {
-    bad("ops must be a non-empty list");
-    return problems;
-  }
-  r.ops.forEach((/** @type {any} */ op, /** @type {number} */ i) => {
-    const allowed = op !== null && typeof op === "object" && Object.hasOwn(OP_KEYS, op.op) ? OP_KEYS[op.op] : undefined;
-    if (allowed === undefined) {
-      bad(`unknown op ${JSON.stringify(op?.op)}`, i);
-      return;
-    }
-    for (const key of Object.keys(op)) if (!allowed.includes(key)) bad(`${op.op}: unknown key "${key}"`, i);
-    if (!isIndex(op.docPrId)) bad(`${op.op}: docPrId must be a non-negative integer`, i);
-    if (op.op !== "fillParagraph") {
-      if (typeof op.tag !== "string" || !TAG_NAME.test(op.tag)) bad(`${op.op}: tag must match [a-z][a-z0-9_]*`, i);
-    }
-    if (op.op !== "setTag" && !isIndex(op.paragraph)) bad(`${op.op}: paragraph must be a non-negative integer`, i);
-    if (op.op === "setTag") {
-      if (!isIndex(op.label)) bad("setTag: label must be the docPr id of the neighbouring label box", i);
-      if (typeof r.constants?.emptyValueParagraph !== "string" || typeof r.constants?.valueRunRPr !== "string") {
-        bad("setTag needs constants.emptyValueParagraph and constants.valueRunRPr", i);
-      }
-    }
-    if (op.op === "replaceRuns") {
-      const [from, to] = Array.isArray(op.runs) ? op.runs : [];
-      if (!Array.isArray(op.runs) || op.runs.length !== 2 || !isIndex(from) || !isIndex(to) || !(from < to)) bad("replaceRuns: runs must be [from, to) with from < to", i);
-      else {
-        if (!Array.isArray(op.expectTexts) || op.expectTexts.length !== to - from || !op.expectTexts.every((/** @type {unknown} */ t) => typeof t === "string")) {
-          bad("replaceRuns: expectTexts must hold one string per run in the range", i);
-        }
-        if (!isIndex(op.keepRPrOf) || op.keepRPrOf < from || op.keepRPrOf >= to) bad("replaceRuns: keepRPrOf must be a run index inside the range", i);
-      }
-    }
-    if (op.op === "tagText") {
-      if (!isIndex(op.run)) bad("tagText: run must be a non-negative integer", i);
-      if (typeof op.find !== "string" || op.find === "") bad("tagText: find must be a non-empty string", i);
-    }
-    if (op.op === "fillParagraph") {
-      if (typeof op.expect !== "string" || op.expect === "") bad("fillParagraph: expect must be the paragraph's exact XML", i);
-      if (typeof op.paragraphXml !== "string" || op.paragraphXml === "") bad("fillParagraph: paragraphXml must be a paragraph's XML", i);
-    }
-  });
-  return problems;
-}
-
-// --- locating boxes, paragraphs and runs ----------------------------------------------
-
-/**
- * @typedef {object} Box
- * @property {number} acIndex
- * @property {import("./xml-scan.js").XmlElement} choice    the Choice copy's w:txbxContent
- * @property {import("./xml-scan.js").XmlElement} fallback  the Fallback copy's w:txbxContent
- */
-
-/**
- * Every box (an AlternateContent in the fill engine's shape) by its docPr id,
- * with how many boxes carry that id.
- * @param {import("./xml-scan.js").XmlElement} root
- * @returns {{boxes: Map<number, Box>, counts: Map<number, number>, malformed: Set<number>}}
- */
-function locateBoxes(root) {
-  /** @type {Map<number, Box>} */
-  const boxes = new Map();
-  /** @type {Map<number, number>} */
-  const counts = new Map();
-  /** @type {Set<number>} */
-  const malformed = new Set();
-  for (const ac of collectAlternateContents(root)) {
-    for (const anchor of ac.choiceAnchors) {
-      const docPr = findChild(anchor, WP_NS, "docPr");
-      const raw = docPr ? getAttr(docPr, "", "id") : undefined;
-      if (raw === undefined || !/^[0-9]+$/.test(raw)) continue;
-      const id = Number(raw);
-      counts.set(id, (counts.get(id) ?? 0) + 1);
-      const shaped =
-        !ac.nested && ac.choices.length === 1 && ac.fallbacks.length === 1 && ac.choiceTx.length === 1 && ac.fallbackTx.length === 1 &&
-        ac.choiceAnchors.length === 1 && isElement(anchor, WP_NS, "anchor");
-      if (shaped) boxes.set(id, { acIndex: ac.index, choice: ac.choiceTx[0], fallback: ac.fallbackTx[0] });
-      else malformed.add(id);
-    }
-  }
-  return { boxes, counts, malformed };
-}
-
-/**
- * @param {import("./xml-scan.js").XmlElement} el
- * @param {string} localName
- * @returns {import("./xml-scan.js").XmlElement[]}
- */
-function wChildren(el, localName) {
-  return /** @type {import("./xml-scan.js").XmlElement[]} */ (el.children.filter((c) => c.kind === "element" && c.uri === W_NS && c.localName === localName));
-}
-
-/**
- * The text a run shows: its w:t texts, "\t" for a w:tab. Null when it holds
- * anything else (a break, a drawing, a field) — not a run a recipe rewrites.
- * @param {import("./xml-scan.js").XmlElement} run
- * @returns {string | null}
- */
-function runText(run) {
-  let text = "";
-  for (const c of run.children) {
-    if (c.kind === "text" && c.value.trim() === "") continue;
-    if (c.kind !== "element" || c.uri !== W_NS) return null;
-    if (c.localName === "rPr") continue;
-    if (c.localName === "t") text += c.children.map((x) => (x.kind === "text" || x.kind === "cdata" ? x.value : "")).join("");
-    else if (c.localName === "tab") text += "\t";
-    else return null;
-  }
-  return text;
-}
-
-/**
- * A run's rPr as a comparable key with every w:spacing left out — the PDF
- * converter wrote one per word to imitate justification (ADR-0040 Bağlam).
- * @param {import("./xml-scan.js").XmlElement | undefined} rPr
- * @returns {string}
- */
-function rPrKeyWithoutSpacing(rPr) {
-  if (rPr === undefined) return "";
-  /** @param {import("./xml-scan.js").XmlElement} el @returns {string} */
-  const key = (el) =>
-    `${el.uri}|${el.localName}|${el.attributes.map((a) => `${a.uri}|${a.localName}=${a.value}`).sort().join(",")}|` +
-    el.children.filter((c) => c.kind === "element").map((c) => key(/** @type {import("./xml-scan.js").XmlElement} */ (c))).join(";");
-  return rPr.children
-    .filter((c) => c.kind === "element" && !(c.uri === W_NS && c.localName === "spacing"))
-    .map((c) => key(/** @type {import("./xml-scan.js").XmlElement} */ (c)))
-    .join(";");
-}
-
-/**
- * Whether an element's start tag declares a namespace. The recipe drops the
- * start tags it replaces (a paragraph, a run), so a prefix bound there would
- * come loose in the bytes it keeps or writes.
- * @param {import("./xml-scan.js").XmlElement} el
- * @param {Uint8Array} xmlBytes
- * @returns {boolean}
- */
-function declaresNamespace(el, xmlBytes) {
-  return /\sxmlns(:|\s*=)/.test(decoder.decode(xmlBytes.subarray(el.start, el.contentStart)));
-}
-
-/** @typedef {{kind: "t" | "br", text?: string}} Token  a w:t (with its text) or a w:br */
-
-/**
- * @typedef {object} PlannedEdit
- * @property {number} start
- * @property {number} end
- * @property {Uint8Array} bytes
- * @property {Token[]} tokens  the w:t / w:br tokens the new bytes hold
- * @property {number} op
- */
-
-/**
- * The tokens (w:t texts in order) of a well-formed XML fragment.
- * @param {import("./xml-scan.js").XmlElement} el
- * @returns {Token[]}
- */
-function fragmentTokens(el) {
-  /** @type {Token[]} */
-  const out = [];
-  for (const c of el.children) {
-    if (c.kind !== "element") continue;
-    if (c.uri === W_NS && c.localName === "t") out.push({ kind: "t", text: c.children.map((x) => (x.kind === "text" ? x.value : "")).join("") });
-    else if (c.uri === W_NS && c.localName === "br") out.push({ kind: "br" });
-    else out.push(...fragmentTokens(c));
-  }
-  return out;
-}
-
-/**
- * Checks a fillParagraph fragment: one w:p of allowed elements, text only inside
- * a w:t, every w:t plain text that is either a whole `{tag}` or holds no brace.
- * Returns its tags and tokens.
- * @param {string} xml
- * @returns {{problem: string} | {tags: string[], tokens: Token[]}}
- */
-function readFragment(xml) {
-  let root;
-  try {
-    root = scanXml(encoder.encode(`<w:fragment xmlns:w="${W_NS}">${xml}</w:fragment>`)).root;
-  } catch (err) {
-    return { problem: `the fragment does not parse — ${/** @type {Error} */ (err).message}` };
-  }
-  const kids = root.children.filter((c) => !(c.kind === "text" && c.value.trim() === ""));
-  if (kids.length !== 1 || kids[0].kind !== "element" || !isElement(kids[0], W_NS, "p")) return { problem: "the fragment must be exactly one w:p" };
-  /** @type {string[]} */
-  const tags = [];
-  /** @type {string | null} */
-  let problem = null;
-  /** @param {import("./xml-scan.js").XmlElement} el */
-  const visit = (el) => {
-    const name = `${el.prefix ? `${el.prefix}:` : ""}${el.localName}`;
-    if (el.uri !== W_NS || !FRAGMENT_ELEMENTS.has(el.localName)) problem ??= `<${name}> is not allowed in a fillParagraph fragment`;
-    if (el.localName === "t" && el.uri === W_NS) {
-      if (el.children.some((x) => x.kind !== "text")) problem ??= "a fragment w:t holds something other than plain text";
-      const text = el.children.map((x) => (x.kind === "text" ? x.value : "")).join("");
-      const tag = TAG_TEXT.exec(text);
-      if (tag !== null) tags.push(tag[1]);
-      else if (text.includes("{") || text.includes("}")) problem ??= "a fragment w:t holds a brace that is not a whole {tag}";
-    } else if (el.children.some((x) => x.kind === "cdata" || (x.kind === "text" && x.value.trim() !== ""))) {
-      problem ??= `<${name}> holds text outside a w:t`;
-    }
-    for (const c of el.children) if (c.kind === "element") visit(c);
-  };
-  visit(/** @type {import("./xml-scan.js").XmlElement} */ (kids[0]));
-  if (problem !== null) return { problem };
-  if (tags.length === 0) return { problem: "the fragment holds no {tag}" };
-  return { tags, tokens: fragmentTokens(root) };
-}
-
-/**
- * @typedef {object} Target
- * @property {import("./xml-scan.js").XmlElement} p  the addressed paragraph
- * @property {import("./xml-scan.js").XmlElement[]} runs  the addressed runs (replaceRuns, tagText)
- * @property {number} start  the bytes the op reads, compared between the copies
- * @property {number} end
- * @property {number} editStart  the bytes the op replaces; an empty range inserts
- * @property {number} editEnd
- */
-
-/**
- * @typedef {{code: string, message: string}} Miss  a problem without its op's address
- */
-
-/**
- * Finds what an op addresses in one copy of its box — structure only.
- * @param {any} op
- * @param {import("./xml-scan.js").XmlElement} txbx
- * @returns {Target | Miss}
- */
-function locate(op, txbx) {
-  const paragraphs = wChildren(txbx, "p");
-  if (op.op === "setTag" && paragraphs.length !== 1) {
-    return { code: "EXPECT_MISMATCH", message: `the box holds ${paragraphs.length} paragraphs; setTag expects one, constants.emptyValueParagraph` };
-  }
-  const p = paragraphs[op.op === "setTag" ? 0 : op.paragraph];
-  if (p === undefined) return { code: "PARAGRAPH_NOT_FOUND", message: `the box has ${paragraphs.length} paragraph(s), no index ${op.paragraph}` };
-  // Every literal the recipe writes says w:, bound to WordprocessingML above it.
-  if (p.prefix !== "w") return { code: "PREFIX_UNSUPPORTED", message: "the recipe writes the w: prefix, the paragraph does not use it" };
-  if (op.op === "setTag") return { p, runs: [], start: p.start, end: p.end, editStart: p.contentEnd, editEnd: p.contentEnd };
-  if (op.op === "fillParagraph") return { p, runs: [], start: p.start, end: p.end, editStart: p.start, editEnd: p.end };
-  const runs = wChildren(p, "r");
-  const [from, to] = op.op === "replaceRuns" ? op.runs : [op.run, op.run + 1];
-  if (to > runs.length) return { code: "RUN_RANGE", message: `the paragraph has ${runs.length} run(s), the op needs run ${to - 1}` };
-  const range = runs.slice(from, to);
-  const start = range[0].start;
-  const end = range[range.length - 1].end;
-  return { p, runs: range, start, end, editStart: start, editEnd: end };
-}
-
-/**
- * What an op writes, read from one copy — its addressed bytes are the other
- * copy's too. Checks every expectation the op carries.
- * @param {any} op
- * @param {Target} target
- * @param {Uint8Array} xmlBytes
- * @param {{emptyValueParagraph?: string, valueRunRPr?: string}} constants
- * @returns {{bytes: Uint8Array, tokens: Token[], tags: string[]} | Miss}
- */
-function plan(op, { p, runs }, xmlBytes, constants) {
-  const source = (/** @type {{start: number, end: number}} */ el) => decoder.decode(xmlBytes.subarray(el.start, el.end));
-  const tagRun = (/** @type {string} */ rPr) => `<w:r>${rPr}<w:t>{${op.tag}}</w:t></w:r>`;
-  /** @type {Token[]} */
-  const tagToken = [{ kind: "t", text: `{${op.tag}}` }];
-
-  if (op.op === "setTag") {
-    if (source(p) !== constants.emptyValueParagraph) return { code: "EXPECT_MISMATCH", message: "the box's paragraph is not constants.emptyValueParagraph" };
-    return { bytes: encoder.encode(tagRun(/** @type {string} */ (constants.valueRunRPr))), tokens: tagToken, tags: [op.tag] };
-  }
-
-  if (op.op === "fillParagraph") {
-    if (source(p) !== op.expect) return { code: "EXPECT_MISMATCH", message: "the paragraph is not the one `expect` names" };
-    if (declaresNamespace(p, xmlBytes)) return { code: "PREFIX_UNSUPPORTED", message: "the paragraph declares a namespace, which the new paragraph would leave out" };
-    const fragment = readFragment(op.paragraphXml);
-    if ("problem" in fragment) return { code: "FRAGMENT_INVALID", message: fragment.problem };
-    return { bytes: encoder.encode(op.paragraphXml), tokens: fragment.tokens, tags: fragment.tags };
-  }
-
-  if (op.op === "replaceRuns") {
-    const from = op.runs[0];
-    for (let k = 0; k + 1 < runs.length; k += 1) {
-      if (runs[k].end !== runs[k + 1].start) return { code: "RUNS_NOT_CONTIGUOUS", message: `something stands between run ${from + k} and run ${from + k + 1}` };
-    }
-    const texts = runs.map(runText);
-    if (texts.some((t) => t === null)) return { code: "RUN_CONTENT_UNSUPPORTED", message: "a run in the range holds more than rPr, w:t and w:tab" };
-    if (texts.some((t, k) => t !== op.expectTexts[k])) return { code: "EXPECT_MISMATCH", message: "the runs' texts are not expectTexts" };
-    const keys = runs.map((r) => rPrKeyWithoutSpacing(findChild(r, W_NS, "rPr")));
-    if (new Set(keys).size !== 1) return { code: "RPR_DIFFER", message: "the runs' rPr differ beyond w:spacing — one tag run would change their look" };
-    const keptRun = runs[op.keepRPrOf - from];
-    if (declaresNamespace(keptRun, xmlBytes)) return { code: "PREFIX_UNSUPPORTED", message: "the run whose rPr is kept declares a namespace, which its rPr would leave behind" };
-    const kept = findChild(keptRun, W_NS, "rPr");
-    return { bytes: encoder.encode(tagRun(kept === undefined ? "" : source(kept))), tokens: tagToken, tags: [op.tag] };
-  }
-
-  // tagText: the run becomes [before] {tag} [after], every piece in the run's own rPr.
-  const run = runs[0];
-  const ts = wChildren(run, "t");
-  const other = run.children.filter((c) => c.kind === "element" && !(c.uri === W_NS && (c.localName === "t" || c.localName === "rPr")));
-  if (ts.length !== 1 || other.length > 0) return { code: "RUN_CONTENT_UNSUPPORTED", message: "tagText splits a run holding rPr and exactly one w:t" };
-  const t = ts[0];
-  if (t.attributes.some((a) => !(a.uri === XML_NS && a.localName === "space" && a.value === "preserve"))) {
-    return { code: "RUN_CONTENT_UNSUPPORTED", message: "the run's w:t carries attributes other than xml:space=\"preserve\"" };
-  }
-  const only = t.children.length === 1 ? t.children[0] : null;
-  const text = only !== null && only.kind === "text" ? only.value : null;
-  if (text === null || decoder.decode(xmlBytes.subarray(t.contentStart, t.contentEnd)) !== text) {
-    return { code: "TEXT_ENCODED", message: "the run's text is not one plain text node written as it reads (no entity, no character reference)" };
-  }
-  const at = text.indexOf(op.find);
-  if (at < 0 || text.indexOf(op.find, at + 1) >= 0) return { code: "TEXT_NOT_FOUND", message: "`find` must occur exactly once in the run's text" };
-  if (declaresNamespace(run, xmlBytes)) return { code: "PREFIX_UNSUPPORTED", message: "the run declares a namespace, which its rPr would leave behind" };
-  const kept = findChild(run, W_NS, "rPr");
-  const rPr = kept === undefined ? "" : source(kept);
-  const piece = (/** @type {string} */ s) => `<w:r>${rPr}<w:t${/^\s|\s$/.test(s) ? ' xml:space="preserve"' : ""}>${s}</w:t></w:r>`;
-  const before = text.slice(0, at);
-  const after = text.slice(at + op.find.length);
-  /** @type {Token[]} */
-  const tokens = [];
-  let xml = "";
-  if (before !== "") {
-    xml += piece(before);
-    tokens.push({ kind: "t", text: before });
-  }
-  xml += tagRun(rPr);
-  tokens.push(...tagToken);
-  if (after !== "") {
-    xml += piece(after);
-    tokens.push({ kind: "t", text: after });
-  }
-  return { bytes: encoder.encode(xml), tokens, tags: [op.tag] };
-}
-
-// --- applying ---------------------------------------------------------------------------
-
-/**
- * Applies a recipe to word/document.xml. Every problem — the recipe's shape, the
- * pins, every op's target and expectation — is collected and thrown together;
- * otherwise the patched part comes back with a report. `parts` supplies the
- * other parts the recipe pins (e.g. word/styles.xml), by name.
- * @param {Uint8Array} xmlBytes
- * @param {Recipe} recipe
- * @param {{parts?: Record<string, Uint8Array>}} [options]
- * @returns {Promise<{xml: Uint8Array, report: RecipeReport}>}
- */
-export async function applyRecipeToDocumentXml(xmlBytes, recipe, { parts = {} } = {}) {
-  const shape = recipeShapeProblems(recipe);
-  if (shape.length > 0) throw recipeError("recipe", shape);
-
-  /** @type {RecipeProblem[]} */
-  const problems = [];
-  const inputSha = await sha256Hex(xmlBytes);
-  for (const [name, want] of Object.entries(recipe.source.parts)) {
-    const bytes = name === "word/document.xml" ? xmlBytes : parts[name];
-    if (bytes === undefined) {
-      problems.push({ code: "PART_MISSING", message: `the recipe pins ${name}, which was not supplied`, part: name });
-      continue;
-    }
-    const got = name === "word/document.xml" ? inputSha : await sha256Hex(bytes);
-    if (got !== want) problems.push({ code: "PART_PIN_MISMATCH", message: `${name} is not the part the recipe was written for`, part: name });
-  }
-  if (problems.length > 0) throw recipeError("recipe", problems);
-
-  const { root } = scanXml(xmlBytes);
-  const { boxes, counts, malformed } = locateBoxes(root);
-  const raw = (/** @type {{start: number, end: number}} */ el) => xmlBytes.subarray(el.start, el.end);
-  const same = (/** @type {Uint8Array} */ a, /** @type {Uint8Array} */ b) => a.length === b.length && a.every((x, i) => x === b[i]);
-  const constants = recipe.constants ?? {};
-
-  /** @type {PlannedEdit[]} */
-  const edits = [];
-  /** @type {{tag: string, docPrId: number}[]} */
-  const expectedTags = [];
-  /** @type {Set<number>} */
-  const touchedAcs = new Set();
-  /** @type {Record<string, number>} */
-  const opCounts = { setTag: 0, replaceRuns: 0, tagText: 0, fillParagraph: 0 };
-
-  recipe.ops.forEach((/** @type {any} */ op, /** @type {number} */ i) => {
-    opCounts[op.op] += 1;
-    const problem = (/** @type {string} */ code, /** @type {string} */ message) => problems.push({ code, message, op: i, docPrId: op.docPrId });
-    const n = counts.get(op.docPrId) ?? 0;
-    if (n !== 1) return problem(n === 0 ? "BOX_NOT_FOUND" : "BOX_NOT_UNIQUE", `${n} boxes carry wp:docPr id ${op.docPrId}`);
-    const box = boxes.get(op.docPrId);
-    if (box === undefined || malformed.has(op.docPrId)) return problem("BOX_SHAPE", "the box is not one Choice + one Fallback with one w:txbxContent each and a wp:anchor");
-    if (op.op === "setTag" && (counts.get(op.label) ?? 0) !== 1) return problem("LABEL_NOT_FOUND", `no single box carries the label's wp:docPr id ${op.label}`);
-    if (!compareCopies(box.choice, box.fallback).equal) return problem("COPIES_DIFFER", "the box's two copies are not structurally equal");
-
-    /** @type {Target[]} */
-    const targets = [];
-    for (const txbx of [box.choice, box.fallback]) {
-      const target = locate(op, txbx);
-      if ("code" in target) return problem(target.code, target.message);
-      targets.push(target);
-    }
-    // Structurally equal copies can still be spelled differently; the op reads one and writes both.
-    const [c, f] = targets;
-    if (!same(raw(c), raw(f))) return problem("COPIES_NOT_IDENTICAL", "the addressed bytes differ between the Choice and the Fallback copy");
-    const planned = plan(op, c, xmlBytes, constants);
-    if ("code" in planned) return problem(planned.code, planned.message);
-    for (const t of targets) edits.push({ start: t.editStart, end: t.editEnd, bytes: planned.bytes, tokens: planned.tokens, op: i });
-    touchedAcs.add(box.acIndex);
-    for (const tag of planned.tags) expectedTags.push({ tag, docPrId: op.docPrId });
-  });
-
-  // Ops are disjoint — checked here, so the error names the ops, not applyEdits' offsets.
-  // Both copies overlap alike; a pair of ops is named once.
-  const sorted = [...edits].sort((a, b) => a.start - b.start || a.end - b.end);
-  /** @type {Set<string>} */
-  const named = new Set();
-  for (let k = 0; k + 1 < sorted.length; k += 1) {
-    const a = sorted[k];
-    const b = sorted[k + 1];
-    if (b.start < a.end || (a.start === b.start && a.end === b.end)) {
-      const [x, y] = [a.op, b.op].sort((m, n) => m - n);
-      if (named.has(`${x},${y}`)) continue;
-      named.add(`${x},${y}`);
-      problems.push({ code: "OPS_OVERLAP", message: `ops ${x} and ${y} touch the same bytes`, op: y });
-    }
-  }
-  if (problems.length > 0) throw recipeError("recipe", problems);
-
-  const xml = applyEdits(xmlBytes, edits.map(({ start, end, bytes }) => ({ start, end, bytes })));
-  readBackRecipe(root, xml, edits, touchedAcs);
-
-  // The template the engine will fill: exactly the recipe's tags, nothing to refuse, nothing to warn about.
-  const outRoot = scanXml(xml).root;
-  const scan = scanTemplate(outRoot, xml);
-  /** @type {RecipeProblem[]} */
-  const after = [];
-  for (const p of [...scan.problems, ...scan.warnings]) {
-    /** @type {RecipeProblem} */
-    const q = { code: `TEMPLATE_${p.code}`, message: `the template the recipe writes: ${p.message}` };
-    if (p.tag !== undefined) q.tag = p.tag;
-    if (typeof p.docPrId === "number") q.docPrId = p.docPrId;
-    after.push(q);
-  }
-  const want = expectedTags.map((x) => `${x.tag}@${x.docPrId}`).sort();
-  const got = scan.occurrences.map((o) => `${o.name}@${o.docPrId}`).sort();
-  if (want.join("\n") !== got.join("\n")) {
-    after.push({ code: "TEMPLATE_TAGS_DIFFER", message: `the template holds ${got.length} tag occurrence(s), the recipe declares ${want.length}` });
-  }
-  if (after.length > 0) throw recipeError("recipe: the written template", after);
-
-  return {
-    xml,
-    report: {
-      recipe: { id: recipe.id, sha256: await recipeSha256(recipe) },
-      tags: tagInfo(scan),
-      ops: opCounts,
-      documentXml: { input: inputSha, output: await sha256Hex(xml) },
-    },
-  };
-}
-
-/**
- * Reads the patched part back. A failure is a bug in this module, a plain Error:
- * the output's w:t + w:br tokens must be the input's with exactly the planned
- * edits' tokens in place of the ones they covered, and every touched box's two
- * copies must still be equal (ADR-0038). Exported for its own tests.
- * @param {import("./xml-scan.js").XmlElement} inputRoot
- * @param {Uint8Array} out
- * @param {PlannedEdit[]} edits
- * @param {Set<number>} touchedAcs
- * @returns {void}
- */
-export function readBackRecipe(inputRoot, out, edits, touchedAcs) {
-  /** @type {import("./xml-scan.js").XmlElement} */
-  let outRoot;
-  try {
-    outRoot = scanXml(out).root;
-  } catch (err) {
-    throw new Error(`recipe: the patched document.xml does not parse — ${/** @type {Error} */ (err).message}`, { cause: err });
-  }
-  /** @type {{at: number, tokens: {kind: string, text?: string}[]}[]} */
-  const segments = [];
-  for (const token of textTokens(inputRoot)) {
-    const covered = edits.some((e) => token.el.start >= e.start && token.el.start < e.end);
-    if (!covered) segments.push({ at: token.el.start, tokens: [token.kind === "t" ? { kind: "t", text: token.text } : { kind: "br" }] });
-  }
-  for (const e of edits) segments.push({ at: e.start, tokens: e.tokens });
-  segments.sort((a, b) => a.at - b.at);
-  const expected = segments.flatMap((s) => s.tokens);
-  const after = textTokens(outRoot);
-  if (after.length !== expected.length) {
-    throw new Error(`recipe: the patched document.xml holds ${after.length} w:t/w:br token(s), the recipe accounts for ${expected.length}`);
-  }
-  for (let k = 0; k < expected.length; k += 1) {
-    const e = expected[k];
-    const a = after[k];
-    if (a.kind !== e.kind || (a.kind === "t" && a.text !== e.text)) {
-      throw new Error(`recipe: token #${k + 1} does not read back as the recipe wrote it`);
-    }
-  }
-  const acs = collectAlternateContents(outRoot);
-  for (const index of touchedAcs) {
-    const ac = acs[index];
-    if (ac === undefined || ac.choiceTx.length !== 1 || ac.fallbackTx.length !== 1) throw new Error(`recipe: AlternateContent #${index} lost its shape`);
-    const copies = compareCopies(ac.choiceTx[0], ac.fallbackTx[0]);
-    if (!copies.equal) throw new Error(`recipe: the two copies of AlternateContent #${index} differ after the recipe, at ${copies.path}`);
-  }
-}
-
-/**
- * Applies a recipe to a .docx: word/document.xml patched, every other part's
- * bytes copied verbatim (invariant #10). The parts the recipe pins are read
- * from the package for the pin check.
- * @param {Uint8Array} docx
- * @param {Recipe} recipe
- * @returns {Promise<{bytes: Uint8Array, documentXml: Uint8Array, report: RecipeReport}>}
- */
-export async function applyRecipe(docx, recipe) {
-  if (!(docx instanceof Uint8Array)) throw new TypeError("applyRecipe: docx must be a Uint8Array (a .docx file's bytes)");
-  const entries = parseZipContainer(docx);
-  const main = resolveMainDocumentPart(entries);
-  const xml = await inflateEntry(docx, main);
-  /** @type {Record<string, Uint8Array>} */
-  const parts = {};
-  for (const name of Object.keys(recipe?.source?.parts ?? {})) {
-    if (name === main.name) continue;
-    const entry = entries.find((e) => e.name === name);
-    if (entry !== undefined) parts[name] = await inflateEntry(docx, entry);
-  }
-  const { xml: documentXml, report } = await applyRecipeToDocumentXml(xml, recipe, { parts });
-  const bytes = await writePackage(docx, entries, { [main.name]: documentXml });
-  return { bytes, documentXml, report };
-}
+// Template recipes (FR3, ADR-0040): a form becomes a `{tag}` template only
+// through a recipe — a JSON pinned to the SHA-256 of the parts it reads —
+// applied as ONE byte patch of word/document.xml, the same edit in both copies
+// of every box (ADR-0038). Never by saving in Word: Word 2010+ writes a
+// w14:paraId into every paragraph and the copies would part (ADR-0037
+// DOĞRULANMALI 5).
+//
+// Four ops, each addressed by its box's wp:docPr id and, where it matters, a
+// paragraph and a run index, each carrying an expectation that catches an
+// authoring mistake and keeps the recipe readable:
+//   setTag         the box's one empty value paragraph gets a tag run at its end
+//   replaceRuns    a contiguous run range becomes one tag run, a named run's rPr kept
+//   tagText        a substring of one run's text becomes a tag run, the run split
+//   fillParagraph  the paragraph `expect` names, byte for byte (empty or not), is
+//                  replaced by a literal, validated paragraph
+//
+// Problems are collected stage by stage — the recipe's shape, the pins, every op
+// and their overlaps, the written template's scan — and each stage's are thrown
+// together; a later stage does not run when an earlier one failed. Nothing is written
+// while any remains. The output is then READ BACK: its w:t + w:br token stream
+// must be the input's with exactly each op's declared change, every touched box's
+// copies are compared again, and the template scan must find exactly the
+// recipe's tags — no problem, no warning. A read-back failure is a bug here, a
+// plain Error; a scan finding is the recipe's, a problem.
+//
+// Internal: not exported from /docx (ADR-0040 Karar 2). It imports neither the
+// importer's entry (import.js) nor the exporter, the style resolver or the model —
+// their gates can refuse a form that templates fine. slots.js's section count
+// reaches the importer's helpers (sections.js -> drawingml.js -> import-gate.js),
+// but no gate is called on that path.
+
+import { scanXml, getAttr, isElement, findChild } from "./xml-scan.js";
+import { scanTemplate, compareCopies, collectAlternateContents, textTokens } from "./slots.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 { tagInfo } from "./fill.js";
+import { W_NS, WP_NS, XML_NS } from "./ns.js";
+
+const encoder = new TextEncoder();
+const decoder = new TextDecoder("utf-8", { fatal: true });
+const TAG_NAME = /^[a-z][a-z0-9_]*$/;
+const TAG_TEXT = /^\{([a-z][a-z0-9_]*)\}$/;
+const SHA256_HEX = /^[0-9a-f]{64}$/;
+
+/** Elements a fillParagraph fragment may hold (WordprocessingML, local names). */
+const FRAGMENT_ELEMENTS = new Set([
+  "p", "pPr", "pStyle", "spacing", "ind", "jc", "tabs", "tab", "rPr", "rFonts", "sz", "szCs", "b", "bCs", "i", "iCs", "color", "position", "r", "t",
+]);
+
+const RECIPE_KEYS = new Set(["recipe", "id", "title", "source", "constants", "ops"]);
+/** @type {Record<string, string[]>} */
+const OP_KEYS = {
+  setTag: ["op", "docPrId", "tag", "label"],
+  replaceRuns: ["op", "docPrId", "paragraph", "runs", "expectTexts", "keepRPrOf", "tag"],
+  tagText: ["op", "docPrId", "paragraph", "run", "find", "tag"],
+  fillParagraph: ["op", "docPrId", "paragraph", "expect", "paragraphXml"],
+};
+
+/**
+ * @typedef {object} RecipeProblem
+ * @property {string} code
+ * @property {string} message
+ * @property {number} [op]  index of the op in `ops`
+ * @property {number} [docPrId]
+ * @property {string} [tag]
+ * @property {string} [part]
+ */
+
+/**
+ * @typedef {object} Recipe
+ * @property {1} recipe
+ * @property {string} id
+ * @property {string} [title]
+ * @property {{parts: Record<string, string>}} source  part name -> SHA-256 (hex)
+ * @property {{emptyValueParagraph?: string, valueRunRPr?: string}} [constants]
+ * @property {any[]} ops
+ */
+
+/**
+ * @typedef {object} RecipeReport
+ * @property {{id: string, sha256: string}} recipe  sha256 of the recipe's canonical JSON
+ * @property {import("./fill.js").TagInfo[]} tags  the template's tags, as the fill engine sees them
+ * @property {Record<string, number>} ops  how many of each op
+ * @property {{input: string, output: string}} documentXml  SHA-256 of word/document.xml before and after
+ */
+
+/**
+ * @param {string} message
+ * @param {RecipeProblem[]} problems
+ * @returns {Error & {problems: RecipeProblem[]}}
+ */
+function recipeError(message, problems) {
+  const shown = problems.slice(0, 5).map((p) => (p.op === undefined ? p.code : `${p.code} (op ${p.op})`)).join("; ");
+  const more = problems.length > 5 ? `; and ${problems.length - 5} more` : "";
+  return Object.assign(new Error(`${message}: ${problems.length} problem(s) — ${shown}${more}`), { problems });
+}
+
+/**
+ * JSON with every object's keys sorted, arrays in order — the recipe's identity
+ * does not depend on key order or on the line endings a checkout gives the file.
+ * @param {unknown} value
+ * @returns {string}
+ */
+export function canonicalJson(value) {
+  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`;
+  if (value !== null && typeof value === "object") {
+    const obj = /** @type {Record<string, unknown>} */ (value);
+    return `{${Object.keys(obj).sort().map((k) => `${JSON.stringify(k)}:${canonicalJson(obj[k])}`).join(",")}}`;
+  }
+  return JSON.stringify(value);
+}
+
+/**
+ * SHA-256 of `bytes` as lowercase hex, through Web Crypto — touched only when
+ * called (invariant #5). Node 20+, Deno and browsers on a secure context
+ * (127.0.0.1 is one) all have it.
+ * @param {Uint8Array} bytes
+ * @returns {Promise<string>}
+ */
+export async function sha256Hex(bytes) {
+  const subtle = globalThis.crypto?.subtle;
+  if (subtle === undefined) throw new Error("recipe: Web Crypto (crypto.subtle) is not available here");
+  const digest = new Uint8Array(await subtle.digest("SHA-256", /** @type {BufferSource} */ (bytes)));
+  return [...digest].map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+
+/**
+ * @param {Recipe} recipe
+ * @returns {Promise<string>}  the recipe's identity: SHA-256 of its canonical JSON
+ */
+export function recipeSha256(recipe) {
+  return sha256Hex(encoder.encode(canonicalJson(recipe)));
+}
+
+// --- the recipe's shape ---------------------------------------------------------------
+
+/**
+ * @param {unknown} v
+ * @returns {v is number}
+ */
+const isIndex = (v) => typeof v === "number" && Number.isInteger(v) && v >= 0;
+
+/**
+ * Every shape problem of a recipe, in one list (strict: an unknown key is one).
+ * @param {unknown} recipe
+ * @returns {RecipeProblem[]}
+ */
+export function recipeShapeProblems(recipe) {
+  /** @type {RecipeProblem[]} */
+  const problems = [];
+  /**
+   * @param {string} message
+   * @param {number} [op]
+   */
+  const bad = (message, op) => {
+    /** @type {RecipeProblem} */
+    const p = { code: "RECIPE_SHAPE", message };
+    if (op !== undefined) p.op = op;
+    problems.push(p);
+  };
+  if (recipe === null || typeof recipe !== "object" || Array.isArray(recipe)) {
+    bad("a recipe is a JSON object");
+    return problems;
+  }
+  const r = /** @type {Record<string, any>} */ (recipe);
+  for (const key of Object.keys(r)) if (!RECIPE_KEYS.has(key)) bad(`unknown key "${key}"`);
+  if (r.recipe !== 1) bad("recipe must be 1 (the format version)");
+  if (typeof r.id !== "string" || !/^[a-z0-9][a-z0-9-]*$/.test(r.id)) bad("id must be a lowercase name");
+  if (r.title !== undefined && typeof r.title !== "string") bad("title must be a string");
+  const parts = r.source?.parts;
+  if (r.source === null || typeof r.source !== "object" || Object.keys(r.source).some((k) => k !== "parts")) bad("source must be {parts}");
+  if (parts === null || typeof parts !== "object" || !("word/document.xml" in parts)) bad("source.parts must pin word/document.xml");
+  else for (const [name, sha] of Object.entries(parts)) if (typeof sha !== "string" || !SHA256_HEX.test(sha)) bad(`source.parts["${name}"] must be a SHA-256 in lowercase hex`);
+  if (r.constants !== undefined) {
+    if (r.constants === null || typeof r.constants !== "object") bad("constants must be an object");
+    else {
+      for (const key of Object.keys(r.constants)) if (key !== "emptyValueParagraph" && key !== "valueRunRPr") bad(`unknown constant "${key}"`);
+      for (const [key, v] of Object.entries(r.constants)) if (typeof v !== "string" || v === "") bad(`constants.${key} must be a non-empty string`);
+    }
+  }
+  if (!Array.isArray(r.ops) || r.ops.length === 0) {
+    bad("ops must be a non-empty list");
+    return problems;
+  }
+  r.ops.forEach((/** @type {any} */ op, /** @type {number} */ i) => {
+    const allowed = op !== null && typeof op === "object" && Object.hasOwn(OP_KEYS, op.op) ? OP_KEYS[op.op] : undefined;
+    if (allowed === undefined) {
+      bad(`unknown op ${JSON.stringify(op?.op)}`, i);
+      return;
+    }
+    for (const key of Object.keys(op)) if (!allowed.includes(key)) bad(`${op.op}: unknown key "${key}"`, i);
+    if (!isIndex(op.docPrId)) bad(`${op.op}: docPrId must be a non-negative integer`, i);
+    if (op.op !== "fillParagraph") {
+      if (typeof op.tag !== "string" || !TAG_NAME.test(op.tag)) bad(`${op.op}: tag must match [a-z][a-z0-9_]*`, i);
+    }
+    if (op.op !== "setTag" && !isIndex(op.paragraph)) bad(`${op.op}: paragraph must be a non-negative integer`, i);
+    if (op.op === "setTag") {
+      if (!isIndex(op.label)) bad("setTag: label must be the docPr id of the neighbouring label box", i);
+      if (typeof r.constants?.emptyValueParagraph !== "string" || typeof r.constants?.valueRunRPr !== "string") {
+        bad("setTag needs constants.emptyValueParagraph and constants.valueRunRPr", i);
+      }
+    }
+    if (op.op === "replaceRuns") {
+      const [from, to] = Array.isArray(op.runs) ? op.runs : [];
+      if (!Array.isArray(op.runs) || op.runs.length !== 2 || !isIndex(from) || !isIndex(to) || !(from < to)) bad("replaceRuns: runs must be [from, to) with from < to", i);
+      else {
+        if (!Array.isArray(op.expectTexts) || op.expectTexts.length !== to - from || !op.expectTexts.every((/** @type {unknown} */ t) => typeof t === "string")) {
+          bad("replaceRuns: expectTexts must hold one string per run in the range", i);
+        }
+        if (!isIndex(op.keepRPrOf) || op.keepRPrOf < from || op.keepRPrOf >= to) bad("replaceRuns: keepRPrOf must be a run index inside the range", i);
+      }
+    }
+    if (op.op === "tagText") {
+      if (!isIndex(op.run)) bad("tagText: run must be a non-negative integer", i);
+      if (typeof op.find !== "string" || op.find === "") bad("tagText: find must be a non-empty string", i);
+    }
+    if (op.op === "fillParagraph") {
+      if (typeof op.expect !== "string" || op.expect === "") bad("fillParagraph: expect must be the paragraph's exact XML", i);
+      if (typeof op.paragraphXml !== "string" || op.paragraphXml === "") bad("fillParagraph: paragraphXml must be a paragraph's XML", i);
+    }
+  });
+  return problems;
+}
+
+// --- locating boxes, paragraphs and runs ----------------------------------------------
+
+/**
+ * @typedef {object} Box
+ * @property {number} acIndex
+ * @property {import("./xml-scan.js").XmlElement} choice    the Choice copy's w:txbxContent
+ * @property {import("./xml-scan.js").XmlElement} fallback  the Fallback copy's w:txbxContent
+ */
+
+/**
+ * Every box (an AlternateContent in the fill engine's shape) by its docPr id,
+ * with how many boxes carry that id.
+ * @param {import("./xml-scan.js").XmlElement} root
+ * @returns {{boxes: Map<number, Box>, counts: Map<number, number>, malformed: Set<number>}}
+ */
+function locateBoxes(root) {
+  /** @type {Map<number, Box>} */
+  const boxes = new Map();
+  /** @type {Map<number, number>} */
+  const counts = new Map();
+  /** @type {Set<number>} */
+  const malformed = new Set();
+  for (const ac of collectAlternateContents(root)) {
+    for (const anchor of ac.choiceAnchors) {
+      const docPr = findChild(anchor, WP_NS, "docPr");
+      const raw = docPr ? getAttr(docPr, "", "id") : undefined;
+      if (raw === undefined || !/^[0-9]+$/.test(raw)) continue;
+      const id = Number(raw);
+      counts.set(id, (counts.get(id) ?? 0) + 1);
+      const shaped =
+        !ac.nested && ac.choices.length === 1 && ac.fallbacks.length === 1 && ac.choiceTx.length === 1 && ac.fallbackTx.length === 1 &&
+        ac.choiceAnchors.length === 1 && isElement(anchor, WP_NS, "anchor");
+      if (shaped) boxes.set(id, { acIndex: ac.index, choice: ac.choiceTx[0], fallback: ac.fallbackTx[0] });
+      else malformed.add(id);
+    }
+  }
+  return { boxes, counts, malformed };
+}
+
+/**
+ * @param {import("./xml-scan.js").XmlElement} el
+ * @param {string} localName
+ * @returns {import("./xml-scan.js").XmlElement[]}
+ */
+function wChildren(el, localName) {
+  return /** @type {import("./xml-scan.js").XmlElement[]} */ (el.children.filter((c) => c.kind === "element" && c.uri === W_NS && c.localName === localName));
+}
+
+/**
+ * The text a run shows: its w:t texts, "\t" for a w:tab. Null when it holds
+ * anything else (a break, a drawing, a field) — not a run a recipe rewrites.
+ * @param {import("./xml-scan.js").XmlElement} run
+ * @returns {string | null}
+ */
+function runText(run) {
+  let text = "";
+  for (const c of run.children) {
+    if (c.kind === "text" && c.value.trim() === "") continue;
+    if (c.kind !== "element" || c.uri !== W_NS) return null;
+    if (c.localName === "rPr") continue;
+    if (c.localName === "t") text += c.children.map((x) => (x.kind === "text" || x.kind === "cdata" ? x.value : "")).join("");
+    else if (c.localName === "tab") text += "\t";
+    else return null;
+  }
+  return text;
+}
+
+/**
+ * A run's rPr as a comparable key with every w:spacing left out — the PDF
+ * converter wrote one per word to imitate justification (ADR-0040 Bağlam).
+ * @param {import("./xml-scan.js").XmlElement | undefined} rPr
+ * @returns {string}
+ */
+function rPrKeyWithoutSpacing(rPr) {
+  if (rPr === undefined) return "";
+  /** @param {import("./xml-scan.js").XmlElement} el @returns {string} */
+  const key = (el) =>
+    `${el.uri}|${el.localName}|${el.attributes.map((a) => `${a.uri}|${a.localName}=${a.value}`).sort().join(",")}|` +
+    el.children.filter((c) => c.kind === "element").map((c) => key(/** @type {import("./xml-scan.js").XmlElement} */ (c))).join(";");
+  return rPr.children
+    .filter((c) => c.kind === "element" && !(c.uri === W_NS && c.localName === "spacing"))
+    .map((c) => key(/** @type {import("./xml-scan.js").XmlElement} */ (c)))
+    .join(";");
+}
+
+/**
+ * Whether an element's start tag declares a namespace. The recipe drops the
+ * start tags it replaces (a paragraph, a run), so a prefix bound there would
+ * come loose in the bytes it keeps or writes.
+ * @param {import("./xml-scan.js").XmlElement} el
+ * @param {Uint8Array} xmlBytes
+ * @returns {boolean}
+ */
+function declaresNamespace(el, xmlBytes) {
+  return /\sxmlns(:|\s*=)/.test(decoder.decode(xmlBytes.subarray(el.start, el.contentStart)));
+}
+
+/** @typedef {{kind: "t" | "br", text?: string}} Token  a w:t (with its text) or a w:br */
+
+/**
+ * @typedef {object} PlannedEdit
+ * @property {number} start
+ * @property {number} end
+ * @property {Uint8Array} bytes
+ * @property {Token[]} tokens  the w:t / w:br tokens the new bytes hold
+ * @property {number} op
+ */
+
+/**
+ * The tokens (w:t texts in order) of a well-formed XML fragment.
+ * @param {import("./xml-scan.js").XmlElement} el
+ * @returns {Token[]}
+ */
+function fragmentTokens(el) {
+  /** @type {Token[]} */
+  const out = [];
+  for (const c of el.children) {
+    if (c.kind !== "element") continue;
+    if (c.uri === W_NS && c.localName === "t") out.push({ kind: "t", text: c.children.map((x) => (x.kind === "text" ? x.value : "")).join("") });
+    else if (c.uri === W_NS && c.localName === "br") out.push({ kind: "br" });
+    else out.push(...fragmentTokens(c));
+  }
+  return out;
+}
+
+/**
+ * Checks a fillParagraph fragment: one w:p of allowed elements, text only inside
+ * a w:t, every w:t plain text that is either a whole `{tag}` or holds no brace.
+ * Returns its tags and tokens.
+ * @param {string} xml
+ * @returns {{problem: string} | {tags: string[], tokens: Token[]}}
+ */
+function readFragment(xml) {
+  let root;
+  try {
+    root = scanXml(encoder.encode(`<w:fragment xmlns:w="${W_NS}">${xml}</w:fragment>`)).root;
+  } catch (err) {
+    return { problem: `the fragment does not parse — ${/** @type {Error} */ (err).message}` };
+  }
+  const kids = root.children.filter((c) => !(c.kind === "text" && c.value.trim() === ""));
+  if (kids.length !== 1 || kids[0].kind !== "element" || !isElement(kids[0], W_NS, "p")) return { problem: "the fragment must be exactly one w:p" };
+  /** @type {string[]} */
+  const tags = [];
+  /** @type {string | null} */
+  let problem = null;
+  /** @param {import("./xml-scan.js").XmlElement} el */
+  const visit = (el) => {
+    const name = `${el.prefix ? `${el.prefix}:` : ""}${el.localName}`;
+    if (el.uri !== W_NS || !FRAGMENT_ELEMENTS.has(el.localName)) problem ??= `<${name}> is not allowed in a fillParagraph fragment`;
+    if (el.localName === "t" && el.uri === W_NS) {
+      if (el.children.some((x) => x.kind !== "text")) problem ??= "a fragment w:t holds something other than plain text";
+      const text = el.children.map((x) => (x.kind === "text" ? x.value : "")).join("");
+      const tag = TAG_TEXT.exec(text);
+      if (tag !== null) tags.push(tag[1]);
+      else if (text.includes("{") || text.includes("}")) problem ??= "a fragment w:t holds a brace that is not a whole {tag}";
+    } else if (el.children.some((x) => x.kind === "cdata" || (x.kind === "text" && x.value.trim() !== ""))) {
+      problem ??= `<${name}> holds text outside a w:t`;
+    }
+    for (const c of el.children) if (c.kind === "element") visit(c);
+  };
+  visit(/** @type {import("./xml-scan.js").XmlElement} */ (kids[0]));
+  if (problem !== null) return { problem };
+  if (tags.length === 0) return { problem: "the fragment holds no {tag}" };
+  return { tags, tokens: fragmentTokens(root) };
+}
+
+/**
+ * @typedef {object} Target
+ * @property {import("./xml-scan.js").XmlElement} p  the addressed paragraph
+ * @property {import("./xml-scan.js").XmlElement[]} runs  the addressed runs (replaceRuns, tagText)
+ * @property {number} start  the bytes the op reads, compared between the copies
+ * @property {number} end
+ * @property {number} editStart  the bytes the op replaces; an empty range inserts
+ * @property {number} editEnd
+ */
+
+/**
+ * @typedef {{code: string, message: string}} Miss  a problem without its op's address
+ */
+
+/**
+ * Finds what an op addresses in one copy of its box — structure only.
+ * @param {any} op
+ * @param {import("./xml-scan.js").XmlElement} txbx
+ * @returns {Target | Miss}
+ */
+function locate(op, txbx) {
+  const paragraphs = wChildren(txbx, "p");
+  if (op.op === "setTag" && paragraphs.length !== 1) {
+    return { code: "EXPECT_MISMATCH", message: `the box holds ${paragraphs.length} paragraphs; setTag expects one, constants.emptyValueParagraph` };
+  }
+  const p = paragraphs[op.op === "setTag" ? 0 : op.paragraph];
+  if (p === undefined) return { code: "PARAGRAPH_NOT_FOUND", message: `the box has ${paragraphs.length} paragraph(s), no index ${op.paragraph}` };
+  // Every literal the recipe writes says w:, bound to WordprocessingML above it.
+  if (p.prefix !== "w") return { code: "PREFIX_UNSUPPORTED", message: "the recipe writes the w: prefix, the paragraph does not use it" };
+  if (op.op === "setTag") return { p, runs: [], start: p.start, end: p.end, editStart: p.contentEnd, editEnd: p.contentEnd };
+  if (op.op === "fillParagraph") return { p, runs: [], start: p.start, end: p.end, editStart: p.start, editEnd: p.end };
+  const runs = wChildren(p, "r");
+  const [from, to] = op.op === "replaceRuns" ? op.runs : [op.run, op.run + 1];
+  if (to > runs.length) return { code: "RUN_RANGE", message: `the paragraph has ${runs.length} run(s), the op needs run ${to - 1}` };
+  const range = runs.slice(from, to);
+  const start = range[0].start;
+  const end = range[range.length - 1].end;
+  return { p, runs: range, start, end, editStart: start, editEnd: end };
+}
+
+/**
+ * What an op writes, read from one copy — its addressed bytes are the other
+ * copy's too. Checks every expectation the op carries.
+ * @param {any} op
+ * @param {Target} target
+ * @param {Uint8Array} xmlBytes
+ * @param {{emptyValueParagraph?: string, valueRunRPr?: string}} constants
+ * @returns {{bytes: Uint8Array, tokens: Token[], tags: string[]} | Miss}
+ */
+function plan(op, { p, runs }, xmlBytes, constants) {
+  const source = (/** @type {{start: number, end: number}} */ el) => decoder.decode(xmlBytes.subarray(el.start, el.end));
+  const tagRun = (/** @type {string} */ rPr) => `<w:r>${rPr}<w:t>{${op.tag}}</w:t></w:r>`;
+  /** @type {Token[]} */
+  const tagToken = [{ kind: "t", text: `{${op.tag}}` }];
+
+  if (op.op === "setTag") {
+    if (source(p) !== constants.emptyValueParagraph) return { code: "EXPECT_MISMATCH", message: "the box's paragraph is not constants.emptyValueParagraph" };
+    return { bytes: encoder.encode(tagRun(/** @type {string} */ (constants.valueRunRPr))), tokens: tagToken, tags: [op.tag] };
+  }
+
+  if (op.op === "fillParagraph") {
+    if (source(p) !== op.expect) return { code: "EXPECT_MISMATCH", message: "the paragraph is not the one `expect` names" };
+    if (declaresNamespace(p, xmlBytes)) return { code: "PREFIX_UNSUPPORTED", message: "the paragraph declares a namespace, which the new paragraph would leave out" };
+    const fragment = readFragment(op.paragraphXml);
+    if ("problem" in fragment) return { code: "FRAGMENT_INVALID", message: fragment.problem };
+    return { bytes: encoder.encode(op.paragraphXml), tokens: fragment.tokens, tags: fragment.tags };
+  }
+
+  if (op.op === "replaceRuns") {
+    const from = op.runs[0];
+    for (let k = 0; k + 1 < runs.length; k += 1) {
+      if (runs[k].end !== runs[k + 1].start) return { code: "RUNS_NOT_CONTIGUOUS", message: `something stands between run ${from + k} and run ${from + k + 1}` };
+    }
+    const texts = runs.map(runText);
+    if (texts.some((t) => t === null)) return { code: "RUN_CONTENT_UNSUPPORTED", message: "a run in the range holds more than rPr, w:t and w:tab" };
+    if (texts.some((t, k) => t !== op.expectTexts[k])) return { code: "EXPECT_MISMATCH", message: "the runs' texts are not expectTexts" };
+    const keys = runs.map((r) => rPrKeyWithoutSpacing(findChild(r, W_NS, "rPr")));
+    if (new Set(keys).size !== 1) return { code: "RPR_DIFFER", message: "the runs' rPr differ beyond w:spacing — one tag run would change their look" };
+    const keptRun = runs[op.keepRPrOf - from];
+    if (declaresNamespace(keptRun, xmlBytes)) return { code: "PREFIX_UNSUPPORTED", message: "the run whose rPr is kept declares a namespace, which its rPr would leave behind" };
+    const kept = findChild(keptRun, W_NS, "rPr");
+    return { bytes: encoder.encode(tagRun(kept === undefined ? "" : source(kept))), tokens: tagToken, tags: [op.tag] };
+  }
+
+  // tagText: the run becomes [before] {tag} [after], every piece in the run's own rPr.
+  const run = runs[0];
+  const ts = wChildren(run, "t");
+  const other = run.children.filter((c) => c.kind === "element" && !(c.uri === W_NS && (c.localName === "t" || c.localName === "rPr")));
+  if (ts.length !== 1 || other.length > 0) return { code: "RUN_CONTENT_UNSUPPORTED", message: "tagText splits a run holding rPr and exactly one w:t" };
+  const t = ts[0];
+  if (t.attributes.some((a) => !(a.uri === XML_NS && a.localName === "space" && a.value === "preserve"))) {
+    return { code: "RUN_CONTENT_UNSUPPORTED", message: "the run's w:t carries attributes other than xml:space=\"preserve\"" };
+  }
+  const only = t.children.length === 1 ? t.children[0] : null;
+  const text = only !== null && only.kind === "text" ? only.value : null;
+  if (text === null || decoder.decode(xmlBytes.subarray(t.contentStart, t.contentEnd)) !== text) {
+    return { code: "TEXT_ENCODED", message: "the run's text is not one plain text node written as it reads (no entity, no character reference)" };
+  }
+  const at = text.indexOf(op.find);
+  if (at < 0 || text.indexOf(op.find, at + 1) >= 0) return { code: "TEXT_NOT_FOUND", message: "`find` must occur exactly once in the run's text" };
+  if (declaresNamespace(run, xmlBytes)) return { code: "PREFIX_UNSUPPORTED", message: "the run declares a namespace, which its rPr would leave behind" };
+  const kept = findChild(run, W_NS, "rPr");
+  const rPr = kept === undefined ? "" : source(kept);
+  const piece = (/** @type {string} */ s) => `<w:r>${rPr}<w:t${/^\s|\s$/.test(s) ? ' xml:space="preserve"' : ""}>${s}</w:t></w:r>`;
+  const before = text.slice(0, at);
+  const after = text.slice(at + op.find.length);
+  /** @type {Token[]} */
+  const tokens = [];
+  let xml = "";
+  if (before !== "") {
+    xml += piece(before);
+    tokens.push({ kind: "t", text: before });
+  }
+  xml += tagRun(rPr);
+  tokens.push(...tagToken);
+  if (after !== "") {
+    xml += piece(after);
+    tokens.push({ kind: "t", text: after });
+  }
+  return { bytes: encoder.encode(xml), tokens, tags: [op.tag] };
+}
+
+// --- applying ---------------------------------------------------------------------------
+
+/**
+ * Applies a recipe to word/document.xml. Every problem — the recipe's shape, the
+ * pins, every op's target and expectation — is collected and thrown together;
+ * otherwise the patched part comes back with a report. `parts` supplies the
+ * other parts the recipe pins (e.g. word/styles.xml), by name.
+ * @param {Uint8Array} xmlBytes
+ * @param {Recipe} recipe
+ * @param {{parts?: Record<string, Uint8Array>}} [options]
+ * @returns {Promise<{xml: Uint8Array, report: RecipeReport}>}
+ */
+export async function applyRecipeToDocumentXml(xmlBytes, recipe, { parts = {} } = {}) {
+  const shape = recipeShapeProblems(recipe);
+  if (shape.length > 0) throw recipeError("recipe", shape);
+
+  /** @type {RecipeProblem[]} */
+  const problems = [];
+  const inputSha = await sha256Hex(xmlBytes);
+  for (const [name, want] of Object.entries(recipe.source.parts)) {
+    const bytes = name === "word/document.xml" ? xmlBytes : parts[name];
+    if (bytes === undefined) {
+      problems.push({ code: "PART_MISSING", message: `the recipe pins ${name}, which was not supplied`, part: name });
+      continue;
+    }
+    const got = name === "word/document.xml" ? inputSha : await sha256Hex(bytes);
+    if (got !== want) problems.push({ code: "PART_PIN_MISMATCH", message: `${name} is not the part the recipe was written for`, part: name });
+  }
+  if (problems.length > 0) throw recipeError("recipe", problems);
+
+  const { root } = scanXml(xmlBytes);
+  const { boxes, counts, malformed } = locateBoxes(root);
+  const raw = (/** @type {{start: number, end: number}} */ el) => xmlBytes.subarray(el.start, el.end);
+  const same = (/** @type {Uint8Array} */ a, /** @type {Uint8Array} */ b) => a.length === b.length && a.every((x, i) => x === b[i]);
+  const constants = recipe.constants ?? {};
+
+  /** @type {PlannedEdit[]} */
+  const edits = [];
+  /** @type {{tag: string, docPrId: number}[]} */
+  const expectedTags = [];
+  /** @type {Set<number>} */
+  const touchedAcs = new Set();
+  /** @type {Record<string, number>} */
+  const opCounts = { setTag: 0, replaceRuns: 0, tagText: 0, fillParagraph: 0 };
+
+  recipe.ops.forEach((/** @type {any} */ op, /** @type {number} */ i) => {
+    opCounts[op.op] += 1;
+    const problem = (/** @type {string} */ code, /** @type {string} */ message) => problems.push({ code, message, op: i, docPrId: op.docPrId });
+    const n = counts.get(op.docPrId) ?? 0;
+    if (n !== 1) return problem(n === 0 ? "BOX_NOT_FOUND" : "BOX_NOT_UNIQUE", `${n} boxes carry wp:docPr id ${op.docPrId}`);
+    const box = boxes.get(op.docPrId);
+    if (box === undefined || malformed.has(op.docPrId)) return problem("BOX_SHAPE", "the box is not one Choice + one Fallback with one w:txbxContent each and a wp:anchor");
+    if (op.op === "setTag" && (counts.get(op.label) ?? 0) !== 1) return problem("LABEL_NOT_FOUND", `no single box carries the label's wp:docPr id ${op.label}`);
+    if (!compareCopies(box.choice, box.fallback).equal) return problem("COPIES_DIFFER", "the box's two copies are not structurally equal");
+
+    /** @type {Target[]} */
+    const targets = [];
+    for (const txbx of [box.choice, box.fallback]) {
+      const target = locate(op, txbx);
+      if ("code" in target) return problem(target.code, target.message);
+      targets.push(target);
+    }
+    // Structurally equal copies can still be spelled differently; the op reads one and writes both.
+    const [c, f] = targets;
+    if (!same(raw(c), raw(f))) return problem("COPIES_NOT_IDENTICAL", "the addressed bytes differ between the Choice and the Fallback copy");
+    const planned = plan(op, c, xmlBytes, constants);
+    if ("code" in planned) return problem(planned.code, planned.message);
+    for (const t of targets) edits.push({ start: t.editStart, end: t.editEnd, bytes: planned.bytes, tokens: planned.tokens, op: i });
+    touchedAcs.add(box.acIndex);
+    for (const tag of planned.tags) expectedTags.push({ tag, docPrId: op.docPrId });
+  });
+
+  // Ops are disjoint — checked here, so the error names the ops, not applyEdits' offsets.
+  // Both copies overlap alike; a pair of ops is named once.
+  const sorted = [...edits].sort((a, b) => a.start - b.start || a.end - b.end);
+  /** @type {Set<string>} */
+  const named = new Set();
+  for (let k = 0; k + 1 < sorted.length; k += 1) {
+    const a = sorted[k];
+    const b = sorted[k + 1];
+    if (b.start < a.end || (a.start === b.start && a.end === b.end)) {
+      const [x, y] = [a.op, b.op].sort((m, n) => m - n);
+      if (named.has(`${x},${y}`)) continue;
+      named.add(`${x},${y}`);
+      problems.push({ code: "OPS_OVERLAP", message: `ops ${x} and ${y} touch the same bytes`, op: y });
+    }
+  }
+  if (problems.length > 0) throw recipeError("recipe", problems);
+
+  const xml = applyEdits(xmlBytes, edits.map(({ start, end, bytes }) => ({ start, end, bytes })));
+  readBackRecipe(root, xml, edits, touchedAcs);
+
+  // The template the engine will fill: exactly the recipe's tags, nothing to refuse, nothing to warn about.
+  const outRoot = scanXml(xml).root;
+  const scan = scanTemplate(outRoot, xml);
+  /** @type {RecipeProblem[]} */
+  const after = [];
+  for (const p of [...scan.problems, ...scan.warnings]) {
+    /** @type {RecipeProblem} */
+    const q = { code: `TEMPLATE_${p.code}`, message: `the template the recipe writes: ${p.message}` };
+    if (p.tag !== undefined) q.tag = p.tag;
+    if (typeof p.docPrId === "number") q.docPrId = p.docPrId;
+    after.push(q);
+  }
+  const want = expectedTags.map((x) => `${x.tag}@${x.docPrId}`).sort();
+  const got = scan.occurrences.map((o) => `${o.name}@${o.docPrId}`).sort();
+  if (want.join("\n") !== got.join("\n")) {
+    after.push({ code: "TEMPLATE_TAGS_DIFFER", message: `the template holds ${got.length} tag occurrence(s), the recipe declares ${want.length}` });
+  }
+  if (after.length > 0) throw recipeError("recipe: the written template", after);
+
+  return {
+    xml,
+    report: {
+      recipe: { id: recipe.id, sha256: await recipeSha256(recipe) },
+      tags: tagInfo(scan),
+      ops: opCounts,
+      documentXml: { input: inputSha, output: await sha256Hex(xml) },
+    },
+  };
+}
+
+/**
+ * Reads the patched part back. A failure is a bug in this module, a plain Error:
+ * the output's w:t + w:br tokens must be the input's with exactly the planned
+ * edits' tokens in place of the ones they covered, and every touched box's two
+ * copies must still be equal (ADR-0038). Exported for its own tests.
+ * @param {import("./xml-scan.js").XmlElement} inputRoot
+ * @param {Uint8Array} out
+ * @param {PlannedEdit[]} edits
+ * @param {Set<number>} touchedAcs
+ * @returns {void}
+ */
+export function readBackRecipe(inputRoot, out, edits, touchedAcs) {
+  /** @type {import("./xml-scan.js").XmlElement} */
+  let outRoot;
+  try {
+    outRoot = scanXml(out).root;
+  } catch (err) {
+    throw new Error(`recipe: the patched document.xml does not parse — ${/** @type {Error} */ (err).message}`, { cause: err });
+  }
+  /** @type {{at: number, tokens: {kind: string, text?: string}[]}[]} */
+  const segments = [];
+  for (const token of textTokens(inputRoot)) {
+    const covered = edits.some((e) => token.el.start >= e.start && token.el.start < e.end);
+    if (!covered) segments.push({ at: token.el.start, tokens: [token.kind === "t" ? { kind: "t", text: token.text } : { kind: "br" }] });
+  }
+  for (const e of edits) segments.push({ at: e.start, tokens: e.tokens });
+  segments.sort((a, b) => a.at - b.at);
+  const expected = segments.flatMap((s) => s.tokens);
+  const after = textTokens(outRoot);
+  if (after.length !== expected.length) {
+    throw new Error(`recipe: the patched document.xml holds ${after.length} w:t/w:br token(s), the recipe accounts for ${expected.length}`);
+  }
+  for (let k = 0; k < expected.length; k += 1) {
+    const e = expected[k];
+    const a = after[k];
+    if (a.kind !== e.kind || (a.kind === "t" && a.text !== e.text)) {
+      throw new Error(`recipe: token #${k + 1} does not read back as the recipe wrote it`);
+    }
+  }
+  const acs = collectAlternateContents(outRoot);
+  for (const index of touchedAcs) {
+    const ac = acs[index];
+    if (ac === undefined || ac.choiceTx.length !== 1 || ac.fallbackTx.length !== 1) throw new Error(`recipe: AlternateContent #${index} lost its shape`);
+    const copies = compareCopies(ac.choiceTx[0], ac.fallbackTx[0]);
+    if (!copies.equal) throw new Error(`recipe: the two copies of AlternateContent #${index} differ after the recipe, at ${copies.path}`);
+  }
+}
+
+/**
+ * Applies a recipe to a .docx: word/document.xml patched, every other part's
+ * bytes copied verbatim (invariant #10). The parts the recipe pins are read
+ * from the package for the pin check.
+ * @param {Uint8Array} docx
+ * @param {Recipe} recipe
+ * @returns {Promise<{bytes: Uint8Array, documentXml: Uint8Array, report: RecipeReport}>}
+ */
+export async function applyRecipe(docx, recipe) {
+  if (!(docx instanceof Uint8Array)) throw new TypeError("applyRecipe: docx must be a Uint8Array (a .docx file's bytes)");
+  const entries = parseZipContainer(docx);
+  const main = resolveMainDocumentPart(entries);
+  const xml = await inflateEntry(docx, main);
+  /** @type {Record<string, Uint8Array>} */
+  const parts = {};
+  for (const name of Object.keys(recipe?.source?.parts ?? {})) {
+    if (name === main.name) continue;
+    const entry = entries.find((e) => e.name === name);
+    if (entry !== undefined) parts[name] = await inflateEntry(docx, entry);
+  }
+  const { xml: documentXml, report } = await applyRecipeToDocumentXml(xml, recipe, { parts });
+  const bytes = await writePackage(docx, entries, { [main.name]: documentXml });
+  return { bytes, documentXml, report };
+}