@stll/folio-core 0.52.0 → 0.54.0

package/dist/compare/inline-atoms.js

@@ -1,10 +1,14 @@
 import { buildCleanBlockText } from "../ai-edits/clean-text.js";
-import { sourceDocumentOf } from "../ai-edits/snapshot.js";
+import { noteReferenceOf } from "../ai-edits/note-references.js";
+import { collectNoteReferenceLabels, sourceDocumentOf } from "../ai-edits/snapshot.js";
+import { drawingXmlWithoutIdentity } from "../docx/drawingIdNormalization.js";
 import { resolveAllChangesInHeadlessStateWithMapping } from "../prosemirror/commands/comments.js";
 import { runFormattingInlineAtomResultText } from "../prosemirror/runFormattingInlineCarriers.js";
 import { canonicalJson } from "../utils/canonicalJson.js";
 import { prepareTargetInlineAtom } from "./inline-atom-resources.js";
 //#region src/compare/inline-atoms.ts
+/** A revised reference names a note the redline's package does not have. */
+const MISSING_NOTE_DETAIL = "a note reference names a footnote or endnote the base document does not have";
 const actionRangeCount = (action) => action.kind === "replace-text" && action.textDisposition === "retained" || action.kind === "replace-atom" && action.atomDisposition === "retained" ? 2 : 1;
 const MAX_INLINE_ATOM_LCS_CELLS = 16384;
 const isSupportedAtom = (node) => node.isInline && node.isAtom && (node.type.name === "field" || node.type.name === "image" || node.type.name === "pageBreakRun");
@@ -65,6 +69,11 @@ const offsetAt = ({ offsets, position }) => {
 */
 const CONVERSION_LOCAL_ATTRS = { textBoxAnchor: ["anchorId"] };
 const documentFactAttrs = (node) => {
+	if (node.type.name === "field" || node.type.name === "structuredField") {
+		const equivalentFieldForms = node.type.name === "field" && (node.attrs["fieldKind"] === "simple" || node.attrs["fieldKind"] === "complex") && node.attrs["fieldResultIsFallback"] == null;
+		return Object.fromEntries(Object.entries(node.attrs).filter(([name]) => name !== "_docxFieldCode" && (!equivalentFieldForms || name !== "fieldKind")));
+	}
+	if (node.type.name === "image") return Object.fromEntries(Object.entries(node.attrs).filter(([name]) => name !== "docPrId").map(([name, value]) => [name, name === "_docxRawXml" && typeof value === "string" ? drawingXmlWithoutIdentity(value) : value]));
 	const local = CONVERSION_LOCAL_ATTRS[node.type.name];
 	if (!local) return node.attrs;
 	return Object.fromEntries(Object.entries(node.attrs).filter(([name]) => !local.includes(name)));
@@ -74,8 +83,22 @@ const atomKey = (node) => canonicalJson({
 	attrs: documentFactAttrs(node),
 	content: node.content.toJSON()
 });
-const atomBlockOf = ({ node, from }, fieldResults) => {
-	const clean = buildCleanBlockText(node, from, { fieldResults });
+const atomBlockOf = ({ node, from }, fieldResults, noteReferences) => {
+	const clean = buildCleanBlockText(node, from, {
+		fieldResults,
+		noteReferences
+	});
+	const references = [];
+	for (const boundary of clean.structuralBoundaries) {
+		if (boundary.type !== "noteReference") continue;
+		references.push({
+			noteType: boundary.noteType,
+			noteId: boundary.noteId,
+			offset: boundary.offset,
+			length: boundary.length,
+			from: boundary.from
+		});
+	}
 	const supported = [];
 	const unsupportedTopology = [];
 	node.descendants((child, relativePosition) => {
@@ -116,7 +139,8 @@ const atomBlockOf = ({ node, from }, fieldResults) => {
 		cleanText: clean.text,
 		offsets: clean.offsets,
 		supported,
-		unsupportedTopology
+		unsupportedTopology,
+		noteReferences: references
 	};
 };
 const targetBlockIdLookup = (snapshot) => {
@@ -138,7 +162,44 @@ const targetBlockIdLookup = (snapshot) => {
 		return owner?.id;
 	};
 };
-const atomBlocksOf = (doc, fieldResults) => textBlocksOf(doc).map((block) => atomBlockOf(block, fieldResults));
+const atomBlocksOf = (doc, fieldResults, noteReferences = "sourceText") => textBlocksOf(doc).map((block) => atomBlockOf(block, fieldResults, noteReferences));
+const noteReferenceKey = ({ noteType, noteId }) => `${noteType}:${noteId}`;
+/** Every note a story references, tracked-deleted references included. */
+const referencedNotesOf = (doc) => {
+	const notes = /* @__PURE__ */ new Set();
+	doc.descendants((node) => {
+		const reference = noteReferenceOf(node);
+		if (reference) notes.add(noteReferenceKey(reference));
+		return !node.isText;
+	});
+	return notes;
+};
+const hasNoteReference = (doc) => {
+	let found = false;
+	doc.descendants((node) => {
+		if (found) return false;
+		if (noteReferenceOf(node)) found = true;
+		return !node.isText;
+	});
+	return found;
+};
+/**
+* Whether this comparison inserted text that may stand for a note reference.
+* Operations carry clean text, where a reference reads as its marker, so an
+* operation that brings a reference writes the marker as text.
+*/
+const wroteNoteReferenceMarker = (doc, originalRevisionIdSeed) => {
+	let found = false;
+	doc.descendants((node) => {
+		if (found) return false;
+		if (!node.isText) return true;
+		if (!node.text?.includes("[^") || noteReferenceOf(node)) return false;
+		const revisionId = node.marks.find(({ type }) => type.name === "insertion")?.attrs["revisionId"];
+		if (typeof revisionId === "number" && revisionId >= originalRevisionIdSeed) found = true;
+		return false;
+	});
+	return found;
+};
 const sameBlockTopology = (left, right) => {
 	if (left.node.type !== right.node.type || left.cleanText !== right.cleanText) return false;
 	const supportedOffsets = /* @__PURE__ */ new Set([...left.supported.map(({ offset }) => offset), ...right.supported.map(({ offset }) => offset)]);
@@ -279,12 +340,15 @@ const sourceTextBlockIds = (source) => {
 	}
 	return blocks;
 };
-const sameParagraphSourcePosition = ({ sourceBlocks, reviewed, offset, fieldResults }) => {
+const sameParagraphSourcePosition = ({ sourceBlocks, reviewed, offset, fieldResults, noteReferences }) => {
 	const paraId = reviewed.node.attrs["paraId"];
 	if (typeof paraId !== "string" || paraId.length === 0) return null;
 	const source = sourceBlocks.get(paraId);
 	if (!source || source.node.type !== reviewed.node.type) return null;
-	const clean = buildCleanBlockText(source.node, source.from, { fieldResults });
+	const clean = buildCleanBlockText(source.node, source.from, {
+		fieldResults,
+		noteReferences
+	});
 	return clean.text === reviewed.cleanText ? clean.offsets[offset] ?? null : null;
 };
 const textRangeDisposition = ({ doc, from, to, expectedText, originalRevisionIdSeed }) => {
@@ -332,14 +396,17 @@ const atomDisposition = ({ atom, originalRevisionIdSeed }) => {
 	return typeof revisionId === "number" && revisionId >= originalRevisionIdSeed ? "inserted" : null;
 };
 /**
-* Restore field, image, and page-break atoms omitted by text-only comparison operations.
+* Restore field, image, and page-break atoms omitted by text-only comparison
+* operations, and the note references whose markers they wrote as text.
 * Positions come from the legacy review resolver's mapping, never a guessed
 * paragraph correspondence: paragraph-mark deletions can merge paragraphs.
 */
-const matchInlineAtoms = ({ state, targetSnapshot, revisionStamp, originalRevisionIdSeed, author, maxRanges }) => {
+const matchInlineAtoms = ({ state, targetSnapshot, revisionStamp, originalRevisionIdSeed, author, maxRanges, noteReferenceLabels, baseNotes }) => {
 	if (!Number.isSafeInteger(maxRanges) || maxRanges < 0) return { status: "budget-exceeded" };
 	const targetDocument = sourceDocumentOf(targetSnapshot);
-	if (!hasSupportedAtom(state.doc) && !hasSupportedAtom(targetDocument)) return {
+	const restoresNoteReferences = wroteNoteReferenceMarker(state.doc, originalRevisionIdSeed) && hasNoteReference(targetDocument);
+	const noteReferences = restoresNoteReferences ? noteReferenceLabels ?? collectNoteReferenceLabels(targetDocument) : "sourceText";
+	if (!restoresNoteReferences && !hasSupportedAtom(state.doc) && !hasSupportedAtom(targetDocument)) return {
 		status: "matched",
 		transaction: state.tr,
 		nextRevisionId: revisionStamp.idSeed,
@@ -349,8 +416,8 @@ const matchInlineAtoms = ({ state, targetSnapshot, revisionStamp, originalRevisi
 	const reviewed = resolveAllChangesInHeadlessStateWithMapping(state, "accept");
 	const targetBlockIdAt = targetBlockIdLookup(targetSnapshot);
 	let sourceBlocks;
-	const liveBlocks = atomBlocksOf(reviewed.state.doc, "text");
-	const targetBlocks = atomBlocksOf(targetDocument, "text");
+	const liveBlocks = atomBlocksOf(reviewed.state.doc, "text", noteReferences);
+	const targetBlocks = atomBlocksOf(targetDocument, "text", noteReferences);
 	if (liveBlocks.length !== targetBlocks.length) return { status: "unalignable" };
 	const actions = [];
 	let rangeCount = 0;
@@ -361,19 +428,63 @@ const matchInlineAtoms = ({ state, targetSnapshot, revisionStamp, originalRevisi
 		actions.push(action);
 		return true;
 	};
+	let referencedNotes;
 	let omittedLiveBlocks;
 	let omittedTargetBlocks;
 	for (const [index, fullLive] of liveBlocks.entries()) {
 		const fullTarget = targetBlocks[index];
 		if (!fullTarget) return { status: "unalignable" };
+		if ((fullLive.noteReferences.length > 0 || fullTarget.noteReferences.length > 0) && fullLive.cleanText === fullTarget.cleanText) {
+			const kept = new Map(fullLive.noteReferences.map((reference) => [reference.offset, reference]));
+			for (const reference of fullTarget.noteReferences) {
+				const live = kept.get(reference.offset);
+				if (live) {
+					kept.delete(reference.offset);
+					if (noteReferenceKey(live) !== noteReferenceKey(reference) || live.length !== reference.length) return { status: "unalignable" };
+					continue;
+				}
+				referencedNotes ??= baseNotes ?? referencedNotesOf(state.doc);
+				if (!referencedNotes.has(noteReferenceKey(reference))) return {
+					status: "unalignable",
+					detail: MISSING_NOTE_DETAIL
+				};
+				const node = targetDocument.nodeAt(reference.from);
+				const reviewedFrom = fullLive.offsets[reference.offset];
+				const reviewedLast = fullLive.offsets[reference.offset + reference.length - 1];
+				if (!node || !noteReferenceOf(node) || reviewedFrom === void 0 || reviewedLast === void 0) return { status: "unalignable" };
+				const from = mappedSourcePosition({
+					mapping: reviewed.mapping,
+					position: reviewedFrom
+				});
+				const to = mappedSourcePosition({
+					mapping: reviewed.mapping,
+					position: reviewedLast + 1
+				});
+				if (from === null || to === null || textRangeDisposition({
+					doc: state.doc,
+					from,
+					to,
+					expectedText: fullTarget.cleanText.slice(reference.offset, reference.offset + reference.length),
+					originalRevisionIdSeed
+				}) !== "inserted") return { status: "unalignable" };
+				if (!planAction({
+					kind: "note-reference",
+					from,
+					to,
+					node,
+					targetBlockId: targetBlockIdAt(fullTarget.from)
+				})) return { status: "budget-exceeded" };
+			}
+			if (kept.size > 0) return { status: "unalignable" };
+		}
 		if (fullLive.supported.length === 0 && fullTarget.supported.length === 0) continue;
 		if (sameSupportedAtoms(fullLive, fullTarget)) continue;
 		let live = fullLive;
 		let target = fullTarget;
 		let fieldResults = "text";
 		if (!sameBlockTopology(live, target)) {
-			omittedLiveBlocks ??= atomBlocksOf(reviewed.state.doc, "omitted");
-			omittedTargetBlocks ??= atomBlocksOf(targetDocument, "omitted");
+			omittedLiveBlocks ??= atomBlocksOf(reviewed.state.doc, "omitted", noteReferences);
+			omittedTargetBlocks ??= atomBlocksOf(targetDocument, "omitted", noteReferences);
 			const omittedLive = omittedLiveBlocks[index];
 			const omittedTarget = omittedTargetBlocks[index];
 			if (!omittedLive || !omittedTarget || !sameBlockTopology(omittedLive, omittedTarget)) return { status: "unalignable" };
@@ -441,7 +552,8 @@ const matchInlineAtoms = ({ state, targetSnapshot, revisionStamp, originalRevisi
 				sourceBlocks: sourceBlocks ??= sourceTextBlockIds(state.doc),
 				reviewed: live,
 				offset: atom.offset,
-				fieldResults
+				fieldResults,
+				noteReferences
 			});
 			if (from === null) return { status: "unalignable" };
 			const resultText = runFormattingInlineAtomResultText(atom.node);
@@ -520,6 +632,16 @@ const matchInlineAtoms = ({ state, targetSnapshot, revisionStamp, originalRevisi
 			if (action.targetBlockId) changedTargetBlockIds.add(action.targetBlockId);
 			continue;
 		}
+		if (action.kind === "note-reference") {
+			const from = transaction.mapping.map(action.from, 1);
+			const to = transaction.mapping.map(action.to, -1);
+			const written = transaction.doc.nodeAt(from);
+			const noteMark = action.node.marks.find(({ type }) => type.name === "footnoteRef");
+			if (from >= to || !written?.isText || !noteMark) return { status: "unalignable" };
+			transaction.replaceWith(from, to, state.schema.text(action.node.text ?? "", noteMark.addToSet(written.marks)));
+			if (action.targetBlockId) changedTargetBlockIds.add(action.targetBlockId);
+			continue;
+		}
 		if (action.kind === "replace-atom") {
 			const from = transaction.mapping.map(action.from, 1);
 			const to = transaction.mapping.map(action.to, -1);
@@ -581,4 +703,4 @@ const sameInlineAtoms = (leftDocument, rightDocument) => {
 	});
 };
 //#endregion
-export { matchInlineAtoms, sameInlineAtoms };
+export { MISSING_NOTE_DETAIL, matchInlineAtoms, sameInlineAtoms };

package/dist/compare/inline-provenance.js

@@ -1,6 +1,6 @@
 import { sourceDocumentOf, styleResolverOf } from "../ai-edits/snapshot.js";
 import { expectHyperlinkMarkAttrs, expectRunPropertyChangeMarkAttrs, expectTableCellAttrs } from "../prosemirror/attrs/index.js";
-import { getDocumentStyleResolver } from "../prosemirror/plugins/documentStyles.js";
+import { getDocumentStyleResolver } from "../prosemirror/plugins/documentStyleState.js";
 import { applyMarksToRunFormattingRepresentation, expandRunFormattingCarrier, runFormattingCarrierReviewText } from "../prosemirror/runFormattingInlineCarriers.js";
 import { readAuthoredRunFormatting, reconcileRunFormattingMarks } from "../prosemirror/runFormattingReconciliation.js";
 import { nearestParagraphRunStyleContext } from "../prosemirror/runStyleFormatting.js";

package/dist/compare/plan.js

@@ -223,6 +223,7 @@ const shareAContainer = (left, right) => {
 /** Narrow the neutral patch to the operation contract without explicit undefined fields. */
 const toFolioAIBlockParagraphProperties = (properties) => ({
 	...properties.styleId !== void 0 && { styleId: properties.styleId },
+	...properties.outlineLevel !== void 0 && { outlineLevel: properties.outlineLevel },
 	...properties.listLevel !== void 0 && { listLevel: properties.listLevel },
 	...properties.listReference !== void 0 && { numbering: properties.listReference },
 	...properties.alignment !== void 0 && { alignment: properties.alignment },
@@ -594,18 +595,22 @@ const planStoryCompare = ({ story, baseSnapshot, targetSnapshot, maxOperations,
 		const moveSourceId = moveSourceByTargetBlockId.get(block.id);
 		const structuralBoundary = block.structuralBoundaries?.at(0);
 		const hardPageBreak = block.text.length === 0 && block.structuralBoundaries?.length === 1 && structuralBoundary?.type === "pageBreak" && structuralBoundary.offset === 0 ? { ...structuralBoundary.clear !== void 0 && { clear: structuralBoundary.clear } } : void 0;
-		const shared = {
-			text: block.text,
-			...(block.text.includes("	") || block.text.includes("\n")) && { lineBreakMode: "inline" },
-			...moveSourceId !== void 0 && { moveId: moveIdOf(moveSourceId) },
-			...hardPageBreak !== void 0 && { hardPageBreak },
+		const paragraphProperties = {
 			styleId: block.styleId ?? null,
+			outlineLevel: block.directOutlineLevel ?? null,
 			listLevel: block.listLevel ?? null,
 			numbering: block.listReference ?? null,
 			alignment: block.directAlignment ?? null,
 			spacing: block.directSpacing ?? null,
 			indentation: block.directIndentation ?? null
 		};
+		const shared = {
+			text: block.text,
+			...(block.text.includes("	") || block.text.includes("\n")) && { lineBreakMode: "inline" },
+			...moveSourceId !== void 0 && { moveId: moveIdOf(moveSourceId) },
+			...hardPageBreak !== void 0 && { hardPageBreak },
+			...paragraphProperties
+		};
 		if (anchorId !== null) {
 			operations.push({
 				id: nextOperationId(),

package/dist/compare/scenario.js

@@ -1,5 +1,6 @@
 import { FolioDocxReviewer } from "../ai-edits/headless.js";
 import { createFolioAITextRangeHandle } from "../ai-edits/snapshot.js";
+import "../document-operations.js";
 import { CompareDocxParseError, compareDocxSerializeError } from "./types.js";
 import { Result, panic } from "better-result";
 //#region src/compare/scenario.ts
@@ -234,14 +235,24 @@ const applyEditScript = async (base, script) => {
 			operations: plan.operations
 		});
 	}
-	const { skipped } = reviewer.applyOperations(planned.flatMap(({ operations }) => [...operations]), {
-		mode: "direct",
-		snapshot
+	const { skipped } = reviewer.applyDocumentOperationsToStory({
+		story: { type: "main" },
+		batch: {
+			version: 1,
+			mode: "direct",
+			operations: planned.flatMap(({ operations }) => [...operations])
+		},
+		snapshot,
+		undefinedStyles: "keep"
 	});
 	const skippedIds = new Set(skipped.map(({ id }) => id));
 	const applied = [];
 	for (const { step, operations } of planned) {
 		if (operations.some(({ id }) => skippedIds.has(id))) {
+			if (!operations.every(({ id }) => skippedIds.has(id))) panic("An edit script step was applied in part", {
+				step,
+				skipped
+			});
 			unresolved.push({
 				step,
 				reason: "refused"

package/dist/compare/section-boundary-properties.js

@@ -12,7 +12,7 @@ const boundaryChildrenOf = (document) => {
 	let hasChangeHistory = false;
 	document.forEach((node, position) => {
 		if (node.type.name !== "paragraph") {
-			if (node.type.name === "preservedBlock") return;
+			if (node.type.name === "preservedBlock" || node.type.name === "blockBookmarkBoundary") return;
 			children.push({
 				type: "other",
 				nodeType: node.type.name

package/dist/compare/types.d.ts

@@ -25,7 +25,9 @@ type CompareDocxOptions = {
    * redline that reads plausibly and is wrong is worse than no redline.
    * `"emit"` returns the redline anyway, with `verification` naming every
    * invariant that did not hold, for a caller that would rather show its best
-   * attempt and say what is missing.
+   * attempt and say what is missing. A reference to a note the base document
+   * does not have is refused either way: the redline would carry its marker
+   * as text that reads like a reference.
    */
   onUnverified?: "refuse" | "emit";
   /**
@@ -222,7 +224,7 @@ type CompareChange = {
   baseBlockIds: readonly string[];
 };
 /** Why a part of the package is absent from `changes`. */
-declare const COMPARE_UNSUPPORTED_REASONS: readonly ["story-missing-in-base", "story-missing-in-target", "story-not-editable"];
+declare const COMPARE_UNSUPPORTED_REASONS: readonly ["story-missing-in-base", "story-missing-in-target", "story-not-editable", "unsupported-content"];
 type CompareUnsupportedReason = (typeof COMPARE_UNSUPPORTED_REASONS)[number];
 /**
  * A package part the comparison did not cover. Reported rather than dropped so

package/dist/compare/types.js

@@ -10,7 +10,8 @@ const COMPARE_REVISION_FORMATS = ["word", "folio-exact"];
 const COMPARE_UNSUPPORTED_REASONS = Object.freeze([
 	"story-missing-in-base",
 	"story-missing-in-target",
-	"story-not-editable"
+	"story-not-editable",
+	"unsupported-content"
 ]);
 var InvalidCompareDocxOptionsError = class extends TaggedError("InvalidCompareDocxOptionsError") {};
 var CompareDocxParseError = class extends TaggedError("CompareDocxParseError") {};

package/dist/compare/verification.d.ts

@@ -33,7 +33,7 @@ type CompareVerification = {
   status: "unverified";
   failures: readonly CompareVerificationFailure[];
 };
-type ProjectedBlock = Pick<FolioAIBlock, "text" | "table" | "styleId" | "listLevel" | "listReference" | "directAlignment" | "directSpacing" | "directIndentation" | "structuralBoundaries">;
+type ProjectedBlock = Pick<FolioAIBlock, "kind" | "headingLevel" | "text" | "table" | "styleId" | "directOutlineLevel" | "listLevel" | "listReference" | "directAlignment" | "directSpacing" | "directIndentation" | "structuralBoundaries">;
 type ClassifyOptions<T> = {
   invariant: CompareVerificationInvariant;
   story: FolioDocumentStoryHandle;

package/dist/compare/verification.js

@@ -1,5 +1,6 @@
 import { paragraphIndentationEqual } from "../prosemirror/paragraphIndentation.js";
 import { paragraphSpacingEqual } from "../prosemirror/paragraphSpacing.js";
+import { sameFolioContentOutlineLevel } from "./content.js";
 import { PARAGRAPH_MARK_CHANGE_KINDS } from "@stll/docx-core/model";
 //#region src/compare/verification.ts
 /**
@@ -8,10 +9,15 @@ import { PARAGRAPH_MARK_CHANGE_KINDS } from "@stll/docx-core/model";
 * The check compares two block projections: what accepting the generated
 * revisions leaves against the target, and what rejecting them leaves against
 * the base. A projection carries each block's container, style, list level,
-* direct alignment, spacing, indentation and text, so WHICH field diverged names
+* direct outline level, alignment, spacing, indentation and text, so WHICH field diverged names
 * which part of the pipeline lost the difference — and that is worth reporting
 * as a typed cause rather than as one opaque "did not reproduce".
 *
+* It also carries what a reader sees those properties add up to: the block's
+* kind and heading level. The stated properties are what an operation writes,
+* so a projection of them alone checks the applier against its own vocabulary;
+* the resolved classification is checked independently of how it was reached.
+*
 * Every `detail` string here is structural: counts, offsets, container kinds.
 * Never a phrase of either document, because a caller may log it, put it in a
 * report, or quote it in a review.
@@ -51,11 +57,15 @@ const sameStructuralBoundaries = (left, right) => {
 	for (let index = 0; index < leftLength; index++) {
 		const boundary = left[index];
 		const other = right[index];
-		if (boundary === void 0 || other === void 0 || boundary.type !== other.type || boundary.offset !== other.offset || boundary.clear !== other.clear) return false;
+		if (boundary === void 0 || other === void 0 || boundary.offset !== other.offset) return false;
+		if (boundary.type === "pageBreak") {
+			if (other.type !== "pageBreak" || boundary.clear !== other.clear) return false;
+		} else if (other.type !== "noteReference" || boundary.noteType !== other.noteType || boundary.length !== other.length) return false;
 	}
 	return true;
 };
-const sameProjectedBlock = (left, right) => sameContainer(left.table, right.table) && sameStructuralBoundaries(left.structuralBoundaries, right.structuralBoundaries) && left.styleId === right.styleId && left.listLevel === right.listLevel && left.listReference?.numId === right.listReference?.numId && left.listReference?.level === right.listReference?.level && left.directAlignment === right.directAlignment && paragraphSpacingEqual(left.directSpacing, right.directSpacing) && paragraphIndentationEqual(left.directIndentation, right.directIndentation) && left.text === right.text;
+const sameClassification = (left, right) => left.kind === right.kind && left.headingLevel === right.headingLevel;
+const sameProjectedBlock = (left, right) => sameContainer(left.table, right.table) && sameClassification(left, right) && sameStructuralBoundaries(left.structuralBoundaries, right.structuralBoundaries) && left.styleId === right.styleId && sameFolioContentOutlineLevel(left.directOutlineLevel, right.directOutlineLevel) && left.listLevel === right.listLevel && left.listReference?.numId === right.listReference?.numId && left.listReference?.level === right.listReference?.level && left.directAlignment === right.directAlignment && paragraphSpacingEqual(left.directSpacing, right.directSpacing) && paragraphIndentationEqual(left.directIndentation, right.directIndentation) && left.text === right.text;
 const containerKind = (container) => container ? "cell" : "body";
 const collapseWhitespace = (text) => text.replace(/\s+/gu, " ").trim();
 const sameBlockProjection = (left, right) => left.length === right.length && left.every((entry, index) => {
@@ -172,8 +182,10 @@ const classifyProjectionMismatch = ({ invariant, story, actual, expected }) => {
 	if (!sameContainer(left.table, right.table)) return failure("container", `a block sits in a ${containerKind(left.table)} where it is expected in a ${containerKind(right.table)}, ${at} (${counts})`);
 	if (!sameStructuralBoundaries(left.structuralBoundaries, right.structuralBoundaries)) return failure("inline-structure", `a block's zero-width inline structure does not match ${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 && !sameFolioContentOutlineLevel(left.directOutlineLevel, right.directOutlineLevel)) return failure("style", `the direct outline level 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 (left.text === right.text && (left.listReference?.numId !== right.listReference?.numId || left.listReference?.level !== right.listReference?.level)) return failure("list-level", `the numbering reference did not move ${at} (${counts})`);
+	if (left.text === right.text && !sameClassification(left, right)) return left.kind === "heading" || right.kind === "heading" ? failure("style", `the heading classification did not move ${at} (${counts})`) : failure("list-level", `the list membership did not move ${at} (${counts})`);
 	if (left.text === right.text && left.directAlignment !== right.directAlignment) return failure("alignment", `the direct paragraph alignment did not move ${at} (${counts})`);
 	if (left.text === right.text && !paragraphSpacingEqual(left.directSpacing, right.directSpacing)) return failure("spacing", `the direct paragraph spacing did not move ${at} (${counts})`);
 	if (left.text === right.text && !paragraphIndentationEqual(left.directIndentation, right.directIndentation)) return failure("indentation", `the direct paragraph indentation did not move ${at} (${counts})`);

package/dist/controller/committedLayoutDiff.d.ts

@@ -0,0 +1,25 @@
+import { DirtyRange } from "../paged-layout/incrementalMeasure.js";
+import { LayoutTemplatePreview } from "./layoutSession.js";
+import { Node } from "prosemirror-model";
+//#region src/controller/committedLayoutDiff.d.ts
+type LayoutFlowSource = {
+  doc: Node;
+  preview: LayoutTemplatePreview;
+};
+type CommittedLayoutDiff = {
+  type: "full";
+} | {
+  type: "range";
+  /** In the next document's positions. */
+  range: DirtyRange;
+};
+/**
+ * The span of `next` whose flow blocks may differ from the ones the committed
+ * layout measured for `committed`, or `full` when no span bounds it.
+ *
+ * `full` also covers "nothing in the body flow changed": such a pass was
+ * requested for an input outside it (a header, footer or note story).
+ */
+declare const diffAgainstCommittedLayout: (committed: LayoutFlowSource, next: LayoutFlowSource) => CommittedLayoutDiff;
+//#endregion
+export { CommittedLayoutDiff, LayoutFlowSource, diffAgainstCommittedLayout };

package/dist/controller/committedLayoutDiff.js

@@ -0,0 +1,71 @@
+import { templatePreviewDirtyRange } from "../layout-bridge/convert/templatePreviewFlow.js";
+//#region src/controller/committedLayoutDiff.ts
+const FULL = { type: "full" };
+const diffDocuments = (before, after) => {
+	const start = before.content.findDiffStart(after.content);
+	if (start === null) return null;
+	const end = before.content.findDiffEnd(after.content);
+	if (end === null) return null;
+	const overlap = start - Math.min(end.a, end.b);
+	return overlap > 0 ? {
+		start,
+		endBefore: end.a + overlap,
+		endAfter: end.b + overlap
+	} : {
+		start,
+		endBefore: end.a,
+		endAfter: end.b
+	};
+};
+/** Map a range of the previous document into the next one's positions. */
+const mapRangeThroughDiff = (range, diff) => {
+	const shift = diff.endAfter - diff.endBefore;
+	const mapPosition = (pos, insideChange) => {
+		if (pos < diff.start) return pos;
+		if (pos >= diff.endBefore) return pos + shift;
+		return insideChange;
+	};
+	return {
+		...range,
+		from: mapPosition(range.from, diff.start),
+		to: mapPosition(range.to, diff.endAfter)
+	};
+};
+const mapPreviewThroughDiff = (preview, diff) => ({
+	entries: preview.entries.map((entry) => mapRangeThroughDiff(entry, diff)),
+	hidden: preview.hidden.map((range) => mapRangeThroughDiff(range, diff))
+});
+const unionRanges = (first, second) => {
+	if (!first) return second;
+	if (!second) return first;
+	return {
+		from: Math.min(first.from, second.from),
+		to: Math.max(first.to, second.to)
+	};
+};
+/**
+* The span of `next` whose flow blocks may differ from the ones the committed
+* layout measured for `committed`, or `full` when no span bounds it.
+*
+* `full` also covers "nothing in the body flow changed": such a pass was
+* requested for an input outside it (a header, footer or note story).
+*/
+const diffAgainstCommittedLayout = (committed, next) => {
+	if (committed.preview.mode !== next.preview.mode) return FULL;
+	if (!committed.doc.sameMarkup(next.doc)) return FULL;
+	const docDiff = diffDocuments(committed.doc, next.doc);
+	let range = docDiff ? {
+		from: docDiff.start,
+		to: docDiff.endAfter
+	} : null;
+	if (committed.preview.entries !== next.preview.entries || committed.preview.hidden !== next.preview.hidden) {
+		const previousPreview = docDiff ? mapPreviewThroughDiff(committed.preview, docDiff) : committed.preview;
+		range = unionRanges(range, templatePreviewDirtyRange(previousPreview, next.preview));
+	}
+	return range ? {
+		type: "range",
+		range
+	} : FULL;
+};
+//#endregion
+export { diffAgainstCommittedLayout };

package/dist/controller/contentControlWidgetController.d.ts

@@ -1,5 +1,5 @@
-import { ContentControlWidgetEvent } from "../prosemirror/plugins/contentControlWidgets.js";
 import { Subscribable } from "../managers/Subscribable.js";
+import { ContentControlWidgetEvent } from "../prosemirror/plugins/contentControlWidgets.js";
 import { EditorView } from "prosemirror-view";
 //#region src/controller/contentControlWidgetController.d.ts
 type ContentControlListItem = {

package/dist/controller/folioEditor.d.ts

@@ -3,7 +3,7 @@ import { DocxInput } from "../utils/docxInput.js";
 import { Layout } from "../layout-engine/types.js";
 import { HiddenEditorApi } from "./hiddenEditorApi.js";
 import { FolioEditorEmitter } from "./folioEditorEvents.js";
-import { LayoutRunOptions } from "./layoutScheduler.js";
+import { LayoutRunOptions } from "./layoutRunOptions.js";
 import { EditorState } from "prosemirror-state";
 //#region src/controller/folioEditor.d.ts
 type FolioEditorDeps = {

package/dist/controller/fontReadiness.d.ts

@@ -1,8 +1,58 @@
 import { document_d_exports } from "../types/document.js";
 import { EditorState } from "prosemirror-state";
 //#region src/controller/fontReadiness.d.ts
+/** The parts of a `FontFace` layout readiness reads. */
+type LayoutFontSetFace = Pick<FontFace, "family" | "status">;
+type LayoutFontSetListener = (event: {
+  fontfaces: readonly LayoutFontSetFace[];
+}) => void;
+/**
+ * The parts of a `FontFaceSet` layout readiness uses; `document.fonts` in a
+ * browser, a scripted stand-in in tests.
+ */
+type LayoutFontSet = Iterable<LayoutFontSetFace> & {
+  load: (font: string, text?: string) => Promise<unknown>;
+  readonly ready: Promise<unknown>;
+  addEventListener: (type: "loadingdone", listener: LayoutFontSetListener) => void;
+  removeEventListener: (type: "loadingdone", listener: LayoutFontSetListener) => void;
+};
 declare function getDocumentFontSet(): FontFaceSet | null;
-declare function documentFontsAreLoaded(): boolean;
+/**
+ * Names the faces available to measurement: which faces of the families
+ * measured stacks name have loaded. Equal signatures mean every measured glyph
+ * resolves to the same face, so a measurement taken under one is valid under
+ * the other; a host UI face loading leaves it unchanged.
+ *
+ * Counted over loaded faces only (a face never unloads, and a failed one adds
+ * no glyphs) with a per-face identity sum, so a removal replaced by an addition
+ * still changes it: a new face's id exceeds every earlier one. The family set
+ * only grows, and a family joins it when first measured, so read it after
+ * measuring to name what a layout measured in. Without a font set (a server or
+ * headless host) there is nothing to load and the signature is constant.
+ */
+declare function readFontSetSignature(fontSet?: LayoutFontSet | null): string;
+type WatchLayoutFontLoadsOptions = {
+  /**
+   * The font-set signature the committed layout was measured in, or `null`
+   * before one is committed (the first layout measures whatever has loaded).
+   */
+  measuredFontSet: () => string | null;
+  relayout: () => void;
+  fontSet?: LayoutFontSet | null;
+};
+/**
+ * Re-run layout whenever a face that can change a measured width finishes
+ * loading after the committed layout measured without it.
+ *
+ * Tied to what loaded, never to a time window: fontsource splits each face
+ * into `unicode-range` subsets the browser fetches when painted text first
+ * needs them, so a subset can land at any moment after the first layout. A
+ * load the committed layout already saw (its event can arrive after the layout
+ * ran) leaves the signature unchanged and relays nothing, as does a face of a
+ * family no measured stack names (a host UI font). Returns the unsubscribe
+ * function.
+ */
+declare function watchLayoutFontLoads({ measuredFontSet, relayout, fontSet }: WatchLayoutFontLoadsOptions): () => void;
 declare const LAYOUT_FONT_DESCRIPTORS: readonly [{
   readonly style: "normal";
   readonly weight: 400;
@@ -21,8 +71,25 @@ type LayoutFontFace = {
   style: (typeof LAYOUT_FONT_DESCRIPTORS)[number]["style"];
   weight: (typeof LAYOUT_FONT_DESCRIPTORS)[number]["weight"];
 };
-declare function waitForInitialLayoutFonts(documentModel: document_d_exports.Document | null, pmDoc: EditorState["doc"]): Promise<boolean>;
+/**
+ * Resolve once every face the first layout will measure has loaded (`true`),
+ * or after a timeout (`false`), so the first layout does not measure fallbacks.
+ *
+ * Each face is loaded for the document's own characters. A bundled face is a
+ * set of `unicode-range` subsets, and `FontFaceSet.load` fetches only the
+ * subsets covering the text it is given; without text it takes a single space
+ * and loads only the Latin subset, so Czech, Polish, Greek and Cyrillic were
+ * measured in a fallback.
+ */
+declare function waitForInitialLayoutFonts(documentModel: document_d_exports.Document | null, pmDoc: EditorState["doc"], fontSet?: LayoutFontSet | null): Promise<boolean>;
+/**
+ * Every distinct character the layout will measure, as one string: the body
+ * text (tracked deletions included, since All Markup paints them), list
+ * markers, headers, footers and notes. Always carries a space, which every
+ * line measures.
+ */
+declare function collectLayoutText(documentModel: document_d_exports.Document | null, pmDoc: EditorState["doc"]): string;
 declare function collectInitialLayoutFontFamilies(documentModel: document_d_exports.Document | null, pmDoc: EditorState["doc"]): Set<string>;
 declare function collectInitialLayoutFontFaces(documentModel: document_d_exports.Document | null, pmDoc: EditorState["doc"]): LayoutFontFace[];
 //#endregion
-export { LayoutFontFace, collectInitialLayoutFontFaces, collectInitialLayoutFontFamilies, documentFontsAreLoaded, getDocumentFontSet, waitForInitialLayoutFonts };
+export { LayoutFontFace, LayoutFontSet, LayoutFontSetFace, WatchLayoutFontLoadsOptions, collectInitialLayoutFontFaces, collectInitialLayoutFontFamilies, collectLayoutText, getDocumentFontSet, readFontSetSignature, waitForInitialLayoutFonts, watchLayoutFontLoads };