@stll/folio-core 0.0.1-placeholder.0 → 0.1.1

package/dist/controller/layoutPipeline.js

@@ -0,0 +1,406 @@
+import "../layout-engine/types.js";
+import { renderPages } from "../layout-painter/renderPage.js";
+import { templatePreviewValuesKey } from "../prosemirror/plugins/templatePreviewValues.js";
+import { toFlowBlocks } from "../layout-bridge/convert/toFlowBlocks.js";
+import { recordLayoutComplete, recordLayoutError, recordLayoutPhase } from "../layout-engine/layoutInstrumentation.js";
+import { buildBookmarkPageMap } from "../fields/bookmarkPages.js";
+import { buildBookmarkText } from "../fields/bookmarkText.js";
+import { buildHeaderFooterFieldValues, fieldValuesEqual, resolveFieldValues } from "../fields/resolveFieldValues.js";
+import { buildSectionPageCounts } from "../fields/sectionPageCounts.js";
+import { buildSeqValues } from "../fields/seqValues.js";
+import { installCanvasMeasureProvider } from "../layout-engine/measure/measureContainer.js";
+import { buildFootnoteContentMap, collectFootnoteRefs } from "../layout-bridge/convert/footnoteLayout.js";
+import { applyTemplatePreviewToBlocks } from "../layout-bridge/convert/templatePreviewFlow.js";
+import { layoutDocument } from "../layout-engine/index.js";
+import { measureBlocks, measureSingleBlockWithoutFloatingZones } from "../layout-engine/measure/measureBlocks.js";
+import { computeFirstPageHeaderFooterMarginExtender, computeHeaderFooterMarginExtender, extendSectionBreakMargins } from "../paged-layout/headerFooterMargins.js";
+import { tryBuildIncrementalMeasures } from "../paged-layout/incrementalMeasure.js";
+import { computePerBlockMeasureInputs } from "../paged-layout/sectionBlockWidths.js";
+import { twipsToPixels } from "../paged-layout/sectionGeometry.js";
+import { getDocumentWatermark } from "../watermark/index.js";
+//#region src/controller/layoutPipeline.ts
+function pageMarginsEqual(left, right) {
+	return left.top === right.top && left.right === right.right && left.bottom === right.bottom && left.left === right.left && left.header === right.header && left.footer === right.footer;
+}
+function optionalPageMarginsEqual(left, right) {
+	if (left === void 0 || right === void 0) return left === right;
+	return pageMarginsEqual(left, right);
+}
+function runLayoutPipeline(deps, state, options = {}) {
+	const { contentWidth, columns, pageSize, margins, pageGap, syncCoordinator, headerContent, footerContent, firstPageHeaderContent, firstPageFooterContent, headerContentRId, footerContentRId, firstPageHeaderContentRId, firstPageFooterContentRId, sectionHeaderFooterRefs, theme: _theme, sectionProperties, document, defaultTabStop, styles, layout, hfPMs, painter, pagesContainer, session, renderHfFromContentOrPm, renderHeaderFooterContentByRId, documentFontsAreLoaded, buildFootnoteRenderItems, describeInvalidHighlightMarks, emptyTemplatePreviewEntries: EMPTY_TEMPLATE_PREVIEW_ENTRIES } = deps;
+	let outcome = {};
+	let pendingArtifacts;
+	let pendingTemplatePreview;
+	installCanvasMeasureProvider();
+	const reason = options.reason ?? "manual";
+	const recordPhaseDuration = (phase, startedAt) => {
+		recordLayoutPhase(reason, phase, performance.now() - startedAt);
+	};
+	const currentEpoch = syncCoordinator.getStateSeq();
+	syncCoordinator.onLayoutStart();
+	try {
+		let phaseStartedAt = performance.now();
+		const flowOpts = { pageContentHeight: pageSize.h - margins.top - margins.bottom };
+		if (_theme !== void 0) flowOpts.theme = _theme;
+		if (defaultTabStop !== void 0) flowOpts.defaultTabStopTwips = defaultTabStop;
+		let newBlocks = toFlowBlocks(state.doc, flowOpts);
+		const previewState = templatePreviewValuesKey.getState(state);
+		const previewEntries = previewState?.entries ?? EMPTY_TEMPLATE_PREVIEW_ENTRIES;
+		const previewMode = previewState?.preview?.mode ?? "plain";
+		if (previewEntries.length > 0) newBlocks = applyTemplatePreviewToBlocks(newBlocks, {
+			entries: previewEntries,
+			mode: previewMode
+		});
+		pendingTemplatePreview = {
+			entries: previewEntries,
+			mode: previewMode
+		};
+		outcome.blocks = newBlocks;
+		recordPhaseDuration("flow-blocks", phaseStartedAt);
+		phaseStartedAt = performance.now();
+		const footnoteRefs = collectFootnoteRefs(newBlocks);
+		const documentFootnotes = document?.package.footnotes;
+		const hasFootnotes = footnoteRefs.length > 0 && documentFootnotes !== void 0;
+		const hfMetricsHeader = {
+			section: "header",
+			pageSize,
+			margins
+		};
+		const hfMetricsFooter = {
+			section: "footer",
+			pageSize,
+			margins
+		};
+		const hfPageCountEstimate = layout?.pages.length ?? 1;
+		const hfClock = /* @__PURE__ */ new Date();
+		const buildHfOptions = (pageCount, fieldInputs) => {
+			const hfMeasureBlocks = (hfBlocks, hfWidth) => measureBlocks(hfBlocks, hfWidth, void 0, void 0, buildHeaderFooterFieldValues(hfBlocks, pageCount, hfClock, fieldInputs));
+			return {
+				...styles ? { styles } : {},
+				..._theme !== void 0 ? { theme: _theme } : {},
+				measureBlocks: hfMeasureBlocks,
+				...defaultTabStop !== void 0 ? { defaultTabStopTwips: defaultTabStop } : {}
+			};
+		};
+		const hfOptions = buildHfOptions(hfPageCountEstimate);
+		let headerContentForRender = renderHfFromContentOrPm(headerContent, headerContentRId, hfPMs, contentWidth, hfMetricsHeader, hfOptions);
+		let footerContentForRender = renderHfFromContentOrPm(footerContent, footerContentRId, hfPMs, contentWidth, hfMetricsFooter, hfOptions);
+		const hasTitlePg = sectionProperties?.titlePg === true;
+		let firstPageHeaderForRender = hasTitlePg ? renderHfFromContentOrPm(firstPageHeaderContent, firstPageHeaderContentRId, hfPMs, contentWidth, hfMetricsHeader, hfOptions) : void 0;
+		let firstPageFooterForRender = hasTitlePg ? renderHfFromContentOrPm(firstPageFooterContent, firstPageFooterContentRId, hfPMs, contentWidth, hfMetricsFooter, hfOptions) : void 0;
+		let headerContentByRId = renderHeaderFooterContentByRId(document?.package.headers, hfPMs, contentWidth, hfMetricsHeader, hfOptions);
+		let footerContentByRId = renderHeaderFooterContentByRId(document?.package.footers, hfPMs, contentWidth, hfMetricsFooter, hfOptions);
+		const hfExtenderContent = {
+			headerContent: headerContentForRender,
+			footerContent: footerContentForRender,
+			firstPageHeaderContent: firstPageHeaderForRender,
+			firstPageFooterContent: firstPageFooterForRender
+		};
+		const hfWarn = (msg) => {
+			console.warn(`[PagedEditor] ${msg}`);
+		};
+		const extendForHfOverflow = computeHeaderFooterMarginExtender({
+			...hfExtenderContent,
+			pageSize,
+			warn: hfWarn
+		});
+		const extendForFirstPage = computeFirstPageHeaderFooterMarginExtender({
+			...hfExtenderContent,
+			pageSize,
+			warn: hfWarn
+		});
+		let effectiveMargins = extendForHfOverflow(margins);
+		let effectiveFirstPageMargins = hasTitlePg ? extendForFirstPage(margins) : void 0;
+		const sectionBreaks = newBlocks.filter((block) => block.kind === "sectionBreak");
+		const originalSectionBreakMargins = /* @__PURE__ */ new Map();
+		for (const sectionBreak of sectionBreaks) originalSectionBreakMargins.set(sectionBreak.id, sectionBreak.margins ? { ...sectionBreak.margins } : void 0);
+		const restoreSectionBreakMargins = () => {
+			for (const sectionBreak of sectionBreaks) {
+				const originalMargins = originalSectionBreakMargins.get(sectionBreak.id);
+				if (originalMargins === void 0) {
+					delete sectionBreak.margins;
+					continue;
+				}
+				sectionBreak.margins = { ...originalMargins };
+			}
+		};
+		const applySectionBreakMargins = (content, bodyMargins) => {
+			restoreSectionBreakMargins();
+			extendSectionBreakMargins(sectionBreaks, {
+				content,
+				bodyPageSize: pageSize,
+				bodyMargins,
+				warn: hfWarn
+			});
+		};
+		applySectionBreakMargins(hfExtenderContent, effectiveMargins);
+		recordPhaseDuration("header-footer", phaseStartedAt);
+		phaseStartedAt = performance.now();
+		let bodyLayoutConfig = {
+			pageSize,
+			margins: effectiveMargins
+		};
+		if (columns !== void 0) bodyLayoutConfig.columns = columns;
+		let blockMeasureInputs = computePerBlockMeasureInputs({
+			blocks: newBlocks,
+			bodyConfig: bodyLayoutConfig,
+			finalConfig: bodyLayoutConfig
+		});
+		let blockWidths = blockMeasureInputs.widths;
+		const previousArtifacts = session.artifacts;
+		const incrementalResult = options.dirtyRange && !options.forceFull && previousArtifacts ? tryBuildIncrementalMeasures({
+			previousBlocks: previousArtifacts.blocks,
+			previousMeasures: previousArtifacts.measures,
+			previousBlockWidths: previousArtifacts.blockWidths,
+			nextBlocks: newBlocks,
+			nextBlockWidths: blockWidths,
+			dirtyRange: options.dirtyRange,
+			measureBlock: measureSingleBlockWithoutFloatingZones
+		}) : null;
+		let newMeasures = incrementalResult?.measures ?? measureBlocks(newBlocks, blockWidths, blockMeasureInputs.marginTops, {
+			pageHeight: blockMeasureInputs.pageHeights,
+			marginBottom: blockMeasureInputs.marginBottoms
+		});
+		pendingArtifacts = {
+			blocks: newBlocks,
+			blockWidths,
+			measures: newMeasures
+		};
+		outcome.measures = newMeasures;
+		recordPhaseDuration("measure-blocks", phaseStartedAt);
+		phaseStartedAt = performance.now();
+		let newLayout;
+		let pageFootnoteMap = /* @__PURE__ */ new Map();
+		let footnoteContentMap = /* @__PURE__ */ new Map();
+		const bodyBreakType = sectionProperties?.sectionStart;
+		const buildLayoutOpts = (nextMargins, nextFirstPageMargins) => {
+			const nextLayoutOpts = {
+				pageSize,
+				margins: nextMargins,
+				pageGap
+			};
+			if (nextFirstPageMargins !== void 0) nextLayoutOpts.firstPageMargins = nextFirstPageMargins;
+			if (columns !== void 0) nextLayoutOpts.columns = columns;
+			if (bodyBreakType !== void 0) nextLayoutOpts.bodyBreakType = bodyBreakType;
+			if (sectionHeaderFooterRefs !== void 0) nextLayoutOpts.sectionHeaderFooterRefs = sectionHeaderFooterRefs;
+			return nextLayoutOpts;
+		};
+		const layoutOpts = buildLayoutOpts(effectiveMargins, effectiveFirstPageMargins);
+		let layoutOptsUsed = layoutOpts;
+		if (hasFootnotes) {
+			footnoteContentMap = buildFootnoteContentMap(documentFootnotes, footnoteRefs, contentWidth, (() => {
+				const footnoteOptions = { measureBlocks };
+				if (styles) footnoteOptions.styles = styles;
+				if (_theme !== void 0) footnoteOptions.theme = _theme;
+				if (defaultTabStop !== void 0) footnoteOptions.defaultTabStopTwips = defaultTabStop;
+				return footnoteOptions;
+			})());
+			const footnoteHeightById = /* @__PURE__ */ new Map();
+			for (const [id, content] of footnoteContentMap) footnoteHeightById.set(id, content.height + 0);
+			layoutOptsUsed = {
+				...layoutOpts,
+				footnoteHeightById
+			};
+			newLayout = layoutDocument(newBlocks, newMeasures, layoutOptsUsed);
+			pageFootnoteMap = /* @__PURE__ */ new Map();
+			for (const page of newLayout.pages) if (page.footnoteIds && page.footnoteIds.length > 0) pageFootnoteMap.set(page.number, page.footnoteIds);
+		} else newLayout = layoutDocument(newBlocks, newMeasures, layoutOpts);
+		const rebuildFootnotePageMap = () => {
+			pageFootnoteMap = /* @__PURE__ */ new Map();
+			for (const page of newLayout.pages) if (page.footnoteIds && page.footnoteIds.length > 0) pageFootnoteMap.set(page.number, page.footnoteIds);
+		};
+		const withFootnoteHeights = (nextLayoutOpts) => {
+			if (!hasFootnotes) return nextLayoutOpts;
+			const footnoteHeightById = /* @__PURE__ */ new Map();
+			for (const [id, content] of footnoteContentMap) footnoteHeightById.set(id, content.height + 0);
+			return {
+				...nextLayoutOpts,
+				footnoteHeightById
+			};
+		};
+		const relayoutWithCurrentMeasures = (nextLayoutOpts) => {
+			layoutOptsUsed = withFootnoteHeights(nextLayoutOpts);
+			newLayout = layoutDocument(newBlocks, newMeasures, layoutOptsUsed);
+			if (hasFootnotes) rebuildFootnotePageMap();
+		};
+		const stabilizeFieldWidths = () => {
+			if (incrementalResult) return;
+			const MAX_FIELD_STABILIZATION_PASSES = 3;
+			const fieldClock = /* @__PURE__ */ new Date();
+			let previousFieldValues = null;
+			for (let pass = 0; pass < MAX_FIELD_STABILIZATION_PASSES; pass++) {
+				const seqValues = buildSeqValues(newBlocks);
+				const bookmarkTextInputs = previousFieldValues === null ? { seqValues } : {
+					fieldValues: previousFieldValues,
+					seqValues
+				};
+				const { values, changed } = resolveFieldValues(newBlocks, newLayout.pages, {
+					totalPages: newLayout.pages.length,
+					bookmarkPages: buildBookmarkPageMap(newLayout.pages, newBlocks),
+					bookmarkText: buildBookmarkText(newBlocks, bookmarkTextInputs),
+					seqValues,
+					sectionPageCounts: buildSectionPageCounts(newLayout.pages),
+					now: fieldClock
+				});
+				if (previousFieldValues === null ? !changed : fieldValuesEqual(previousFieldValues, values)) {
+					stabilizedFieldValues = values;
+					break;
+				}
+				previousFieldValues = values;
+				stabilizedFieldValues = values;
+				newMeasures = measureBlocks(newBlocks, blockWidths, blockMeasureInputs.marginTops, {
+					pageHeight: blockMeasureInputs.pageHeights,
+					marginBottom: blockMeasureInputs.marginBottoms
+				}, values);
+				relayoutWithCurrentMeasures(layoutOptsUsed);
+				pendingArtifacts = {
+					blocks: newBlocks,
+					blockWidths,
+					measures: newMeasures
+				};
+				outcome.measures = newMeasures;
+			}
+		};
+		let stabilizedFieldValues;
+		stabilizeFieldWidths();
+		const rebuildHeaderFooterForLayout = () => {
+			const seqValues = buildSeqValues(newBlocks);
+			const bookmarkTextInputs = stabilizedFieldValues === void 0 ? { seqValues } : {
+				fieldValues: stabilizedFieldValues,
+				seqValues
+			};
+			const finalHfFieldInputs = {
+				bookmarkPages: buildBookmarkPageMap(newLayout.pages, newBlocks),
+				bookmarkText: buildBookmarkText(newBlocks, bookmarkTextInputs),
+				seqValues,
+				sectionPageCounts: buildSectionPageCounts(newLayout.pages)
+			};
+			const finalHfOptions = buildHfOptions(newLayout.pages.length, finalHfFieldInputs);
+			headerContentForRender = renderHfFromContentOrPm(headerContent, headerContentRId, hfPMs, contentWidth, hfMetricsHeader, finalHfOptions);
+			footerContentForRender = renderHfFromContentOrPm(footerContent, footerContentRId, hfPMs, contentWidth, hfMetricsFooter, finalHfOptions);
+			firstPageHeaderForRender = hasTitlePg ? renderHfFromContentOrPm(firstPageHeaderContent, firstPageHeaderContentRId, hfPMs, contentWidth, hfMetricsHeader, finalHfOptions) : void 0;
+			firstPageFooterForRender = hasTitlePg ? renderHfFromContentOrPm(firstPageFooterContent, firstPageFooterContentRId, hfPMs, contentWidth, hfMetricsFooter, finalHfOptions) : void 0;
+			headerContentByRId = renderHeaderFooterContentByRId(document?.package.headers, hfPMs, contentWidth, hfMetricsHeader, finalHfOptions);
+			footerContentByRId = renderHeaderFooterContentByRId(document?.package.footers, hfPMs, contentWidth, hfMetricsFooter, finalHfOptions);
+			return {
+				headerContent: headerContentForRender,
+				footerContent: footerContentForRender,
+				firstPageHeaderContent: firstPageHeaderForRender,
+				firstPageFooterContent: firstPageFooterForRender
+			};
+		};
+		const MAX_HEADER_FOOTER_STABILIZATION_PASSES = 3;
+		for (let pass = 0; pass < MAX_HEADER_FOOTER_STABILIZATION_PASSES; pass++) {
+			const finalHfExtenderContent = rebuildHeaderFooterForLayout();
+			const finalEffectiveMargins = computeHeaderFooterMarginExtender({
+				...finalHfExtenderContent,
+				pageSize,
+				warn: hfWarn
+			})(margins);
+			const finalEffectiveFirstPageMargins = hasTitlePg ? computeFirstPageHeaderFooterMarginExtender({
+				...finalHfExtenderContent,
+				pageSize,
+				warn: hfWarn
+			})(margins) : void 0;
+			if (!pageMarginsEqual(effectiveMargins, finalEffectiveMargins) || !optionalPageMarginsEqual(effectiveFirstPageMargins, finalEffectiveFirstPageMargins)) {
+				effectiveMargins = finalEffectiveMargins;
+				effectiveFirstPageMargins = finalEffectiveFirstPageMargins;
+				applySectionBreakMargins(finalHfExtenderContent, effectiveMargins);
+				bodyLayoutConfig = {
+					pageSize,
+					margins: effectiveMargins
+				};
+				if (columns !== void 0) bodyLayoutConfig.columns = columns;
+				blockMeasureInputs = computePerBlockMeasureInputs({
+					blocks: newBlocks,
+					bodyConfig: bodyLayoutConfig,
+					finalConfig: bodyLayoutConfig
+				});
+				blockWidths = blockMeasureInputs.widths;
+				newMeasures = measureBlocks(newBlocks, blockWidths, blockMeasureInputs.marginTops, {
+					pageHeight: blockMeasureInputs.pageHeights,
+					marginBottom: blockMeasureInputs.marginBottoms
+				});
+				pendingArtifacts = {
+					blocks: newBlocks,
+					blockWidths,
+					measures: newMeasures
+				};
+				outcome.measures = newMeasures;
+				relayoutWithCurrentMeasures(buildLayoutOpts(effectiveMargins, effectiveFirstPageMargins));
+				stabilizeFieldWidths();
+				continue;
+			}
+			break;
+		}
+		outcome.layout = newLayout;
+		recordPhaseDuration("layout-document", phaseStartedAt);
+		if (pagesContainer && painter) {
+			phaseStartedAt = performance.now();
+			const blockLookup = /* @__PURE__ */ new Map();
+			for (let i = 0; i < newBlocks.length; i++) {
+				const block = newBlocks[i];
+				const measure = newMeasures[i];
+				if (block && measure) blockLookup.set(String(block.id), {
+					block,
+					measure
+				});
+			}
+			outcome.blockLookup = blockLookup;
+			const footnotesByPage = hasFootnotes ? buildFootnoteRenderItems(pageFootnoteMap, footnoteContentMap, document) : void 0;
+			const renderOpts = {
+				pageGap,
+				showShadow: true,
+				blockLookup,
+				titlePg: hasTitlePg
+			};
+			if (headerContentForRender) renderOpts.headerContent = headerContentForRender;
+			if (footerContentForRender) renderOpts.footerContent = footerContentForRender;
+			if (firstPageHeaderForRender) renderOpts.firstPageHeaderContent = firstPageHeaderForRender;
+			if (firstPageFooterForRender) renderOpts.firstPageFooterContent = firstPageFooterForRender;
+			if (headerContentByRId) renderOpts.headerContentByRId = headerContentByRId;
+			if (footerContentByRId) renderOpts.footerContentByRId = footerContentByRId;
+			if (sectionHeaderFooterRefs === void 0 && sectionProperties?.headerDistance !== void 0 && sectionProperties.headerDistance !== 0) renderOpts.headerDistance = twipsToPixels(sectionProperties.headerDistance);
+			if (sectionHeaderFooterRefs === void 0 && sectionProperties?.footerDistance !== void 0 && sectionProperties.footerDistance !== 0) renderOpts.footerDistance = twipsToPixels(sectionProperties.footerDistance);
+			if (sectionProperties?.pageBorders) renderOpts.pageBorders = sectionProperties.pageBorders;
+			if (_theme) renderOpts.theme = _theme;
+			if (footnotesByPage !== void 0 && footnotesByPage.size > 0) renderOpts.footnotesByPage = footnotesByPage;
+			const bookmarkPages = buildBookmarkPageMap(newLayout.pages, newBlocks);
+			if (bookmarkPages.size > 0) renderOpts.bookmarkPages = bookmarkPages;
+			const seqValues = buildSeqValues(newBlocks);
+			if (seqValues.size > 0) renderOpts.seqValues = seqValues;
+			const bookmarkText = buildBookmarkText(newBlocks, stabilizedFieldValues === void 0 ? { seqValues } : {
+				fieldValues: stabilizedFieldValues,
+				seqValues
+			});
+			if (bookmarkText.size > 0) renderOpts.bookmarkText = bookmarkText;
+			renderOpts.sectionPageCounts = buildSectionPageCounts(newLayout.pages);
+			if (document) {
+				const watermark = getDocumentWatermark(document);
+				if (watermark) renderOpts.watermark = watermark;
+				const headers = document.package.headers;
+				if (headers) {
+					const watermarkByHeaderRId = /* @__PURE__ */ new Map();
+					for (const [rId, header] of headers) if (header.watermark) watermarkByHeaderRId.set(rId, header.watermark);
+					if (watermarkByHeaderRId.size > 0) renderOpts.watermarkByHeaderRId = watermarkByHeaderRId;
+				}
+			}
+			renderPages(newLayout.pages, pagesContainer, renderOpts);
+			recordPhaseDuration("render-pages", phaseStartedAt);
+		}
+		session.artifacts = pendingArtifacts;
+		session.lastTemplatePreview = pendingTemplatePreview;
+		session.lastEditorState = state;
+		session.lastPmDoc = state.doc;
+		session.usedLoadedFonts = documentFontsAreLoaded();
+		recordLayoutComplete(reason);
+	} catch (error) {
+		const invalidHighlights = describeInvalidHighlightMarks(state.doc);
+		recordLayoutError(reason, invalidHighlights ? /* @__PURE__ */ new Error(`${String(error)} Invalid highlights: ${invalidHighlights}`) : error);
+		outcome = {};
+	}
+	syncCoordinator.onLayoutComplete(currentEpoch);
+	return outcome;
+}
+//#endregion
+export { runLayoutPipeline };

package/dist/controller/layoutScheduler.d.ts

@@ -0,0 +1,41 @@
+import { LayoutRunReason } from "../layout-engine/layoutInstrumentation.js";
+import { DirtyRange } from "../paged-layout/incrementalMeasure.js";
+
+//#region src/controller/layoutScheduler.d.ts
+type LayoutRunOptions = {
+  dirtyRange?: DirtyRange;
+  forceFull?: boolean;
+  reason: LayoutRunReason;
+};
+type RunLayout<TState> = (state: TState, options: LayoutRunOptions) => void;
+type SchedulerClock = {
+  requestFrame: (callback: () => void) => number;
+  cancelFrame: (id: number) => void;
+  setTimer: (callback: () => void, delayMs: number) => number;
+  clearTimer: (id: number) => void;
+  now: () => number;
+};
+declare const browserClock: SchedulerClock;
+type LayoutSchedulerConfig<TState> = {
+  runLayout: RunLayout<TState>; /** Quiet-window debounce before an interactive layout pass. */
+  debounceMs: number; /** Hard cap on latency from the first edit in a burst. */
+  maxDelayMs: number;
+  /**
+   * Timing source. Pass `browserClock` in the browser; a host injects its own
+   * for desktop/headless. Required (no browser default) so the scheduler never
+   * silently depends on `window`.
+   */
+  clock: SchedulerClock;
+};
+type LayoutScheduler<TState> = {
+  /**
+   * Schedule a layout pass after a short coalescing window. Repeated calls in
+   * the window replace the pending state and merge dirty ranges, so a typing
+   * burst paints once while still honoring the max-latency cap.
+   */
+  schedule: (state: TState, dirtyRange: DirtyRange | null) => void; /** Cancel any pending timer/frame. Call on teardown. */
+  dispose: () => void;
+};
+declare const createLayoutScheduler: <TState>(config: LayoutSchedulerConfig<TState>) => LayoutScheduler<TState>;
+//#endregion
+export { LayoutRunOptions, LayoutScheduler, LayoutSchedulerConfig, RunLayout, SchedulerClock, browserClock, createLayoutScheduler };

package/dist/controller/layoutScheduler.js

@@ -0,0 +1,59 @@
+import { mergeDirtyRanges } from "../paged-layout/incrementalMeasure.js";
+//#region src/controller/layoutScheduler.ts
+const browserClock = {
+	requestFrame: (callback) => window.requestAnimationFrame(callback),
+	cancelFrame: (id) => window.cancelAnimationFrame(id),
+	setTimer: (callback, delayMs) => window.setTimeout(callback, delayMs),
+	clearTimer: (id) => window.clearTimeout(id),
+	now: () => window.performance.now()
+};
+const createLayoutScheduler = (config) => {
+	const clock = config.clock;
+	let pending = null;
+	const flushPending = () => {
+		if (!pending || pending.rafId !== null) return;
+		pending.timerId = null;
+		pending.rafId = clock.requestFrame(() => {
+			const latest = pending;
+			pending = null;
+			if (!latest) return;
+			const options = { reason: "transaction" };
+			if (latest.dirtyRange) options.dirtyRange = latest.dirtyRange;
+			config.runLayout(latest.state, options);
+		});
+	};
+	const armTimer = (request) => {
+		if (request.rafId !== null) return;
+		if (request.timerId !== null) clock.clearTimer(request.timerId);
+		const elapsedMs = clock.now() - request.firstScheduledAt;
+		const delayMs = elapsedMs >= config.maxDelayMs ? 0 : Math.min(config.debounceMs, config.maxDelayMs - elapsedMs);
+		request.timerId = clock.setTimer(flushPending, delayMs);
+	};
+	return {
+		schedule(state, dirtyRange) {
+			if (pending) {
+				pending.state = state;
+				pending.dirtyRange = mergeDirtyRanges(pending.dirtyRange, dirtyRange);
+				armTimer(pending);
+				return;
+			}
+			const next = {
+				dirtyRange,
+				firstScheduledAt: clock.now(),
+				rafId: null,
+				state,
+				timerId: null
+			};
+			pending = next;
+			armTimer(next);
+		},
+		dispose() {
+			if (!pending) return;
+			if (pending.timerId !== null) clock.clearTimer(pending.timerId);
+			if (pending.rafId !== null) clock.cancelFrame(pending.rafId);
+			pending = null;
+		}
+	};
+};
+//#endregion
+export { browserClock, createLayoutScheduler };

package/dist/controller/layoutSession.d.ts

@@ -0,0 +1,24 @@
+import { FlowBlock, Measure } from "../layout-engine/types.js";
+import { TemplatePreviewEntry, TemplatePreviewValues } from "../prosemirror/plugins/templatePreviewValues.js";
+import { EditorState } from "prosemirror-state";
+
+//#region src/controller/layoutSession.d.ts
+type LayoutArtifacts = {
+  blocks: FlowBlock[];
+  blockWidths: number[];
+  measures: Measure[];
+};
+type LayoutTemplatePreview = {
+  entries: readonly TemplatePreviewEntry[];
+  mode: TemplatePreviewValues["mode"];
+};
+type LayoutSession = {
+  artifacts: LayoutArtifacts | null;
+  lastEditorState: EditorState | null;
+  lastPmDoc: EditorState["doc"] | null;
+  usedLoadedFonts: boolean;
+  lastTemplatePreview: LayoutTemplatePreview;
+};
+declare const createLayoutSession: () => LayoutSession;
+//#endregion
+export { LayoutArtifacts, LayoutSession, LayoutTemplatePreview, createLayoutSession };

package/dist/controller/layoutSession.js

@@ -0,0 +1,13 @@
+//#region src/controller/layoutSession.ts
+const createLayoutSession = () => ({
+	artifacts: null,
+	lastEditorState: null,
+	lastPmDoc: null,
+	usedLoadedFonts: false,
+	lastTemplatePreview: {
+		entries: [],
+		mode: "plain"
+	}
+});
+//#endregion
+export { createLayoutSession };

package/dist/docx/blockContentParser.d.ts

@@ -0,0 +1,13 @@
+import { document_d_exports } from "../types/document.js";
+import { NumberingMap } from "./numberingParser.js";
+import { StyleMap } from "./styleParser.js";
+import { XmlElement } from "./xmlParser.js";
+
+//#region src/docx/blockContentParser.d.ts
+type ParseBlockContentOptions = {
+  inHeaderFooter?: boolean;
+  rootXmlns?: Record<string, string>;
+};
+declare const parseBlockContent: (parent: XmlElement, styles: StyleMap | null, theme: document_d_exports.Theme | null, numbering: NumberingMap | null, rels: document_d_exports.RelationshipMap | null, media: Map<string, document_d_exports.MediaFile> | null, options?: ParseBlockContentOptions) => document_d_exports.BlockContent[];
+//#endregion
+export { parseBlockContent };