@stll/folio-core 0.32.2 → 0.33.0

package/dist/compare/types.js

@@ -0,0 +1,32 @@
+import { TaggedError } from "better-result";
+//#region src/compare/types.ts
+/**
+* Public vocabulary of {@link ./compare.compareDocx}: the change list, the
+* options that pin its output, and the failures it reports.
+*/
+/** Why a part of the package is absent from `changes`. */
+const COMPARE_UNSUPPORTED_REASONS = Object.freeze([
+	"story-missing-in-base",
+	"story-missing-in-target",
+	"story-not-editable"
+]);
+var InvalidCompareDocxOptionsError = class extends TaggedError("InvalidCompareDocxOptionsError") {};
+var CompareDocxParseError = class extends TaggedError("CompareDocxParseError") {};
+/**
+* The applier refused at least one derived operation, so accepting the result
+* would not reproduce the target. Reported instead of returning a package that
+* silently under-represents the difference.
+*/
+var CompareDocxApplyError = class extends TaggedError("CompareDocxApplyError") {};
+/**
+* The generated tracked changes do not accept back to the target. Raised by
+* the self-check {@link compareDocx} runs before returning: a redline that
+* quietly loses part of the difference is worse than no redline, so the
+* mismatch is surfaced instead of the document.
+*/
+var CompareDocxRoundTripError = class extends TaggedError("CompareDocxRoundTripError") {};
+/** The difference needs more operations than the engine will generate. */
+var CompareDocxOperationLimitError = class extends TaggedError("CompareDocxOperationLimitError") {};
+var CompareDocxSerializeError = class extends TaggedError("CompareDocxSerializeError") {};
+//#endregion
+export { COMPARE_UNSUPPORTED_REASONS, CompareDocxApplyError, CompareDocxOperationLimitError, CompareDocxParseError, CompareDocxRoundTripError, CompareDocxSerializeError, InvalidCompareDocxOptionsError };

package/dist/compare/verification.d.ts

@@ -0,0 +1,55 @@
+import { FolioAIBlock } from "../ai-edits/types.js";
+import { FolioDocumentStoryHandle } from "../ai-edits/headless.js";
+//#region src/compare/verification.d.ts
+/** The two directions of the round trip, each an invariant of its own. */
+declare const COMPARE_VERIFICATION_INVARIANTS: readonly ["accept-reproduces-target", "reject-reproduces-base"];
+type CompareVerificationInvariant = (typeof COMPARE_VERIFICATION_INVARIANTS)[number];
+/**
+ * What diverged. Ordered from the structural to the textual: the first cause
+ * that fits is the one reported, because a block in the wrong container is a
+ * different finding from a block whose words are wrong even when both are true.
+ */
+declare const COMPARE_VERIFICATION_CAUSES: readonly ["invisible-structure", "block-count", "container", "style", "list-level", "inline-formatting", "whitespace", "text"];
+type CompareVerificationCause = (typeof COMPARE_VERIFICATION_CAUSES)[number];
+/** One invariant that did not hold, in one story. */
+type CompareVerificationFailure = {
+  invariant: CompareVerificationInvariant;
+  cause: CompareVerificationCause;
+  story: FolioDocumentStoryHandle;
+  /** Structural facts only: counts, offsets, container kinds. Safe to quote. */
+  detail: string;
+};
+/**
+ * Whether the redline was proven to round-trip.
+ *
+ * `unverified` is only ever returned when the caller asked for it with
+ * `onUnverified: "emit"`; the default refuses instead, because a redline that
+ * reads plausibly and is wrong is worse than no redline.
+ */
+type CompareVerification = {
+  status: "verified";
+} | {
+  status: "unverified";
+  failures: readonly CompareVerificationFailure[];
+};
+/** Effective supported formatting with equivalent adjacent runs normalized. */
+declare const projectSupportedInlineFormatting: ({ text, previewRuns }: FolioAIBlock) => string;
+/** Element by element, never by joining: a block's text may hold the separator. */
+declare const sameProjection: (left: readonly string[], right: readonly string[]) => boolean;
+type ClassifyOptions = {
+  invariant: CompareVerificationInvariant;
+  story: FolioDocumentStoryHandle;
+  /** What the redline actually leaves. */
+  actual: readonly string[];
+  /** What the invariant says it should leave. */
+  expected: readonly string[];
+};
+/**
+ * The failure two projections describe, or `null` when they agree.
+ *
+ * Total over the causes by construction: the last branch is unconditional, so
+ * a divergence always produces a failure rather than being dropped.
+ */
+declare const classifyProjectionMismatch: ({ invariant, story, actual, expected }: ClassifyOptions) => CompareVerificationFailure | null;
+//#endregion
+export { COMPARE_VERIFICATION_CAUSES, COMPARE_VERIFICATION_INVARIANTS, CompareVerification, CompareVerificationCause, CompareVerificationFailure, CompareVerificationInvariant, classifyProjectionMismatch, projectSupportedInlineFormatting, sameProjection };

package/dist/compare/verification.js

@@ -0,0 +1,146 @@
+//#region src/compare/verification.ts
+/** The two directions of the round trip, each an invariant of its own. */
+const COMPARE_VERIFICATION_INVARIANTS = Object.freeze(["accept-reproduces-target", "reject-reproduces-base"]);
+/**
+* What diverged. Ordered from the structural to the textual: the first cause
+* that fits is the one reported, because a block in the wrong container is a
+* different finding from a block whose words are wrong even when both are true.
+*/
+const COMPARE_VERIFICATION_CAUSES = Object.freeze([
+	"invisible-structure",
+	"block-count",
+	"container",
+	"style",
+	"list-level",
+	"inline-formatting",
+	"whitespace",
+	"text"
+]);
+const supportedInlineStyle = ({ bold, italic, underline, strike }) => `${bold === true ? "b" : ""}${italic === true ? "i" : ""}${underline === true ? "u" : ""}${strike === true ? "s" : ""}`;
+/** Effective supported formatting with equivalent adjacent runs normalized. */
+const projectSupportedInlineFormatting = ({ text, previewRuns }) => {
+	const projected = [];
+	for (const run of previewRuns ?? [{ text }]) {
+		if (run.text.length === 0) continue;
+		const style = supportedInlineStyle(run);
+		const previous = projected.at(-1);
+		if (previous?.style === style) {
+			previous.length += run.text.length;
+			continue;
+		}
+		projected.push({
+			length: run.text.length,
+			style
+		});
+	}
+	return projected.map(({ length, style }) => `${String(length)}:${style}`).join(",");
+};
+const parseProjection = (entry) => {
+	const first = entry.indexOf("|");
+	const second = entry.indexOf("|", first + 1);
+	const third = entry.indexOf("|", second + 1);
+	if (first === -1 || second === -1 || third === -1) return {
+		container: "",
+		styleId: "",
+		listLevel: "",
+		text: entry
+	};
+	return {
+		container: entry.slice(0, first),
+		styleId: entry.slice(first + 1, second),
+		listLevel: entry.slice(second + 1, third),
+		text: entry.slice(third + 1)
+	};
+};
+const CONTAINER_PATTERN = /^t(\d+)r(\d+)c(\d+)p(\d+)$/u;
+const containerKind = (container) => CONTAINER_PATTERN.test(container) ? "cell" : "body";
+const collapseWhitespace = (text) => text.replace(/\s+/gu, " ").trim();
+/** Element by element, never by joining: a block's text may hold the separator. */
+const sameProjection = (left, right) => left.length === right.length && left.every((entry, index) => entry === right[index]);
+/**
+* The same projection with every table coordinate renumbered by first
+* appearance, so it counts the blocks the model holds rather than the
+* paragraphs the package contains.
+*
+* The snapshot skips a hidden row's whole subtree, so a table that hides a row
+* on one side only reports every later row one position along. No operation
+* can put a block at those coordinates, because none can create or remove the
+* hidden row that produces them. When two projections agree here and disagree
+* on the raw coordinates, the redline holds every block the other side does,
+* in order, and the difference is one the block model cannot see.
+*/
+const byVisibleOrdinal = (entries) => {
+	const ordinals = /* @__PURE__ */ new Map();
+	const counts = /* @__PURE__ */ new Map();
+	const ordinalWithin = (scope, index) => {
+		const key = `${scope}:${index}`;
+		const existing = ordinals.get(key);
+		if (existing !== void 0) return existing;
+		const next = counts.get(scope) ?? 0;
+		counts.set(scope, next + 1);
+		ordinals.set(key, next);
+		return next;
+	};
+	const paragraphCounts = /* @__PURE__ */ new Map();
+	return entries.map((entry) => {
+		const first = entry.indexOf("|");
+		const match = CONTAINER_PATTERN.exec(entry.slice(0, first));
+		if (!match) return entry;
+		const [, table = "", row = "", cell = ""] = match;
+		const tableOrdinal = ordinalWithin("t", table);
+		const rowScope = `r${String(tableOrdinal)}`;
+		const rowOrdinal = ordinalWithin(rowScope, row);
+		const cellScope = `c${String(tableOrdinal)}.${String(rowOrdinal)}`;
+		const cellOrdinal = ordinalWithin(cellScope, cell);
+		const cellKey = `${cellScope}:${cell}`;
+		const paragraphOrdinal = paragraphCounts.get(cellKey) ?? 0;
+		paragraphCounts.set(cellKey, paragraphOrdinal + 1);
+		return `t${String(tableOrdinal)}r${String(rowOrdinal)}c${String(cellOrdinal)}p${String(paragraphOrdinal)}` + entry.slice(first);
+	});
+};
+/**
+* Where two projections first diverge, and what diverged there. A pair that
+* matches everywhere but in length diverges at the shorter one's end.
+*/
+const firstDivergence = (actual, expected) => {
+	const shared = Math.min(actual.length, expected.length);
+	for (let index = 0; index < shared; index++) if (actual[index] !== expected[index]) return {
+		index,
+		actual: parseProjection(actual[index] ?? ""),
+		expected: parseProjection(expected[index] ?? "")
+	};
+	return {
+		index: shared,
+		actual: shared < actual.length ? parseProjection(actual[shared] ?? "") : null,
+		expected: shared < expected.length ? parseProjection(expected[shared] ?? "") : null
+	};
+};
+/**
+* The failure two projections describe, or `null` when they agree.
+*
+* Total over the causes by construction: the last branch is unconditional, so
+* a divergence always produces a failure rather than being dropped.
+*/
+const classifyProjectionMismatch = ({ invariant, story, actual, expected }) => {
+	if (sameProjection(actual, expected)) return null;
+	const failure = (cause, detail) => ({
+		invariant,
+		cause,
+		story,
+		detail
+	});
+	if (sameProjection(byVisibleOrdinal(actual), byVisibleOrdinal(expected))) return failure("invisible-structure", `every block matches once table coordinates count visible blocks (${String(expected.length)} blocks)`);
+	const divergence = firstDivergence(actual, expected);
+	const at = `at block ${String(divergence.index)}/${String(expected.length)}`;
+	const counts = `${String(actual.length)} blocks against ${String(expected.length)}`;
+	if (divergence.actual === null || divergence.expected === null) return failure("block-count", `${actual.length > expected.length ? "more" : "fewer"} blocks than expected (${counts}), diverging ${at}`);
+	const { actual: left, expected: right } = divergence;
+	if (left.container !== right.container) return failure("container", `a block sits in a ${containerKind(left.container)} where it is expected in a ${containerKind(right.container)}, ${at} (${counts})`);
+	if (left.text === right.text && left.styleId !== right.styleId) return failure("style", `the paragraph style did not move ${at} (${counts})`);
+	if (left.text === right.text && left.listLevel !== right.listLevel) return failure("list-level", `the list level did not move ${at} (${counts})`);
+	if (collapseWhitespace(left.text) === collapseWhitespace(right.text)) return failure("whitespace", `a block's text differs only in whitespace ${at} (${counts})`);
+	if (actual.length !== expected.length) return failure("block-count", `${counts}, first differing ${at}`);
+	return failure("text", `a ${containerKind(left.container)} block's text does not match ${at}, length ${String(left.text.length)} against ${String(right.text.length)} (${counts})`);
+};
+//#endregion
+export { COMPARE_VERIFICATION_CAUSES, COMPARE_VERIFICATION_INVARIANTS, classifyProjectionMismatch, projectSupportedInlineFormatting, sameProjection };

package/dist/compat/eigenpal.d.ts

@@ -1,14 +1,17 @@
-import { FolioAIBlock, FolioAIBlockAnchor, FolioAIBlockKind, FolioAIBlockPreviewRun, FolioAIComment, FolioAIEditAppliedOperation, FolioAIEditApplyMode, FolioAIEditApplyResult, FolioAIEditNormalization, FolioAIEditNormalizationCode, FolioAIEditOperation, FolioAIEditPrecondition, FolioAIEditReviewMeta, FolioAIEditSeverity, FolioAIEditSkipReason, FolioAIEditSkippedOperation, FolioAIEditSnapshot, FolioAISignatureParty } from "../ai-edits/types.js";
-import { applyFolioAIEditOperations } from "../ai-edits/apply.js";
+import { FolioAIBlock, FolioAIBlockAnchor, FolioAIBlockKind, FolioAIBlockPreviewRun, FolioAIBlockTableLocation, FolioAIComment, FolioAIEditAppliedOperation, FolioAIEditApplyMode, FolioAIEditApplyResult, FolioAIEditNormalization, FolioAIEditNormalizationCode, FolioAIEditOperation, FolioAIEditPrecondition, FolioAIEditReviewMeta, FolioAIEditSeverity, FolioAIEditSkipReason, FolioAIEditSkippedOperation, FolioAIEditSnapshot, FolioAISignatureParty } from "../ai-edits/types.js";
+import { WORD_DIFF_GRANULARITIES, WordDiffGranularity, WordDiffNormalization, WordDiffOptions, WordDiffSegment, diffWordSegments } from "../ai-edits/word-diff.js";
+import { FolioAIEditApplyOutcome, FolioRevisionStamp, FolioWordDiffOptions, applyFolioAIEditOperations } from "../ai-edits/apply.js";
 import { document_d_exports } from "../types/document.js";
-import { ApplyFolioDocumentOperationsOptions, FOLIO_DOCUMENT_OPERATION_BATCH_MODES, FOLIO_DOCUMENT_OPERATION_CONTRACT_VERSION, FOLIO_DOCUMENT_OPERATION_MODES, FOLIO_DOCUMENT_OPERATION_MODES_BY_TYPE, FOLIO_DOCUMENT_OPERATION_PRECONDITIONS, FOLIO_DOCUMENT_OPERATION_STORIES, FOLIO_DOCUMENT_OPERATION_TYPES, FolioDocumentOperation, FolioDocumentOperationAffectedTarget, FolioDocumentOperationBatch, FolioDocumentOperationCapabilities, FolioDocumentOperationIssue, FolioDocumentOperationMode, FolioDocumentOperationPrecondition, FolioDocumentOperationReceipt, FolioDocumentOperationRecovery, FolioDocumentOperationResult, FolioDocumentOperationStatus, FolioDocumentOperationStory, FolioDocumentOperationType, FolioDocumentOperationUndoFailureReason, FolioDocumentOperationUndoHandle, FolioDocumentOperationUndoResult, InvalidFolioDocumentOperationBatchError, UnsupportedFolioDocumentOperationVersionError, applyFolioDocumentOperations, assertSupportedFolioDocumentOperationVersion, getFolioDocumentOperationCapabilities, getFolioDocumentOperationIssues, getFolioDocumentOperationReceipts, isFolioDocumentOperationModeSupported, isSupportedFolioDocumentOperationVersion, parseFolioDocumentOperationBatch } from "../document-operations.js";
-import { createFolioAIEditSnapshot, hashFolioAIBlockText, normalizeFolioAIBlockText } from "../ai-edits/snapshot.js";
+import { ApplyFolioDocumentOperationsOptions, FOLIO_DOCUMENT_OPERATION_BATCH_MODES, FOLIO_DOCUMENT_OPERATION_CONTRACT_VERSION, FOLIO_DOCUMENT_OPERATION_MODES, FOLIO_DOCUMENT_OPERATION_MODES_BY_TYPE, FOLIO_DOCUMENT_OPERATION_PRECONDITIONS, FOLIO_DOCUMENT_OPERATION_STORIES, FOLIO_DOCUMENT_OPERATION_TYPES, FolioDocumentOperation, FolioDocumentOperationAffectedTarget, FolioDocumentOperationBatch, FolioDocumentOperationCapabilities, FolioDocumentOperationIssue, FolioDocumentOperationMode, FolioDocumentOperationPrecondition, FolioDocumentOperationReceipt, FolioDocumentOperationRecovery, FolioDocumentOperationResult, FolioDocumentOperationResultBase, FolioDocumentOperationStatus, FolioDocumentOperationStory, FolioDocumentOperationType, FolioDocumentOperationUndoFailureReason, FolioDocumentOperationUndoHandle, FolioDocumentOperationUndoResult, InvalidFolioDocumentOperationBatchError, UnsupportedFolioDocumentOperationVersionError, applyFolioDocumentOperations, assertSupportedFolioDocumentOperationVersion, getFolioDocumentOperationCapabilities, getFolioDocumentOperationIssues, getFolioDocumentOperationReceipts, isFolioDocumentOperationModeSupported, isSupportedFolioDocumentOperationVersion, parseFolioDocumentOperationBatch } from "../document-operations.js";
+import { createFolioAIEditSnapshot, hashFolioAIBlockText, isFolioAIContentBlock, normalizeFolioAIBlockText } from "../ai-edits/snapshot.js";
 import { DeriveBlockIdInput, FolioBlockId, deriveBlockId, getFolioParaIdFromBlockId, isFolioBlockId, isSequentialFolioBlockId } from "../types/block-id.js";
-import { WordDiffSegment, diffWordSegments } from "../ai-edits/word-diff.js";
 import { AIBarStatus, AIChatMode, AICitation, AICitationSource, AIGenerateInput, AISuggestion, AISuggestionApplyMode, AISuggestionPreset, AISuggestionSeverity, AISuggestionStatus, DEFAULT_AI_SUGGESTION_PRESETS } from "../ai-suggestions/types.js";
 import { ApplyResult, applySuggestions } from "../ai-suggestions/apply.js";
 import { ResolvedAnchor, isSuggestionStale, resolveSuggestionAnchor } from "../ai-suggestions/conflict.js";
 import { PositionalText, buildPositionalText } from "../ai-suggestions/text-positions.js";
+import { COMPARE_VERIFICATION_CAUSES, COMPARE_VERIFICATION_INVARIANTS, CompareVerification, CompareVerificationCause, CompareVerificationFailure, CompareVerificationInvariant } from "../compare/verification.js";
+import { COMPARE_UNSUPPORTED_REASONS, CompareChange, CompareChangeLocation, CompareDocxApplyError, CompareDocxError, CompareDocxOperationLimitError, CompareDocxOptions, CompareDocxParseError, CompareDocxRoundTripError, CompareDocxSerializeError, CompareFormatRange, CompareResult, CompareUnsupportedPart, CompareUnsupportedReason, InvalidCompareDocxOptionsError } from "../compare/types.js";
+import { MAX_COMPARE_OPERATIONS, compareDocx } from "../compare/compare.js";
 import { DOCUMENT_PRESET_VERSION, DOCUMENT_STYLE_SET_VERSION, DocumentPreset, DocumentStyleSet } from "../style-sets/types.js";
 import { CreateEmptyDocumentOptions, createEmptyDocument } from "../utils/createDocument.js";
 import { mergeDocumentContent } from "../utils/mergeDocumentContent.js";
@@ -34,4 +37,4 @@ import { getGoogleFontsEnabled, setEmbeddedFontFamilyMap, setGoogleFontsEnabled
 import { DOCX_CONFORMANCE_CLASSES } from "../index.js";
 type Document = document_d_exports.Document;
 type DocxConformanceClass = document_d_exports.DocxConformanceClass;
-export { type AIBarStatus, type AIChatMode, type AICitation, type AICitationRange, type AICitationSource, type AIGenerateInput, type AISuggestion, type AISuggestionApplyMode, type AISuggestionPreset, type AISuggestionSeverity, type AISuggestionStatus, type AcceptAutocompleteResult, type AnonymizationMatch, type AnonymizationTerm, type ApplyFolioDocumentOperationsOptions, type ApplyResult, type AutocompleteSuggestionPluginOptions, type AutocompleteSuggestionState, type AutocompleteSuggestionStatus, type AutocompleteTriggerCheck, type AutocompleteTriggerOptions, type AutocompleteTriggerSkipReason, type BlockRect, type CreateEmptyDocumentOptions, DEFAULT_AI_SUGGESTION_PRESETS, DEFAULT_AUTOCOMPLETE_DEAD_ZONE_NODES, DOCUMENT_PRESET_VERSION, DOCUMENT_STYLE_SET_VERSION, DOCX_CONFORMANCE_CLASSES, type DeriveBlockIdInput, type DirectiveKind, type DirectiveRange, type Document, type DocumentPreset, type DocumentStyleCatalog, type DocumentStyleCatalogEntry, type DocumentStyleSet, type DocxCompatibility, type DocxCompatibilityContext, type DocxCompatibilityIssue, type DocxCompatibilityLocation, type DocxCompatibilityPart, type DocxConformanceClass, type EmbeddedFont, type EmbeddedFontParts, type ExtractDocumentStyleSetOptions, FOLIO_DOCUMENT_OPERATION_BATCH_MODES, FOLIO_DOCUMENT_OPERATION_CONTRACT_VERSION, FOLIO_DOCUMENT_OPERATION_MODES, FOLIO_DOCUMENT_OPERATION_MODES_BY_TYPE, FOLIO_DOCUMENT_OPERATION_PRECONDITIONS, FOLIO_DOCUMENT_OPERATION_STORIES, FOLIO_DOCUMENT_OPERATION_TYPES, type FolioAIBlock, type FolioAIBlockAnchor, type FolioAIBlockKind, type FolioAIBlockPreviewRun, type FolioAIComment, type FolioAIEditAppliedOperation, type FolioAIEditApplyMode, type FolioAIEditApplyResult, type FolioAIEditNormalization, type FolioAIEditNormalizationCode, type FolioAIEditOperation, type FolioAIEditPrecondition, type FolioAIEditReviewMeta, type FolioAIEditSeverity, type FolioAIEditSkipReason, type FolioAIEditSkippedOperation, type FolioAIEditSnapshot, type FolioAISignatureParty, type FolioBlockId, type FolioDocumentOperation, type FolioDocumentOperationAffectedTarget, type FolioDocumentOperationBatch, type FolioDocumentOperationCapabilities, type FolioDocumentOperationIssue, type FolioDocumentOperationMode, type FolioDocumentOperationPrecondition, type FolioDocumentOperationReceipt, type FolioDocumentOperationRecovery, type FolioDocumentOperationResult, type FolioDocumentOperationStatus, type FolioDocumentOperationStory, type FolioDocumentOperationType, type FolioDocumentOperationUndoFailureReason, type FolioDocumentOperationUndoHandle, type FolioDocumentOperationUndoResult, type FolioDocxCompatibilityHost, type FolioDocxCompatibilityProfile, type ImageMeta, type ImageRef, type InspectDocxCompatibilityOptions, InvalidFolioDocumentOperationBatchError, type MarkdownOptions, type MarkdownResult, type PositionalText, type ResolvedAnchor, STELLA_STYLE_SET_NAME, type TemplatePreviewSpan, type TemplatePreviewValue, type TemplatePreviewValues, type TemplateSlashMenuKeyAction, type TemplateSlashMenuState, UnsupportedFolioDocumentOperationVersionError, type WordDiffSegment, acceptAutocompleteSuggestion, acceptAutocompleteWord, anonymizationDecorationsKey, appendAutocompleteToken, applyFolioAIEditOperations, applyFolioDocumentOperations, applySuggestions, assertSupportedFolioDocumentOperationVersion, autocompleteSuggestionKey, autocompleteSuggestionPlugin, buildEmbeddedFontFamilyMap, buildPositionalText, clearAutocompleteSuggestion, clearTemplateSlashMenu, consumeTemplateSlashQuery, createAICitationDecorationsPlugin, createDocx, createEmptyDocument, createFolioAIEditSnapshot, createStellaStyleDocumentPreset, createStellaStyleSet, deriveBlockId, diffWordSegments, extractDocumentStyleSet, extractDocumentStyleSetFromDocx, extractEmbeddedFonts, finishAutocompleteSuggestion, fromMarkdown, getAnonymizationMatches, getAutocompleteSuggestion, getEmbeddedFontFaces, getFolioCaretViewportRect, getFolioDocumentOperationCapabilities, getFolioDocumentOperationIssues, getFolioDocumentOperationReceipts, getFolioParaIdFromBlockId, getFolioSelectionViewportRect, getGoogleFontsEnabled, getTemplateDirectives, getTemplateSlashMenu, hashFolioAIBlockText, inspectDocumentStyles, inspectDocumentStylesFromDocx, inspectDocxCompatibility, isFolioBlockId, isFolioDocumentOperationModeSupported, isSequentialFolioBlockId, isSuggestionStale, isSupportedFolioDocumentOperationVersion, mergeDocumentContent, normalizeFolioAIBlockText, parseFolioDocumentOperationBatch, resetTemplateSlashQuery, resolveSuggestionAnchor, scanDirectives, scopeEmbeddedFontFamily, scrollFolioPositionIntoView, setAICitationsMeta, setAISuggestionsMeta, setActiveCitationMeta, setAnonymizationTermsMeta, setEmbeddedFontFamilyMap, setFocusedSuggestionMeta, setGoogleFontsEnabled, setTemplatePreviewValues, shouldTriggerAutocomplete, startAutocompleteSuggestion, templateSlashMenuKey, toMarkdown, toMarkdownResult };
+export { type AIBarStatus, type AIChatMode, type AICitation, type AICitationRange, type AICitationSource, type AIGenerateInput, type AISuggestion, type AISuggestionApplyMode, type AISuggestionPreset, type AISuggestionSeverity, type AISuggestionStatus, type AcceptAutocompleteResult, type AnonymizationMatch, type AnonymizationTerm, type ApplyFolioDocumentOperationsOptions, type ApplyResult, type AutocompleteSuggestionPluginOptions, type AutocompleteSuggestionState, type AutocompleteSuggestionStatus, type AutocompleteTriggerCheck, type AutocompleteTriggerOptions, type AutocompleteTriggerSkipReason, type BlockRect, COMPARE_UNSUPPORTED_REASONS, COMPARE_VERIFICATION_CAUSES, COMPARE_VERIFICATION_INVARIANTS, type CompareChange, type CompareChangeLocation, CompareDocxApplyError, type CompareDocxError, CompareDocxOperationLimitError, type CompareDocxOptions, CompareDocxParseError, CompareDocxRoundTripError, CompareDocxSerializeError, type CompareFormatRange, type CompareResult, type CompareUnsupportedPart, type CompareUnsupportedReason, type CompareVerification, type CompareVerificationCause, type CompareVerificationFailure, type CompareVerificationInvariant, type CreateEmptyDocumentOptions, DEFAULT_AI_SUGGESTION_PRESETS, DEFAULT_AUTOCOMPLETE_DEAD_ZONE_NODES, DOCUMENT_PRESET_VERSION, DOCUMENT_STYLE_SET_VERSION, DOCX_CONFORMANCE_CLASSES, type DeriveBlockIdInput, type DirectiveKind, type DirectiveRange, type Document, type DocumentPreset, type DocumentStyleCatalog, type DocumentStyleCatalogEntry, type DocumentStyleSet, type DocxCompatibility, type DocxCompatibilityContext, type DocxCompatibilityIssue, type DocxCompatibilityLocation, type DocxCompatibilityPart, type DocxConformanceClass, type EmbeddedFont, type EmbeddedFontParts, type ExtractDocumentStyleSetOptions, FOLIO_DOCUMENT_OPERATION_BATCH_MODES, FOLIO_DOCUMENT_OPERATION_CONTRACT_VERSION, FOLIO_DOCUMENT_OPERATION_MODES, FOLIO_DOCUMENT_OPERATION_MODES_BY_TYPE, FOLIO_DOCUMENT_OPERATION_PRECONDITIONS, FOLIO_DOCUMENT_OPERATION_STORIES, FOLIO_DOCUMENT_OPERATION_TYPES, type FolioAIBlock, type FolioAIBlockAnchor, type FolioAIBlockKind, type FolioAIBlockPreviewRun, type FolioAIBlockTableLocation, type FolioAIComment, type FolioAIEditAppliedOperation, type FolioAIEditApplyMode, type FolioAIEditApplyOutcome, type FolioAIEditApplyResult, type FolioAIEditNormalization, type FolioAIEditNormalizationCode, type FolioAIEditOperation, type FolioAIEditPrecondition, type FolioAIEditReviewMeta, type FolioAIEditSeverity, type FolioAIEditSkipReason, type FolioAIEditSkippedOperation, type FolioAIEditSnapshot, type FolioAISignatureParty, type FolioBlockId, type FolioDocumentOperation, type FolioDocumentOperationAffectedTarget, type FolioDocumentOperationBatch, type FolioDocumentOperationCapabilities, type FolioDocumentOperationIssue, type FolioDocumentOperationMode, type FolioDocumentOperationPrecondition, type FolioDocumentOperationReceipt, type FolioDocumentOperationRecovery, type FolioDocumentOperationResult, type FolioDocumentOperationResultBase, type FolioDocumentOperationStatus, type FolioDocumentOperationStory, type FolioDocumentOperationType, type FolioDocumentOperationUndoFailureReason, type FolioDocumentOperationUndoHandle, type FolioDocumentOperationUndoResult, type FolioDocxCompatibilityHost, type FolioDocxCompatibilityProfile, type FolioRevisionStamp, type FolioWordDiffOptions, type ImageMeta, type ImageRef, type InspectDocxCompatibilityOptions, InvalidCompareDocxOptionsError, InvalidFolioDocumentOperationBatchError, MAX_COMPARE_OPERATIONS, type MarkdownOptions, type MarkdownResult, type PositionalText, type ResolvedAnchor, STELLA_STYLE_SET_NAME, type TemplatePreviewSpan, type TemplatePreviewValue, type TemplatePreviewValues, type TemplateSlashMenuKeyAction, type TemplateSlashMenuState, UnsupportedFolioDocumentOperationVersionError, WORD_DIFF_GRANULARITIES, type WordDiffGranularity, type WordDiffNormalization, type WordDiffOptions, type WordDiffSegment, acceptAutocompleteSuggestion, acceptAutocompleteWord, anonymizationDecorationsKey, appendAutocompleteToken, applyFolioAIEditOperations, applyFolioDocumentOperations, applySuggestions, assertSupportedFolioDocumentOperationVersion, autocompleteSuggestionKey, autocompleteSuggestionPlugin, buildEmbeddedFontFamilyMap, buildPositionalText, clearAutocompleteSuggestion, clearTemplateSlashMenu, compareDocx, consumeTemplateSlashQuery, createAICitationDecorationsPlugin, createDocx, createEmptyDocument, createFolioAIEditSnapshot, createStellaStyleDocumentPreset, createStellaStyleSet, deriveBlockId, diffWordSegments, extractDocumentStyleSet, extractDocumentStyleSetFromDocx, extractEmbeddedFonts, finishAutocompleteSuggestion, fromMarkdown, getAnonymizationMatches, getAutocompleteSuggestion, getEmbeddedFontFaces, getFolioCaretViewportRect, getFolioDocumentOperationCapabilities, getFolioDocumentOperationIssues, getFolioDocumentOperationReceipts, getFolioParaIdFromBlockId, getFolioSelectionViewportRect, getGoogleFontsEnabled, getTemplateDirectives, getTemplateSlashMenu, hashFolioAIBlockText, inspectDocumentStyles, inspectDocumentStylesFromDocx, inspectDocxCompatibility, isFolioAIContentBlock, isFolioBlockId, isFolioDocumentOperationModeSupported, isSequentialFolioBlockId, isSuggestionStale, isSupportedFolioDocumentOperationVersion, mergeDocumentContent, normalizeFolioAIBlockText, parseFolioDocumentOperationBatch, resetTemplateSlashQuery, resolveSuggestionAnchor, scanDirectives, scopeEmbeddedFontFamily, scrollFolioPositionIntoView, setAICitationsMeta, setAISuggestionsMeta, setActiveCitationMeta, setAnonymizationTermsMeta, setEmbeddedFontFamilyMap, setFocusedSuggestionMeta, setGoogleFontsEnabled, setTemplatePreviewValues, shouldTriggerAutocomplete, startAutocompleteSuggestion, templateSlashMenuKey, toMarkdown, toMarkdownResult };

package/dist/compat/eigenpal.js

@@ -1,10 +1,13 @@
 import { applyFolioAIEditOperations } from "../ai-edits/apply.js";
-import { createFolioAIEditSnapshot, hashFolioAIBlockText, normalizeFolioAIBlockText } from "../ai-edits/snapshot.js";
-import { diffWordSegments } from "../ai-edits/word-diff.js";
+import { createFolioAIEditSnapshot, hashFolioAIBlockText, isFolioAIContentBlock, normalizeFolioAIBlockText } from "../ai-edits/snapshot.js";
+import { WORD_DIFF_GRANULARITIES, diffWordSegments } from "../ai-edits/word-diff.js";
 import { applySuggestions } from "../ai-suggestions/apply.js";
 import { isSuggestionStale, resolveSuggestionAnchor } from "../ai-suggestions/conflict.js";
 import { buildPositionalText } from "../ai-suggestions/text-positions.js";
 import { DEFAULT_AI_SUGGESTION_PRESETS } from "../ai-suggestions/types.js";
+import { MAX_COMPARE_OPERATIONS, compareDocx } from "../compare/compare.js";
+import { COMPARE_UNSUPPORTED_REASONS, CompareDocxApplyError, CompareDocxOperationLimitError, CompareDocxParseError, CompareDocxRoundTripError, CompareDocxSerializeError, InvalidCompareDocxOptionsError } from "../compare/types.js";
+import { COMPARE_VERIFICATION_CAUSES, COMPARE_VERIFICATION_INVARIANTS } from "../compare/verification.js";
 import { FOLIO_DOCUMENT_OPERATION_BATCH_MODES, FOLIO_DOCUMENT_OPERATION_CONTRACT_VERSION, FOLIO_DOCUMENT_OPERATION_MODES, FOLIO_DOCUMENT_OPERATION_MODES_BY_TYPE, FOLIO_DOCUMENT_OPERATION_PRECONDITIONS, FOLIO_DOCUMENT_OPERATION_STORIES, FOLIO_DOCUMENT_OPERATION_TYPES, InvalidFolioDocumentOperationBatchError, UnsupportedFolioDocumentOperationVersionError, applyFolioDocumentOperations, assertSupportedFolioDocumentOperationVersion, getFolioDocumentOperationCapabilities, getFolioDocumentOperationIssues, getFolioDocumentOperationReceipts, isFolioDocumentOperationModeSupported, isSupportedFolioDocumentOperationVersion, parseFolioDocumentOperationBatch } from "../document-operations.js";
 import { inspectDocxCompatibility } from "../docx/compatibility.js";
 import { createDocx } from "../docx/rezip.js";
@@ -28,4 +31,4 @@ import { deriveBlockId, getFolioParaIdFromBlockId, isFolioBlockId, isSequentialF
 import { createEmptyDocument } from "../utils/createDocument.js";
 import { getGoogleFontsEnabled, setEmbeddedFontFamilyMap, setGoogleFontsEnabled } from "../utils/fontResolver.js";
 import { mergeDocumentContent } from "../utils/mergeDocumentContent.js";
-export { DEFAULT_AI_SUGGESTION_PRESETS, DEFAULT_AUTOCOMPLETE_DEAD_ZONE_NODES, DOCUMENT_PRESET_VERSION, DOCUMENT_STYLE_SET_VERSION, DOCX_CONFORMANCE_CLASSES, FOLIO_DOCUMENT_OPERATION_BATCH_MODES, FOLIO_DOCUMENT_OPERATION_CONTRACT_VERSION, FOLIO_DOCUMENT_OPERATION_MODES, FOLIO_DOCUMENT_OPERATION_MODES_BY_TYPE, FOLIO_DOCUMENT_OPERATION_PRECONDITIONS, FOLIO_DOCUMENT_OPERATION_STORIES, FOLIO_DOCUMENT_OPERATION_TYPES, InvalidFolioDocumentOperationBatchError, STELLA_STYLE_SET_NAME, UnsupportedFolioDocumentOperationVersionError, acceptAutocompleteSuggestion, acceptAutocompleteWord, anonymizationDecorationsKey, appendAutocompleteToken, applyFolioAIEditOperations, applyFolioDocumentOperations, applySuggestions, assertSupportedFolioDocumentOperationVersion, autocompleteSuggestionKey, autocompleteSuggestionPlugin, buildEmbeddedFontFamilyMap, buildPositionalText, clearAutocompleteSuggestion, clearTemplateSlashMenu, consumeTemplateSlashQuery, createAICitationDecorationsPlugin, createDocx, createEmptyDocument, createFolioAIEditSnapshot, createStellaStyleDocumentPreset, createStellaStyleSet, deriveBlockId, diffWordSegments, extractDocumentStyleSet, extractDocumentStyleSetFromDocx, extractEmbeddedFonts, finishAutocompleteSuggestion, fromMarkdown, getAnonymizationMatches, getAutocompleteSuggestion, getEmbeddedFontFaces, getFolioCaretViewportRect, getFolioDocumentOperationCapabilities, getFolioDocumentOperationIssues, getFolioDocumentOperationReceipts, getFolioParaIdFromBlockId, getFolioSelectionViewportRect, getGoogleFontsEnabled, getTemplateDirectives, getTemplateSlashMenu, hashFolioAIBlockText, inspectDocumentStyles, inspectDocumentStylesFromDocx, inspectDocxCompatibility, isFolioBlockId, isFolioDocumentOperationModeSupported, isSequentialFolioBlockId, isSuggestionStale, isSupportedFolioDocumentOperationVersion, mergeDocumentContent, normalizeFolioAIBlockText, parseFolioDocumentOperationBatch, resetTemplateSlashQuery, resolveSuggestionAnchor, scanDirectives, scopeEmbeddedFontFamily, scrollFolioPositionIntoView, setAICitationsMeta, setAISuggestionsMeta, setActiveCitationMeta, setAnonymizationTermsMeta, setEmbeddedFontFamilyMap, setFocusedSuggestionMeta, setGoogleFontsEnabled, setTemplatePreviewValues, shouldTriggerAutocomplete, startAutocompleteSuggestion, templateSlashMenuKey, toMarkdown, toMarkdownResult };
+export { COMPARE_UNSUPPORTED_REASONS, COMPARE_VERIFICATION_CAUSES, COMPARE_VERIFICATION_INVARIANTS, CompareDocxApplyError, CompareDocxOperationLimitError, CompareDocxParseError, CompareDocxRoundTripError, CompareDocxSerializeError, DEFAULT_AI_SUGGESTION_PRESETS, DEFAULT_AUTOCOMPLETE_DEAD_ZONE_NODES, DOCUMENT_PRESET_VERSION, DOCUMENT_STYLE_SET_VERSION, DOCX_CONFORMANCE_CLASSES, FOLIO_DOCUMENT_OPERATION_BATCH_MODES, FOLIO_DOCUMENT_OPERATION_CONTRACT_VERSION, FOLIO_DOCUMENT_OPERATION_MODES, FOLIO_DOCUMENT_OPERATION_MODES_BY_TYPE, FOLIO_DOCUMENT_OPERATION_PRECONDITIONS, FOLIO_DOCUMENT_OPERATION_STORIES, FOLIO_DOCUMENT_OPERATION_TYPES, InvalidCompareDocxOptionsError, InvalidFolioDocumentOperationBatchError, MAX_COMPARE_OPERATIONS, STELLA_STYLE_SET_NAME, UnsupportedFolioDocumentOperationVersionError, WORD_DIFF_GRANULARITIES, acceptAutocompleteSuggestion, acceptAutocompleteWord, anonymizationDecorationsKey, appendAutocompleteToken, applyFolioAIEditOperations, applyFolioDocumentOperations, applySuggestions, assertSupportedFolioDocumentOperationVersion, autocompleteSuggestionKey, autocompleteSuggestionPlugin, buildEmbeddedFontFamilyMap, buildPositionalText, clearAutocompleteSuggestion, clearTemplateSlashMenu, compareDocx, consumeTemplateSlashQuery, createAICitationDecorationsPlugin, createDocx, createEmptyDocument, createFolioAIEditSnapshot, createStellaStyleDocumentPreset, createStellaStyleSet, deriveBlockId, diffWordSegments, extractDocumentStyleSet, extractDocumentStyleSetFromDocx, extractEmbeddedFonts, finishAutocompleteSuggestion, fromMarkdown, getAnonymizationMatches, getAutocompleteSuggestion, getEmbeddedFontFaces, getFolioCaretViewportRect, getFolioDocumentOperationCapabilities, getFolioDocumentOperationIssues, getFolioDocumentOperationReceipts, getFolioParaIdFromBlockId, getFolioSelectionViewportRect, getGoogleFontsEnabled, getTemplateDirectives, getTemplateSlashMenu, hashFolioAIBlockText, inspectDocumentStyles, inspectDocumentStylesFromDocx, inspectDocxCompatibility, isFolioAIContentBlock, isFolioBlockId, isFolioDocumentOperationModeSupported, isSequentialFolioBlockId, isSuggestionStale, isSupportedFolioDocumentOperationVersion, mergeDocumentContent, normalizeFolioAIBlockText, parseFolioDocumentOperationBatch, resetTemplateSlashQuery, resolveSuggestionAnchor, scanDirectives, scopeEmbeddedFontFamily, scrollFolioPositionIntoView, setAICitationsMeta, setAISuggestionsMeta, setActiveCitationMeta, setAnonymizationTermsMeta, setEmbeddedFontFamilyMap, setFocusedSuggestionMeta, setGoogleFontsEnabled, setTemplatePreviewValues, shouldTriggerAutocomplete, startAutocompleteSuggestion, templateSlashMenuKey, toMarkdown, toMarkdownResult };

package/dist/controller/layoutPipeline.d.ts

@@ -7,6 +7,7 @@ import { ConvertHeaderFooterOptions, HeaderFooterMetrics } from "../layout-bridg
 import "../layout-engine/index.js";
 import { FootnoteRenderItem } from "../layout-painter/renderPage.js";
 import { BlockLookup, LayoutPainter } from "../layout-painter/index.js";
+import { PageRendererName } from "../display-list/editor/pageRenderer.js";
 import { LayoutSelectionGate } from "../paged-layout/LayoutSelectionGate.js";
 import { LayoutSession } from "./layoutSession.js";
 import { EditorState } from "prosemirror-state";
@@ -59,6 +60,18 @@ type LayoutPipelineDeps<THfPMs> = {
   documentFontsAreLoaded: () => boolean;
   buildFootnoteRenderItems: (pageFootnoteMap: Map<number, number[]>, footnoteContentMap: Map<number, FootnoteContent>, doc: document_d_exports.Document | null) => Map<number, FootnoteRenderItem[]>;
   describeInvalidHighlightMarks: (doc: EditorState["doc"]) => string;
+  /**
+   * Which renderer paints the pages. `"legacy"` is the painter that has always
+   * painted them; `"display-list"` builds the painter-neutral paint IR from
+   * this layout and paints the pages from it, so the editor and an export draw
+   * from one structure.
+   *
+   * Only the *painting* is swapped. Page shells, virtualization, the
+   * fingerprint comparison that skips an unchanged page and the painted event
+   * are page-container concerns and stay shared, because a second copy of them
+   * is how incremental repaint would quietly stop working on long documents.
+   */
+  pageRenderer?: PageRendererName;
   emptyTemplatePreviewEntries: readonly TemplatePreviewEntry[];
 };
 declare function runLayoutPipeline<THfPMs>(deps: LayoutPipelineDeps<THfPMs>, state: EditorState, options?: LayoutRunOptions): LayoutOutcome;

package/dist/controller/layoutPipeline.js

@@ -1,3 +1,5 @@
+import { createDisplayListPagePainter } from "../display-list/editor/displayListPagePainter.js";
+import { PAGE_RENDERER, displayListFurnitureFrom } from "../display-list/editor/pageRenderer.js";
 import { resolveDocumentGridLinePitch } from "../docx/documentGrid.js";
 import { buildBookmarkPageMap } from "../fields/bookmarkPages.js";
 import { buildBookmarkText } from "../fields/bookmarkText.js";
@@ -15,6 +17,7 @@ import { recordLayoutComplete, recordLayoutError, recordLayoutPhase, recordLayou
 import { measureBlocks, measureSingleBlockWithoutFloatingZones } from "../layout-engine/measure/measureBlocks.js";
 import { installCanvasMeasureProvider } from "../layout-engine/measure/measureContainer.js";
 import { resolveEffectiveParagraphSpacingTree } from "../layout-engine/paragraphSpacing.js";
+import { resolveTableIndentCompatibility } from "../layout-engine/tableIndentCompatibility.js";
 import "../layout-engine/types.js";
 import { renderPages } from "../layout-painter/renderPage.js";
 import { tryBuildIncrementalMeasures } from "../paged-layout/incrementalMeasure.js";
@@ -84,7 +87,7 @@ function attachAuthoredMarginsToLayoutPages(layout, options) {
 	} : layout;
 }
 function runLayoutPipeline(deps, state, options = {}) {
-	const { contentWidth, columns, pageSize, margins, pageGap, showMarginGuides, marginGuideColor, syncCoordinator, headerContent, footerContent, firstPageHeaderContent, firstPageFooterContent, headerContentRId, footerContentRId, firstPageHeaderContentRId, firstPageFooterContentRId, sectionHeaderFooterRefs, theme: _theme, sectionProperties, document, defaultTabStop, mirrorMargins, styles, layout, hfPMs, painter, pagesContainer, session, renderHfFromContentOrPm, renderHeaderFooterContentByRId, documentFontsAreLoaded, buildFootnoteRenderItems, describeInvalidHighlightMarks, emptyTemplatePreviewEntries: EMPTY_TEMPLATE_PREVIEW_ENTRIES } = deps;
+	const { contentWidth, columns, pageSize, margins, pageGap, showMarginGuides, marginGuideColor, syncCoordinator, headerContent, footerContent, firstPageHeaderContent, firstPageFooterContent, headerContentRId, footerContentRId, firstPageHeaderContentRId, firstPageFooterContentRId, sectionHeaderFooterRefs, theme: _theme, sectionProperties, document, defaultTabStop, mirrorMargins, styles, layout, hfPMs, painter, pagesContainer, session, renderHfFromContentOrPm, renderHeaderFooterContentByRId, documentFontsAreLoaded, buildFootnoteRenderItems, describeInvalidHighlightMarks, pageRenderer = PAGE_RENDERER.legacy, emptyTemplatePreviewEntries: EMPTY_TEMPLATE_PREVIEW_ENTRIES } = deps;
 	let outcome = {};
 	let pendingArtifacts;
 	let pendingTemplatePreview;
@@ -110,6 +113,8 @@ function runLayoutPipeline(deps, state, options = {}) {
 		const documentSettings = document?.package.settings;
 		const justificationCompatibility = resolveJustificationCompatibility(documentSettings?.compatibilityMode);
 		if (justificationCompatibility) flowOpts.justificationCompatibility = justificationCompatibility;
+		const tableIndentCompatibility = resolveTableIndentCompatibility(documentSettings?.compatibilityMode);
+		if (tableIndentCompatibility) flowOpts.tableIndentCompatibility = tableIndentCompatibility;
 		if (documentSettings?.autoHyphenation === true) flowOpts.automaticHyphenation = {
 			enabled: true,
 			...documentSettings.doNotHyphenateCaps !== void 0 ? { doNotHyphenateCaps: documentSettings.doNotHyphenateCaps } : {},
@@ -166,6 +171,7 @@ function runLayoutPipeline(deps, state, options = {}) {
 				...defaultTabStop !== void 0 ? { defaultTabStopTwips: defaultTabStop } : {},
 				...flowOpts.lineBreakRules ? { lineBreakRules: flowOpts.lineBreakRules } : {},
 				...flowOpts.justificationCompatibility ? { justificationCompatibility: flowOpts.justificationCompatibility } : {},
+				...flowOpts.tableIndentCompatibility ? { tableIndentCompatibility: flowOpts.tableIndentCompatibility } : {},
 				...flowOpts.automaticHyphenation ? { automaticHyphenation: flowOpts.automaticHyphenation } : {}
 			};
 		};
@@ -312,6 +318,7 @@ function runLayoutPipeline(deps, state, options = {}) {
 				if (defaultTabStop !== void 0) footnoteOptions.defaultTabStopTwips = defaultTabStop;
 				if (flowOpts.lineBreakRules) footnoteOptions.lineBreakRules = flowOpts.lineBreakRules;
 				if (flowOpts.justificationCompatibility) footnoteOptions.justificationCompatibility = flowOpts.justificationCompatibility;
+				if (flowOpts.tableIndentCompatibility) footnoteOptions.tableIndentCompatibility = flowOpts.tableIndentCompatibility;
 				if (flowOpts.automaticHyphenation) footnoteOptions.automaticHyphenation = flowOpts.automaticHyphenation;
 				return footnoteOptions;
 			})());
@@ -479,6 +486,13 @@ function runLayoutPipeline(deps, state, options = {}) {
 					if (watermarkByHeaderRId.size > 0) renderOpts.watermarkByHeaderRId = watermarkByHeaderRId;
 				}
 			}
+			if (pageRenderer === PAGE_RENDERER.displayList) renderOpts.paintPage = createDisplayListPagePainter({
+				layout: newLayout,
+				blockLookup,
+				doc: pagesContainer.ownerDocument,
+				...displayListFurnitureFrom(renderOpts),
+				...footnoteContentMap.size === 0 ? {} : { footnoteContentById: footnoteContentMap }
+			}).paintPage;
 			renderPages(newLayout.pages, pagesContainer, renderOpts);
 			recordPhaseDuration("render-pages", phaseStartedAt);
 		}

package/dist/display-list/build/buildContext.d.ts

@@ -0,0 +1,39 @@
+import { DisplayColor, DisplayLink, DisplayLinkTarget, DisplayStoryRef } from "../types.js";
+import { FontTable } from "./fontTable.js";
+import { ImageTable } from "./imagePrimitives.js";
+import { UnsupportedCollector } from "./unsupported.js";
+//#region src/display-list/build/buildContext.d.ts
+/** Word's per-author redline palette, assigned in first-seen order per build. */
+declare class AuthorColorTable {
+  private readonly indexByAuthor;
+  colorFor(author: string | undefined): DisplayColor;
+}
+/** Colour a tracked change paints in: the author's hue, or the proposal hue. */
+declare const trackedChangeColor: (authorColors: AuthorColorTable, changeAuthor: string | undefined, isSuggestion: boolean | undefined) => DisplayColor;
+/**
+ * Which OOXML story the primitives being built belong to, named precisely
+ * enough to address it: a document has many headers and many notes, and a
+ * position only means something against one of them.
+ */
+type DisplayStory = DisplayStoryRef;
+type BuildContext = {
+  readonly fonts: FontTable;
+  readonly images: ImageTable;
+  readonly unsupported: UnsupportedCollector;
+  readonly authorColors: AuthorColorTable;
+  /** Link sink for the page being built. */
+  readonly links: DisplayLink[];
+  /**
+   * Bookmark name → where it lands, collected in a first pass over the layout.
+   * A `#name` hyperlink can only become a `page` target once every page is
+   * known, which is why this is resolved before any page is painted.
+   */
+  readonly bookmarkTargets: ReadonlyMap<string, DisplayLinkTarget>;
+  readonly story: DisplayStory;
+  readonly pageIndex: number;
+  /** Authored page number, for `PAGE` fields. */
+  readonly pageNumber: number;
+  readonly totalPages: number;
+};
+//#endregion
+export { AuthorColorTable, BuildContext, DisplayStory, trackedChangeColor };

package/dist/display-list/build/buildContext.js

@@ -0,0 +1,31 @@
+import { AUTHOR_COLORS } from "../../utils/authorColors.js";
+import { SUGGESTION_COLOR, parseDisplayColor } from "./colors.js";
+//#region src/display-list/build/buildContext.ts
+/**
+* State threaded through one `buildDisplayList` call.
+*
+* Everything mutable the builder needs lives here so the builder itself stays a
+* pure function of its arguments: the font table, the image table, the
+* unsupported log and the author-colour assignment are all born and die inside
+* a single call. `utils/authorColors.ts`'s `getAuthorColorIdx` deliberately is
+* not used: it keeps a module-level map, so the colour an author gets depends
+* on which documents the process opened earlier, and two builds of the same
+* layout would not compare equal.
+*/
+/** Word's per-author redline palette, assigned in first-seen order per build. */
+var AuthorColorTable = class {
+	indexByAuthor = /* @__PURE__ */ new Map();
+	colorFor(author) {
+		const key = author ?? "";
+		let index = this.indexByAuthor.get(key);
+		if (index === void 0) {
+			index = this.indexByAuthor.size % AUTHOR_COLORS.length;
+			this.indexByAuthor.set(key, index);
+		}
+		return parseDisplayColor(AUTHOR_COLORS[index]) ?? SUGGESTION_COLOR;
+	}
+};
+/** Colour a tracked change paints in: the author's hue, or the proposal hue. */
+const trackedChangeColor = (authorColors, changeAuthor, isSuggestion) => isSuggestion ? SUGGESTION_COLOR : authorColors.colorFor(changeAuthor);
+//#endregion
+export { AuthorColorTable, trackedChangeColor };

package/dist/display-list/build/buildDisplayList.d.ts

@@ -0,0 +1,79 @@
+import { EmbeddedFont } from "../../fonts/embeddedFonts.js";
+import { Layout } from "../../layout-engine/types.js";
+import { BlockLookup } from "../../layout-painter/index.js";
+import { DisplayColor, DisplayList, DisplayMetadata, DisplayPage } from "../types.js";
+import { PageFurnitureInputs } from "./furniture.js";
+//#region src/display-list/build/buildDisplayList.d.ts
+/**
+ * Every feature a source document can have that a `Layout` does not record and
+ * that nothing on a page betrays, with the reason it paints nothing when the
+ * caller supplies neither the construct nor a flag denying it. The list is the
+ * single source of truth: {@link DocumentFeatures} is derived from it, so a
+ * feature added here cannot be left without a flag or without a reason.
+ *
+ * Footnote bodies and header/footer stories are deliberately absent: a page
+ * that carries them says so itself (`footnoteIds`, `headerFooterRefs`), so
+ * their gaps are reported per page from the layout rather than from a
+ * document-wide flag the caller would have to remember to set.
+ */
+declare const DOCUMENT_FEATURE_GAPS: readonly [readonly ["pageBorders", "w:pgBorders reach the painter through render options, not through Layout, and none were supplied to the builder"], readonly ["watermark", "watermarks reach the painter through render options, not through Layout, and none was supplied to the builder"]];
+/**
+ * Which of those features the source document actually has. The builder cannot
+ * detect them, so the caller that parsed the document states it.
+ */
+type DocumentFeatures = { readonly [Feature in (typeof DOCUMENT_FEATURE_GAPS)[number][0]]: boolean; };
+type BuildDisplayListOptions = PageFurnitureInputs & {
+  readonly layout: Layout;
+  readonly blockLookup: BlockLookup;
+  readonly metadata?: DisplayMetadata;
+  /** Page background. Defaults to opaque white: the PDF has no theme. */
+  readonly pageBackground?: DisplayColor;
+  /**
+   * States, for each construct in {@link DOCUMENT_FEATURE_GAPS}, whether the
+   * document has one at all. Omitted means unknown, and an unknown document is
+   * reported as having both: a silent gap is worse than one the reader can
+   * dismiss. A construct supplied through {@link PageFurnitureInputs} is
+   * painted and never reported, whatever this says.
+   */
+  readonly documentFeatures?: DocumentFeatures;
+  /**
+   * The package's own font faces (`fonts/embeddedFonts.ts`). Absent: a face the
+   * measurer resolved to an embedded family travels as a name, and a backend
+   * that cannot find that name on the host paints the document in a substitute.
+   */
+  readonly embeddedFonts?: readonly EmbeddedFont[];
+};
+/**
+ * A document's display list, one page at a time.
+ *
+ * The tables a page refers to (faces, images), the bookmark targets a link can
+ * resolve against, and the outline are properties of the whole document, so
+ * they are computed once; a page's primitives are not, and an editor paints a
+ * window of pages rather than all of them. Building every page to paint three
+ * of them is the difference between work proportional to the screen and work
+ * proportional to the document, which on a long one is the difference a reader
+ * feels on every keystroke.
+ *
+ * A page is built at most once. `snapshot` returns what has been built so far,
+ * so a caller that wants the whole list asks for every page first — which is
+ * what {@link buildDisplayList} does.
+ */
+type DisplayListBuilder = {
+  readonly pageCount: number;
+  /** The page at that index, built on first request and kept. */
+  readonly pageAt: (pageIndex: number) => DisplayPage | undefined;
+  /**
+   * The list as far as it has been built. The tables grow as pages are built,
+   * so a backend reads them after the page it is about to paint, never before.
+   */
+  readonly snapshot: () => DisplayList;
+};
+declare const createDisplayListBuilder: ({ layout, blockLookup, metadata, pageBackground, documentFeatures, embeddedFonts, ...furniture }: BuildDisplayListOptions) => DisplayListBuilder;
+/**
+ * The whole document's display list. Every page is built, so the tables, the
+ * outline and the gap report are complete; an editor that paints a window of
+ * pages uses {@link createDisplayListBuilder} instead.
+ */
+declare const buildDisplayList: (options: BuildDisplayListOptions) => DisplayList;
+//#endregion
+export { BuildDisplayListOptions, DisplayListBuilder, DocumentFeatures, buildDisplayList, createDisplayListBuilder };