@createiq/htmldiff 1.2.0-beta.0 → 1.2.0-beta.2

package/dist/HtmlDiff.d.cts

@@ -99,6 +99,16 @@ declare class HtmlDiff {
   private newText;
   private oldText;
   private tablePreprocessDepth;
+  /**
+   * Tracks currently-open formatting-tag wraps. Each entry pairs the
+   * opening tag (so a later closing tag can find its match) with the
+   * styling info needed to RE-OPEN the wrap if an overlapping
+   * formatting-tag close forces it to split. Without the styling info,
+   * an overlap like `<strong>X</strong>` ↔ `<u>X</u>` produces an
+   * unclosable wrap (the closing tag for the outer wrap arrives while
+   * an inner wrap is still on the stack); see `insertTag`'s closing
+   * handler for the split logic.
+   */
   private specialTagDiffStack;
   private newWords;
   private oldWords;
@@ -208,7 +218,26 @@ declare class HtmlDiff {
    * pairs would project on their own. Pass an explicit boolean to
    * override.
    */
-  static executeThreeWay(v1: string, v2: string, v3: string, options?: ThreeWayOptions): string;
+  /**
+   * Three-way HTML diff against a shared genesis. Produces attributed
+   * HTML that distinguishes CP's accumulated changes (genesis → cpLatest)
+   * from Me's accumulated changes (genesis → meCurrent). Use this for
+   * blackline UX where the negotiation has gone through multiple turns
+   * and the reader wants to see "who proposed what" across the whole
+   * history, not just the most recent round.
+   *
+   * When both parties happen to have made the same change (e.g. CP
+   * proposed a wording change in turn N, Me adopted it in turn N+1),
+   * the change reads as "settled" and is emitted unmarked — only
+   * disagreements and pending proposals carry author attribution.
+   *
+   * @param genesis    the shared common ancestor (per-user — the FE
+   *                   picks between V1.0 and /preview/initialAnswers
+   *                   based on `prefillReceiverAnswers`)
+   * @param cpLatest   the counterparty's current published version
+   * @param meCurrent  Me's current draft (the document on screen)
+   */
+  static executeThreeWay(genesis: string, cpLatest: string, meCurrent: string, options?: ThreeWayOptions): string;
   private static executeThreeWayWithDepth;
   /**
    * Drives a fresh `HtmlDiff` instance through `insertTag` for ins/del

package/dist/HtmlDiff.d.mts

@@ -99,6 +99,16 @@ declare class HtmlDiff {
   private newText;
   private oldText;
   private tablePreprocessDepth;
+  /**
+   * Tracks currently-open formatting-tag wraps. Each entry pairs the
+   * opening tag (so a later closing tag can find its match) with the
+   * styling info needed to RE-OPEN the wrap if an overlapping
+   * formatting-tag close forces it to split. Without the styling info,
+   * an overlap like `<strong>X</strong>` ↔ `<u>X</u>` produces an
+   * unclosable wrap (the closing tag for the outer wrap arrives while
+   * an inner wrap is still on the stack); see `insertTag`'s closing
+   * handler for the split logic.
+   */
   private specialTagDiffStack;
   private newWords;
   private oldWords;
@@ -208,7 +218,26 @@ declare class HtmlDiff {
    * pairs would project on their own. Pass an explicit boolean to
    * override.
    */
-  static executeThreeWay(v1: string, v2: string, v3: string, options?: ThreeWayOptions): string;
+  /**
+   * Three-way HTML diff against a shared genesis. Produces attributed
+   * HTML that distinguishes CP's accumulated changes (genesis → cpLatest)
+   * from Me's accumulated changes (genesis → meCurrent). Use this for
+   * blackline UX where the negotiation has gone through multiple turns
+   * and the reader wants to see "who proposed what" across the whole
+   * history, not just the most recent round.
+   *
+   * When both parties happen to have made the same change (e.g. CP
+   * proposed a wording change in turn N, Me adopted it in turn N+1),
+   * the change reads as "settled" and is emitted unmarked — only
+   * disagreements and pending proposals carry author attribution.
+   *
+   * @param genesis    the shared common ancestor (per-user — the FE
+   *                   picks between V1.0 and /preview/initialAnswers
+   *                   based on `prefillReceiverAnswers`)
+   * @param cpLatest   the counterparty's current published version
+   * @param meCurrent  Me's current draft (the document on screen)
+   */
+  static executeThreeWay(genesis: string, cpLatest: string, meCurrent: string, options?: ThreeWayOptions): string;
   private static executeThreeWayWithDepth;
   /**
    * Drives a fresh `HtmlDiff` instance through `insertTag` for ins/del