@stll/folio-core 0.35.1 → 0.37.0

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

@@ -1,20 +1,26 @@
+import { document_d_exports } from "../types/document.js";
+import { FolioContentBlock, FolioContentInlineBooleanProperty, FolioContentInlineFormatting, FolioContentInlineFormattingPatch, FolioContentParagraphSpacing, FolioContentRun, FolioContentSnapshot, FolioContentTableLocation } from "../compare/content-types.js";
 //#region src/ai-edits/types.d.ts
 type FolioAIBlockKind = "heading" | "listItem" | "paragraph";
-type FolioAIInlineFormatting = Partial<Record<"bold" | "italic" | "underline" | "strike", boolean>> & {
-  fontFamily?: string | null;
-  fontSizePt?: number | null;
-  color?: string | null;
-};
-type FolioAIBlockPreviewRun = {
-  text: string;
-  bold?: boolean;
-  italic?: boolean;
-  underline?: boolean;
-  strike?: boolean;
-  fontFamily?: string;
-  fontSizePt?: number;
-  color?: string;
-  directFormatting?: FolioAIInlineFormatting;
+/** Boolean run properties supported by snapshots and range-formatting mutations. */
+type FolioAIInlineBooleanProperty = FolioContentInlineBooleanProperty;
+type FolioAIInlineFormatting = FolioContentInlineFormatting;
+/**
+ * A run-formatting mutation: `false` authors an explicit off value, while
+ * `null` removes the direct property so its inherited value becomes effective.
+ */
+type FolioAIInlineFormattingPatch = FolioContentInlineFormattingPatch;
+type FolioAIBlockPreviewRun = FolioContentRun;
+/**
+ * A zero-width inline structure at one clean-text boundary. `pageBreak`
+ * always represents an authored `<w:br w:type="page"/>`; an omitted `clear`
+ * remains distinct from any explicit value even though it does not affect
+ * layout for this break type.
+ */
+type FolioAIBlockStructuralBoundary = {
+  type: "pageBreak";
+  offset: number;
+  clear?: document_d_exports.BreakContent["clear"];
 };
 /**
  * Where a block sits inside its innermost enclosing table. Every index is
@@ -24,47 +30,20 @@ type FolioAIBlockPreviewRun = {
  * 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;
-  text: string;
-  /** One-based heading depth when the block has outline semantics. */
-  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;
+type FolioAIBlockTableLocation = FolioContentTableLocation;
+type FolioAIBlock = FolioContentBlock<FolioAIBlockKind> & {
+  structuralBoundaries?: readonly FolioAIBlockStructuralBoundary[];
 };
+/**
+ * The complete modeled attribute set of one direct `w:pPr/w:spacing` child.
+ * Optional fields preserve the distinction between an absent attribute and
+ * an explicit zero or false value.
+ */
+type FolioAIParagraphSpacing = FolioContentParagraphSpacing;
 /**
  * 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.
+ * scope: properties a comparison can see in a block projection and an agent
+ * has a reason to change.
  */
 type FolioAIBlockParagraphProperties = {
   /** `w:pStyle`. `null` clears the style back to the default. */
@@ -74,6 +53,10 @@ type FolioAIBlockParagraphProperties = {
    * paragraph stops being a list item rather than moving to another level.
    */
   listLevel?: number | null;
+  /** Direct `w:jc`. `null` clears the override and restores style inheritance. */
+  alignment?: document_d_exports.ParagraphAlignment | null;
+  /** Direct `w:spacing` attributes. `null` removes the whole direct child. */
+  spacing?: FolioAIParagraphSpacing | null;
 };
 /**
  * Every paragraph of one story, blank ones included.
@@ -84,8 +67,7 @@ type FolioAIBlockParagraphProperties = {
  * document for a person or a model wants only the paragraphs that carry text,
  * and says so with `isFolioAIContentBlock`.
  */
-type FolioAIEditSnapshot = {
-  blocks: FolioAIBlock[];
+type FolioAIEditSnapshot = FolioContentSnapshot<FolioAIBlock> & {
   anchors: Record<string, FolioAIBlockAnchor>;
 };
 type FolioAIBlockAnchor = {
@@ -95,6 +77,8 @@ type FolioAIBlockAnchor = {
   text: string;
   normalizedText: string;
   textHash: string;
+  /** Hash of zero-width structural boundaries in the clean block view. */
+  structuralBoundaryHash: string;
   hashOccurrenceCount: number;
 };
 type FolioAIComment = {
@@ -213,7 +197,7 @@ type FolioAIEditOperation = FolioAIEditReviewMeta & {
   id: string;
   type: "formatRange";
   range: FolioAITextRangeHandle;
-  formatting: FolioAIInlineFormatting;
+  formatting: FolioAIInlineFormattingPatch;
 } | {
   id: string;
   type: "insertAfterBlock" | "insertBeforeBlock";
@@ -222,7 +206,7 @@ type FolioAIEditOperation = FolioAIEditReviewMeta & {
    * 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
+   * gets `styleId` / `alignment` / `inheritFormatting`, later ones use body
    * formatting. Blank lines are dropped. Reported as a
    * `splitMultilineText` normalization when it happens.
    *
@@ -262,6 +246,16 @@ type FolioAIEditOperation = FolioAIEditReviewMeta & {
    * inheritance alone cannot say.
    */
   listLevel?: number | null;
+  /**
+   * Direct `w:jc` for the inserted block. `null` clears alignment copied
+   * from the anchor and lets the inserted paragraph's style decide.
+   */
+  alignment?: document_d_exports.ParagraphAlignment | null;
+  /**
+   * Direct `w:spacing` for the inserted block. `null` clears spacing
+   * copied from the anchor and lets the inserted paragraph's style decide.
+   */
+  spacing?: FolioAIParagraphSpacing | null;
   comment?: FolioAIComment;
 } | {
   id: string;
@@ -269,7 +263,8 @@ type FolioAIEditOperation = FolioAIEditReviewMeta & {
   blockId: string;
   text: string;
   preserveFormatting?: boolean;
-  styleId?: string;
+  /** Paragraph style to apply; `null` clears the direct style. */
+  styleId?: string | null;
   comment?: FolioAIComment;
 } |
 /**
@@ -464,14 +459,18 @@ type FolioAIEditOperation = FolioAIEditReviewMeta & {
  *   provenance: rendered with the tracked-change grammar but stripped from
  *   serialized DOCX until a human accepts them. Behaves like `"tracked-changes"`
  *   and covers the inline text/format operations (replaceInBlock, replaceRange,
- *   formatRange) plus the block and table row/column structural operations
- *   (insertAfterBlock, insertBeforeBlock, replaceBlock, deleteBlock,
+ *   formatRange), paragraph properties, plus the block and table row/column structural
+ *   operations (insertAfterBlock, insertBeforeBlock, replaceBlock, deleteBlock,
  *   insertSignatureTable, insertTableRow, deleteTableRow, insertTableColumn,
  *   deleteTableColumn). Only comment operations and cell merge/split report
  *   `unsupportedMode`.
  */
 type FolioAIEditApplyMode = "direct" | "tracked-changes" | "suggested";
 type FolioAIEditSkipReason = "missingBlock" | "changedBlock" | "ambiguousFind" | "missingFind" | "unsupportedBlock" | "unsupportedMode" | "atomicBatchRejected" | "preconditionFailed" | "staleRange" | "emptyOperation" |
+/** The paragraph already owns the one `w:pPrChange` OOXML permits. */
+"pendingParagraphPropertyChange" |
+/** The affected run already owns the one `w:rPrChange` OOXML permits. */
+"pendingRunPropertyChange" |
 /**
  * The operation would not change the document — find equals
  * replace, or replaceBlock's `text` matches the live block.
@@ -506,6 +505,8 @@ type FolioAIEditAppliedOperation = {
    * fromProseDoc serialises a single id carrying both as a Word
    * "moveTo/moveFrom" pair, not an ins/del — so the two sides must
    * be distinct ids in the doc but conceptually one operation here.
+   * The list also includes a paragraph-property revision synthesized
+   * when an inserted final paragraph mark rotates to its carrier.
    * Use this list when you need to accept or reject every mark
    * belonging to this op.
    */
@@ -558,4 +559,4 @@ type FolioAIEditApplyResult = {
   normalizations?: FolioAIEditNormalization[];
 };
 //#endregion
-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 };
+export { FolioAIBlock, FolioAIBlockAnchor, FolioAIBlockKind, FolioAIBlockParagraphProperties, FolioAIBlockPreviewRun, FolioAIBlockStructuralBoundary, FolioAIBlockTableLocation, FolioAIComment, FolioAIEditAppliedOperation, FolioAIEditApplyMode, FolioAIEditApplyResult, FolioAIEditNormalization, FolioAIEditNormalizationCode, FolioAIEditOperation, FolioAIEditPrecondition, FolioAIEditReviewMeta, FolioAIEditSeverity, FolioAIEditSkipReason, FolioAIEditSkippedOperation, FolioAIEditSnapshot, FolioAIInlineBooleanProperty, FolioAIInlineFormatting, FolioAIInlineFormattingPatch, FolioAIParagraphSpacing, FolioAISignatureParty, FolioAITextRangeHandle, FolioDocumentNavigationTarget, FolioDocumentOutline, FolioDocumentOutlineEntry, FolioDocumentSection, FolioDocumentSectionHandle, FolioDocumentSectionReadResult };

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

@@ -23,8 +23,11 @@
  * 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.
+ * Common affixes and unique-token anchors split the input into independent
+ * gaps before any quadratic work. The residual gaps share one
+ * {@link MAX_WORD_DIFF_CELLS} allowance per comparison or apply scope; once it
+ * is spent, a gap is a single `del` + `ins` pair. A standalone call owns one
+ * fresh scope.
  */
 type WordDiffSegment = {
   type: "equal" | "del" | "ins";
@@ -58,6 +61,18 @@ type WordDiffOptions = {
   /** Default: nothing normalized, so both strings reconstruct exactly. */
   normalization?: WordDiffNormalization;
 };
+/**
+ * One internal comparison/apply scope. Every diff shares the same quadratic
+ * allowance; public standalone calls below still receive a fresh allowance.
+ * Not re-exported from a package entry point.
+ */
+declare const createWordDiffSession: (options?: WordDiffOptions) => {
+  diff: (before: string, after: string) => WordDiffSegment[];
+};
+/** Attach one internal work scope without widening a caller-facing option type. */
+declare const createScopedWordDiffOptions: <Options extends WordDiffOptions>(options: Options) => Options;
+/** Reuse an internal scope when present; ordinary public callers get a fresh one. */
+declare const wordDiffSessionFromOptions: (options: WordDiffOptions | undefined) => ReturnType<typeof createWordDiffSession>;
 declare const diffWordSegments: (before: string, after: string, options?: WordDiffOptions) => WordDiffSegment[];
 //#endregion
-export { WORD_DIFF_GRANULARITIES, WordDiffGranularity, WordDiffNormalization, WordDiffOptions, WordDiffSegment, diffWordSegments };
+export { WORD_DIFF_GRANULARITIES, WordDiffGranularity, WordDiffNormalization, WordDiffOptions, WordDiffSegment, createScopedWordDiffOptions, createWordDiffSession, diffWordSegments, wordDiffSessionFromOptions };