@adeu/core 1.9.0 → 1.10.0

package/src/engine.ts

@@ -247,6 +247,42 @@ export class RedlineEngine {
     this.comments_manager = new CommentsManager(this.doc);
   }
 
+  private _check_punctuation_warning(target_text: string): string | null {
+    if (!target_text) return null;
+    if (target_text.includes("_") || target_text.includes("-")) {
+      return `Warning: target_text '${target_text}' contains tokenization-splitting punctuation ('_' or '-'). This can trigger mid-word splits in the diff engine. Consider using a longer plain-prose anchor.`;
+    }
+    return null;
+  }
+
+  private _build_edit_context_previews(edit: any): [string | null, string | null] {
+    if (edit.type !== "modify") return [null, null];
+    if (edit._resolved_proxy_edit) {
+      edit = edit._resolved_proxy_edit;
+    }
+    const start_idx = edit._resolved_start_idx;
+    if (start_idx === undefined || start_idx === null) return [null, null];
+    const target_text = edit.target_text || "";
+    const new_text = edit.new_text || "";
+    const length = target_text.length;
+    const active_mapper = edit._active_mapper_ref || this.mapper;
+    const full_text = active_mapper.full_text;
+    if (!full_text) return [null, null];
+
+    const before_start = Math.max(0, start_idx - 30);
+    const context_before = full_text.substring(before_start, start_idx);
+    const context_after = full_text.substring(start_idx + length, start_idx + length + 30);
+
+    const critic_markup = `${context_before}{--${target_text}--}{++${new_text}++}${context_after}`;
+
+    let clean_text = critic_markup;
+    clean_text = clean_text.replace(/\{>>.*?<<\}/gs, "");
+    clean_text = clean_text.replace(/\{--.*?--\}/gs, "");
+    clean_text = clean_text.replace(/\{\+\+(.*?)\+\+\}/gs, "$1");
+
+    return [critic_markup, clean_text];
+  }
+
   private _scan_existing_ids(): number {
     let maxId = 0;
     for (const tag of ["w:ins", "w:del"]) {
@@ -351,35 +387,99 @@ export class RedlineEngine {
       }
     }
 
-    // Final pass: remove any free-standing comments
-    const comment_ids = new Set<string>();
-    for (const tag of [
-      "w:commentRangeStart",
-      "w:commentRangeEnd",
-      "w:commentReference",
-    ]) {
-      for (const node of findAllDescendants(this.doc.element, tag)) {
-        const cid = node.getAttribute("w:id");
-        if (cid) comment_ids.add(cid);
+    // Final pass: completely eject all comments, anchors, and parts
+    for (const root_element of parts_to_process) {
+      for (const tag of ["w:commentRangeStart", "w:commentRangeEnd"]) {
+        for (const el of findAllDescendants(root_element, tag)) {
+          el.parentNode?.removeChild(el);
+        }
+      }
+
+      const refs = findAllDescendants(root_element, "w:commentReference");
+      for (const ref of refs) {
+        const parent = ref.parentNode as Element | null;
+        if (parent) {
+          if (parent.tagName === "w:r" || parent.tagName.endsWith(":r")) {
+            const nonRprChildren = Array.from(parent.childNodes).filter(
+              (c) => c.nodeType === 1 && (c as Element).tagName !== "w:rPr" && (c as Element).tagName !== "rPr"
+            );
+            if (nonRprChildren.length <= 1) {
+              parent.parentNode?.removeChild(parent);
+            } else {
+              parent.removeChild(ref);
+            }
+          } else {
+            parent.removeChild(ref);
+          }
+        }
       }
     }
 
-    const comments_part = this.doc.pkg.parts.find(
-      (p) =>
-        p.contentType ===
-        "application/vnd.openxmlformats-officedocument.wordprocessingml.comments+xml",
-    );
-    if (comments_part) {
-      for (const c of findAllDescendants(comments_part._element, "w:comment")) {
-        const cid = c.getAttribute("w:id");
-        if (cid) comment_ids.add(cid);
+    const pkg = this.doc.pkg;
+    const comment_partnames = new Set<string>();
+    for (const part of pkg.parts) {
+      if (part.partname.toLowerCase().includes("comments")) {
+        comment_partnames.add(part.partname);
+        const withSlash = part.partname.startsWith("/") ? part.partname : "/" + part.partname;
+        const withoutSlash = part.partname.startsWith("/") ? part.partname.substring(1) : part.partname;
+        comment_partnames.add(withSlash);
+        comment_partnames.add(withoutSlash);
       }
     }
 
-    for (const cid of comment_ids) {
-      this.comments_manager.deleteComment(cid);
+    if (comment_partnames.size > 0) {
+      // Sever relationships referencing comments
+      for (const part of pkg.parts) {
+        if (part.partname.endsWith(".rels")) {
+          const rels = findAllDescendants(part._element, "Relationship");
+          const toRemove: Element[] = [];
+          for (const rel of rels) {
+            const target = rel.getAttribute("Target") || "";
+            if (target.toLowerCase().includes("comments")) {
+              toRemove.push(rel);
+              
+              const sourcePath = part.partname.replace("/_rels/", "/").replace(".rels", "");
+              const sourcePart = pkg.getPartByPath(sourcePath);
+              if (sourcePart) {
+                const relId = rel.getAttribute("Id");
+                if (relId) sourcePart.rels.delete(relId);
+              }
+            }
+          }
+          for (const relEl of toRemove) {
+            relEl.parentNode?.removeChild(relEl);
+          }
+        }
+      }
+
+      // Remove overrides from [Content_Types].xml
+      const ctPart = pkg.getPartByPath("[Content_Types].xml");
+      if (ctPart) {
+        const overrides = findAllDescendants(ctPart._element, "Override");
+        const toRemove: Element[] = [];
+        for (const override of overrides) {
+          const partName = override.getAttribute("PartName") || "";
+          if (comment_partnames.has(partName) || partName.toLowerCase().includes("comments")) {
+            toRemove.push(override);
+          }
+        }
+        for (const overrideEl of toRemove) {
+          overrideEl.parentNode?.removeChild(overrideEl);
+        }
+      }
+
+      // Remove comment parts from pkg.parts
+      pkg.parts = pkg.parts.filter(p => !p.partname.toLowerCase().includes("comments"));
+
+      // Remove comment files from pkg.unzipped
+      for (const key of Object.keys(pkg.unzipped)) {
+        if (key.toLowerCase().includes("comments")) {
+          delete pkg.unzipped[key];
+        }
+      }
     }
   }
+
   private _getNextId(): string {
     this.current_id++;
     return this.current_id.toString();
@@ -505,7 +605,9 @@ export class RedlineEngine {
       end_p.appendChild(range_end);
       end_p.appendChild(ref_run);
     }
-  } /**
+  }
+
+  /**
    * Inserts `text` as one or more tracked paragraphs anchored relative to
    * either an existing run or a paragraph. Returns:
    *   { first_node, last_p, last_ins, used_block_mode }
@@ -734,8 +836,19 @@ export class RedlineEngine {
         const anchor_rPr = findChild(anchor_run._element, "w:rPr");
         if (anchor_rPr) {
           const clone = anchor_rPr.cloneNode(true) as Element;
-          // Strip vanish / strike to avoid invisible inserts.
-          for (const tag of ["w:vanish", "w:strike", "w:dstrike"]) {
+          // Strip vanish / strike to avoid invisible inserts, and emphasis
+          // (bold/italic) so inserted replacement text does not silently
+          // inherit the anchor run's character formatting (BUG-23-2). Explicit
+          // markdown emphasis is re-applied per-segment via _apply_run_props.
+          for (const tag of [
+            "w:vanish",
+            "w:strike",
+            "w:dstrike",
+            "w:i",
+            "w:iCs",
+            "w:b",
+            "w:bCs",
+          ]) {
             const found = findChild(clone, tag);
             if (found) clone.removeChild(found);
           }
@@ -750,6 +863,7 @@ export class RedlineEngine {
     }
     return ins;
   }
+
   private _parse_markdown_style(text: string): [string, string | null] {
     const stripped_text = text.trimStart();
 
@@ -855,6 +969,7 @@ export class RedlineEngine {
       }
     }
   }
+
   /**
    * Replaces (or creates) a paragraph's <w:pPr> with a single <w:pStyle> entry
    * pointing at `style_name`. Strips any existing pPr to avoid layering a new
@@ -884,6 +999,7 @@ export class RedlineEngine {
     // pPr is the first child of <w:p> per OOXML schema.
     p_element.insertBefore(pPr, p_element.firstChild);
   }
+
   private _anchor_reply_comment(parent_id: string, new_id: string) {
     const docEl = this.doc.part._element.ownerDocument!;
 
@@ -938,6 +1054,7 @@ export class RedlineEngine {
 
     insertAfter(ref_run, new_end);
   }
+
   private _clean_wrapping_comments(element: Element) {
     let first_node: Element = element;
     while (true) {
@@ -1046,6 +1163,7 @@ export class RedlineEngine {
       }
     }
   }
+
   public validate_edits(edits: any[]): string[] {
     const errors: string[] = [];
     if (!this.mapper.full_text) this.mapper["_build_map"]();
@@ -1066,6 +1184,24 @@ export class RedlineEngine {
         if (matches.length > 0) activeText = this.clean_mapper.full_text;
       }
 
+      // BUG-23-5: a copy of the target that lives entirely inside a tracked
+      // deletion (<w:del>) is not a live, editable occurrence and must not
+      // count toward ambiguity. Drop matches whose overlapping real text is
+      // exclusively deleted. Only applies to the raw mapper (the clean mapper
+      // already omits deleted text).
+      if (activeText === this.mapper.full_text && matches.length > 1) {
+        const liveMatches = matches.filter(([start, length]) => {
+          const realSpans = this.mapper.spans.filter(
+            (s) => s.run !== null && s.end > start && s.start < start + length,
+          );
+          if (realSpans.length === 0) return true; // virtual-only; keep
+          // Keep only if at least one overlapping real span is live (not
+          // part of a tracked deletion).
+          return realSpans.some((s) => !s.del_id);
+        });
+        if (liveMatches.length > 0) matches = liveMatches;
+      }
+
       if (matches.length === 0) {
         errors.push(
           `- Edit ${i + 1} Failed: Target text not found in document:\n  "${edit.target_text}"`,
@@ -1085,6 +1221,35 @@ export class RedlineEngine {
         );
       }
 
+      // BUG-23-4: when the effective (context-trimmed) target spans a
+      // paragraph boundary with real body text on BOTH sides, we must reject
+      // the modification to prevent silent corruption of the paragraph structure.
+      if (matches.length === 1) {
+        const [m_start, m_len] = matches[0];
+        const matched = activeText.substring(m_start, m_start + m_len);
+        const [pfx, sfx] = trim_common_context(matched, edit.new_text || "");
+        const t_end = matched.length - sfx;
+        const final_target = matched.substring(pfx, t_end);
+        const final_new = (edit.new_text || "").substring(pfx, (edit.new_text || "").length - sfx);
+        if (final_target.includes("\n\n")) {
+          if (final_new.includes("\n\n")) {
+            const parts = matched.split("\n\n");
+            if (parts.length >= 2 && parts[0].trim() !== "" && parts[parts.length - 1].trim() !== "") {
+              errors.push(
+                `- Edit ${i + 1} Failed: target_text spans a paragraph boundary with body text on both sides. The paragraph break is a structural element, not literal text, so it cannot be replaced as a single span without corrupting the document. Split this into one edit per paragraph.`,
+              );
+            }
+          } else {
+            const parts = final_target.split("\n\n");
+            if (parts.length >= 2 && parts[0].trim() !== "" && parts[parts.length - 1].trim() !== "") {
+              errors.push(
+                `- Edit ${i + 1} Failed: target_text spans a paragraph boundary with body text on both sides. The paragraph break is a structural element, not literal text, so it cannot be replaced as a single span without corrupting the document. Split this into one edit per paragraph.`,
+              );
+            }
+          }
+        }
+      }
+
       for (const [start, length] of matches) {
         const spans = this.mapper.spans.filter(
           (s) => s.end > start && s.start < start + length,
@@ -1111,6 +1276,7 @@ export class RedlineEngine {
     }
     return errors;
   }
+
   public validate_review_actions(actions: any[]): string[] {
     const errors: string[] = [];
     for (let i = 0; i < actions.length; i++) {
@@ -1151,7 +1317,35 @@ export class RedlineEngine {
     }
     return errors;
   }
-  public process_batch(changes: DocumentChange[]): any {
+
+  public process_batch(changes: DocumentChange[], dry_run: boolean = false): any {
+    if (dry_run) {
+      const baselines = new Map<any, Element>();
+      for (const part of this.doc.pkg.parts) {
+        if (part._element) {
+          baselines.set(part, part._element.cloneNode(true) as Element);
+        }
+      }
+      try {
+        return this._process_batch_internal(changes, true);
+      } finally {
+        for (const [part, originalEl] of baselines.entries()) {
+          const doc = part._element.ownerDocument;
+          if (doc && doc.documentElement) {
+            doc.replaceChild(originalEl, doc.documentElement);
+          }
+          part._element = originalEl;
+        }
+        this.mapper = new DocumentMapper(this.doc);
+        this.comments_manager = new CommentsManager(this.doc);
+        this.clean_mapper = null;
+      }
+    } else {
+      return this._process_batch_internal(changes, false);
+    }
+  }
+
+  private _process_batch_internal(changes: DocumentChange[], dry_run_mode: boolean = false): any {
     this.skipped_details = [];
     const actions = changes.filter((c) =>
       ["accept", "reject", "reply"].includes(c.type),
@@ -1160,37 +1354,124 @@ export class RedlineEngine {
       (c) => !["accept", "reject", "reply"].includes(c.type),
     );
 
-    const all_errors: string[] = [];
-
-    if (actions.length > 0) {
-      all_errors.push(...this.validate_review_actions(actions));
-    }
-    if (edits.length > 0) {
-      all_errors.push(...this.validate_edits(edits));
-    }
-
-    if (all_errors.length > 0) {
-      throw new BatchValidationError(all_errors);
+    // BUG-7: Unified single-pass validation in wet-run / standard mode
+    if (!dry_run_mode) {
+      const all_errors: string[] = [];
+      if (actions.length > 0) {
+        all_errors.push(...this.validate_review_actions(actions));
+      }
+      if (edits.length > 0) {
+        all_errors.push(...this.validate_edits(edits));
+      }
+      if (all_errors.length > 0) {
+        throw new BatchValidationError(all_errors);
+      }
+    } else {
+      if (actions.length > 0) {
+        const action_errors = this.validate_review_actions(actions);
+        if (action_errors.length > 0) {
+          throw new BatchValidationError(action_errors);
+        }
+      }
     }
 
-    let applied_actions = 0,
-      skipped_actions = 0;
+    let applied_actions = 0;
+    let skipped_actions = 0;
     if (actions.length > 0) {
       const res = this.apply_review_actions(actions);
       applied_actions = res[0];
       skipped_actions = res[1];
+      if (skipped_actions > 0) {
+        throw new BatchValidationError(this.skipped_details);
+      }
       if (applied_actions > 0) {
         this.mapper["_build_map"]();
         if (this.clean_mapper) this.clean_mapper["_build_map"]();
       }
     }
 
-    let applied_edits = 0,
-      skipped_edits = 0;
+    const edits_reports: any[] = [];
+    let applied_edits = 0;
+    let skipped_edits = 0;
+
     if (edits.length > 0) {
-      const res = this.apply_edits(edits as any[]);
-      applied_edits = res[0];
-      skipped_edits = res[1];
+      if (dry_run_mode) {
+        for (const edit of edits) {
+          const single_errors = this.validate_edits([edit]);
+          const warning = this._check_punctuation_warning((edit as any).target_text || "");
+          if (single_errors.length > 0) {
+            skipped_edits++;
+            edits_reports.push({
+              status: "failed",
+              target_text: (edit as any).target_text || "",
+              new_text: (edit as any).new_text || "",
+              warning: warning,
+              error: single_errors[0],
+              critic_markup: null,
+              clean_text: null,
+            });
+            continue;
+          }
+          const res = this.apply_edits([edit]);
+          const applied = res[0];
+          if (applied > 0) {
+            applied_edits++;
+            const previews = this._build_edit_context_previews(edit);
+            edits_reports.push({
+              status: "applied",
+              target_text: (edit as any).target_text || "",
+              new_text: (edit as any).new_text || "",
+              warning: warning,
+              error: null,
+              critic_markup: previews[0],
+              clean_text: previews[1],
+            });
+          } else {
+            skipped_edits++;
+            const error_msg = this.skipped_details.length > 0 ? this.skipped_details[this.skipped_details.length - 1] : "Failed to apply edit";
+            edits_reports.push({
+              status: "failed",
+              target_text: (edit as any).target_text || "",
+              new_text: (edit as any).new_text || "",
+              warning: warning,
+              error: error_msg,
+              critic_markup: null,
+              clean_text: null,
+            });
+          }
+        }
+      } else {
+        const errors = this.validate_edits(edits);
+        if (errors.length > 0) {
+          throw new BatchValidationError(errors);
+        }
+        const cloned_edits = edits.map(e => JSON.parse(JSON.stringify(e)));
+        const res = this.apply_edits(cloned_edits);
+        applied_edits = res[0];
+        skipped_edits = res[1];
+
+        for (const edit of cloned_edits) {
+          const success = (edit as any)._applied_status || false;
+          const error_msg = (edit as any)._error_msg || null;
+          const warning = this._check_punctuation_warning((edit as any).target_text || "");
+          let critic_markup = null;
+          let clean_text = null;
+          if (success) {
+            const previews = this._build_edit_context_previews(edit);
+            critic_markup = previews[0];
+            clean_text = previews[1];
+          }
+          edits_reports.push({
+            status: success ? "applied" : "failed",
+            target_text: (edit as any).target_text || "",
+            new_text: (edit as any).new_text || "",
+            warning: warning,
+            error: error_msg,
+            critic_markup: critic_markup,
+            clean_text: clean_text,
+          });
+        }
+      }
     }
 
     return {
@@ -1199,6 +1480,9 @@ export class RedlineEngine {
       edits_applied: applied_edits,
       edits_skipped: skipped_edits,
       skipped_details: this.skipped_details,
+      edits: edits_reports,
+      engine: "node",
+      version: "1.9.0",
     };
   }
 
@@ -1207,47 +1491,84 @@ export class RedlineEngine {
     let skipped = 0;
     const resolved_edits: [any, string | null][] = [];
 
+    for (const edit of edits) {
+      edit._applied_status = false;
+      edit._error_msg = null;
+    }
+
     for (const edit of edits) {
       if (
+        edit._resolved_start_idx !== undefined &&
+        edit._resolved_start_idx !== null
+      ) {
+        resolved_edits.push([edit, edit.new_text || null]);
+      } else if (
         edit._match_start_index !== undefined &&
         edit._match_start_index !== null
       ) {
+        edit._resolved_start_idx = edit._match_start_index;
         resolved_edits.push([edit, edit.new_text || null]);
       } else if (edit.type === "insert_row" || edit.type === "delete_row") {
-        const [idx] = this.mapper.find_match_index(edit.target_text);
-        if (idx !== -1) {
-          edit._match_start_index = idx;
+        let matches = this.mapper.find_all_match_indices(edit.target_text);
+        if (matches.length === 0) {
+          if (!this.clean_mapper) {
+            this.clean_mapper = new DocumentMapper(this.doc, true);
+          }
+          matches = this.clean_mapper.find_all_match_indices(edit.target_text);
+        }
+
+        if (matches.length > 0) {
+          edit._resolved_start_idx = matches[0][0];
           resolved_edits.push([edit, null]);
         } else {
           skipped++;
-          this.skipped_details.push(
-            `- Failed to locate row target: '${(edit.target_text || "").substring(0, 40)}...'`,
-          );
+          edit._applied_status = false;
+          const target_snippet = (edit.target_text || "").trim().substring(0, 40);
+          const msg = `- Failed to locate row target: '${target_snippet}...'`;
+          this.skipped_details.push(msg);
+          edit._error_msg = msg;
         }
       } else {
         const resolved = this._pre_resolve_heuristic_edit(edit);
         if (resolved) {
           if (Array.isArray(resolved)) {
-            for (const r of resolved) resolved_edits.push([r, r.new_text]);
+            for (const r of resolved) {
+              r._resolved_start_idx = r._match_start_index;
+              r._parent_edit_ref = edit;
+              if (edit._resolved_start_idx === undefined || edit._resolved_start_idx === null) {
+                edit._resolved_start_idx = r._resolved_start_idx;
+              }
+              if (!edit._resolved_proxy_edit) {
+                edit._resolved_proxy_edit = r;
+              }
+              resolved_edits.push([r, r.new_text]);
+            }
           } else {
+            resolved._resolved_start_idx = resolved._match_start_index;
+            resolved._parent_edit_ref = edit;
+            edit._resolved_start_idx = resolved._resolved_start_idx;
+            edit._resolved_proxy_edit = resolved;
             resolved_edits.push([resolved, (resolved as any).new_text]);
           }
         } else {
           skipped++;
-          this.skipped_details.push(
-            `- Failed to apply edit targeting: '${(edit.target_text || "insertion").substring(0, 40)}...'`,
-          );
+          edit._applied_status = false;
+          const display_text = edit.target_text || "insertion";
+          const target_snippet = display_text.trim().substring(0, 40);
+          const msg = `- Failed to apply edit targeting: '${target_snippet}...'`;
+          this.skipped_details.push(msg);
+          edit._error_msg = msg;
         }
       }
     }
 
     resolved_edits.sort(
-      (a, b) => (b[0]._match_start_index || 0) - (a[0]._match_start_index || 0),
+      (a, b) => (b[0]._resolved_start_idx || 0) - (a[0]._resolved_start_idx || 0),
     );
     const occupied_ranges: [number, number][] = [];
 
     for (const [edit, orig_new] of resolved_edits) {
-      const start = edit._match_start_index || 0;
+      const start = edit._resolved_start_idx || 0;
       const end = start + (edit.target_text ? edit.target_text.length : 0);
 
       const overlaps = occupied_ranges.some(
@@ -1255,9 +1576,17 @@ export class RedlineEngine {
       );
       if (overlaps) {
         skipped++;
-        this.skipped_details.push(
-          `- Skipped overlapping edit targeting: '${(edit.target_text || "insertion").substring(0, 40)}...'`,
-        );
+        const display_text = edit.target_text || "insertion";
+        const target_snippet = display_text.trim().substring(0, 40);
+        const msg = `- Skipped overlapping edit targeting: '${target_snippet}...'`;
+        this.skipped_details.push(msg);
+        edit._applied_status = false;
+        edit._error_msg = msg;
+        const parent = edit._parent_edit_ref;
+        if (parent) {
+          parent._applied_status = false;
+          parent._error_msg = msg;
+        }
         continue;
       }
 
@@ -1271,11 +1600,26 @@ export class RedlineEngine {
       if (success) {
         applied++;
         occupied_ranges.push([start, end]);
+        edit._applied_status = true;
+        const parent = edit._parent_edit_ref;
+        if (parent) {
+          parent._applied_status = true;
+        }
       } else {
         skipped++;
-        this.skipped_details.push(
-          `- Failed to apply edit targeting: '${(edit.target_text || "insertion").substring(0, 40)}...'`,
-        );
+        const display_text = edit.target_text || "insertion";
+        const target_snippet = display_text.trim().substring(0, 40);
+        const msg = `- Failed to apply edit targeting: '${target_snippet}...'`;
+        this.skipped_details.push(msg);
+        edit._applied_status = false;
+        edit._error_msg = msg;
+        const parent = edit._parent_edit_ref;
+        if (parent) {
+          if (!parent._applied_status) {
+            parent._applied_status = false;
+            parent._error_msg = msg;
+          }
+        }
       }
     }
 
@@ -1378,7 +1722,7 @@ export class RedlineEngine {
   }
 
   private _apply_table_edit(edit: any, rebuild_map: boolean): boolean {
-    const start_idx = edit._match_start_index || 0;
+    const start_idx = edit._resolved_start_idx !== undefined && edit._resolved_start_idx !== null ? edit._resolved_start_idx : (edit._match_start_index || 0);
     const [anchor_run, anchor_para] = this.mapper.get_insertion_anchor(
       start_idx,
       rebuild_map,
@@ -1427,10 +1771,33 @@ export class RedlineEngine {
     return false;
   }
 
+  /**
+   * Returns the first match of `target_text` in the raw mapper that is NOT
+   * entirely contained within a tracked deletion (<w:del>). Tracked-deleted
+   * copies are not live, editable text, so an edit must resolve to a live
+   * occurrence even when a dead copy appears earlier in the document
+   * (BUG-23-5). Falls back to the plain first match when no live copy is
+   * found (e.g. fuzzy/normalized matches the span filter cannot align).
+   */
+  private _first_live_match(target_text: string): [number, number] {
+    const all = this.mapper.find_all_match_indices(target_text);
+    if (all.length <= 1) {
+      return this.mapper.find_match_index(target_text);
+    }
+    for (const [start, length] of all) {
+      const realSpans = this.mapper.spans.filter(
+        (s) => s.run !== null && s.end > start && s.start < start + length,
+      );
+      if (realSpans.length === 0) return [start, length];
+      if (realSpans.some((s) => !s.del_id)) return [start, length];
+    }
+    return this.mapper.find_match_index(target_text);
+  }
+
   private _pre_resolve_heuristic_edit(edit: any): any {
     if (!edit.target_text) return null;
 
-    let [start_idx, match_len] = this.mapper.find_match_index(edit.target_text);
+    let [start_idx, match_len] = this._first_live_match(edit.target_text);
     let use_clean_map = false;
 
     if (start_idx === -1) {
@@ -1510,7 +1877,7 @@ export class RedlineEngine {
   ): boolean {
     let op = edit._internal_op;
     const active_mapper = edit._active_mapper_ref || this.mapper;
-    const start_idx = edit._match_start_index || 0;
+    const start_idx = edit._resolved_start_idx !== undefined && edit._resolved_start_idx !== null ? edit._resolved_start_idx : (edit._match_start_index || 0);
     const length = edit.target_text ? edit.target_text.length : 0;
 
     const del_id = ["DELETION", "MODIFICATION"].includes(op)
@@ -1576,6 +1943,88 @@ export class RedlineEngine {
       );
       if (!anchor_run && !anchor_para) return false;
 
+      // BUG-23-3: a prefix insertion whose new_text ends in a paragraph break
+      // (e.g. "Summary\n\n" inserted before "Conclusion") must become a NEW
+      // paragraph placed BEFORE the anchor paragraph, not inline text merged
+      // into a neighbouring paragraph. _track_insert_multiline drops the
+      // trailing break and inlines the remainder, which both loses the
+      // paragraph boundary and mis-orders the content. Handle this case here.
+      const _bug233_new = edit.new_text || "";
+      const _bug233_trailing_break = /\n\s*$/.test(_bug233_new);
+      let _bug233_target_para: Element | null = null;
+      {
+        const startingSpans = active_mapper.spans.filter(
+          (s: TextSpan) => s.paragraph !== null && s.start === start_idx,
+        );
+        if (startingSpans.length > 0 && startingSpans[0].paragraph) {
+          _bug233_target_para = startingSpans[0].paragraph._element;
+        }
+      }
+      if (
+        _bug233_trailing_break &&
+        _bug233_target_para &&
+        _bug233_target_para.parentNode
+      ) {
+        const body = _bug233_target_para.parentNode as Element;
+        const xmlDoc = this.doc.part._element.ownerDocument!;
+        const lines = _bug233_new.split(/[\r\n]+/).filter((l: string) => l !== "");
+        let firstNew: Element | null = null;
+        let lastNew: Element | null = null;
+        let lastIns: Element | null = null;
+        for (const raw_line of lines) {
+          const [clean_text, style_name] = this._parse_markdown_style(raw_line);
+          const new_p = xmlDoc.createElement("w:p");
+          if (style_name) {
+            this._set_paragraph_style(new_p, style_name);
+          } else {
+            const existing_pPr = findChild(_bug233_target_para, "w:pPr");
+            if (existing_pPr) new_p.appendChild(existing_pPr.cloneNode(true));
+          }
+          let pPr = findChild(new_p, "w:pPr");
+          if (!pPr) {
+            pPr = xmlDoc.createElement("w:pPr");
+            new_p.insertBefore(pPr, new_p.firstChild);
+          }
+          let rPr = findChild(pPr, "w:rPr");
+          if (!rPr) {
+            rPr = xmlDoc.createElement("w:rPr");
+            pPr.appendChild(rPr);
+          }
+          rPr.appendChild(this._create_track_change_tag("w:ins", "", ins_id!));
+          const content_ins = this._build_tracked_ins_for_line(
+            clean_text,
+            anchor_run,
+            ins_id!,
+            xmlDoc,
+          );
+          if (content_ins) new_p.appendChild(content_ins);
+          body.insertBefore(new_p, _bug233_target_para);
+          if (!firstNew) firstNew = new_p;
+          lastNew = new_p;
+          lastIns = content_ins;
+        }
+        if (firstNew) {
+          if (edit.comment && lastNew && lastIns) {
+            const ascend = (el: Element, p: Element): Element => {
+              let cur: Element = el;
+              while (cur.parentNode && cur.parentNode !== p)
+                cur = cur.parentNode as Element;
+              return cur;
+            };
+            const startIns =
+              findAllDescendants(firstNew, "w:ins")[0] || firstNew;
+            this._attach_comment_spanning(
+              firstNew,
+              ascend(startIns, firstNew),
+              lastNew,
+              ascend(lastIns, lastNew),
+              edit.comment,
+            );
+          }
+          return true;
+        }
+      }
+
       const result = this._track_insert_multiline(
         edit.new_text || "",
         anchor_run,