@stll/folio-core 0.58.5 → 0.59.0

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

@@ -1,6 +1,6 @@
 import { document_d_exports } from "../types/document.js";
 import { CanonicalGap } from "../types/canonicalCapabilities.js";
-import { FolioContentBlock, FolioContentInlineBooleanProperty, FolioContentInlineFormatting, FolioContentInlineFormattingPatch, FolioContentListReference, FolioContentParagraphIndentation, FolioContentParagraphKind, FolioContentParagraphSpacing, FolioContentRun, FolioContentSnapshot, FolioContentTableLocation } from "../compare/content-types.js";
+import { FolioContentBlock, FolioContentBlockIdentity, FolioContentInlineBooleanProperty, FolioContentInlineFormatting, FolioContentInlineFormattingPatch, FolioContentListReference, FolioContentParagraphIndentation, FolioContentParagraphKind, FolioContentParagraphSpacing, FolioContentRun, FolioContentSnapshot, FolioContentStatedNumbering, FolioContentTableLocation } from "../compare/content-types.js";
 import { ListKind } from "../docx/listNumberingInstances.js";
 //#region src/ai-edits/types.d.ts
 type FolioAIBlockKind = FolioContentParagraphKind | "diagnostic";
@@ -46,14 +46,17 @@ type FolioAIBlockStructuralBoundary = {
  * own blocks. Absent on a block that is not inside a table.
  */
 type FolioAIBlockTableLocation = FolioContentTableLocation;
-type FolioAIBlock = FolioContentBlock<FolioAIBlockKind> & {
+type FolioAIParagraphBlock = FolioContentBlock<FolioContentParagraphKind> & {
   structuralBoundaries?: readonly FolioAIBlockStructuralBoundary[];
+};
+type FolioAIDiagnosticBlock = FolioContentBlockIdentity<"diagnostic"> & {
   /** Present on a read-only block that reports preserved content Folio cannot interpret. */
-  diagnostic?: {
+  diagnostic: {
     type: "opaqueCarrier";
     carrier: string;
   };
 };
+type FolioAIBlock = FolioAIParagraphBlock | FolioAIDiagnosticBlock;
 /**
  * The complete modeled attribute set of one direct `w:pPr/w:spacing` child.
  * Optional fields preserve the distinction between an absent attribute and
@@ -66,19 +69,19 @@ type FolioAIListReference = FolioContentListReference;
 /** The kinds of list an operation can start. */
 type FolioAIListKind = ListKind;
 /**
- * Start a new list: a numbering instance of `kind`, defined for the
+ * Start a new list: a numbering instance of `format`, defined for the
  * operation, with its paragraphs at `level` (zero-based, default 0). Every
  * paragraph one operation numbers this way joins the same new list; separate
  * operations start separate lists. A package without a numbering part gets
  * one.
  */
 type FolioAINewListReference = {
-  start: "new";
-  kind: FolioAIListKind;
+  kind: "newList";
+  format: FolioAIListKind;
   level?: number;
 };
 /** An existing numbering instance and level, or a new list. */
-type FolioAIListNumbering = FolioAIListReference | FolioAINewListReference;
+type FolioAIListNumbering = FolioContentStatedNumbering | FolioAINewListReference;
 /** Which paragraphs split from one insertion's `text` receive its paragraph formatting. */
 type FolioAIInsertFormattingScope = "firstParagraph" | "allParagraphs";
 /**
@@ -86,18 +89,13 @@ type FolioAIInsertFormattingScope = "firstParagraph" | "allParagraphs";
  * scope: properties a comparison can see in a block projection and an agent
  * has a reason to change.
  */
-type FolioAIBlockParagraphProperties = {
+type FolioAIBlockParagraphProperties<Numbering = FolioAIListNumbering> = {
   /** `w:pStyle`. `null` clears the style back to the default. */
   styleId?: string | null;
   /** Direct `w:outlineLvl`. `null` restores style inheritance. */
   outlineLevel?: document_d_exports.OutlineLevel | null;
-  /**
-   * `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?: FolioAIListNumbering | null;
+  /** Exact stated numbering: inherit, cancellation, level-only, or an authored reference. */
+  numbering?: Numbering;
   /** 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. */
@@ -213,7 +211,7 @@ type FolioAISignatureParty = {
   signatory?: string;
   title?: string;
 };
-type FolioAIEditOperation = FolioAIEditReviewMeta & {
+type FolioAIEditOperation<Numbering = FolioAIListNumbering> = FolioAIEditReviewMeta & {
   precondition?: FolioAIEditPrecondition;
   /**
    * Groups this operation's produced marks under one logical suggestion so the
@@ -272,7 +270,7 @@ type FolioAIEditOperation = FolioAIEditReviewMeta & {
   /**
    * Which paragraphs split from `text` receive the operation's
    * paragraph formatting: the inherited anchor formatting plus
-   * `styleId`, `outlineLevel`, `listLevel`, `numbering`, `alignment`,
+   * `styleId`, `outlineLevel`, `numbering`, `alignment`,
    * `spacing` and `indentation`. `"firstParagraph"` (the default) formats the first
    * and leaves the rest as body paragraphs, for a heading followed by
    * its body. `"allParagraphs"` formats every paragraph alike, for
@@ -315,16 +313,8 @@ type FolioAIEditOperation = FolioAIEditReviewMeta & {
    * becomes a heading. `null` clears it and lets the style decide.
    */
   outlineLevel?: document_d_exports.OutlineLevel | 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 unless `numbering` supplies a concrete instance; together
-   * they retain that instance without an authored level.
-   */
-  listLevel?: number | null;
-  numbering?: FolioAIListNumbering | null;
+  /** Exact stated numbering for the inserted paragraph; omission copies the anchor. */
+  numbering?: Numbering;
   /**
    * Direct `w:jc` for the inserted block. `null` clears alignment copied
    * from the anchor and lets the inserted paragraph's style decide.
@@ -397,12 +387,12 @@ type FolioAIEditOperation = FolioAIEditReviewMeta & {
    * Paragraph properties for the first result. Omitted properties keep
    * the source paragraph's value.
    */
-  firstParagraphProperties?: FolioAIBlockParagraphProperties;
+  firstParagraphProperties?: FolioAIBlockParagraphProperties<Numbering>;
   /**
    * Paragraph properties for the second result. Omitted properties keep
    * the source paragraph's value.
    */
-  secondParagraphProperties?: FolioAIBlockParagraphProperties;
+  secondParagraphProperties?: FolioAIBlockParagraphProperties<Numbering>;
 } |
 /**
  * Add a whole table next to the anchor block, its rows marked inserted in
@@ -446,7 +436,7 @@ type FolioAIEditOperation = FolioAIEditReviewMeta & {
   id: string;
   type: "setBlockParagraphProperties";
   blockId: string;
-  properties: FolioAIBlockParagraphProperties;
+  properties: FolioAIBlockParagraphProperties<Numbering>;
 } |
 /**
  * Join the block with the one after it, the mirror of `splitBlock`: in
@@ -472,7 +462,7 @@ type FolioAIEditOperation = FolioAIEditReviewMeta & {
    * Paragraph properties for the joined result. Omitted properties keep
    * the first paragraph's value.
    */
-  mergedParagraphProperties?: FolioAIBlockParagraphProperties;
+  mergedParagraphProperties?: FolioAIBlockParagraphProperties<Numbering>;
 } | {
   id: string;
   type: "commentOnBlock";
@@ -553,6 +543,8 @@ type FolioAIEditOperation = FolioAIEditReviewMeta & {
   /** Stable paragraph anchor inside the cell to split. */
   blockId: string;
 });
+/** Operations after the numbering allocator has resolved every request. */
+type FolioAIResolvedEditOperation = FolioAIEditOperation<FolioContentStatedNumbering>;
 /**
  * How AI-authored operations are applied:
  * - `"direct"` — edits are written straight into the document.
@@ -754,4 +746,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, FolioAIInsertFormattingScope, FolioAIListKind, FolioAIListNumbering, FolioAIListReference, FolioAINewListReference, FolioAIParagraphIndentation, FolioAIParagraphSpacing, FolioAISignatureParty, FolioAITextRangeHandle, FolioDocumentNavigationTarget, FolioDocumentOutline, FolioDocumentOutlineEntry, FolioDocumentSection, FolioDocumentSectionHandle, FolioDocumentSectionReadResult };
+export { FolioAIBlock, FolioAIBlockAnchor, FolioAIBlockKind, FolioAIBlockParagraphProperties, FolioAIBlockPreviewRun, FolioAIBlockStructuralBoundary, FolioAIBlockTableLocation, FolioAIComment, FolioAIDiagnosticBlock, FolioAIEditAppliedOperation, FolioAIEditApplyMode, FolioAIEditApplyResult, FolioAIEditNormalization, FolioAIEditNormalizationCode, FolioAIEditOperation, FolioAIEditPrecondition, FolioAIEditReviewMeta, FolioAIEditSeverity, FolioAIEditSkipReason, FolioAIEditSkippedOperation, FolioAIEditSnapshot, FolioAIInlineBooleanProperty, FolioAIInlineFormatting, FolioAIInlineFormattingPatch, FolioAIInsertFormattingScope, FolioAIListKind, FolioAIListNumbering, FolioAIListReference, FolioAINewListReference, FolioAIParagraphBlock, FolioAIParagraphIndentation, FolioAIParagraphSpacing, FolioAIResolvedEditOperation, FolioAISignatureParty, FolioAITextRangeHandle, FolioDocumentNavigationTarget, FolioDocumentOutline, FolioDocumentOutlineEntry, FolioDocumentSection, FolioDocumentSectionHandle, FolioDocumentSectionReadResult };

package/dist/compare/column-alignment.d.ts

@@ -1,6 +1,6 @@
-import { FolioContentBlock, FolioContentTableLocation } from "./content-types.js";
+import { FolioContentBlock, FolioContentBlockIdentity, FolioContentTableLocation } from "./content-types.js";
 //#region src/compare/column-alignment.d.ts
-type TableColumnAlignmentStep<Block extends FolioContentBlock = FolioContentBlock> = {
+type TableColumnAlignmentStep<Block extends FolioContentBlockIdentity = FolioContentBlock> = {
   type: "baseColumn";
   blocks: readonly Block[];
   location: FolioContentTableLocation;
@@ -15,13 +15,13 @@ type TableColumnAlignmentStep<Block extends FolioContentBlock = FolioContentBloc
     position: "after" | "before";
   };
 };
-type TableColumnAlignment<Block extends FolioContentBlock = FolioContentBlock> = {
+type TableColumnAlignment<Block extends FolioContentBlockIdentity = FolioContentBlock> = {
   steps: TableColumnAlignmentStep<Block>[];
   baseBlocks: Block[];
   revisedBlocks: Block[];
   baseColumnKeys: ReadonlyMap<number, number>;
   revisedColumnKeys: ReadonlyMap<number, number>;
 };
-declare const alignTableColumns: <Block extends FolioContentBlock>(baseBlocks: readonly Block[], revisedBlocks: readonly Block[]) => TableColumnAlignment<Block> | null;
+declare const alignTableColumns: <Block extends FolioContentBlockIdentity>(baseBlocks: readonly Block[], revisedBlocks: readonly Block[]) => TableColumnAlignment<Block> | null;
 //#endregion
 export { TableColumnAlignment, TableColumnAlignmentStep, alignTableColumns };

package/dist/compare/compare.d.ts

@@ -5,6 +5,7 @@ import { FolioRevisionStamp } from "../ai-edits/apply.js";
 import { FolioDocumentStoryHandle, FolioDocxReviewer } from "../ai-edits/headless.js";
 import { CompareVerification } from "./verification.js";
 import { CompareChange, CompareCompatibility, CompareDocxApplyError, CompareDocxError, CompareDocxFinalParagraphMarkError, CompareDocxOperationLimitError, CompareDocxOptions, CompareDocxParseError, CompareDocxSerializeError, CompareResult, CompareUnsupportedPart, InvalidCompareDocxOptionsError } from "./types.js";
+import { importStyleClosureWithNumbering } from "./import-style-closure.js";
 import { CompareStoryPlan } from "./plan.js";
 import { Result } from "better-result";
 //#region src/compare/compare.d.ts
@@ -51,12 +52,7 @@ 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>;
+  numberingStage: ReturnType<typeof importStyleClosureWithNumbering>["numberingStage"];
   finalSectionComparison: FinalSectionComparison;
   styleImportFailure: string | undefined;
   unsupported: readonly CompareUnsupportedPart[];
@@ -100,7 +96,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, revisionFormat, terminalTableCarrierStaged, numberingChanges, targetNumbering, targetNumberingReferences, targetNumberingReferenceMap, finalSectionComparison, styleImportFailure, pairs, unsupported }: ParsedComparison, planned: readonly PlannedStoryComparison[]) => Result<AppliedComparison, CompareDocxApplyError | CompareDocxOperationLimitError>;
+declare const applyComparison: ({ reviewer, revisionStamp, granularity, revisionFormat, terminalTableCarrierStaged, numberingChanges, numberingStage, finalSectionComparison, styleImportFailure, pairs, unsupported }: ParsedComparison, planned: readonly PlannedStoryComparison[]) => Result<AppliedComparison, CompareDocxApplyError | CompareDocxOperationLimitError>;
 /**
  * Stage 4: the result package, with every ZIP entry date pinned.
  *

package/dist/compare/compare.js

@@ -1,6 +1,6 @@
 import { FolioDocxReviewer, getFolioDocxComparisonAccess } from "../ai-edits/headless.js";
 import { withComparisonNoteReferenceEdits } from "../ai-edits/note-references.js";
-import { alignedNoteReferenceLabels, detachFolioAIEditSnapshotExternalHyperlinks, numberingReferenceKeysOf, relabelFolioAIEditSnapshotNoteReferences, remapFolioAIEditSnapshotNumberingReferences, remapFolioAIEditSnapshotStyleReferences, sourceDocumentOf, storyTablesOf } from "../ai-edits/snapshot.js";
+import { alignedNoteReferenceLabels, detachFolioAIEditSnapshotExternalHyperlinks, numberingReferenceKeysOf, relabelFolioAIEditSnapshotNoteReferences, sourceDocumentOf, storyTablesOf } from "../ai-edits/snapshot.js";
 import { projectTableGeometry } from "../ai-edits/table-geometry.js";
 import { tableTemplateCanCrossPackageLosslessly } from "../ai-edits/table-template.js";
 import { createScopedWordDiffOptions } from "../ai-edits/word-diff.js";
@@ -11,9 +11,9 @@ import { isOpaqueNestedRowMarkup, opaqueRevisionCarrierName } from "../docx/opaq
 import { sectionReferenceHistory } from "../docx/sectionReferenceHistory.js";
 import { sameCanonicalInlinePresentation } from "../internal/compare/inline-presentation.js";
 import { revisionIdSeedAbove } from "../prosemirror/plugins/revisionIds.js";
-import { createStyleResolver } from "../prosemirror/styles/styleResolver.js";
 import { canonicalJson } from "../utils/canonicalJson.js";
 import { createContentComparisonWorkSession } from "./content.js";
+import { importStyleClosureWithNumbering } from "./import-style-closure.js";
 import { MISSING_NOTE_DETAIL, sameInlineAtoms } from "./inline-atoms.js";
 import { sameAuthoredInlineProvenance } from "./inline-provenance.js";
 import { planStoryCompare } from "./plan.js";
@@ -348,29 +348,30 @@ const parseComparison = async (base, target, options) => {
 			targetSnapshot
 		});
 	}
-	const styleImport = getFolioDocxComparisonAccess(reviewer).stageTargetStyles(targetReviewer, pairs.map(({ targetSnapshot }) => targetSnapshot), [...importedHeaderFooterTargetSnapshots]);
-	const styleAlignedPairs = styleImport.status === "unalignable" ? pairs : pairs.map(({ baseStory, targetStory, baseSnapshot, rawBaseSnapshot, targetSnapshot }) => ({
-		baseStory,
-		targetStory,
-		baseSnapshot,
-		rawBaseSnapshot: rawBaseSnapshot ?? baseSnapshot,
-		targetSnapshot: remapFolioAIEditSnapshotStyleReferences({
-			snapshot: targetSnapshot,
-			styleIdMap: styleImport.styleIdMap,
-			defaultParagraphStyleId: styleImport.defaultParagraphStyleId,
-			importedStyleResolver: createStyleResolver(styleImport.styles),
-			reconcileAuthoredFormatting: true
-		})
+	const targetNumberingReferences = pairs.flatMap(({ targetSnapshot }) => targetSnapshot.blocks.flatMap((block) => {
+		switch (block.kind) {
+			case "diagnostic": return [];
+			case "paragraph":
+			case "heading":
+			case "listItem": return block.listReference ? [block.listReference] : [];
+			default: return panic("Unhandled comparison block kind", { block });
+		}
 	}));
-	const targetNumbering = getFolioDocxComparisonAccess(targetReviewer).numberingDefinitions();
-	const targetNumberingReferences = styleAlignedPairs.flatMap(({ targetSnapshot }) => targetSnapshot.blocks.flatMap((block) => block.listReference ? [block.listReference] : []));
-	const targetNumberingReferenceMap = getFolioDocxComparisonAccess(reviewer).planTargetNumberingReferences(targetNumbering, targetNumberingReferences);
-	const comparisonPairs = targetNumberingReferenceMap === null ? styleAlignedPairs : styleAlignedPairs.map(({ baseStory, targetStory, baseSnapshot, rawBaseSnapshot, targetSnapshot }) => ({
+	const numberingChanges = compareNumbering(reviewer, targetReviewer, referencedNumberingLevels);
+	const resources = importStyleClosureWithNumbering({
+		destination: reviewer,
+		source: targetReviewer,
+		snapshots: pairs.map(({ targetSnapshot }) => targetSnapshot),
+		importedHeaderFooterSnapshots: [...importedHeaderFooterTargetSnapshots],
+		numberingReferences: targetNumberingReferences
+	});
+	const { styleImport, numberingStage } = resources;
+	const comparisonPairs = pairs.map(({ baseStory, targetStory, baseSnapshot, rawBaseSnapshot }, index) => ({
 		baseStory,
 		targetStory,
 		baseSnapshot,
 		rawBaseSnapshot: rawBaseSnapshot ?? baseSnapshot,
-		targetSnapshot: remapFolioAIEditSnapshotNumberingReferences(targetSnapshot, targetNumberingReferenceMap)
+		targetSnapshot: resources.snapshots.at(index) ?? panic("A comparison resource import lost its snapshot")
 	}));
 	const finalSectionComparison = compareFinalSectionProperties({
 		base: getFolioDocxComparisonAccess(reviewer).finalSectionProperties(),
@@ -391,10 +392,8 @@ const parseComparison = async (base, target, options) => {
 		},
 		packageDate,
 		pairs: comparisonPairs,
-		numberingChanges: compareNumbering(reviewer, targetReviewer, referencedNumberingLevels),
-		targetNumbering,
-		targetNumberingReferences,
-		targetNumberingReferenceMap: targetNumberingReferenceMap ?? /* @__PURE__ */ new Map(),
+		numberingChanges,
+		numberingStage,
 		finalSectionComparison,
 		styleImportFailure: styleImport.status === "unalignable" ? styleImport.detail : void 0,
 		unsupported
@@ -538,7 +537,7 @@ const resolveTableTemplates = (targetTables, requests) => {
 * 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.
 */
-const applyComparison = ({ reviewer, revisionStamp, granularity, revisionFormat, terminalTableCarrierStaged, numberingChanges, targetNumbering, targetNumberingReferences, targetNumberingReferenceMap, finalSectionComparison, styleImportFailure, pairs, unsupported }, planned) => {
+const applyComparison = ({ reviewer, revisionStamp, granularity, revisionFormat, terminalTableCarrierStaged, numberingChanges, numberingStage, finalSectionComparison, styleImportFailure, pairs, unsupported }, planned) => {
 	const relationshipIds = sectionRelationshipMap(pairs);
 	const baseNotes = /* @__PURE__ */ new Set();
 	for (const { baseStory } of [...pairs, ...unsupported]) if (baseStory?.type === "footnote" || baseStory?.type === "endnote") baseNotes.add(`${baseStory.type}:${String(baseStory.noteId)}`);
@@ -549,7 +548,6 @@ const applyComparison = ({ reviewer, revisionStamp, granularity, revisionFormat,
 		limit: MAX_COMPARE_OPERATIONS
 	}));
 	const comparisonAccess = getFolioDocxComparisonAccess(reviewer);
-	const numberingStage = comparisonAccess.stageTargetNumbering(targetNumbering, targetNumberingReferences, targetNumberingReferenceMap);
 	const changes = [...numberingChanges];
 	const failures = [];
 	if (styleImportFailure !== void 0) failures.push({
@@ -622,7 +620,7 @@ const applyComparison = ({ reviewer, revisionStamp, granularity, revisionFormat,
 				},
 				tableTemplates: resolveTableTemplates(targetTables, plan.tableTemplates),
 				replacementBackground: "keep",
-				undefinedStyles: "keep"
+				undefinedReferences: "keep"
 			}));
 			if (nextRevisionId === void 0) panic("The applier did not report where it left the revision-id counter", { story: pair.baseStory });
 			idSeed = nextRevisionId;

package/dist/compare/content-alignment.d.ts

@@ -1,4 +1,4 @@
-import { FolioContentBlock, FolioContentIdStability, FolioContentTableLocation } from "./content-types.js";
+import { FolioContentBlock, FolioContentBlockIdentity, FolioContentIdStability, FolioContentTableLocation } from "./content-types.js";
 import { TableColumnAlignmentStep } from "./column-alignment.js";
 //#region src/compare/content-alignment.d.ts
 type FolioContentAlignmentWorkSession = {
@@ -29,7 +29,7 @@ type IncreasingPairOptions = {
  * stable-anchor pass from quadratic to O(n log n).
  */
 declare const longestIncreasingFolioContentPairs: (pairs: readonly FolioContentBlockPair[], options?: IncreasingPairOptions) => FolioContentBlockPair[];
-type FolioContentAlignedBlockEvent<Block extends FolioContentBlock = FolioContentBlock> = {
+type FolioContentAlignedBlockEvent<Block extends FolioContentBlockIdentity = FolioContentBlock> = {
   type: "pair";
   baseBlock: Block;
   revisedBlock: Block;
@@ -40,15 +40,15 @@ type FolioContentAlignedBlockEvent<Block extends FolioContentBlock = FolioConten
   type: "revisedOnly";
   block: Block;
 };
-type AlignFolioContentBlocksOptions<Block extends FolioContentBlock> = {
+type AlignFolioContentBlocksOptions<Block extends FolioContentBlockIdentity> = {
   workSession?: FolioContentAlignmentWorkSession;
   /** Let an already-aligned structural slot outrank differing authored IDs. */
   stableIdMismatch?: "pair" | "separate";
   /** @internal Compatibility hook for adapters whose source model predates `idStability`. */
   idStability?: ((block: Block) => FolioContentIdStability) | undefined;
 };
-declare const alignFolioContentBlocks: <Block extends FolioContentBlock>(baseBlocks: readonly Block[], revisedBlocks: readonly Block[], options?: AlignFolioContentBlocksOptions<Block>) => FolioContentAlignedBlockEvent<Block>[];
-type FolioContentAlignmentStep<Block extends FolioContentBlock = FolioContentBlock> = {
+declare const alignFolioContentBlocks: <Block extends FolioContentBlockIdentity>(baseBlocks: readonly Block[], revisedBlocks: readonly Block[], options?: AlignFolioContentBlocksOptions<Block>) => FolioContentAlignedBlockEvent<Block>[];
+type FolioContentAlignmentStep<Block extends FolioContentBlockIdentity = FolioContentBlock> = {
   type: "pair";
   baseBlock: Block;
   revisedBlock: Block;
@@ -82,8 +82,8 @@ type FolioContentMoveScope = {
   readonly bucket: number;
   readonly gap: number;
 };
-declare const groupFolioContentTableRows: <Block extends FolioContentBlock>(blocks: readonly Block[]) => Block[][];
-type AlignFolioContentStructureOptions<Block extends FolioContentBlock> = {
+declare const groupFolioContentTableRows: <Block extends FolioContentBlockIdentity>(blocks: readonly Block[]) => Block[][];
+type AlignFolioContentStructureOptions<Block extends FolioContentBlockIdentity> = {
   baseBlocks: readonly Block[];
   revisedBlocks: readonly Block[];
   workSession?: FolioContentAlignmentWorkSession;
@@ -93,7 +93,7 @@ type AlignFolioContentStructureOptions<Block extends FolioContentBlock> = {
   /** @internal Compatibility hook for adapters whose source model predates `idStability`. */
   idStability?: ((block: Block) => FolioContentIdStability) | undefined;
 };
-declare const alignFolioContentStructure: <Block extends FolioContentBlock>({ baseBlocks, revisedBlocks, workSession, wholeTableReplacement, stableIdMismatch, idStability }: AlignFolioContentStructureOptions<Block>) => FolioContentAlignmentStep<Block>[];
-declare const contentBlocksShareContainer: (left: FolioContentBlock, right: FolioContentBlock) => boolean;
+declare const alignFolioContentStructure: <Block extends FolioContentBlockIdentity>({ baseBlocks, revisedBlocks, workSession, wholeTableReplacement, stableIdMismatch, idStability }: AlignFolioContentStructureOptions<Block>) => FolioContentAlignmentStep<Block>[];
+declare const contentBlocksShareContainer: (left: FolioContentBlockIdentity, right: FolioContentBlockIdentity) => boolean;
 //#endregion
 export { AlignFolioContentBlocksOptions, AlignFolioContentStructureOptions, CreateFolioContentAlignmentWorkSessionOptions, FolioContentAlignedBlockEvent, FolioContentAlignmentStep, FolioContentAlignmentWorkSession, FolioContentBlockPair, FolioContentMoveScope, alignFolioContentBlocks, alignFolioContentStructure, contentBlocksShareContainer, createFolioContentAlignmentWorkSession, exceedsFolioContentLcsBudget, groupFolioContentTableRows, longestIncreasingFolioContentPairs };

package/dist/compare/content-types.d.ts

@@ -1,4 +1,5 @@
 import { document_d_exports } from "../types/document.js";
+import { ParagraphNumberingOverride } from "@stll/docx-core/model";
 //#region src/compare/content-types.d.ts
 /** How callers expect a block identifier to behave across document revisions. */
 type FolioContentIdStability = "stable" | "positional";
@@ -91,13 +92,21 @@ type FolioContentListReference = {
   numId: number;
   level: number;
 };
+/** Authored paragraph numbering state, separate from effective list membership. */
+type FolioContentStatedNumbering = ParagraphNumberingOverride | {
+  readonly kind: "inherit";
+};
+declare const INHERITED_PARAGRAPH_NUMBERING: {
+  readonly kind: "inherit";
+};
+declare const sameFolioContentStatedNumbering: (left: FolioContentStatedNumbering, right: FolioContentStatedNumbering) => boolean;
 /**
  * The complete modeled attribute set of direct paragraph spacing. Optional
  * fields distinguish an absent attribute from an explicit zero or false value.
  */
 type FolioContentParagraphSpacing = Pick<document_d_exports.ParagraphFormatting, "spaceBefore" | "spaceAfter" | "lineSpacing" | "lineSpacingRule" | "beforeAutospacing" | "afterAutospacing">;
-/** A representation-neutral block in one ordered document story. */
-type FolioContentBlock<Kind extends string = string> = {
+/** Identity and shared projection fields for any block in one ordered story. */
+type FolioContentBlockIdentity<Kind extends string = string> = {
   id: string;
   kind: Kind;
   text: string;
@@ -111,6 +120,13 @@ type FolioContentBlock<Kind extends string = string> = {
    */
   displayLabel?: string;
   styleId?: string;
+  previewRuns?: readonly FolioContentRun[];
+  table?: FolioContentTableLocation;
+  /** Structural ancestry, ordered from the outermost to the innermost container. */
+  containerPath?: readonly FolioContentContainerPathEntry[];
+};
+/** A paragraph block with authored paragraph numbering state. */
+type FolioContentBlock<Kind extends FolioContentParagraphKind = FolioContentParagraphKind> = FolioContentBlockIdentity<Kind> & {
   /** Authored `w:outlineLvl`; absent when heading depth comes only from a style. */
   directOutlineLevel?: document_d_exports.OutlineLevel;
   /** Direct paragraph alignment; absent when alignment comes only from a style. */
@@ -119,17 +135,14 @@ type FolioContentBlock<Kind extends string = string> = {
   directSpacing?: FolioContentParagraphSpacing;
   /** Direct paragraph indentation; absent when every indentation value is inherited. */
   directIndentation?: FolioContentParagraphIndentation;
-  /** Zero-based list indent level when the block carries numbering. */
-  listLevel?: number;
+  /** Effective list membership resolved from authored and inherited numbering. */
   listReference?: FolioContentListReference;
-  previewRuns?: readonly FolioContentRun[];
-  table?: FolioContentTableLocation;
-  /** Structural ancestry, ordered from the outermost to the innermost container. */
-  containerPath?: readonly FolioContentContainerPathEntry[];
+  /** Authored paragraph numbering override; `inherit` means no direct override. */
+  statedNumbering: FolioContentStatedNumbering;
 };
 /** Every block of one story, in document order. */
-type FolioContentSnapshot<Block extends FolioContentBlock = FolioContentBlock> = {
+type FolioContentSnapshot<Block extends FolioContentBlockIdentity = FolioContentBlock> = {
   blocks: readonly Block[];
 };
 //#endregion
-export { FolioContentBlock, FolioContentContainerPathEntry, FolioContentFormatRange, FolioContentIdStability, FolioContentInlineBooleanProperty, FolioContentInlineComparisonResult, FolioContentInlineFormatting, FolioContentInlineFormattingPatch, FolioContentLineSpacingRule, FolioContentListReference, FolioContentParagraphAlignment, FolioContentParagraphIndentation, FolioContentParagraphKind, FolioContentParagraphSpacing, FolioContentRun, FolioContentSnapshot, FolioContentTableLocation };
+export { FolioContentBlock, FolioContentBlockIdentity, FolioContentContainerPathEntry, FolioContentFormatRange, FolioContentIdStability, FolioContentInlineBooleanProperty, FolioContentInlineComparisonResult, FolioContentInlineFormatting, FolioContentInlineFormattingPatch, FolioContentLineSpacingRule, FolioContentListReference, FolioContentParagraphAlignment, FolioContentParagraphIndentation, FolioContentParagraphKind, FolioContentParagraphSpacing, FolioContentRun, FolioContentSnapshot, FolioContentStatedNumbering, FolioContentTableLocation, INHERITED_PARAGRAPH_NUMBERING, sameFolioContentStatedNumbering };

package/dist/compare/content-types.js

@@ -0,0 +1,14 @@
+//#region src/compare/content-types.ts
+const INHERITED_PARAGRAPH_NUMBERING = { kind: "inherit" };
+const sameFolioContentStatedNumbering = (left, right) => {
+	if (left.kind !== right.kind) return false;
+	switch (left.kind) {
+		case "inherit":
+		case "none": return true;
+		case "levelOnly": return right.kind === "levelOnly" && left.ilvl === right.ilvl;
+		case "reference": return right.kind === "reference" && left.numId === right.numId && left.ilvl === right.ilvl;
+		default: return left;
+	}
+};
+//#endregion
+export { INHERITED_PARAGRAPH_NUMBERING, sameFolioContentStatedNumbering };

package/dist/compare/content.d.ts

@@ -1,4 +1,4 @@
-import { FolioContentBlock, FolioContentFormatRange, FolioContentIdStability, FolioContentListReference, FolioContentParagraphIndentation, FolioContentParagraphSpacing, FolioContentSnapshot } from "./content-types.js";
+import { FolioContentBlock, FolioContentBlockIdentity, FolioContentFormatRange, FolioContentIdStability, FolioContentParagraphIndentation, FolioContentParagraphSpacing, FolioContentSnapshot, FolioContentStatedNumbering } from "./content-types.js";
 import { WordDiffGranularity, createWordDiffSession } from "../ai-edits/word-diff.js";
 import { FolioContentAlignmentStep, FolioContentAlignmentWorkSession } from "./content-alignment.js";
 import { Result } from "better-result";
@@ -56,8 +56,7 @@ type FolioContentTextSegment = {
 type FolioContentParagraphFormattingPatch = {
   styleId?: string | null;
   outlineLevel?: FolioContentBlock["directOutlineLevel"] | null;
-  listLevel?: number | null;
-  listReference?: FolioContentListReference | null;
+  numbering?: FolioContentStatedNumbering;
   alignment?: FolioContentBlock["directAlignment"] | null;
   spacing?: FolioContentParagraphSpacing | null;
   indentation?: FolioContentParagraphIndentation | null;
@@ -71,15 +70,15 @@ type FolioContentFormattingChange = {
 };
 /** Non-presentation block fields that changed on a paired block. */
 type FolioContentBlockProperty = "kind" | "headingLevel" | "displayLabel";
-type PairedEvent<Block extends FolioContentBlock> = {
+type PairedEvent<Block extends FolioContentBlockIdentity> = {
   baseBlocks: readonly [Block];
   revisedBlocks: readonly [Block];
 };
-type BaseOnlyEvent<Block extends FolioContentBlock> = {
+type BaseOnlyEvent<Block extends FolioContentBlockIdentity> = {
   baseBlocks: readonly [Block];
   revisedBlocks: readonly [];
 };
-type RevisedOnlyEvent<Block extends FolioContentBlock> = {
+type RevisedOnlyEvent<Block extends FolioContentBlockIdentity> = {
   baseBlocks: readonly [];
   revisedBlocks: readonly [Block];
 };
@@ -87,7 +86,7 @@ type RevisedOnlyEvent<Block extends FolioContentBlock> = {
  * One item in the complete comparison stream. Tuple cardinality is fixed by
  * the discriminator, making both document projections mechanically exact.
  */
-type FolioContentComparisonEvent<Block extends FolioContentBlock = FolioContentBlock> = ({
+type FolioContentComparisonEvent<Block extends FolioContentBlockIdentity = FolioContentBlock> = ({
   type: "unchanged";
 } & PairedEvent<Block>) | ({
   type: "modified";
@@ -158,12 +157,12 @@ type FolioContentStructuralChange = ({
   columnIndex: number;
 } & RevisedStructuralChange);
 /** Result of one representation-neutral story comparison. */
-type FolioContentComparison<Block extends FolioContentBlock = FolioContentBlock> = {
+type FolioContentComparison<Block extends FolioContentBlockIdentity = FolioContentBlock> = {
   events: readonly FolioContentComparisonEvent<Block>[];
   structuralChanges: readonly FolioContentStructuralChange[];
 };
 /** Inputs to {@link compareContent}. */
-type CompareContentOptions<Block extends FolioContentBlock = FolioContentBlock> = {
+type CompareContentOptions<Block extends FolioContentBlockIdentity = FolioContentBlock> = {
   base: FolioContentSnapshot<Block>;
   revised: FolioContentSnapshot<Block>;
   /** Token size for modified-block segments; defaults to `"word"`. */
@@ -176,8 +175,8 @@ type FolioContentComparisonWorkSession = {
   diffText: ReturnType<typeof createWordDiffSession>["diff"];
 };
 declare const createContentComparisonWorkSession: (granularity?: WordDiffGranularity) => FolioContentComparisonWorkSession;
-declare const changedFolioContentParagraphFormatting: (base: FolioContentBlock, revised: FolioContentBlock) => FolioContentParagraphFormattingPatch | null;
-type ParagraphMarkPlan<Block extends FolioContentBlock> = {
+declare const changedFolioContentParagraphFormatting: (base: FolioContentBlockIdentity, revised: FolioContentBlockIdentity) => FolioContentParagraphFormattingPatch | null;
+type ParagraphMarkPlan<Block extends FolioContentBlockIdentity> = {
   type: "split";
   baseBlock: Block;
   revisedBlocks: readonly [Block, Block];
@@ -190,18 +189,18 @@ type ParagraphMarkPlan<Block extends FolioContentBlock> = {
   separator: string;
 };
 /** Plans keyed by their first step; each consumes the step after it. */
-declare const detectFolioContentParagraphMarkPlans: <Block extends FolioContentBlock>(steps: readonly FolioContentAlignmentStep<Block>[]) => ReadonlyMap<number, ParagraphMarkPlan<Block>>;
-type MovePair<Block extends FolioContentBlock> = {
+declare const detectFolioContentParagraphMarkPlans: <Block extends FolioContentBlockIdentity>(steps: readonly FolioContentAlignmentStep<Block>[]) => ReadonlyMap<number, ParagraphMarkPlan<Block>>;
+type MovePair<Block extends FolioContentBlockIdentity> = {
   baseBlock: Block;
   revisedBlock: Block;
 };
-declare const detectFolioContentMoves: <Block extends FolioContentBlock>({ steps, consumedStepIndexes, workSession, idStability }: {
+declare const detectFolioContentMoves: <Block extends FolioContentBlockIdentity>({ steps, consumedStepIndexes, workSession, idStability }: {
   steps: readonly FolioContentAlignmentStep<Block>[];
   consumedStepIndexes: ReadonlySet<number>;
   workSession: FolioContentComparisonWorkSession;
   idStability?: (block: Block) => FolioContentIdStability;
 }) => readonly MovePair<Block>[];
-type CompareAlignedContentOptions<Block extends FolioContentBlock> = {
+type CompareAlignedContentOptions<Block extends FolioContentBlockIdentity> = {
   baseBlocks: readonly Block[];
   revisedBlocks: readonly Block[];
   steps: readonly FolioContentAlignmentStep<Block>[];
@@ -209,8 +208,8 @@ type CompareAlignedContentOptions<Block extends FolioContentBlock> = {
   maxChanges: number;
   idStability?: (block: Block) => FolioContentIdStability;
 };
-declare const compareAlignedFolioContent: <Block extends FolioContentBlock>({ baseBlocks, revisedBlocks, steps, workSession, maxChanges, idStability }: CompareAlignedContentOptions<Block>) => Result<FolioContentComparison<Block>, FolioContentComparisonLimitError | FolioContentInlinePresentationProjectionError>;
+declare const compareAlignedFolioContent: <Block extends FolioContentBlockIdentity>({ baseBlocks, revisedBlocks, steps, workSession, maxChanges, idStability }: CompareAlignedContentOptions<Block>) => Result<FolioContentComparison<Block>, FolioContentComparisonLimitError | FolioContentInlinePresentationProjectionError>;
 /** Compare two representation-neutral ordered content snapshots. */
-declare const compareContent: <Block extends FolioContentBlock = FolioContentBlock>(options: CompareContentOptions<Block>) => Result<FolioContentComparison<Block>, FolioContentComparisonError>;
+declare const compareContent: <Block extends FolioContentBlockIdentity = FolioContentBlock>(options: CompareContentOptions<Block>) => Result<FolioContentComparison<Block>, FolioContentComparisonError>;
 //#endregion
 export { CompareContentOptions, FOLIO_CONTENT_COMPARISON_LIMITS, FolioContentBlockProperty, FolioContentComparison, FolioContentComparisonError, FolioContentComparisonEvent, FolioContentComparisonLimit, FolioContentComparisonLimitError, FolioContentComparisonWorkSession, type FolioContentFormatRange, FolioContentFormattingChange, FolioContentInlinePresentationProjectionError, FolioContentParagraphFormattingPatch, FolioContentStructuralChange, FolioContentTextSegment, InvalidFolioContentComparisonError, changedFolioContentParagraphFormatting, compareAlignedFolioContent, compareContent, createContentComparisonWorkSession, detectFolioContentMoves, detectFolioContentParagraphMarkPlans, sameFolioContentOutlineLevel };