@adeu/core 1.21.0 → 1.23.0

package/dist/index.js

@@ -253,6 +253,13 @@ var DocumentObject = class _DocumentObject {
   async save() {
     for (const part of this.pkg.parts) {
       let xmlStr = serializeXml(part._element.ownerDocument || part._element);
+      if (xmlStr.includes("w16du:") && !xmlStr.includes("xmlns:w16du=")) {
+        part._element.setAttribute(
+          "xmlns:w16du",
+          "http://schemas.microsoft.com/office/word/2023/wordml/word16du"
+        );
+        xmlStr = serializeXml(part._element.ownerDocument || part._element);
+      }
       if (!xmlStr.startsWith("<?xml")) {
         xmlStr = '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>\n' + xmlStr;
       }
@@ -743,6 +750,62 @@ function extract_comments_data(pkg) {
   return data;
 }
 
+// src/utils/safe-regex.ts
+import * as vm from "vm";
+var USER_PATTERN_TIMEOUT_MS = 2e3;
+var RegexTimeoutError = class extends Error {
+  pattern;
+  constructor(pattern) {
+    super(
+      `Regular expression exceeded the ${USER_PATTERN_TIMEOUT_MS / 1e3}s matching time budget (catastrophic backtracking). Simplify the pattern \u2014 nested quantifiers like (a+)+ are the usual cause \u2014 or use a literal target instead.`
+    );
+    this.name = "RegexTimeoutError";
+    this.pattern = pattern;
+  }
+};
+function runBudgeted(pattern, script, sandbox) {
+  try {
+    return vm.runInNewContext(script, sandbox, {
+      timeout: USER_PATTERN_TIMEOUT_MS
+    });
+  } catch (e) {
+    if (e && e.code === "ERR_SCRIPT_EXECUTION_TIMEOUT") {
+      throw new RegexTimeoutError(pattern);
+    }
+    throw e;
+  }
+}
+function userFindAllMatches(pattern, text, flags = "") {
+  const normalized = flags.includes("g") ? flags : flags + "g";
+  const re = new RegExp(pattern, normalized);
+  const raw = runBudgeted(
+    pattern,
+    `{
+      const out = [];
+      let m;
+      while ((m = re.exec(text)) !== null) {
+        out.push({ start: m.index, end: m.index + m[0].length });
+        if (m.index === re.lastIndex) re.lastIndex++;
+      }
+      out;
+    }`,
+    { re, text }
+  );
+  return raw.map((r) => ({ start: r.start, end: r.end }));
+}
+function userSearch(pattern, text, flags = "") {
+  const re = new RegExp(pattern, flags.replace("g", ""));
+  const raw = runBudgeted(
+    pattern,
+    `{
+      const m = re.exec(text);
+      m ? { start: m.index, end: m.index + m[0].length } : null;
+    }`,
+    { re, text }
+  );
+  return raw ? { start: raw.start, end: raw.end } : null;
+}
+
 // src/utils/docx.ts
 var QN_W_P = "w:p";
 var QN_W_R = "w:r";
@@ -784,7 +847,27 @@ var QN_W_OUTLINELVL = "w:outlineLvl";
 var QN_W_NUMPR = "w:numPr";
 var QN_W_NUMID = "w:numId";
 var QN_W_ILVL = "w:ilvl";
+var QN_W_DRAWING = "w:drawing";
+var QN_W_OBJECT = "w:object";
+var QN_W_PICT = "w:pict";
+var QN_WP_DOCPR = "wp:docPr";
+var QN_V_IMAGEDATA = "v:imagedata";
+var QN_O_TITLE = "o:title";
 var _CUSTOM_HEADING_NAME_RE = /Heading[ ]?([1-6])(?![0-9])/;
+function _resolve_package(obj) {
+  let cur = obj;
+  const seen = /* @__PURE__ */ new Set();
+  while (cur && !seen.has(cur)) {
+    seen.add(cur);
+    if (cur.package) return cur.package;
+    if (cur.pkg) return cur.pkg;
+    if (cur.part && (cur.part.package || cur.part.pkg)) {
+      return cur.part.package || cur.part.pkg;
+    }
+    cur = cur._parent || cur.part || null;
+  }
+  return null;
+}
 function _get_style_cache(part) {
   const pkg = part.package || part.pkg || (part.part ? part.part.pkg : null);
   if (pkg && pkg._adeu_style_cache) {
@@ -818,6 +901,8 @@ function _get_style_cache(part) {
     const based_on_el = findChild(s, "w:basedOn");
     const based_on = based_on_el ? based_on_el.getAttribute("w:val") : null;
     let outline_lvl = null;
+    let num_id = null;
+    let num_ilvl = null;
     const pPr = findChild(s, "w:pPr");
     if (pPr) {
       const oLvl = findChild(pPr, "w:outlineLvl");
@@ -825,6 +910,19 @@ function _get_style_cache(part) {
         const val = oLvl.getAttribute("w:val");
         if (val && /^\d+$/.test(val)) outline_lvl = parseInt(val, 10);
       }
+      const numPr = findChild(pPr, "w:numPr");
+      if (numPr) {
+        const numId_el = findChild(numPr, "w:numId");
+        if (numId_el) {
+          const n_val = numId_el.getAttribute("w:val");
+          if (n_val && n_val !== "0") num_id = n_val;
+        }
+        const ilvl_el = findChild(numPr, "w:ilvl");
+        if (ilvl_el) {
+          const i_val = ilvl_el.getAttribute("w:val");
+          if (i_val && /^\d+$/.test(i_val)) num_ilvl = parseInt(i_val, 10);
+        }
+      }
     }
     let bold = null;
     const rPr = findChild(s, "w:rPr");
@@ -835,23 +933,46 @@ function _get_style_cache(part) {
         bold = val !== "0" && val !== "false" && val !== "off";
       }
     }
-    raw_styles[s_id] = { name, based_on, outline_level: outline_lvl, bold };
+    raw_styles[s_id] = {
+      name,
+      based_on,
+      outline_level: outline_lvl,
+      bold,
+      num_id,
+      num_ilvl
+    };
   }
   const resolve_style = (s_id, visited) => {
     if (cache[s_id]) return cache[s_id];
     if (visited.has(s_id) || !raw_styles[s_id])
-      return { name: s_id, outline_level: null, bold: false };
+      return {
+        name: s_id,
+        outline_level: null,
+        bold: false,
+        num_id: null,
+        num_ilvl: null
+      };
     visited.add(s_id);
     const raw = raw_styles[s_id];
     const based_on_id = raw.based_on;
     let o_lvl = raw.outline_level;
     let bold_val = raw.bold !== null ? raw.bold : false;
+    let n_id = raw.num_id;
+    let n_ilvl = raw.num_ilvl;
     if (based_on_id) {
       const parent = resolve_style(based_on_id, visited);
       if (o_lvl === null) o_lvl = parent.outline_level;
       if (raw.bold === null) bold_val = parent.bold;
-    }
-    const resolved = { name: raw.name, outline_level: o_lvl, bold: bold_val };
+      if (n_id === null) n_id = parent.num_id ?? null;
+      if (n_ilvl === null) n_ilvl = parent.num_ilvl ?? null;
+    }
+    const resolved = {
+      name: raw.name,
+      outline_level: o_lvl,
+      bold: bold_val,
+      num_id: n_id,
+      num_ilvl: n_ilvl
+    };
     cache[s_id] = resolved;
     return resolved;
   };
@@ -860,6 +981,68 @@ function _get_style_cache(part) {
   if (pkg) pkg._adeu_style_cache = result;
   return result;
 }
+function _get_numbering_cache(part) {
+  const pkg = _resolve_package(part);
+  if (!pkg) return {};
+  if (pkg._adeu_numbering_cache) return pkg._adeu_numbering_cache;
+  const cache = {};
+  let numbering_root = null;
+  try {
+    const numberingPart = (pkg.parts || []).find(
+      (p) => String(p.partname).endsWith("/numbering.xml")
+    );
+    if (numberingPart) numbering_root = numberingPart._element;
+  } catch {
+    numbering_root = null;
+  }
+  if (numbering_root) {
+    const abstract_fmts = {};
+    for (const abstract of findAllDescendants(numbering_root, "w:abstractNum")) {
+      const a_id = abstract.getAttribute("w:abstractNumId");
+      if (a_id === null) continue;
+      const lvl_map = {};
+      for (const lvl of findAllDescendants(abstract, "w:lvl")) {
+        const ilvl_val = lvl.getAttribute("w:ilvl");
+        const fmt_el = findChild(lvl, "w:numFmt");
+        if (ilvl_val !== null && /^-?\d+$/.test(ilvl_val) && fmt_el) {
+          const fmt = fmt_el.getAttribute("w:val");
+          if (fmt) lvl_map[parseInt(ilvl_val, 10)] = fmt;
+        }
+      }
+      abstract_fmts[a_id] = lvl_map;
+    }
+    for (const num of findAllDescendants(numbering_root, "w:num")) {
+      const n_id = num.getAttribute("w:numId");
+      const a_ref = findChild(num, "w:abstractNumId");
+      if (n_id === null || !a_ref) continue;
+      const a_id = a_ref.getAttribute("w:val");
+      if (a_id !== null && abstract_fmts[a_id] !== void 0) {
+        cache[n_id] = abstract_fmts[a_id];
+      }
+    }
+  }
+  pkg._adeu_numbering_cache = cache;
+  return cache;
+}
+function get_list_marker(paragraph_part, num_id, ilvl) {
+  let fmt = null;
+  if (num_id !== null && num_id !== void 0) {
+    const lvl_map = _get_numbering_cache(paragraph_part)[num_id];
+    if (lvl_map && Object.keys(lvl_map).length > 0) {
+      fmt = lvl_map[ilvl] !== void 0 ? lvl_map[ilvl] : null;
+      if (fmt === null) {
+        for (let lookup = ilvl; lookup >= 0; lookup--) {
+          if (lvl_map[lookup] !== void 0) {
+            fmt = lvl_map[lookup];
+            break;
+          }
+        }
+      }
+    }
+  }
+  if (fmt !== null && fmt !== "bullet") return "1. ";
+  return "* ";
+}
 function _detect_heading_level_from_name(name) {
   if (!name) return null;
   const match = name.match(_CUSTOM_HEADING_NAME_RE);
@@ -937,21 +1120,48 @@ function get_paragraph_prefix(paragraph, style_cache, default_pstyle) {
     if (/^\d+$/.test(match)) return "#".repeat(parseInt(match, 10)) + " ";
   }
   if (style_name === "Title") return "# ";
+  let list_num_id = null;
+  let list_ilvl = null;
+  let numbering_disabled = false;
   if (pPr) {
     const numPr = findChild(pPr, QN_W_NUMPR);
     if (numPr) {
       const numId = findChild(numPr, QN_W_NUMID);
-      if (numId && numId.getAttribute(QN_W_VAL) !== "0") {
-        let level = 0;
-        const ilvl = findChild(numPr, QN_W_ILVL);
-        if (ilvl) {
-          const valAttr = ilvl.getAttribute(QN_W_VAL);
-          if (valAttr) level = parseInt(valAttr, 10) || 0;
+      if (numId) {
+        const val = numId.getAttribute(QN_W_VAL);
+        if (val === "0") {
+          numbering_disabled = true;
+        } else if (val) {
+          list_num_id = val;
+          const ilvl = findChild(numPr, QN_W_ILVL);
+          if (ilvl) {
+            const valAttr = ilvl.getAttribute(QN_W_VAL);
+            if (valAttr !== null && /^\d+$/.test(valAttr)) {
+              list_ilvl = parseInt(valAttr, 10);
+            }
+          }
         }
-        return "    ".repeat(level) + "* ";
       }
     }
   }
+  if (list_num_id === null && !numbering_disabled && style_info) {
+    const style_num_id = style_info.num_id;
+    if (style_num_id) {
+      list_num_id = style_num_id;
+      if (list_ilvl === null) {
+        list_ilvl = style_info.num_ilvl !== void 0 ? style_info.num_ilvl : null;
+      }
+    }
+  }
+  if (list_num_id !== null) {
+    const level = list_ilvl !== null ? list_ilvl : 0;
+    const marker = get_list_marker(
+      paragraph._parent ? paragraph._parent.part || paragraph._parent : null,
+      list_num_id,
+      level
+    );
+    return "    ".repeat(level) + marker;
+  }
   if (style_name && style_name !== "Normal") {
     const custom_level = _detect_heading_level_from_name(style_name);
     if (custom_level !== null) return "#".repeat(custom_level) + " ";
@@ -1049,6 +1259,9 @@ function* iter_block_items(parent) {
     for (const child of notes) {
       if (child.getAttribute("w:type") === "separator" || child.getAttribute("w:type") === "continuationSeparator")
         continue;
+      const note_id = child.getAttribute("w:id");
+      if (note_id !== null && /^\s*[-+]?\d+\s*$/.test(note_id) && parseInt(note_id, 10) <= 0)
+        continue;
       yield new FootnoteItem(child, parent, parent.note_type);
     }
     return;
@@ -1064,19 +1277,24 @@ function* iter_block_items(parent) {
   }
 }
 function* iter_document_parts(doc) {
+  for (const [container] of iter_document_parts_with_kind(doc)) {
+    yield container;
+  }
+}
+function* iter_document_parts_with_kind(doc) {
   const headers = doc.pkg.parts.filter(
     (p) => p.contentType === "application/vnd.openxmlformats-officedocument.wordprocessingml.header+xml"
   );
-  for (const h of headers) yield h;
-  yield doc;
+  for (const h of headers) yield [h, "header"];
+  yield [doc, "body"];
   const footers = doc.pkg.parts.filter(
     (p) => p.contentType === "application/vnd.openxmlformats-officedocument.wordprocessingml.footer+xml"
   );
-  for (const f of footers) yield f;
+  for (const f of footers) yield [f, "footer"];
   const fnPart = doc.pkg.getPartByPath("word/footnotes.xml");
   const enPart = doc.pkg.getPartByPath("word/endnotes.xml");
-  if (fnPart) yield new NotesPart(fnPart, "fn");
-  if (enPart) yield new NotesPart(enPart, "en");
+  if (fnPart) yield [new NotesPart(fnPart, "fn"), "footnotes"];
+  if (enPart) yield [new NotesPart(enPart, "en"), "endnotes"];
 }
 function _is_page_instr(instr) {
   if (!instr) return false;
@@ -1114,7 +1332,22 @@ function* iter_paragraph_content(paragraph) {
       const child = r_element.childNodes[i];
       if (child.nodeType !== 1) continue;
       const tag = child.tagName;
-      if (tag === QN_W_COMMENTREFERENCE) {
+      if (tag === QN_W_DRAWING || tag === QN_W_OBJECT) {
+        const doc_pr = findAllDescendants(child, QN_WP_DOCPR)[0] || null;
+        let alt = "";
+        let img_id = "0";
+        if (doc_pr) {
+          alt = doc_pr.getAttribute("descr") || doc_pr.getAttribute("title") || "";
+          img_id = doc_pr.getAttribute("id") || "0";
+        }
+        yield { type: "image", id: img_id, date: alt };
+      } else if (tag === QN_W_PICT) {
+        const imagedata = findAllDescendants(child, QN_V_IMAGEDATA)[0] || null;
+        if (imagedata) {
+          const alt = imagedata.getAttribute(QN_O_TITLE) || "";
+          yield { type: "image", id: "vml", date: alt };
+        }
+      } else if (tag === QN_W_COMMENTREFERENCE) {
         const ref_id = child.getAttribute(QN_W_ID);
         if (ref_id) yield { type: "ref", id: ref_id };
       } else if (tag === QN_W_FOOTNOTEREFERENCE) {
@@ -1222,6 +1455,11 @@ var DocumentMapper = class {
   full_text = "";
   spans = [];
   appendix_start_index = -1;
+  // [start, end, kind] per projected part, in projection order. Spans carry
+  // the matching index in .part_index. Together these let the engine refuse
+  // or re-anchor edits at OPC part boundaries (QA 2026-07-18 C1).
+  part_ranges = [];
+  _current_part_index = 0;
   _text_chunks = [];
   _plain_projection = null;
   constructor(doc, clean_view = false, original_view = false) {
@@ -1237,12 +1475,19 @@ var DocumentMapper = class {
     this._text_chunks = [];
     this.full_text = "";
     this._plain_projection = null;
-    for (const part of iter_document_parts(this.doc)) {
+    this.part_ranges = [];
+    this._current_part_index = 0;
+    let part_idx = 0;
+    for (const [part, part_kind] of iter_document_parts_with_kind(this.doc)) {
+      this._current_part_index = part_idx;
+      const part_start = current_offset;
       current_offset = this._map_blocks(part, current_offset);
+      this.part_ranges.push([part_start, current_offset, part_kind]);
       if (this.spans.length > 0 && this.spans[this.spans.length - 1].text !== "\n\n") {
         this._add_virtual_text("\n\n", current_offset, null);
         current_offset += 2;
       }
+      part_idx++;
     }
     while (this.spans.length > 0 && this.spans[this.spans.length - 1].text === "\n\n") {
       this.spans.pop();
@@ -1251,6 +1496,47 @@ var DocumentMapper = class {
     this.full_text = this._text_chunks.join("");
     this.appendix_start_index = -1;
   }
+  /** [part_index, start, end, kind] for parts that projected any text. */
+  _nonempty_part_ranges() {
+    const out = [];
+    for (let i = 0; i < this.part_ranges.length; i++) {
+      const [s, e, k] = this.part_ranges[i];
+      if (e > s) out.push([i, s, e, k]);
+    }
+    return out;
+  }
+  part_kind_of(part_index) {
+    if (part_index >= 0 && part_index < this.part_ranges.length) {
+      return this.part_ranges[part_index][2];
+    }
+    return null;
+  }
+  /** Kind of the part whose projected range contains `index`, or null. */
+  part_kind_at(index) {
+    for (const [, start, end, kind] of this._nonempty_part_ranges()) {
+      if (start <= index && index <= end) return kind;
+    }
+    return null;
+  }
+  /**
+   * When `index` falls strictly AFTER one part's text and at-or-before the
+   * start of the next part's text (i.e. inside the "\n\n" separator or
+   * exactly at the next part's first character), returns
+   * [previous_part_index, next_part_index]. Returns null everywhere else —
+   * including index == previous part's end, which is an ordinary
+   * end-of-part text position, not a boundary gap.
+   */
+  part_boundary_at(index) {
+    const ranges = this._nonempty_part_ranges();
+    for (let j = 1; j < ranges.length; j++) {
+      const [prev_i, , prev_end] = ranges[j - 1];
+      const [next_i, next_start] = ranges[j];
+      if (prev_end < index && index <= next_start) {
+        return [prev_i, next_i];
+      }
+    }
+    return null;
+  }
   _map_blocks(container, offset) {
     let current = offset;
     const c_type = container.constructor.name;
@@ -1380,7 +1666,8 @@ ${header}`;
       end: current,
       text: "",
       run: null,
-      paragraph
+      paragraph,
+      part_index: this._current_part_index
     };
     this.spans.push(span);
     const active_ids = /* @__PURE__ */ new Set();
@@ -1412,7 +1699,8 @@ ${header}`;
             ins_id: i_id || void 0,
             del_id: d_id || void 0,
             hyperlink_id: active_hyperlink_id || void 0,
-            comment_ids: c_ids.length > 0 ? c_ids : void 0
+            comment_ids: c_ids.length > 0 ? c_ids : void 0,
+            part_index: this._current_part_index
           };
           this.spans.push(s);
           this._text_chunks.push(txt);
@@ -1591,7 +1879,15 @@ ${header}`;
         else if (ev.type === "del_end") delete active_del[ev.id];
         else if (ev.type === "fmt_start") active_fmt[ev.id] = ev;
         else if (ev.type === "fmt_end") delete active_fmt[ev.id];
-        else if (ev.type === "footnote" || ev.type === "endnote") {
+        else if (ev.type === "image") {
+          const hidden = this.clean_view && Object.keys(active_del).length > 0 || this.original_view && Object.keys(active_ins).length > 0;
+          if (!hidden) {
+            const alt = (ev.date || "image").replace(/\]/g, ")").replace(/\n/g, " ");
+            const txt = `![${alt}](docx-image:${ev.id})`;
+            this._add_virtual_text(txt, current, paragraph, null, true);
+            current += txt.length;
+          }
+        } else if (ev.type === "footnote" || ev.type === "endnote") {
           flush_pending_runs();
           current_wrappers = ["", ""];
           current_style = ["", ""];
@@ -1706,14 +2002,16 @@ ${header}`;
     }
     return [...change_lines, ...comment_lines].join("\n");
   }
-  _add_virtual_text(text, offset, context_paragraph, hyperlink_id = null) {
+  _add_virtual_text(text, offset, context_paragraph, hyperlink_id = null, is_image_marker = false) {
     const span = {
       start: offset,
       end: offset + text.length,
       text,
       run: null,
       paragraph: context_paragraph,
-      hyperlink_id: hyperlink_id || void 0
+      hyperlink_id: hyperlink_id || void 0,
+      part_index: this._current_part_index,
+      is_image_marker: is_image_marker || void 0
     };
     this.spans.push(span);
     this._text_chunks.push(text);
@@ -1817,10 +2115,10 @@ ${header}`;
   find_match_index(target_text, is_regex = false) {
     if (is_regex) {
       try {
-        const pattern = new RegExp(target_text);
-        const match = pattern.exec(this.full_text);
-        if (match) return [match.index, match[0].length];
+        const match = userSearch(target_text, this.full_text);
+        if (match) return [match.start, match.end - match.start];
       } catch (e) {
+        if (e instanceof RegexTimeoutError) throw e;
       }
       return [-1, 0];
     }
@@ -1849,11 +2147,10 @@ ${header}`;
     if (!target_text) return [];
     if (is_regex) {
       try {
-        const pattern = new RegExp(target_text, "g");
-        const matches2 = [...this.full_text.matchAll(pattern)];
-        if (matches2.length > 0)
-          return matches2.map((m) => [m.index, m[0].length]);
+        const matches2 = userFindAllMatches(target_text, this.full_text);
+        if (matches2.length > 0) return matches2.map((m) => [m.start, m.end - m.start]);
       } catch (e) {
+        if (e instanceof RegexTimeoutError) throw e;
       }
       return [];
     }
@@ -2314,6 +2611,327 @@ function generate_edits_from_text(original_text, modified_text) {
   }
   return edits;
 }
+function _sequence_opcodes(a, b) {
+  const n = a.length;
+  const m = b.length;
+  const dp = [];
+  for (let i2 = 0; i2 <= n; i2++) dp.push(new Int32Array(m + 1));
+  for (let i2 = n - 1; i2 >= 0; i2--) {
+    for (let j2 = m - 1; j2 >= 0; j2--) {
+      dp[i2][j2] = a[i2] === b[j2] ? dp[i2 + 1][j2 + 1] + 1 : Math.max(dp[i2 + 1][j2], dp[i2][j2 + 1]);
+    }
+  }
+  const ops = [];
+  let i = 0;
+  let j = 0;
+  let pend_i1 = 0;
+  let pend_j1 = 0;
+  let pend_del = 0;
+  let pend_ins = 0;
+  const flushPending = () => {
+    if (pend_del === 0 && pend_ins === 0) return;
+    const tag = pend_del > 0 && pend_ins > 0 ? "replace" : pend_del > 0 ? "delete" : "insert";
+    ops.push([tag, pend_i1, pend_i1 + pend_del, pend_j1, pend_j1 + pend_ins]);
+    pend_del = 0;
+    pend_ins = 0;
+  };
+  while (i < n || j < m) {
+    if (i < n && j < m && a[i] === b[j]) {
+      flushPending();
+      const i1 = i;
+      const j1 = j;
+      while (i < n && j < m && a[i] === b[j]) {
+        i++;
+        j++;
+      }
+      ops.push(["equal", i1, i, j1, j]);
+    } else {
+      if (pend_del === 0 && pend_ins === 0) {
+        pend_i1 = i;
+        pend_j1 = j;
+      }
+      if (j < m && (i === n || dp[i][j + 1] >= dp[i + 1][j])) {
+        pend_ins++;
+        j++;
+      } else {
+        pend_del++;
+        i++;
+      }
+    }
+  }
+  flushPending();
+  return ops;
+}
+var _IMAGE_MARKER_RE = /!\[[^\]]*\]\(docx-image:[^)]*\)/g;
+function _drop_image_marker_hunks(edits, warnings) {
+  const _normalized = (s) => s.replace(_IMAGE_MARKER_RE, "").replace(/\s+/g, " ").trim();
+  const kept = [];
+  for (const e of edits) {
+    const t_imgs = ((e.target_text || "").match(_IMAGE_MARKER_RE) || []).sort();
+    const n_imgs = ((e.new_text || "").match(_IMAGE_MARKER_RE) || []).sort();
+    if (JSON.stringify(t_imgs) === JSON.stringify(n_imgs)) {
+      kept.push(e);
+      continue;
+    }
+    if (_normalized(e.target_text || "") === _normalized(e.new_text || "")) {
+      warnings.push(
+        "An inline image was added or removed between the documents. Images cannot be transferred by text edits \u2014 the image-only difference was skipped; apply it manually in Word."
+      );
+    } else {
+      warnings.push(
+        "A text change overlapping an added/removed inline image was skipped \u2014 images cannot be transferred by text edits. Apply that section manually in Word."
+      );
+    }
+  }
+  return kept;
+}
+function _rows_are_plain(text, table) {
+  for (const row of table.rows) {
+    if (text.substring(row.start, row.end) !== row.cells.join(" | ")) {
+      return false;
+    }
+  }
+  return true;
+}
+var _ROW_KEY_SEP = "";
+function _table_row_opcodes(rows_o, rows_m) {
+  const keys_o = rows_o.map((r) => r.cells.join(_ROW_KEY_SEP));
+  const keys_m = rows_m.map((r) => r.cells.join(_ROW_KEY_SEP));
+  const opcodes = _sequence_opcodes(keys_o, keys_m);
+  for (const [tag, i1, i2, j1, j2] of opcodes) {
+    if (tag === "insert" || tag === "delete" || tag === "replace" && i2 - i1 !== j2 - j1) {
+      return opcodes;
+    }
+  }
+  return null;
+}
+function _row_ops_for_table(table_o, table_m, opcodes, warnings) {
+  const rows_o = table_o.rows;
+  const rows_m = table_m.rows;
+  const keys_o = rows_o.map((r) => r.cells.join(_ROW_KEY_SEP));
+  const row_text = (r) => r.cells.join(" | ");
+  if (new Set(keys_o).size !== keys_o.length) {
+    warnings.push(
+      "A table contains rows with identical text; the generated row operations anchor by row text and may be rejected as ambiguous at apply time. If that happens, apply the row changes with explicit insert_row/delete_row edits."
+    );
+  }
+  const removed = /* @__PURE__ */ new Set();
+  const replaced_new_text = {};
+  for (const [tag, i1, i2, j1, j2] of opcodes) {
+    if (tag === "delete") {
+      for (let k = i1; k < i2; k++) removed.add(k);
+    } else if (tag === "replace") {
+      const pairs = Math.min(i2 - i1, j2 - j1);
+      for (let k = i1 + pairs; k < i2; k++) removed.add(k);
+      for (let k = 0; k < pairs; k++) {
+        replaced_new_text[i1 + k] = row_text(rows_m[j1 + k]);
+      }
+    }
+  }
+  const surviving = [];
+  for (let k = 0; k < rows_o.length; k++) {
+    if (!removed.has(k)) surviving.push(k);
+  }
+  const anchor_text = (orig_idx) => {
+    return replaced_new_text[orig_idx] !== void 0 ? replaced_new_text[orig_idx] : row_text(rows_o[orig_idx]);
+  };
+  const insert_ops = (new_rows, at_orig_index) => {
+    const ops2 = [];
+    const before = surviving.filter((k) => k < at_orig_index);
+    const after = surviving.filter((k) => k >= at_orig_index);
+    if (before.length > 0) {
+      const anchor_idx = before[before.length - 1];
+      const anchor = anchor_text(anchor_idx);
+      for (const r of [...new_rows].reverse()) {
+        ops2.push({
+          type: "insert_row",
+          target_text: anchor,
+          position: "below",
+          cells: [...r.cells],
+          // Pin to the anchor row's offset: text anchors alone are
+          // ambiguous when tables share identical rows. Pins do not
+          // survive JSON round-trips (the strict text match applies then,
+          // failing closed with the duplicate-row warning above).
+          _match_start_index: rows_o[anchor_idx].start
+        });
+      }
+    } else if (after.length > 0) {
+      const anchor_idx = after[0];
+      const anchor = anchor_text(anchor_idx);
+      for (const r of new_rows) {
+        ops2.push({
+          type: "insert_row",
+          target_text: anchor,
+          position: "above",
+          cells: [...r.cells],
+          _match_start_index: rows_o[anchor_idx].start
+        });
+      }
+    } else {
+      warnings.push(
+        "A table gained rows but no original row survives to anchor them; these row insertions were skipped \u2014 add them with explicit insert_row operations."
+      );
+    }
+    return ops2;
+  };
+  const ops = [];
+  for (const [tag, i1, i2, j1, j2] of opcodes) {
+    if (tag === "equal") continue;
+    if (tag === "replace") {
+      const pairs = Math.min(i2 - i1, j2 - j1);
+      for (let k = 0; k < pairs; k++) {
+        const o_txt = row_text(rows_o[i1 + k]);
+        const m_txt = row_text(rows_m[j1 + k]);
+        if (o_txt !== m_txt) {
+          ops.push({
+            type: "modify",
+            target_text: o_txt,
+            new_text: m_txt,
+            comment: "Diff: Table row modified"
+          });
+        }
+      }
+      for (let k = i1 + pairs; k < i2; k++) {
+        ops.push({
+          type: "delete_row",
+          target_text: row_text(rows_o[k]),
+          _match_start_index: rows_o[k].start
+        });
+      }
+      const surplus_new = rows_m.slice(j1 + pairs, j2);
+      if (surplus_new.length > 0) {
+        ops.push(...insert_ops(surplus_new, i2));
+      }
+    } else if (tag === "delete") {
+      for (let k = i1; k < i2; k++) {
+        ops.push({
+          type: "delete_row",
+          target_text: row_text(rows_o[k]),
+          _match_start_index: rows_o[k].start
+        });
+      }
+    } else if (tag === "insert") {
+      ops.push(...insert_ops(rows_m.slice(j1, j2), i1));
+    }
+  }
+  return ops;
+}
+function generate_structured_edits(text_orig, struct_orig, text_mod, struct_mod) {
+  const warnings = [];
+  const edits = [];
+  const kinds_o = struct_orig.part_ranges.filter(([s, e]) => e > s).map(([, , k]) => k);
+  const kinds_m = struct_mod.part_ranges.filter(([s, e]) => e > s).map(([, , k]) => k);
+  if (JSON.stringify(kinds_o) !== JSON.stringify(kinds_m)) {
+    warnings.push(
+      `The documents have different part layouts (${kinds_o.join(" + ") || "none"} vs ${kinds_m.join(" + ") || "none"}); comparing flattened text instead. Header/footer additions or removals cannot be expressed as text edits.`
+    );
+    const flat = _drop_image_marker_hunks(
+      generate_edits_from_text(text_orig, text_mod),
+      warnings
+    );
+    return { edits: [...flat], warnings };
+  }
+  const ranges_o = struct_orig.part_ranges.filter(([s, e]) => e > s).map(([s, e]) => [s, e]);
+  const ranges_m = struct_mod.part_ranges.filter(([s, e]) => e > s).map(([s, e]) => [s, e]);
+  for (let p = 0; p < ranges_o.length; p++) {
+    const [po_start, po_end] = ranges_o[p];
+    const [pm_start, pm_end] = ranges_m[p];
+    const tables_o = struct_orig.tables.filter(
+      (t) => po_start <= t.start && t.end <= po_end
+    );
+    const tables_m = struct_mod.tables.filter(
+      (t) => pm_start <= t.start && t.end <= pm_end
+    );
+    const tables_alignable = tables_o.length === tables_m.length && tables_o.every((t) => _rows_are_plain(text_orig, t)) && tables_m.every((t) => _rows_are_plain(text_mod, t));
+    if (tables_o.length !== tables_m.length) {
+      warnings.push(
+        `A ${kinds_o[p]} part has ${tables_o.length} table(s) in the original but ${tables_m.length} in the modified document; its tables were compared as plain text. Adding or removing whole tables is not supported via diff/apply.`
+      );
+    }
+    if (!tables_alignable) {
+      const part_edits = generate_edits_from_text(
+        text_orig.substring(po_start, po_end),
+        text_mod.substring(pm_start, pm_end)
+      );
+      for (const e of part_edits) {
+        e._match_start_index = (e._match_start_index || 0) + po_start;
+      }
+      edits.push(...part_edits);
+      continue;
+    }
+    const boundaries_o = [
+      [po_start, po_start],
+      ...tables_o.map((t) => [t.start, t.end]),
+      [po_end, po_end]
+    ];
+    const boundaries_m = [
+      [pm_start, pm_start],
+      ...tables_m.map((t) => [t.start, t.end]),
+      [pm_end, pm_end]
+    ];
+    for (let seg_idx = 0; seg_idx < boundaries_o.length - 1; seg_idx++) {
+      const seg_o_start = boundaries_o[seg_idx][1];
+      const seg_o_end = boundaries_o[seg_idx + 1][0];
+      const seg_m_start = boundaries_m[seg_idx][1];
+      const seg_m_end = boundaries_m[seg_idx + 1][0];
+      const seg_edits = generate_edits_from_text(
+        text_orig.substring(seg_o_start, seg_o_end),
+        text_mod.substring(seg_m_start, seg_m_end)
+      );
+      for (const e of seg_edits) {
+        e._match_start_index = (e._match_start_index || 0) + seg_o_start;
+      }
+      edits.push(...seg_edits);
+      if (seg_idx < tables_o.length) {
+        const t_o = tables_o[seg_idx];
+        const t_m = tables_m[seg_idx];
+        const row_opcodes = _table_row_opcodes(t_o.rows, t_m.rows);
+        if (row_opcodes !== null) {
+          edits.push(..._row_ops_for_table(t_o, t_m, row_opcodes, warnings));
+        } else {
+          const tbl_edits = generate_edits_from_text(
+            text_orig.substring(t_o.start, t_o.end),
+            text_mod.substring(t_m.start, t_m.end)
+          );
+          for (const e of tbl_edits) {
+            e._match_start_index = (e._match_start_index || 0) + t_o.start;
+          }
+          edits.push(...tbl_edits);
+        }
+      }
+    }
+  }
+  const countOccurrences = (haystack, needle) => {
+    let count = 0;
+    let from = 0;
+    while (true) {
+      const idx = haystack.indexOf(needle, from);
+      if (idx === -1) break;
+      count++;
+      from = idx + needle.length;
+    }
+    return count;
+  };
+  let ambiguous_anchor_warned = false;
+  for (const e of edits) {
+    if ((e.type === "insert_row" || e.type === "delete_row") && !ambiguous_anchor_warned) {
+      if (e.target_text && countOccurrences(text_orig, e.target_text) > 1) {
+        warnings.push(
+          `The row anchor "${e.target_text.substring(0, 60)}" appears more than once in the document. Applying this diff from its JSON output may be rejected as ambiguous \u2014 make the anchor rows unique, or apply the row changes with explicit insert_row/delete_row edits.`
+        );
+        ambiguous_anchor_warned = true;
+      }
+    }
+  }
+  const modify_edits = edits.filter(
+    (e) => e.type === "modify"
+  );
+  const kept_modifies = new Set(_drop_image_marker_hunks(modify_edits, warnings));
+  const final_edits = edits.filter(
+    (e) => e.type !== "modify" || kept_modifies.has(e)
+  );
+  return { edits: final_edits, warnings };
+}
 function create_unified_diff(original_text, modified_text, context_lines = 3) {
   const dmp = new diff_match_patch.diff_match_patch();
   dmp.Diff_Timeout = 2;
@@ -2621,6 +3239,30 @@ function _strip_balanced_markers(text) {
 function _replace_smart_quotes(text) {
   return text.replace(/“/g, '"').replace(/”/g, '"').replace(/‘/g, "'").replace(/’/g, "'");
 }
+function _strip_markdown_for_matching(text) {
+  const result = [];
+  const position_map = [];
+  let i = 0;
+  while (i < text.length) {
+    const pair = text.substring(i, i + 2);
+    if (i < text.length - 1 && (pair === "**" || pair === "__")) {
+      i += 2;
+      continue;
+    }
+    if (text[i] === "*" || text[i] === "_") {
+      const prev_char = i > 0 ? text[i - 1] : " ";
+      const next_char = i < text.length - 1 ? text[i + 1] : " ";
+      if ([" ", "\n", "	"].includes(prev_char) || [" ", "\n", "	"].includes(next_char)) {
+        i += 1;
+        continue;
+      }
+    }
+    position_map.push(i);
+    result.push(text[i]);
+    i += 1;
+  }
+  return [result.join(""), position_map];
+}
 function _find_safe_boundaries(text, start, end) {
   let new_start = start;
   let new_end = end;
@@ -2724,31 +3366,63 @@ function _make_fuzzy_regex(target_text) {
   if (remaining) parts.push(escapeRegExp(remaining));
   return parts.join("");
 }
-function _find_match_in_text(text, target) {
-  if (!target) return [-1, -1];
-  let idx = text.indexOf(target);
-  if (idx !== -1) return _find_safe_boundaries(text, idx, idx + target.length);
+function _find_all_matches_in_text(text, target, is_regex = false) {
+  if (!target) return [];
+  if (is_regex) {
+    try {
+      return userFindAllMatches(target, text).map((m) => [m.start, m.end]);
+    } catch (e) {
+      if (e instanceof RegexTimeoutError) throw e;
+      return [];
+    }
+  }
+  const findAllLiteral = (haystack, needle) => {
+    const out = [];
+    let from = 0;
+    while (true) {
+      const idx = haystack.indexOf(needle, from);
+      if (idx === -1) break;
+      out.push([idx, idx + needle.length]);
+      from = idx + needle.length;
+    }
+    return out;
+  };
+  let spans = findAllLiteral(text, target);
+  if (spans.length > 0) {
+    return spans.map(([s, e]) => _find_safe_boundaries(text, s, e));
+  }
   const norm_text = _replace_smart_quotes(text);
   const norm_target = _replace_smart_quotes(target);
-  idx = norm_text.indexOf(norm_target);
-  if (idx !== -1)
-    return _find_safe_boundaries(text, idx, idx + norm_target.length);
+  spans = findAllLiteral(norm_text, norm_target);
+  if (spans.length > 0) {
+    return spans.map(([s, e]) => _find_safe_boundaries(text, s, e));
+  }
+  const [stripped_text, pos_map] = _strip_markdown_for_matching(norm_text);
+  const [stripped_target] = _strip_markdown_for_matching(norm_target);
+  if (stripped_target && (stripped_text !== norm_text || stripped_target !== norm_target)) {
+    const results = [];
+    for (const [p_start, p_end] of findAllLiteral(stripped_text, stripped_target)) {
+      const raw_start = pos_map[p_start];
+      const raw_end = pos_map[p_end - 1] + 1;
+      results.push(_find_safe_boundaries(text, raw_start, raw_end));
+    }
+    if (results.length > 0) return results;
+  }
   try {
-    const pattern = new RegExp(_make_fuzzy_regex(target));
-    const match = pattern.exec(text);
-    if (match) {
-      const raw_start = match.index;
-      const raw_end = match.index + match[0].length;
+    const pattern = new RegExp(_make_fuzzy_regex(target), "g");
+    const results = [];
+    for (const match of text.matchAll(pattern)) {
       const [refined_start, refined_end] = _refine_match_boundaries(
         text,
-        raw_start,
-        raw_end
+        match.index,
+        match.index + match[0].length
       );
-      return _find_safe_boundaries(text, refined_start, refined_end);
+      results.push(_find_safe_boundaries(text, refined_start, refined_end));
     }
+    if (results.length > 0) return results;
   } catch (e) {
   }
-  return [-1, -1];
+  return [];
 }
 function _build_critic_markup(target_text, new_text, comment, edit_index, include_index, highlight_only) {
   const parts = [];
@@ -2780,19 +3454,55 @@ function _build_critic_markup(target_text, new_text, comment, edit_index, includ
   }
   return parts.join("");
 }
-function apply_edits_to_markdown(markdown_text, edits, include_index = false, highlight_only = false) {
+function apply_edits_to_markdown(markdown_text, edits, include_index = false, highlight_only = false, edit_reports) {
   if (!edits || edits.length === 0) return markdown_text;
+  const _report = (idx, status, error = null, occurrences = 0) => {
+    if (edit_reports) edit_reports.push({ index: idx, status, error, occurrences });
+  };
   const matched_edits = [];
   for (let idx = 0; idx < edits.length; idx++) {
     const edit = edits[idx];
     const target = edit.target_text || "";
+    const match_mode = edit.match_mode || "strict";
+    const is_regex = Boolean(edit.regex);
     if (!target) {
+      _report(
+        idx,
+        "failed",
+        `- Edit ${idx + 1} Failed: target_text is empty. Pure insertions are expressed as a replacement: put the text immediately around the insertion point in target_text and repeat it (plus the new text) in new_text.`
+      );
+      continue;
+    }
+    let spans;
+    try {
+      spans = _find_all_matches_in_text(markdown_text, target, is_regex);
+    } catch (e) {
+      if (!(e instanceof RegexTimeoutError)) throw e;
+      _report(idx, "failed", `- Edit ${idx + 1} Failed: ${e.message}`);
+      continue;
+    }
+    if (spans.length === 0) {
+      _report(
+        idx,
+        "failed",
+        `- Edit ${idx + 1} Failed: Target text not found in document:
+  "${target.substring(0, 80)}"`
+      );
       continue;
     }
-    const [start, end] = _find_match_in_text(markdown_text, target);
-    if (start === -1) continue;
-    const actual_matched_text = markdown_text.substring(start, end);
-    matched_edits.push([start, end, actual_matched_text, edit, idx]);
+    if (spans.length > 1 && match_mode === "strict") {
+      _report(
+        idx,
+        "failed",
+        format_ambiguity_error(idx + 1, target, markdown_text, spans)
+      );
+      continue;
+    }
+    const selected = match_mode === "strict" || match_mode === "first" ? spans.slice(0, 1) : spans;
+    for (const [start, end] of selected) {
+      matched_edits.push([start, end, markdown_text.substring(start, end), edit, idx]);
+    }
+    _report(idx, "applied", null, selected.length);
   }
   const matched_edits_filtered = [];
   const occupied_ranges = [];
@@ -2802,6 +3512,16 @@ function apply_edits_to_markdown(markdown_text, edits, include_index = false, hi
     for (const [occ_start, occ_end] of occupied_ranges) {
       if (start < occ_end && end > occ_start) {
         overlaps = true;
+        if (edit_reports) {
+          const msg = `- Edit ${orig_idx + 1} Failed: overlaps with a previously matched edit.`;
+          for (const r of edit_reports) {
+            if (r.index === orig_idx) {
+              r.status = "failed";
+              r.error = msg;
+              r.occurrences = 0;
+            }
+          }
+        }
         break;
       }
     }
@@ -2831,7 +3551,9 @@ function apply_edits_to_markdown(markdown_text, edits, include_index = false, hi
       isolated_target,
       isolated_new,
       edit.comment,
-      orig_idx,
+      // 1-based, matching apply's "Edit N" reports and batch validation
+      // errors (QA 2026-07-17 F10; mirrors Python).
+      orig_idx + 1,
       include_index,
       highlight_only
     );
@@ -2976,12 +3698,36 @@ function sequential_context_hint(applied_so_far) {
   Note: ${applied_so_far} earlier edit(s) in this batch were already applied. Batches apply sequentially \u2014 each edit must target the document text as it reads AFTER the preceding edits (e.g. target the replacement text an earlier edit introduced, not the original wording).`;
 }
 var TRANSACTIONAL_NOT_APPLIED_ERROR = "Not applied: the batch is transactional and other edits failed validation (see their errors). Fix or remove those edits and re-run.";
+var XML_ILLEGAL_CHARS_RE = /[\x00-\x08\x0b\x0c\x0e-\x1f]/g;
+function describe_illegal_control_chars(text) {
+  if (!text) return null;
+  const found = text.match(XML_ILLEGAL_CHARS_RE);
+  if (!found) return null;
+  const codes = Array.from(new Set(found.map((c) => `0x${c.charCodeAt(0).toString(16).padStart(2, "0")}`))).sort();
+  return codes.join(", ");
+}
 function validate_edit_strings(edits, index_offset = 0) {
   const errors = [];
   for (let i = 0; i < edits.length; i++) {
     const edit = edits[i];
     const t_text = edit.target_text || "";
     const n_text = edit.new_text || "";
+    const checked_fields = [
+      ["target_text", t_text],
+      ["new_text", n_text]
+    ];
+    if (edit.comment) checked_fields.push(["comment", edit.comment]);
+    (edit.cells || []).forEach((cell, cell_idx) => {
+      checked_fields.push([`cells[${cell_idx}]`, cell || ""]);
+    });
+    for (const [field_name, field_value] of checked_fields) {
+      const described = describe_illegal_control_chars(field_value);
+      if (described) {
+        errors.push(
+          `- Edit ${i + 1 + index_offset} Failed: \`${field_name}\` contains control character(s) (${described}) that cannot be stored in a DOCX. Remove them and re-submit.`
+        );
+      }
+    }
     if (n_text.includes("{++") || n_text.includes("{--") || n_text.includes("{>>") || n_text.includes("{==")) {
       errors.push(
         `- Edit ${i + 1 + index_offset} Failed: Do not manually write CriticMarkup tags ({++, {--, {>>, {==) in \`new_text\`. The engine handles redlining automatically. To add a comment, use the \`comment\` parameter.`
@@ -3044,6 +3790,15 @@ function validate_edit_strings(edits, index_offset = 0) {
         }
       }
     }
+    if (t_text.includes("docx-image:") || n_text.includes("docx-image:")) {
+      const t_imgs = (t_text.match(/!\[[^\]]*\]\(docx-image:[^)]*\)/g) || []).sort();
+      const n_imgs = (n_text.match(/!\[[^\]]*\]\(docx-image:[^)]*\)/g) || []).sort();
+      if (JSON.stringify(t_imgs) !== JSON.stringify(n_imgs)) {
+        errors.push(
+          `- Edit ${i + 1 + index_offset} Failed: image markers (![alt](docx-image:N)) are read-only projections of embedded images. They cannot be inserted, altered, or removed via text replacement \u2014 edit the text around the image instead.`
+        );
+      }
+    }
     if (t_text.includes("{#") || n_text.includes("{#")) {
       const t_anchors = t_text.match(/\{#[^\}]+\}/g) || [];
       const n_anchors = n_text.match(/\{#[^\}]+\}/g) || [];
@@ -3288,8 +4043,8 @@ var RedlineEngine = class _RedlineEngine {
    * Snapshots the document text around a resolved edit BEFORE anything is
    * applied. Previews rendered after the batch mutates the DOM cannot slice
    * full_text at the stored offsets: applied edits shift offsets and inject
-   * tracked-change markup, which produced garbled previews mixing unrelated
-   * edits and internal scaffolding (QA H1).
+   * tracked-change markup, garbling previews with unrelated edits and
+   * internal scaffolding (QA H1).
    */
   _capture_preview_context(edit) {
     if (edit.type !== "modify") return;
@@ -3390,8 +4145,8 @@ var RedlineEngine = class _RedlineEngine {
   }
   /**
    * The "new text" a batch report should show for an edit. InsertTableRow has
-   * no new_text field — surface its cell contents instead of the misleading
-   * empty string the report used to print (QA M4).
+   * no new_text field — surface its cell contents rather than a misleading
+   * empty string (QA M4).
    */
   static _report_new_text(edit) {
     if (edit && edit.type === "insert_row" && Array.isArray(edit.cells)) {
@@ -3767,6 +4522,43 @@ var RedlineEngine = class _RedlineEngine {
       element.setAttribute("xml:space", "preserve");
     }
   }
+  /**
+   * Walks `element` to its XML root element. Word (and LibreOffice, which
+   * refuses to LOAD such files) only supports comment ranges in the main
+   * document story ("w:document") — never in headers, footers, footnotes or
+   * endnotes (QA 2026-07-18 H4/C1).
+   */
+  _comment_anchor_in_main_story(element) {
+    let root = element;
+    while (root.parentNode && root.parentNode.nodeType === 1) {
+      root = root.parentNode;
+    }
+    return root.tagName === "w:document";
+  }
+  /**
+   * When the anchor lives outside the main document story, records a
+   * user-visible warning and returns true (caller must skip the comment).
+   * The tracked change itself still applies — only the bubble is dropped.
+   */
+  _skip_comment_outside_main_story(element, text) {
+    if (this._comment_anchor_in_main_story(element)) return false;
+    let root = element;
+    while (root.parentNode && root.parentNode.nodeType === 1) {
+      root = root.parentNode;
+    }
+    const story = {
+      "w:ftr": "footer",
+      "w:hdr": "header",
+      "w:footnotes": "footnote",
+      "w:endnotes": "endnote"
+    }[root.tagName] || "non-body";
+    const msg = `- Warning: the comment "${text.substring(0, 60)}" was NOT attached: Word does not support comments inside a ${story} part, and writing one produces a document other applications cannot open. The tracked change itself was applied.`;
+    this.skipped_details.push(msg);
+    console.error(
+      `Comment anchor outside main story; comment dropped (story=${story})`
+    );
+    return true;
+  }
   /**
    * Attaches a comment that wraps a contiguous range within a single paragraph.
    * start_element and end_element must both be direct children of parent_element
@@ -3775,6 +4567,8 @@ var RedlineEngine = class _RedlineEngine {
    */
   _attach_comment(parent_element, start_element, end_element, text) {
     if (!text) return;
+    if (!parent_element || !start_element || !end_element) return;
+    if (this._skip_comment_outside_main_story(parent_element, text)) return;
     const comment_id = this.comments_manager.addComment(this.author, text);
     const xmlDoc = parent_element.ownerDocument;
     const range_start = xmlDoc.createElement("w:commentRangeStart");
@@ -3808,6 +4602,9 @@ var RedlineEngine = class _RedlineEngine {
    */
   _attach_comment_spanning(start_p, start_el, end_p, end_el, text) {
     if (!text) return;
+    if (!start_p || !end_p) return;
+    if (this._skip_comment_outside_main_story(start_p, text) || this._skip_comment_outside_main_story(end_p, text))
+      return;
     const comment_id = this.comments_manager.addComment(this.author, text);
     const xmlDocStart = start_p.ownerDocument;
     const xmlDocEnd = end_p.ownerDocument;
@@ -4419,6 +5216,51 @@ var RedlineEngine = class _RedlineEngine {
           pfx,
           (edit.new_text || "").length - sfx
         );
+        const multi_part_doc = target_mapper.part_ranges.filter((r) => r[1] > r[0]).length > 1;
+        const raw_span_parts = multi_part_doc ? Array.from(
+          new Set(
+            target_mapper.spans.filter(
+              (s) => s.run !== null && s.end > m_start && s.start < m_start + m_len
+            ).map((s) => s.part_index)
+          )
+        ).sort((a, b) => a - b) : [];
+        if (raw_span_parts.length > 1) {
+          const kinds = raw_span_parts.map((pi) => target_mapper.part_kind_of(pi) || "?").join(" \u2192 ");
+          errors.push(
+            `- Edit ${i + 1 + index_offset} Failed: target_text spans a structural document-part boundary (${kinds}). Headers, body, footers and footnotes are separate Word parts \u2014 an edit cannot cross between them. Anchor the edit on text within a single part (split it into one edit per part if both sides must change).`
+          );
+        }
+        const eff_start = m_start + pfx;
+        const eff_end = m_start + m_len - sfx;
+        if (eff_end > eff_start) {
+          const overlapping = target_mapper.spans.filter(
+            (s) => s.end > eff_start && s.start < eff_end && (s.run !== null || s.text.trim() !== "")
+          );
+          if (overlapping.some((s) => s.is_image_marker)) {
+            errors.push(
+              `- Edit ${i + 1 + index_offset} Failed: the target overlaps a read-only image marker (![alt](docx-image:N)). Images cannot be edited or removed via text replacement \u2014 target the text around the image instead.`
+            );
+          }
+        }
+        if (edit.comment && (edit.new_text || "") === (edit.target_text || "")) {
+          const kind_here = target_mapper.part_kind_at(m_start);
+          if (kind_here !== null && kind_here !== "body") {
+            errors.push(
+              `- Edit ${i + 1 + index_offset} Failed: comments cannot be anchored inside a ${kind_here} part \u2014 Word only supports comments in the main document body. Comment on the related body text instead.`
+            );
+          }
+        }
+        if (_RedlineEngine._introduces_table_row_text(
+          target_mapper,
+          m_start,
+          m_len,
+          final_target,
+          final_new
+        )) {
+          errors.push(
+            `- Edit ${i + 1 + index_offset} Failed: new_text introduces a pipe-delimited row line inside a table. Text replacement cannot create table rows \u2014 use the structured 'insert_row' operation instead (e.g. {"type": "insert_row", "target_text": "<anchor row text>", "cells": ["...", "..."]}).`
+          );
+        }
         if (final_target.includes("\n\n")) {
           const balanced = matched.split("\n\n").length === (edit.new_text || "").split("\n\n").length;
           if (!balanced) {
@@ -4515,6 +5357,19 @@ var RedlineEngine = class _RedlineEngine {
    * [start, start+length) in `mapper`, or null if that text is not inside a
    * table row.
    */
+  /**
+   * True when a replacement anchored in a table would ADD line-separated
+   * pipe-delimited content — the text shape of a table row. Writing that
+   * into a cell renders a fake row inside one cell while the real grid
+   * stays unchanged (QA 2026-07-18 C2); such edits must use insert_row.
+   */
+  static _introduces_table_row_text(mapper, start, length, final_target, final_new) {
+    if (!final_new.includes("\n") || !final_new.includes(" | ")) return false;
+    const new_pipe_lines = final_new.split("\n").filter((line) => line.includes(" | ")).length;
+    const old_pipe_lines = final_target.split("\n").filter((line) => line.includes(" | ")).length;
+    if (new_pipe_lines <= old_pipe_lines) return false;
+    return _RedlineEngine._column_count_at(mapper, start, Math.max(length, 1)) !== null;
+  }
   static _column_count_at(mapper, start, length) {
     for (const s of mapper.spans) {
       if (s.run === null || s.end <= start || s.start >= start + length) {
@@ -4676,7 +5531,13 @@ var RedlineEngine = class _RedlineEngine {
         const reports_by_input = new Array(edits.length);
         const validation_failed_idx = /* @__PURE__ */ new Set();
         for (const { edit, i } of ordered_edits) {
-          let single_errors = this.validate_edits([edit], i);
+          let single_errors;
+          try {
+            single_errors = this.validate_edits([edit], i);
+          } catch (e) {
+            if (!(e instanceof RegexTimeoutError)) throw e;
+            single_errors = [`- Edit ${i + 1} Failed: ${e.message}`];
+          }
           if (single_errors.length > 0) {
             if (applied_edits > 0) {
               const hint = sequential_context_hint(applied_edits);
@@ -4761,7 +5622,13 @@ var RedlineEngine = class _RedlineEngine {
           const sequential_errors = [];
           let applied_so_far = 0;
           for (const { edit, i } of ordered_edits) {
-            let single_errors = this.validate_edits([edit], i);
+            let single_errors;
+            try {
+              single_errors = this.validate_edits([edit], i);
+            } catch (e) {
+              if (!(e instanceof RegexTimeoutError)) throw e;
+              single_errors = [`- Edit ${i + 1} Failed: ${e.message}`];
+            }
             if (single_errors.length > 0) {
               if (applied_so_far > 0) {
                 const hint = sequential_context_hint(applied_so_far);
@@ -4875,7 +5742,18 @@ var RedlineEngine = class _RedlineEngine {
           edit._error_msg = msg;
         }
       } else {
-        const resolved = this._pre_resolve_heuristic_edit(edit);
+        let resolved;
+        try {
+          resolved = this._pre_resolve_heuristic_edit(edit);
+        } catch (e) {
+          if (!(e instanceof RegexTimeoutError)) throw e;
+          skipped++;
+          edit._applied_status = false;
+          const msg = `- Failed to apply edit targeting: '${(edit.target_text || "").substring(0, 40)}...' (${e.message})`;
+          this.skipped_details.push(msg);
+          edit._error_msg = msg;
+          continue;
+        }
         if (resolved) {
           if (Array.isArray(resolved)) {
             for (const r of resolved) {
@@ -4920,7 +5798,7 @@ var RedlineEngine = class _RedlineEngine {
     const counted_split_groups = /* @__PURE__ */ new Set();
     for (const [edit, orig_new] of resolved_edits) {
       const start = edit._resolved_start_idx || 0;
-      const end = start + (edit.target_text ? edit.target_text.length : 0);
+      const end = edit.type === "insert_row" ? start : start + (edit.target_text ? edit.target_text.length : 0);
       const overlaps = occupied_ranges.some(
         ([occ_start, occ_end]) => start < occ_end && end > occ_start
       );
@@ -5034,6 +5912,16 @@ var RedlineEngine = class _RedlineEngine {
         );
         continue;
       }
+      const dup_authors = Array.from(
+        new Set(all_nodes.map((n) => n.getAttribute("w:author") || "Unknown"))
+      ).sort();
+      if (dup_authors.length > 1) {
+        skipped++;
+        this.skipped_details.push(
+          `- Failed to apply action: ${type} on Chg:${target_id} is ambiguous. The document contains ${all_nodes.length} tracked-change elements sharing w:id=${target_id} from different authors (${dup_authors.join(", ")}) \u2014 duplicate revision IDs produced outside this engine (e.g. by a document merge or copy-paste). Acting on this ID would resolve all of them at once. Resolve these changes individually in Word, or apply the intended outcome as an explicit text edit instead.`
+        );
+        continue;
+      }
       for (const node of all_nodes) {
         const is_ins = node.tagName === "w:ins";
         const parent_tag = node.parentNode ? node.parentNode.tagName : "";
@@ -5600,13 +6488,49 @@ var RedlineEngine = class _RedlineEngine {
       return true;
     }
     if (op === "INSERTION") {
-      const [anchor_run, anchor_para] = active_mapper.get_insertion_anchor(
-        start_idx,
-        rebuild_map
-      );
+      let final_new_text = edit.new_text || "";
+      let boundary_anchor = null;
+      const boundary = typeof active_mapper.part_boundary_at === "function" ? active_mapper.part_boundary_at(start_idx) : null;
+      const is_machine_pure_insertion = !edit.target_text && (edit._parent_edit_ref === void 0 || edit._parent_edit_ref === null);
+      if (boundary !== null && is_machine_pure_insertion) {
+        const [prev_i, next_i] = boundary;
+        const prev_kind = active_mapper.part_kind_of(prev_i);
+        const next_kind = active_mapper.part_kind_of(next_i);
+        if (prev_kind === "body" && next_kind !== "body") {
+          const real_before = active_mapper.spans.filter(
+            (s) => s.run !== null && s.part_index === prev_i
+          );
+          if (real_before.length > 0) {
+            boundary_anchor = real_before[real_before.length - 1];
+          }
+        }
+      }
+      let anchor_run;
+      let anchor_para;
+      if (boundary_anchor !== null) {
+        anchor_run = boundary_anchor.run;
+        anchor_para = boundary_anchor.paragraph;
+        if (!final_new_text.startsWith("\n")) {
+          final_new_text = "\n\n" + final_new_text;
+        }
+      } else {
+        [anchor_run, anchor_para] = active_mapper.get_insertion_anchor(
+          start_idx,
+          rebuild_map
+        );
+      }
       if (!anchor_run && !anchor_para) return false;
-      const _bug233_new = edit.new_text || "";
-      const _bug233_trailing_break = /\n\s*$/.test(_bug233_new);
+      if (_RedlineEngine._introduces_table_row_text(
+        active_mapper,
+        start_idx,
+        1,
+        "",
+        final_new_text
+      )) {
+        return false;
+      }
+      const _bug233_new = final_new_text;
+      const _bug233_trailing_break = boundary_anchor === null && /\n\s*$/.test(_bug233_new);
       let _bug233_target_para = null;
       {
         const startingSpans = active_mapper.spans.filter(
@@ -5676,7 +6600,7 @@ var RedlineEngine = class _RedlineEngine {
         }
       }
       const result = this._track_insert_multiline(
-        edit.new_text || "",
+        final_new_text,
         anchor_run,
         anchor_para,
         ins_id
@@ -5765,6 +6689,20 @@ var RedlineEngine = class _RedlineEngine {
       }
       return true;
     }
+    if ((op === "DELETION" || op === "MODIFICATION") && length && active_mapper.part_ranges.filter((r) => r[1] > r[0]).length > 1) {
+      const crossed_parts = /* @__PURE__ */ new Set();
+      for (const s of active_mapper.spans) {
+        if (s.run !== null && s.end > start_idx && s.start < start_idx + length) {
+          crossed_parts.add(s.part_index);
+        }
+      }
+      if (crossed_parts.size > 1) {
+        console.error(
+          `Refusing edit that spans OPC part boundary (start=${start_idx}, parts=${Array.from(crossed_parts).sort().join(",")})`
+        );
+        return false;
+      }
+    }
     const target_runs = active_mapper.find_target_runs_by_index(
       start_idx,
       length,
@@ -6349,6 +7287,27 @@ function scrub_doc_properties(doc) {
         c.textContent = "";
       }
     });
+    const titles = findDescendantsByLocalName(corePart._element, "title");
+    titles.forEach((c) => {
+      if (c.textContent) {
+        lines.push(`Title kept (review manually): "${c.textContent}"`);
+      }
+    });
+    const leakFields = [
+      ["category", "Category"],
+      ["keywords", "Keywords"],
+      ["subject", "Subject"],
+      ["contentStatus", "Content status"],
+      ["description", "Description/comments"]
+    ];
+    for (const [local, label] of leakFields) {
+      findDescendantsByLocalName(corePart._element, local).forEach((c) => {
+        if (c.textContent) {
+          lines.push(`${label}: ${c.textContent}`);
+          c.textContent = "";
+        }
+      });
+    }
     const revisions = findDescendantsByLocalName(corePart._element, "revision");
     revisions.forEach((c) => {
       if (c.textContent && parseInt(c.textContent) > 1) {
@@ -6434,6 +7393,35 @@ function strip_image_alt_text(doc) {
   }
   return count ? [`Image alt text: ${count} auto-generated descriptions removed`] : [];
 }
+function detect_watermarks(doc) {
+  const warnings = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const part of doc.pkg.parts) {
+    const name = String(part.partname);
+    let location;
+    if (name.startsWith("/word/header")) location = "header";
+    else if (name.startsWith("/word/footer")) location = "footer";
+    else if (name === "/word/document.xml") location = "body";
+    else continue;
+    let textpaths;
+    try {
+      textpaths = findDescendantsByLocalName(part._element, "textpath");
+    } catch {
+      continue;
+    }
+    for (const tp of textpaths) {
+      const text = (tp.getAttribute("string") || "").trim();
+      const key = `${location}${text}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      const label = text ? `"${_truncate(text, 60)}"` : "(no text)";
+      warnings.push(
+        `Watermark-like text object in ${location}: ${label} \u2014 NOT removed. It remains in the document package and may render in other applications; review and remove it in Word if it must not reach the counterparty.`
+      );
+    }
+  }
+  return warnings;
+}
 function audit_hyperlinks(doc) {
   const internal = ["sharepoint.com", "onedrive.com", ".internal", "intranet", "localhost", "10.", "192.168.", "172.16."];
   const warnings = [];
@@ -6486,25 +7474,53 @@ function _get_paragraph_text(p) {
   }
   return text;
 }
+var _TERM_BODY = "[A-Z][A-Za-z0-9\\s\\-&'\u2019]{1,60}";
+var _LEADING_TERM_RE = new RegExp(
+  `^(?:[\\d.\\-()a-zA-Z]+\\s*)?["\u201C](${_TERM_BODY})["\u201D]`,
+  "d"
+);
+var _SENTENCE_TERM_RE = new RegExp(
+  `(?<=[.;:!?])\\s+(?:[\\d.\\-()a-zA-Z]+\\s+)?["\u201C](${_TERM_BODY})["\u201D]`,
+  "dg"
+);
+var _INLINE_TERM_RE = new RegExp(
+  `\\([^)]*?["\u201C](${_TERM_BODY})["\u201D][^)]*?\\)`,
+  "dg"
+);
+function extract_terms_from_paragraph(text) {
+  const found = [];
+  const leading = _LEADING_TERM_RE.exec(text);
+  if (leading && leading.indices && leading.indices[1]) {
+    found.push([leading.indices[1][0], leading[1].trim()]);
+  }
+  for (const m of text.matchAll(_SENTENCE_TERM_RE)) {
+    const indices = m.indices;
+    if (indices && indices[1]) found.push([indices[1][0], m[1].trim()]);
+  }
+  for (const m of text.matchAll(_INLINE_TERM_RE)) {
+    const indices = m.indices;
+    if (indices && indices[1]) found.push([indices[1][0], m[1].trim()]);
+  }
+  const terms = [];
+  const seen_positions = /* @__PURE__ */ new Set();
+  found.sort((a, b) => a[0] - b[0]);
+  for (const [pos, term] of found) {
+    if (seen_positions.has(pos)) continue;
+    seen_positions.add(pos);
+    terms.push(term);
+  }
+  return terms;
+}
 function extract_all_domain_metadata(doc, base_text) {
   const definitions = {};
   const duplicates = /* @__PURE__ */ new Set();
   const raw_anchors = {};
   const raw_references = [];
-  const leading_re = /^(?:[\d.\-()a-zA-Z]+\s*)?["“]([A-Z][A-Za-z0-9\s\-&'’]{1,60})["”]/;
-  const inline_re = /\([^)]*?["“]([A-Z][A-Za-z0-9\s\-&'’]{1,60})["”][^)]*?\)/g;
   for (const item of iter_block_items(doc)) {
     if (!(item instanceof Paragraph)) continue;
     const text = _get_paragraph_text(item).trim();
     if (!text) continue;
-    const extracted_terms = [];
-    const leading_match = text.match(leading_re);
-    if (leading_match) extracted_terms.push(leading_match[1].trim());
-    const inline_matches = text.matchAll(inline_re);
-    for (const m of inline_matches) {
-      extracted_terms.push(m[1].trim());
-    }
-    for (const term of extracted_terms) {
+    for (const term of extract_terms_from_paragraph(text)) {
       if (definitions[term]) duplicates.add(term);
       else definitions[term] = { count: 0 };
     }
@@ -6554,7 +7570,11 @@ function extract_all_domain_metadata(doc, base_text) {
     for (const term of def_keys) {
       if (definitions[term].count === 0) {
         delete definitions[term];
-        duplicates.delete(term);
+        if (!duplicates.has(term)) {
+          diagnostics.push(
+            `[Warning] Unused Definition: '${term}' is defined but never used.`
+          );
+        }
       }
     }
   }
@@ -6728,27 +7748,32 @@ function build_structural_appendix(doc, base_text) {
 }
 
 // src/ingest.ts
-async function extractTextFromBuffer(buffer, cleanView = false) {
+async function extractTextFromBuffer(buffer, cleanView = false, includeAppendix = true) {
   const doc = await DocumentObject.load(buffer);
-  return _extractTextFromDoc(doc, cleanView);
+  return _extractTextFromDoc(doc, cleanView, includeAppendix);
 }
-function _extractTextFromDoc(doc, cleanView = false, includeAppendix = true, return_paragraph_offsets = false) {
+function _extractTextFromDoc(doc, cleanView = false, includeAppendix = true, return_paragraph_offsets = false, return_structure = false) {
   const comments_map = extract_comments_data(doc.pkg);
   const full_text = [];
   const paragraph_offsets = /* @__PURE__ */ new Map();
+  const structure = return_structure ? { part_ranges: [], tables: [] } : null;
   let cursor = 0;
-  for (const part of iter_document_parts(doc)) {
+  for (const [part, part_kind] of iter_document_parts_with_kind(doc)) {
     const part_cursor = full_text.length > 0 ? cursor + 2 : cursor;
     const part_text = _extract_blocks(
       part,
       comments_map,
       cleanView,
       part_cursor,
-      return_paragraph_offsets ? paragraph_offsets : void 0
+      return_paragraph_offsets ? paragraph_offsets : void 0,
+      structure ? structure.tables : void 0
     );
     if (part_text) {
       if (full_text.length > 0) cursor += 2;
       full_text.push(part_text);
+      if (structure) {
+        structure.part_ranges.push([cursor, cursor + part_text.length, part_kind]);
+      }
       cursor += part_text.length;
     }
   }
@@ -6760,9 +7785,12 @@ function _extractTextFromDoc(doc, cleanView = false, includeAppendix = true, ret
   if (return_paragraph_offsets) {
     return { text: base_text, paragraph_offsets };
   }
+  if (structure) {
+    return { text: base_text, structure };
+  }
   return base_text;
 }
-function _extract_blocks(container, comments_map, cleanView, cursor, paragraph_offsets) {
+function _extract_blocks(container, comments_map, cleanView, cursor, paragraph_offsets, table_acc) {
   const part = container.part || container;
   const [style_cache, default_pstyle] = _get_style_cache(part);
   const blocks = [];
@@ -6816,17 +7844,23 @@ ${header}`;
       is_first_para = false;
       is_first_block = false;
     } else if (item instanceof Table) {
+      const geometry = table_acc ? { start: block_start, end: block_start, rows: [] } : null;
       const table_text = extract_table(
         item,
         comments_map,
         cleanView,
         block_start,
-        paragraph_offsets
+        paragraph_offsets,
+        geometry
       );
       if (table_text) {
         blocks.push(table_text);
         local_cursor = block_start + table_text.length;
         is_first_block = false;
+        if (geometry && table_acc) {
+          geometry.end = block_start + table_text.length;
+          table_acc.push(geometry);
+        }
       } else if (!is_first_block) {
         local_cursor -= 2;
       }
@@ -6835,7 +7869,7 @@ ${header}`;
   }
   return blocks.join("\n\n");
 }
-function extract_table(table, comments_map, cleanView, cursor, paragraph_offsets) {
+function extract_table(table, comments_map, cleanView, cursor, paragraph_offsets, geometry) {
   const rows_text = [];
   let rows_processed = 0;
   let local_cursor = cursor;
@@ -6881,6 +7915,13 @@ function extract_table(table, comments_map, cleanView, cursor, paragraph_offsets
     }
     rows_text.push(row_str);
     local_cursor = row_start + row_str.length;
+    if (geometry) {
+      geometry.rows.push({
+        start: row_start,
+        end: local_cursor,
+        cells: [...cell_texts]
+      });
+    }
     rows_processed++;
   }
   return rows_text.join("\n");
@@ -7032,7 +8073,12 @@ function build_paragraph_text(paragraph, comments_map, cleanView, style_cache, d
       else if (ev.type === "del_end") delete active_del[ev.id];
       else if (ev.type === "fmt_start") active_fmt[ev.id] = ev;
       else if (ev.type === "fmt_end") delete active_fmt[ev.id];
-      else if (ev.type === "footnote" || ev.type === "endnote") {
+      else if (ev.type === "image") {
+        if (!(cleanView && Object.keys(active_del).length > 0)) {
+          const alt = (ev.date || "image").replace(/\]/g, ")").replace(/\n/g, " ");
+          parts.push(`![${alt}](docx-image:${ev.id})`);
+        }
+      } else if (ev.type === "footnote" || ev.type === "endnote") {
         if (pending_text) {
           parts.push(
             `${current_wrappers[0]}${pending_text}${current_wrappers[1]}`
@@ -7834,6 +8880,7 @@ async function finalize_document(doc, options) {
   report.add_transform_lines(strip_image_alt_text(doc));
   const warnings = audit_hyperlinks(doc);
   for (const w of warnings) report.warnings.push(w);
+  for (const w of detect_watermarks(doc)) report.warnings.push(w);
   report.add_transform_lines(normalize_change_dates(doc));
   if (options.protection_mode === "read_only" || options.protection_mode === "encrypt") {
     if (options.protection_mode === "encrypt") {
@@ -7889,17 +8936,24 @@ export {
   DocumentMapper,
   DocumentObject,
   RedlineEngine,
+  RegexTimeoutError,
+  USER_PATTERN_TIMEOUT_MS,
   _extractTextFromDoc,
   apply_edits_to_markdown,
   create_unified_diff,
   create_word_patch_diff,
+  describe_illegal_control_chars,
   extractTextFromBuffer,
   extract_outline,
   finalize_document,
   generate_edits_from_text,
+  generate_structured_edits,
   identifyEngine,
   paginate,
   split_structural_appendix,
-  trim_common_context
+  trim_common_context,
+  userFindAllMatches,
+  userSearch,
+  validate_edit_strings
 };
 //# sourceMappingURL=index.js.map