@adeu/core 1.9.0 → 1.10.1

package/src/engine.ts

@@ -247,6 +247,47 @@ 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"]) {
@@ -301,7 +342,7 @@ export class RedlineEngine {
             for (const tag of ["w:t", "w:tab", "w:br"]) {
               for (const child of findAllDescendants(p, tag)) {
                 if (tag === "w:t" && !child.textContent) continue;
-                
+
                 let is_deleted = false;
                 let curr = child.parentNode as Element | null;
                 while (curr && curr !== p) {
@@ -351,35 +392,113 @@ 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 +624,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 +855,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 +882,7 @@ export class RedlineEngine {
     }
     return ins;
   }
+
   private _parse_markdown_style(text: string): [string, string | null] {
     const stripped_text = text.trimStart();
 
@@ -855,6 +988,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 +1018,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 +1073,7 @@ export class RedlineEngine {
 
     insertAfter(ref_run, new_end);
   }
+
   private _clean_wrapping_comments(element: Element) {
     let first_node: Element = element;
     while (true) {
@@ -1046,6 +1182,7 @@ export class RedlineEngine {
       }
     }
   }
+
   public validate_edits(edits: any[]): string[] {
     const errors: string[] = [];
     if (!this.mapper.full_text) this.mapper["_build_map"]();
@@ -1066,6 +1203,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 +1240,46 @@ 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 +1306,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 +1347,41 @@ 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 +1390,131 @@ 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 +1523,9 @@ export class RedlineEngine {
       edits_applied: applied_edits,
       edits_skipped: skipped_edits,
       skipped_details: this.skipped_details,
+      edits: edits_reports,
+      engine: "node",
+      version: "1.10.0",
     };
   }
 
@@ -1207,47 +1534,90 @@ 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 +1625,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 +1649,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 +1771,11 @@ 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 +1824,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 +1930,11 @@ 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 +2000,90 @@ 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,
@@ -1620,7 +2128,9 @@ export class RedlineEngine {
           if (start_p) {
             let first_anchor_target = result.first_node;
             if (result.first_node.tagName === "w:p") {
-              first_anchor_target = findAllDescendants(result.first_node, "w:ins")[0] || result.first_node;
+              first_anchor_target =
+                findAllDescendants(result.first_node, "w:ins")[0] ||
+                result.first_node;
             }
             const start_anchor = ascend_to_paragraph_child(
               first_anchor_target,
@@ -1637,22 +2147,27 @@ export class RedlineEngine {
               end_anchor,
               edit.comment,
             );
-            }
-          } else {
-            // Inline only: anchor around first_node in its host paragraph.
-            let host_p: Element | null = result.first_node;
-            while (host_p && host_p.tagName !== "w:p")
+          }
+        } else {
+          // Inline only: anchor around first_node in its host paragraph.
+          let host_p: Element | null = result.first_node;
+          while (host_p && host_p.tagName !== "w:p")
             host_p = host_p.parentNode as Element;
-            if (host_p) {
+          if (host_p) {
             let first_anchor_target = result.first_node;
             if (result.first_node.tagName === "w:p") {
-              first_anchor_target = findAllDescendants(result.first_node, "w:ins")[0] || result.first_node;
+              first_anchor_target =
+                findAllDescendants(result.first_node, "w:ins")[0] ||
+                result.first_node;
             }
-            const anchor = ascend_to_paragraph_child(first_anchor_target, host_p);
+            const anchor = ascend_to_paragraph_child(
+              first_anchor_target,
+              host_p,
+            );
             this._attach_comment(host_p, anchor, anchor, edit.comment);
-            }
           }
         }
+      }
       return true;
     }
 
@@ -1662,7 +2177,10 @@ export class RedlineEngine {
       length,
       rebuild_map,
     );
-    const virtual_spans = active_mapper.get_virtual_spans_in_range(start_idx, length);
+    const virtual_spans = active_mapper.get_virtual_spans_in_range(
+      start_idx,
+      length,
+    );
 
     if (target_runs.length === 0 && virtual_spans.length === 0) return false;
 
@@ -1738,18 +2256,26 @@ export class RedlineEngine {
 
     // PHASE 2: OOXML Paragraph Merge Protocol
     if (op === "DELETION" || op === "MODIFICATION") {
-      if (op === "MODIFICATION" && target_runs.length === 0 && virtual_spans.length > 0 && edit.new_text) {
+      if (
+        op === "MODIFICATION" &&
+        target_runs.length === 0 &&
+        virtual_spans.length > 0 &&
+        edit.new_text
+      ) {
         const first_span = virtual_spans[0];
         if (first_span.paragraph) {
           const p1_el = first_span.paragraph._element;
           const last_runs = findAllDescendants(p1_el, "w:r");
-          const anchor = last_runs.length > 0 ? new Run(last_runs[last_runs.length - 1], first_span.paragraph) : null;
-          
+          const anchor =
+            last_runs.length > 0
+              ? new Run(last_runs[last_runs.length - 1], first_span.paragraph)
+              : null;
+
           const result = this._track_insert_multiline(
             edit.new_text,
             anchor,
             first_span.paragraph,
-            ins_id!
+            ins_id!,
           );
           if (result.first_node) {
             p1_el.appendChild(result.first_node);
@@ -1769,7 +2295,10 @@ export class RedlineEngine {
             let pPr = findChild(p1_element, "w:pPr");
             if (!pPr) {
               pPr = p1_element.ownerDocument!.createElement("w:pPr") as Element;
-              p1_element.insertBefore(pPr, p1_element.firstChild as Node | null);
+              p1_element.insertBefore(
+                pPr,
+                p1_element.firstChild as Node | null,
+              );
             }
             let rPr = findChild(pPr!, "w:rPr");
             if (!rPr) {
@@ -1781,7 +2310,10 @@ export class RedlineEngine {
 
             const children = Array.from(p2_element.childNodes);
             for (const child of children) {
-              if (child.nodeType === 1 && (child as Element).tagName === "w:pPr") {
+              if (
+                child.nodeType === 1 &&
+                (child as Element).tagName === "w:pPr"
+              ) {
                 continue;
               }
               p1_element.appendChild(child);