@stll/folio-core 0.37.4 → 0.38.0

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

@@ -1,7 +1,7 @@
 import { document_d_exports } from "../types/document.js";
-import { FolioContentBlock, FolioContentInlineBooleanProperty, FolioContentInlineFormatting, FolioContentInlineFormattingPatch, FolioContentParagraphSpacing, FolioContentRun, FolioContentSnapshot, FolioContentTableLocation } from "../compare/content-types.js";
+import { FolioContentBlock, FolioContentInlineBooleanProperty, FolioContentInlineFormatting, FolioContentInlineFormattingPatch, FolioContentListReference, FolioContentParagraphIndentation, FolioContentParagraphKind, FolioContentParagraphSpacing, FolioContentRun, FolioContentSnapshot, FolioContentTableLocation } from "../compare/content-types.js";
 //#region src/ai-edits/types.d.ts
-type FolioAIBlockKind = "heading" | "listItem" | "paragraph";
+type FolioAIBlockKind = FolioContentParagraphKind;
 /** Boolean run properties supported by snapshots and range-formatting mutations. */
 type FolioAIInlineBooleanProperty = FolioContentInlineBooleanProperty;
 type FolioAIInlineFormatting = FolioContentInlineFormatting;
@@ -40,6 +40,9 @@ type FolioAIBlock = FolioContentBlock<FolioAIBlockKind> & {
  * an explicit zero or false value.
  */
 type FolioAIParagraphSpacing = FolioContentParagraphSpacing;
+/** The complete modeled attribute set of one direct `w:pPr/w:ind` child. */
+type FolioAIParagraphIndentation = FolioContentParagraphIndentation;
+type FolioAIListReference = FolioContentListReference;
 /**
  * The paragraph properties an operation may set. A subset of `w:pPrChange`'s
  * scope: properties a comparison can see in a block projection and an agent
@@ -49,14 +52,18 @@ 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.
+   * `w:numPr/w:ilvl`, zero-based. `null` removes numbering unless `numbering`
+   * supplies a concrete instance; together they retain that instance without
+   * an authored level.
    */
   listLevel?: number | null;
+  numbering?: FolioAIListReference | 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;
+  /** Direct `w:ind` attributes. `null` removes the whole direct child. */
+  indentation?: FolioAIParagraphIndentation | null;
 };
 /**
  * Every paragraph of one story, blank ones included.
@@ -203,12 +210,13 @@ type FolioAIEditOperation = FolioAIEditReviewMeta & {
   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` / `alignment` / `inheritFormatting`, later ones use body
-   * formatting. Blank lines are dropped. Reported as a
-   * `splitMultilineText` normalization when it happens.
+   * The paragraph text to insert. With the default `lineBreakMode:
+   * "paragraph"`, a line break splits `text` into consecutive
+   * paragraphs at the same anchor: only the first paragraph gets
+   * `styleId` / `alignment` / `inheritFormatting`, later ones use
+   * body formatting. Blank lines are dropped and reported as a
+   * `splitMultilineText` normalization. `"inline"` retains the
+   * control inside one paragraph.
    *
    * `""` 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
@@ -216,6 +224,11 @@ type FolioAIEditOperation = FolioAIEditReviewMeta & {
    * with a tracked paragraph mark, so rejecting closes it away.
    */
   text: string;
+  /**
+   * `"paragraph"` (the default) splits newlines into consecutive blocks.
+   * `"inline"` retains tabs and hard breaks inside this inserted block.
+   */
+  lineBreakMode?: "paragraph" | "inline";
   inheritFormatting?: boolean;
   /**
    * Links this insertion to the deletion that carries the same
@@ -229,6 +242,13 @@ type FolioAIEditOperation = FolioAIEditReviewMeta & {
    * new page. Use for explicit page-break inserts.
    */
   pageBreakBefore?: boolean;
+  /**
+   * Insert one standalone authored `<w:br w:type="page"/>` carrier.
+   * This differs from `pageBreakBefore`, which is a paragraph property.
+   */
+  hardPageBreak?: {
+    clear?: document_d_exports.BreakContent["clear"];
+  };
   /**
    * Override the paragraph `styleId` attr of the inserted
    * block (e.g. `ClauseHeading1`). When omitted the inserted
@@ -242,10 +262,11 @@ type FolioAIEditOperation = FolioAIEditReviewMeta & {
    * 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.
+   * numbering unless `numbering` supplies a concrete instance; together
+   * they retain that instance without an authored level.
    */
   listLevel?: number | null;
+  numbering?: FolioAIListReference | null;
   /**
    * Direct `w:jc` for the inserted block. `null` clears alignment copied
    * from the anchor and lets the inserted paragraph's style decide.
@@ -256,6 +277,8 @@ type FolioAIEditOperation = FolioAIEditReviewMeta & {
    * copied from the anchor and lets the inserted paragraph's style decide.
    */
   spacing?: FolioAIParagraphSpacing | null;
+  /** Direct `w:ind` for the inserted block. `null` clears copied indentation. */
+  indentation?: FolioAIParagraphIndentation | null;
   comment?: FolioAIComment;
 } | {
   id: string;
@@ -545,9 +568,8 @@ type FolioAIEditSkippedOperation = {
  */
 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.
+ * A line-break in paragraph-mode `insertAfterBlock` /
+ * `insertBeforeBlock` text was split into one paragraph per non-blank line.
  */
 {
   id: string;
@@ -574,4 +596,4 @@ type FolioAIEditApplyResult = {
   normalizations?: FolioAIEditNormalization[];
 };
 //#endregion
-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 };
+export { FolioAIBlock, FolioAIBlockAnchor, FolioAIBlockKind, FolioAIBlockParagraphProperties, FolioAIBlockPreviewRun, FolioAIBlockStructuralBoundary, FolioAIBlockTableLocation, FolioAIComment, FolioAIEditAppliedOperation, FolioAIEditApplyMode, FolioAIEditApplyResult, FolioAIEditNormalization, FolioAIEditNormalizationCode, FolioAIEditOperation, FolioAIEditPrecondition, FolioAIEditReviewMeta, FolioAIEditSeverity, FolioAIEditSkipReason, FolioAIEditSkippedOperation, FolioAIEditSnapshot, FolioAIInlineBooleanProperty, FolioAIInlineFormatting, FolioAIInlineFormattingPatch, FolioAIListReference, FolioAIParagraphIndentation, FolioAIParagraphSpacing, FolioAISignatureParty, FolioAITextRangeHandle, FolioDocumentNavigationTarget, FolioDocumentOutline, FolioDocumentOutlineEntry, FolioDocumentSection, FolioDocumentSectionHandle, FolioDocumentSectionReadResult };

package/dist/compare/__fixtures__/body-sequence.d.ts

@@ -53,10 +53,14 @@ type TableProperties = {
     value: number;
     type: "auto" | "dxa" | "pct";
   };
+  /** `w:bidiVisual`. */
+  bidi?: boolean;
   /** `w:jc` on the table. */
   justification?: "left" | "center" | "right";
   /** `w:tblInd` in twips. */
   indent?: number;
+  /** `w:tblCellSpacing` in twips. */
+  cellSpacing?: number;
   /** `w:tblBorders`, single style on every side, in eighths of a point. */
   borderSize?: number;
   /** `w:shd` fill colour on the table, as six hex digits. */

package/dist/compare/__fixtures__/body-sequence.js

@@ -132,9 +132,9 @@ const MARGIN_SIDES = [
 const borders = (element, sides, size) => `<w:${element}>${sides.map((side) => `<w:${side} w:val="single" w:sz="${String(size)}" w:space="0" w:color="000000"/>`).join("")}</w:${element}>`;
 const margins = (element, value) => `<w:${element}>${MARGIN_SIDES.map((side) => `<w:${side} w:w="${String(value)}" w:type="dxa"/>`).join("")}</w:${element}>`;
 /**
-* `w:tblPr` children in the order CT_TblPrBase declares: tblStyle, tblW, jc,
-* tblInd, tblBorders, shd, tblLayout, tblCellMar, tblLook. `w:tblW` is always
-* written.
+* `w:tblPr` children in the order CT_TblPrBase declares: tblStyle, bidiVisual,
+* tblW, jc, tblCellSpacing, tblInd, tblBorders, shd, tblLayout, tblCellMar,
+* tblLook. `w:tblW` is always written.
 */
 const tableProperties = ({ properties }) => {
 	const width = properties?.width ?? {
@@ -143,8 +143,10 @@ const tableProperties = ({ properties }) => {
 	};
 	return `<w:tblPr>${[
 		...properties?.styleId === void 0 ? [] : [`<w:tblStyle w:val="${properties.styleId}"/>`],
+		...properties?.bidi === void 0 ? [] : [properties.bidi ? "<w:bidiVisual/>" : "<w:bidiVisual w:val=\"0\"/>"],
 		`<w:tblW w:w="${String(width.value)}" w:type="${width.type}"/>`,
 		...properties?.justification === void 0 ? [] : [`<w:jc w:val="${properties.justification}"/>`],
+		...properties?.cellSpacing === void 0 ? [] : [`<w:tblCellSpacing w:w="${String(properties.cellSpacing)}" w:type="dxa"/>`],
 		...properties?.indent === void 0 ? [] : [`<w:tblInd w:w="${String(properties.indent)}" w:type="dxa"/>`],
 		...properties?.borderSize === void 0 ? [] : [borders("tblBorders", BORDER_SIDES, properties.borderSize)],
 		...properties?.shadingFill === void 0 ? [] : [`<w:shd w:val="clear" w:color="auto" w:fill="${properties.shadingFill}"/>`],

package/dist/compare/compare.d.ts

@@ -1,9 +1,10 @@
+import { document_d_exports } from "../types/document.js";
 import { FolioAIEditSkipReason, FolioAIEditSnapshot } from "../ai-edits/types.js";
 import { WordDiffGranularity } from "../ai-edits/word-diff.js";
 import { FolioRevisionStamp } from "../ai-edits/apply.js";
 import { FolioDocumentStoryHandle, FolioDocxReviewer } from "../ai-edits/headless.js";
 import { CompareVerification } from "./verification.js";
-import { CompareChange, CompareDocxApplyError, CompareDocxError, CompareDocxFinalParagraphMarkError, CompareDocxOperationLimitError, CompareDocxOptions, CompareDocxParseError, CompareDocxSerializeError, CompareResult, CompareUnsupportedPart, InvalidCompareDocxOptionsError } from "./types.js";
+import { CompareChange, CompareCompatibility, CompareDocxApplyError, CompareDocxError, CompareDocxFinalParagraphMarkError, CompareDocxOperationLimitError, CompareDocxOptions, CompareDocxParseError, CompareDocxSerializeError, CompareResult, CompareUnsupportedPart, InvalidCompareDocxOptionsError } from "./types.js";
 import { CompareStoryPlan } from "./plan.js";
 import { Result } from "better-result";
 //#region src/compare/compare.d.ts
@@ -17,12 +18,26 @@ type ComparedStoryPair = {
   baseStory: FolioDocumentStoryHandle;
   targetStory: FolioDocumentStoryHandle;
   baseSnapshot: FolioAIEditSnapshot;
+  /** Raw base expectation when Folio-exact staging added an untracked carrier. */
+  rawBaseSnapshot?: FolioAIEditSnapshot;
   targetSnapshot: FolioAIEditSnapshot;
 };
+type FinalSectionComparison = {
+  status: "same";
+} | {
+  status: "stage";
+  previous: document_d_exports.SectionProperties;
+  target: document_d_exports.SectionProperties;
+} | {
+  status: "unsupported";
+  detail: string;
+};
 /** Everything the later stages need, and nothing they have to re-derive. */
 type ParsedComparison = {
   /** Token size a changed paragraph's redline is cut at. */
   granularity: WordDiffGranularity;
+  revisionFormat: "word" | "folio-exact";
+  terminalTableCarrierStaged: boolean;
   /**
    * The base package as it arrived. It is the result when nothing changed, but
    * only when it carried no revisions of its own: otherwise the compared base
@@ -36,6 +51,14 @@ type ParsedComparison = {
   pairs: readonly ComparedStoryPair[];
   /** Package-level numbering differences, which belong to no story. */
   numberingChanges: readonly CompareChange[];
+  targetNumbering: document_d_exports.NumberingDefinitions | null | undefined;
+  targetNumberingReferences: readonly {
+    numId: number;
+    level: number;
+  }[];
+  targetNumberingReferenceMap: ReadonlyMap<number, number>;
+  finalSectionComparison: FinalSectionComparison;
+  styleImportFailure: string | undefined;
   unsupported: readonly CompareUnsupportedPart[];
 };
 /** Stage 1: both packages to editor models, paired story by story. */
@@ -53,6 +76,7 @@ declare const planComparison: ({ pairs }: ParsedComparison) => Result<readonly P
 declare const getCompareSkipDisposition: (reason: FolioAIEditSkipReason) => "fatal" | "unwritable";
 /** What stage 3 produced: the change list, whether it was proven, and whether it wrote anything. */
 type AppliedComparison = {
+  compatibility: CompareCompatibility;
   changes: readonly CompareChange[];
   verification: CompareVerification;
   /**
@@ -76,7 +100,7 @@ type AppliedComparison = {
  * what you could not represent" and "give me nothing unless you can prove it"
  * are both legitimate asks and only the caller knows which one it is making.
  */
-declare const applyComparison: ({ reviewer, revisionStamp, granularity, numberingChanges }: ParsedComparison, planned: readonly PlannedStoryComparison[]) => Result<AppliedComparison, CompareDocxApplyError>;
+declare const applyComparison: ({ reviewer, revisionStamp, granularity, revisionFormat, terminalTableCarrierStaged, numberingChanges, targetNumbering, targetNumberingReferences, targetNumberingReferenceMap, finalSectionComparison, styleImportFailure, pairs }: ParsedComparison, planned: readonly PlannedStoryComparison[]) => Result<AppliedComparison, CompareDocxApplyError | CompareDocxOperationLimitError>;
 /**
  * Stage 4: the result package, with every ZIP entry date pinned.
  *