@stll/folio-core 0.51.0 → 0.53.0

package/dist/compare/inline-provenance.js

@@ -3,7 +3,7 @@ import { expectHyperlinkMarkAttrs, expectRunPropertyChangeMarkAttrs, expectTable
 import { getDocumentStyleResolver } from "../prosemirror/plugins/documentStyles.js";
 import { applyMarksToRunFormattingRepresentation, expandRunFormattingCarrier, runFormattingCarrierReviewText } from "../prosemirror/runFormattingInlineCarriers.js";
 import { readAuthoredRunFormatting, reconcileRunFormattingMarks } from "../prosemirror/runFormattingReconciliation.js";
-import { paragraphRunStyleContextAt } from "../prosemirror/runStyleFormatting.js";
+import { nearestParagraphRunStyleContext } from "../prosemirror/runStyleFormatting.js";
 import { isTableCellRetainedInReviewView } from "../prosemirror/tableCellRevisionVisibility.js";
 import { canonicalJson } from "../utils/canonicalJson.js";
 //#region src/compare/inline-provenance.ts
@@ -19,10 +19,11 @@ const hyperlinkIdentity = (node) => {
 	});
 };
 const isInserted = (node) => node.marks.some(({ type }) => type.name === "insertion");
-const carrierRepresentations = (carrier) => carrier.representations.map((representation) => ({
+const carrierRepresentations = ({ carrier, paragraph }) => carrier.representations.map((representation) => ({
 	...representation,
 	from: representation.position,
-	to: representation.position + representation.node.nodeSize
+	to: representation.position + representation.node.nodeSize,
+	paragraph
 }));
 const targetBlockIdLookup = (anchors) => {
 	const ordered = Object.values(anchors).toSorted((left, right) => left.from - right.from || left.to - right.to);
@@ -53,7 +54,13 @@ const collectCarriers = ({ doc, targetSnapshot }) => {
 	const carriers = [];
 	const targetBlockIdAt = targetSnapshot ? targetBlockIdLookup(targetSnapshot.anchors) : void 0;
 	let unanchoredTargetCarrier = false;
+	const openParagraphs = [];
 	doc.descendants((node, position) => {
+		while ((openParagraphs.at(-1)?.end ?? Number.POSITIVE_INFINITY) <= position) openParagraphs.pop();
+		if (node.type.name === "paragraph") openParagraphs.push({
+			node,
+			end: position + node.nodeSize
+		});
 		if ((node.type.name === "tableCell" || node.type.name === "tableHeader") && !isTableCellRetainedInReviewView(expectTableCellAttrs(node).cellMarker?.kind, "final")) return false;
 		if (!node.isInline) return true;
 		const carrier = expandRunFormattingCarrier(node, position);
@@ -69,6 +76,7 @@ const collectCarriers = ({ doc, targetSnapshot }) => {
 		}
 		carriers.push({
 			carrier,
+			paragraph: openParagraphs.at(-1)?.node ?? null,
 			text: runFormattingCarrierReviewText(carrier),
 			targetBlockId
 		});
@@ -106,8 +114,8 @@ const matchCarrierStreams = ({ live, target }) => {
 		const targetIsText = targetCarrier.carrier.disposition === "text-run";
 		if (!liveIsText || !targetIsText) {
 			if (liveOffset !== 0 || targetOffset !== 0 || !sameCarrierShape(liveCarrier, targetCarrier)) return null;
-			const liveRepresentations = carrierRepresentations(liveCarrier.carrier);
-			const targetRepresentations = carrierRepresentations(targetCarrier.carrier);
+			const liveRepresentations = carrierRepresentations(liveCarrier);
+			const targetRepresentations = carrierRepresentations(targetCarrier);
 			for (const [index, liveRepresentation] of liveRepresentations.entries()) {
 				const targetRepresentation = targetRepresentations.at(index);
 				if (!targetRepresentation) return null;
@@ -123,8 +131,8 @@ const matchCarrierStreams = ({ live, target }) => {
 		}
 		const sharedLength = Math.min(liveText.length, targetText.length);
 		if (sharedLength === 0 || liveText.slice(0, sharedLength) !== targetText.slice(0, sharedLength)) return null;
-		const liveRepresentation = carrierRepresentations(liveCarrier.carrier).at(0);
-		const targetRepresentation = carrierRepresentations(targetCarrier.carrier).at(0);
+		const liveRepresentation = carrierRepresentations(liveCarrier).at(0);
+		const targetRepresentation = carrierRepresentations(targetCarrier).at(0);
 		if (!liveRepresentation || !targetRepresentation) return null;
 		matched.push({
 			live: {
@@ -152,12 +160,8 @@ const matchCarrierStreams = ({ live, target }) => {
 	}
 	return matched;
 };
-const authoredFormattingAt = ({ doc, representation, styleResolver }) => readAuthoredRunFormatting({
-	context: paragraphRunStyleContextAt({
-		doc,
-		pos: representation.from,
-		styleResolver
-	}),
+const authoredFormattingAt = ({ representation, styleResolver }) => readAuthoredRunFormatting({
+	context: nearestParagraphRunStyleContext(representation.paragraph, styleResolver),
 	marks: representation.node.marks,
 	styleResolver
 });
@@ -190,12 +194,10 @@ const matchInlineProvenance = ({ state, targetSnapshot, revisionStamp, originalR
 	const planned = [];
 	for (const segment of matched) {
 		const liveFormatting = authoredFormattingAt({
-			doc: state.doc,
 			representation: segment.live,
 			styleResolver: liveStyleResolver
 		});
 		const targetFormatting = authoredFormattingAt({
-			doc: targetDocument,
 			representation: segment.target,
 			styleResolver: targetStyleResolver
 		});
@@ -220,11 +222,7 @@ const matchInlineProvenance = ({ state, targetSnapshot, revisionStamp, originalR
 	let nextRevisionId = revisionStamp.idSeed;
 	const changedTargetBlockIds = /* @__PURE__ */ new Set();
 	for (const change of planned.toReversed()) {
-		const context = paragraphRunStyleContextAt({
-			doc: state.doc,
-			pos: change.live.from,
-			styleResolver: liveStyleResolver
-		});
+		const context = nearestParagraphRunStyleContext(change.live.paragraph, liveStyleResolver);
 		const formattingMarks = reconcileRunFormattingMarks({
 			authoredFormatting: change.formatting,
 			context,
@@ -321,11 +319,9 @@ const sameAuthoredInlineProvenance = (baseSnapshot, targetSnapshot) => {
 	const baseStyleResolver = styleResolverOf(baseSnapshot);
 	const targetStyleResolver = styleResolverOf(targetSnapshot);
 	return matched.every(({ live, target }) => hyperlinkIdentity(live.node) === hyperlinkIdentity(target.node) && canonicalJson(authoredFormattingAt({
-		doc: baseDocument,
 		representation: live,
 		styleResolver: baseStyleResolver
 	})) === canonicalJson(authoredFormattingAt({
-		doc: targetDocument,
 		representation: target,
 		styleResolver: targetStyleResolver
 	})));

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
@@ -108,9 +108,22 @@ const boundaryParagraphEntriesOf = (document) => {
 	if (!children) return null;
 	return children.flatMap((child) => child.type === "paragraph" ? [child.paragraph] : []);
 };
+const hasSectionEndpoint = (document) => {
+	let found = false;
+	document.forEach((node) => {
+		if (node.type.name === "paragraph" && expectParagraphAttrs(node)._sectionProperties !== void 0) found = true;
+	});
+	return found;
+};
 /** Stage section deltas after document operations, against the accepted projection. */
 const stageSectionBoundaryProperties = ({ state, target, originalRevisionIdSeed, revisionStamp, author, maxRanges, mapTargetProperties }) => {
 	if (!Number.isSafeInteger(maxRanges) || maxRanges < 0) return { status: "budget-exceeded" };
+	if (!hasSectionEndpoint(target)) return {
+		status: "matched",
+		transaction: state.tr,
+		nextRevisionId: revisionStamp.idSeed,
+		rangeCount: 0
+	};
 	const reviewedState = resolveAllChangesInHeadlessStateWithMapping(state, "accept");
 	const reviewed = boundaryParagraphEntriesOf(reviewedState.state.doc);
 	const targets = boundaryParagraphEntriesOf(target);

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 };