@stll/folio-core 0.32.1 → 0.33.0

package/dist/ai-edits/types.d.ts

@@ -10,6 +10,33 @@ type FolioAIBlockPreviewRun = {
   fontSizePt?: number;
   color?: string;
 };
+/**
+ * Where a block sits inside its innermost enclosing table. Every index is
+ * zero-based: `tableIndex` counts tables in document order across the story,
+ * `rowIndex` is the row's index in that table, `cellIndex` is the cell's
+ * PHYSICAL index within the row (a merged cell occupies one slot, so this is
+ * not a grid column), and `paragraphIndex` orders the block among the cell's
+ * own blocks. Absent on a block that is not inside a table.
+ */
+type FolioAIBlockTableLocation = {
+  /**
+   * Document-order index of the OUTERMOST table the block sits in — the same
+   * as `tableIndex` unless tables nest. A comparison aligns on this: a table
+   * inside a cell is part of its parent, not a structure of its own that can
+   * be paired against one somewhere else.
+   */
+  outerTableIndex: number;
+  tableIndex: number;
+  rowIndex: number;
+  cellIndex: number;
+  /** Grid column occupied by the cell's left edge, derived from `TableMap`. */
+  gridColumnIndex: number;
+  /** Number of grid columns occupied by this physical cell. */
+  columnSpan: number;
+  /** Number of grid rows occupied by this physical cell. */
+  rowSpan: number;
+  paragraphIndex: number;
+};
 type FolioAIBlock = {
   id: string;
   kind: FolioAIBlockKind;
@@ -18,13 +45,42 @@ type FolioAIBlock = {
   headingLevel?: number;
   displayLabel?: string;
   styleId?: string;
+  /**
+   * `w:numPr/w:ilvl`: the block's list indent level. Present only on a block
+   * that carries numbering, and the only pPr property a redline can move
+   * without touching a word — a demoted list item reads as unchanged text and
+   * is not.
+   */
+  listLevel?: number;
   previewRuns?: FolioAIBlockPreviewRun[];
+  table?: FolioAIBlockTableLocation;
 };
+/**
+ * The paragraph properties an operation may set. A subset of `w:pPrChange`'s
+ * scope: the two a comparison can see in a block projection, and the two an
+ * agent has a reason to change.
+ */
+type FolioAIBlockParagraphProperties = {
+  /** `w:pStyle`. `null` clears the style back to the default. */
+  styleId?: string | null;
+  /**
+   * `w:numPr/w:ilvl`, zero-based. `null` removes `w:numPr` altogether: the
+   * paragraph stops being a list item rather than moving to another level.
+   */
+  listLevel?: number | null;
+};
+/**
+ * Every paragraph of one story, blank ones included.
+ *
+ * A blank paragraph is part of a document's shape: an empty cell is a column,
+ * an empty row is a row, and an operation or a comparison that cannot address
+ * them cannot describe what changed around them. A surface that reads the
+ * document for a person or a model wants only the paragraphs that carry text,
+ * and says so with `isFolioAIContentBlock`.
+ */
 type FolioAIEditSnapshot = {
   blocks: FolioAIBlock[];
   anchors: Record<string, FolioAIBlockAnchor>;
-  /** Hidden empty paragraph used to anchor insertions when `blocks` is empty. */
-  emptyDocumentAnchorId?: string;
 };
 type FolioAIBlockAnchor = {
   id: string;
@@ -113,6 +169,7 @@ type FolioAIInlineFormatting = {
   bold?: boolean;
   italic?: boolean;
   underline?: boolean;
+  strike?: boolean;
 };
 /**
  * A party in an `insertSignatureTable` op. Mirrors the
@@ -161,8 +218,27 @@ type FolioAIEditOperation = FolioAIEditReviewMeta & {
   id: string;
   type: "insertAfterBlock" | "insertBeforeBlock";
   blockId: string;
+  /**
+   * The paragraph text to insert. A line break splits `text` into
+   * consecutive paragraphs at the same anchor instead of becoming
+   * literal newlines inside one paragraph: only the first paragraph
+   * gets `styleId` / `inheritFormatting`, later ones use body
+   * formatting. Blank lines are dropped. Reported as a
+   * `splitMultilineText` normalization when it happens.
+   *
+   * `""` inserts a BLANK paragraph, and is a real edit: adding an empty
+   * line is a change a reader sees, and a document that has one where
+   * another does not differs. It is applied like any other insertion,
+   * with a tracked paragraph mark, so rejecting closes it away.
+   */
   text: string;
   inheritFormatting?: boolean;
+  /**
+   * Links this insertion to the deletion that carries the same
+   * `moveId`: together they are one relocation, written as `w:moveTo`
+   * and `w:moveFrom`. See `deleteBlock`.
+   */
+  moveId?: string;
   /**
    * When true, mark the inserted paragraph with
    * `pageBreakBefore` so the layout engine starts it on a
@@ -173,9 +249,19 @@ type FolioAIEditOperation = FolioAIEditReviewMeta & {
    * Override the paragraph `styleId` attr of the inserted
    * block (e.g. `ClauseHeading1`). When omitted the inserted
    * block inherits the source block's styleId via
-   * `inheritFormatting`.
+   * `inheritFormatting`; `null` gives it no style at all, which
+   * inheritance alone cannot say.
    */
-  styleId?: string;
+  styleId?: string | null;
+  /**
+   * Override `w:numPr/w:ilvl` on the inserted block, keeping the
+   * anchor's `w:numId`. Without it the inserted paragraph takes the
+   * anchor's level, which is the wrong one whenever the new item sits
+   * beside a list item at a different depth. `null` gives it no
+   * numbering at all — an ordinary paragraph next to a list item, which
+   * inheritance alone cannot say.
+   */
+  listLevel?: number | null;
   comment?: FolioAIComment;
 } | {
   id: string;
@@ -185,11 +271,110 @@ type FolioAIEditOperation = FolioAIEditReviewMeta & {
   preserveFormatting?: boolean;
   styleId?: string;
   comment?: FolioAIComment;
-} | {
+} |
+/**
+ * Delete the whole block. A block with words loses them and its paragraph
+ * mark; a BLANK block has only a paragraph mark to lose, and loses it, so
+ * the empty line goes away rather than the operation doing nothing.
+ */
+{
   id: string;
   type: "deleteBlock";
   blockId: string;
+  /**
+   * Links this deletion to the insertion that carries the same
+   * `moveId`: together they are one relocation, written as `w:moveFrom`
+   * and `w:moveTo` rather than as an unrelated deletion and insertion.
+   * A `moveId` that does not name exactly one of each is reported as an
+   * `unpairedMove` normalization and both halves apply plainly.
+   */
+  moveId?: string;
   comment?: FolioAIComment;
+} |
+/**
+ * Break the block in two at `offset`, moving a paragraph mark and no
+ * words. In tracked-changes mode the first half carries an INSERTED
+ * paragraph mark, so accepting keeps the break and rejecting closes it;
+ * the alternative — rewriting the first half and inserting the second —
+ * claims the tail was newly written when nobody touched it.
+ */
+{
+  id: string;
+  type: "splitBlock";
+  /** Offset in the block's text. Must fall strictly inside it. */
+  offset: number;
+  /**
+   * Text at `offset` the break replaces — the space between the two
+   * halves, when the split consumed one. Deleted in `"direct"` mode and
+   * deletion-marked in tracked mode, so rejecting restores it.
+   */
+  separator?: string;
+  blockId: string;
+} |
+/**
+ * Add a whole table next to the anchor block, its rows marked inserted in
+ * tracked mode. `insertTableRow` can only grow a table that already
+ * exists; a comparison whose target gained one needs to say so.
+ */
+{
+  id: string;
+  type: "insertTable";
+  blockId: string;
+  /** Place the table after the anchor (default) or before it. */
+  position?: "after" | "before";
+  /**
+   * Cell texts row by row. Every row must hold the same number of cells.
+   *
+   * A cell holds paragraphs, not lines: a line break in a cell's text
+   * starts a new paragraph in that cell, and a blank line is a blank
+   * paragraph. That is not the rule `insertAfterBlock` follows for
+   * prose, where a blank line between two model-written clauses is
+   * formatting noise and is dropped — a cell's text describes paragraphs
+   * that exist, so dropping one would lose a block.
+   */
+  rows: readonly (readonly string[])[];
+} |
+/**
+ * Remove the whole table the block sits in, its rows marked deleted in
+ * tracked mode. The mirror of `insertTable`.
+ */
+{
+  id: string;
+  type: "deleteTable";
+  blockId: string;
+} |
+/**
+ * Replace the block's paragraph properties, recorded as a `w:pPrChange`
+ * in tracked mode so the previous set is restored on reject. The edit
+ * that moves no words: a list item demoted a level, a paragraph restyled
+ * as a heading.
+ */
+{
+  id: string;
+  type: "setBlockParagraphProperties";
+  blockId: string;
+  properties: FolioAIBlockParagraphProperties;
+} |
+/**
+ * Join the block with the one after it, the mirror of `splitBlock`: in
+ * tracked-changes mode the block carries a DELETED paragraph mark, so
+ * accepting closes the break and rejecting keeps it.
+ *
+ * Refused when the block has no joinable sibling — the last paragraph of
+ * a table cell, or of the story — because a deleted mark there would
+ * accept into a join that cannot happen and leave a revision no reader
+ * can resolve.
+ */
+{
+  id: string;
+  type: "mergeBlockWithNext";
+  /**
+   * Text the join inserts between the two halves — the space the
+   * paragraph break used to stand in for. Insertion-marked in tracked
+   * mode, so rejecting removes it along with the join.
+   */
+  separator?: string;
+  blockId: string;
 } | {
   id: string;
   type: "commentOnBlock";
@@ -214,7 +399,18 @@ type FolioAIEditOperation = FolioAIEditReviewMeta & {
   /** Stable paragraph anchor inside the row that receives the new sibling. */
   blockId: string;
   position?: "after" | "before";
-  /** Initial text for each physical cell in source order; omitted cells stay empty. */
+  /**
+   * Initial text for each cell of the new row, in order — the same order
+   * a block's `table.cellIndex` counts. Cells left unnamed stay empty.
+   *
+   * Sized against the table's COLUMN count, which is the most cells any
+   * row of it could have: more texts than that is refused rather than
+   * silently truncated, and fewer is not, so a row the table can hold is
+   * no longer refused because a span makes it narrower than the table.
+   *
+   * A line break in a cell's text starts a new paragraph in that cell,
+   * as in `insertTable`.
+   */
   cellTexts?: string[];
 } | {
   id: string;
@@ -318,9 +514,41 @@ type FolioAIEditSkippedOperation = {
   id: string;
   reason: FolioAIEditSkipReason;
 };
+/**
+ * One automatic adjustment `apply.ts` made to an operation's input to keep the
+ * applied result well-formed. Reported rather than applied silently: the
+ * caller asked for something the document could not hold, and gets told what
+ * it got instead.
+ */
+type FolioAIEditNormalization =
+/**
+ * A line-break in `insertAfterBlock` / `insertBeforeBlock`'s `text` cannot
+ * become one paragraph with an embedded break (Word paragraphs are single
+ * lines); the applier split it into one paragraph per non-blank line.
+ */
+{
+  id: string;
+  code: "splitMultilineText";
+  /** Number of paragraphs the operation's `text` was split into. */
+  paragraphCount: number;
+} |
+/**
+ * A `moveId` that did not name exactly one deletion and one insertion in
+ * the batch. The operation still applies, as an ordinary insertion or
+ * deletion: half a move pair is not a move, and `w:moveTo` without its
+ * `w:moveFrom` is a relocation from nowhere.
+ */
+{
+  id: string;
+  code: "unpairedMove";
+  moveId: string;
+};
+type FolioAIEditNormalizationCode = FolioAIEditNormalization["code"];
 type FolioAIEditApplyResult = {
   applied: FolioAIEditAppliedOperation[];
   skipped: FolioAIEditSkippedOperation[];
+  /** Present only when at least one operation triggered a normalization. */
+  normalizations?: FolioAIEditNormalization[];
 };
 //#endregion
-export { FolioAIBlock, FolioAIBlockAnchor, FolioAIBlockKind, FolioAIBlockPreviewRun, FolioAIComment, FolioAIEditAppliedOperation, FolioAIEditApplyMode, FolioAIEditApplyResult, FolioAIEditOperation, FolioAIEditPrecondition, FolioAIEditReviewMeta, FolioAIEditSeverity, FolioAIEditSkipReason, FolioAIEditSkippedOperation, FolioAIEditSnapshot, FolioAIInlineFormatting, FolioAISignatureParty, FolioAITextRangeHandle, FolioDocumentNavigationTarget, FolioDocumentOutline, FolioDocumentOutlineEntry, FolioDocumentSection, FolioDocumentSectionHandle, FolioDocumentSectionReadResult };
+export { FolioAIBlock, FolioAIBlockAnchor, FolioAIBlockKind, FolioAIBlockParagraphProperties, FolioAIBlockPreviewRun, FolioAIBlockTableLocation, FolioAIComment, FolioAIEditAppliedOperation, FolioAIEditApplyMode, FolioAIEditApplyResult, FolioAIEditNormalization, FolioAIEditNormalizationCode, FolioAIEditOperation, FolioAIEditPrecondition, FolioAIEditReviewMeta, FolioAIEditSeverity, FolioAIEditSkipReason, FolioAIEditSkippedOperation, FolioAIEditSnapshot, FolioAIInlineFormatting, FolioAISignatureParty, FolioAITextRangeHandle, FolioDocumentNavigationTarget, FolioDocumentOutline, FolioDocumentOutlineEntry, FolioDocumentSection, FolioDocumentSectionHandle, FolioDocumentSectionReadResult };

package/dist/ai-edits/word-diff.d.ts

@@ -1,20 +1,63 @@
 //#region src/ai-edits/word-diff.d.ts
 /**
- * Word-level diff between two strings. Tokenises on whitespace
- * boundaries (preserving the whitespace as part of each token), runs
- * an LCS, and returns a left-to-right ordered list of segments where
- * shared runs render as `equal`, removed runs as `del`, and added
- * runs as `ins`. Used by both the panel (to render minimal-change
- * redlines) and the apply engine (so tracked changes only mark the
- * divergent tokens, not the whole replaced span).
+ * Diff between two strings, as the segments a redline is drawn from.
  *
- * O(n*m) on token counts; if a single replacement ever holds more
- * than a few hundred tokens, swap for a streaming diff.
+ * Tokenises (by default on whitespace boundaries, preserving the whitespace as
+ * part of each token), runs an LCS, and returns a left-to-right ordered list of
+ * segments where shared runs render as `equal`, removed runs as `del`, and
+ * added runs as `ins`. Used by the panel (to render minimal-change redlines),
+ * the version comparison, and the apply engine (so tracked changes mark only
+ * the divergent tokens, not the whole replaced span).
+ *
+ * ## The shortest diff is not the most readable one
+ *
+ * An LCS maximises matched characters, which on a rewritten sentence means
+ * matching every stray "the" and comma it can reach. The reader then gets a
+ * shredded paragraph — a dozen struck-through fragments interleaved with a
+ * dozen inserted ones — where one deletion followed by one insertion says the
+ * same thing and can actually be read. Three rules pull the output back:
+ *
+ * 1. A match made only of separators is not a match ({@link isSeparatorOnly}).
+ * 2. A match too short to carry meaning is dropped unless it opens the string,
+ *    where it is the reader's anchor rather than an island.
+ * 3. When what survives is still too fragmented for its length, the whole
+ *    paragraph is one replacement ({@link isTooFragmented}).
+ *
+ * O(n*m) on token counts; past {@link MAX_WORD_DIFF_CELLS} the DP is skipped
+ * for a single whole-string `del` + `ins` pair.
  */
 type WordDiffSegment = {
   type: "equal" | "del" | "ins";
   text: string;
 };
-declare const diffWordSegments: (before: string, after: string) => WordDiffSegment[];
+/**
+ * What one token is. `"word"` tokenises on whitespace and is what a redline
+ * over prose should use; `"character"` marks the changed letters inside a
+ * word, which reads well for a reference number or a date and badly for a
+ * sentence.
+ */
+declare const WORD_DIFF_GRANULARITIES: readonly ["word", "character"];
+type WordDiffGranularity = (typeof WORD_DIFF_GRANULARITIES)[number];
+/**
+ * Differences the caller does not want marked.
+ *
+ * A normalized run is reported as `equal` and carries the BEFORE string's
+ * text, so the before side still reconstructs exactly while the after side
+ * reconstructs only up to the normalization. A caller that must reproduce the
+ * after string — anything generating tracked changes — leaves both off.
+ */
+type WordDiffNormalization = {
+  /** `"Shall"` and `"shall"` are the same token. */
+  case?: boolean;
+  /** Whitespace around and inside a token does not distinguish it. */
+  whitespace?: boolean;
+};
+type WordDiffOptions = {
+  /** Default `"word"`. */
+  granularity?: WordDiffGranularity;
+  /** Default: nothing normalized, so both strings reconstruct exactly. */
+  normalization?: WordDiffNormalization;
+};
+declare const diffWordSegments: (before: string, after: string, options?: WordDiffOptions) => WordDiffSegment[];
 //#endregion
-export { WordDiffSegment, diffWordSegments };
+export { WORD_DIFF_GRANULARITIES, WordDiffGranularity, WordDiffNormalization, WordDiffOptions, WordDiffSegment, diffWordSegments };