@stll/folio-core 0.49.0 → 0.51.0

package/dist/layout-engine/measure/paragraphMeasureShared.d.ts

@@ -0,0 +1,109 @@
+import { FieldRun, ImageRun, LineBreakRun, MathRun, MeasuredLine, Run, TabRun, TextRun } from "../types.js";
+import { FontMetrics, FontStyle } from "./measureTypes.js";
+import { FloatingLineSegmentZone } from "./floatingZones.js";
+//#region src/layout-engine/measure/paragraphMeasureShared.d.ts
+declare const DEFAULT_FONT_SIZE = 11;
+declare const DEFAULT_LINE_HEIGHT_MULTIPLIER = 1;
+declare const WIDTH_TOLERANCE = 0.5;
+/**
+ * Typography metrics for a line
+ */
+type LineTypography = {
+  ascent: number;
+  descent: number;
+  lineHeight: number;
+};
+/**
+ * State tracking for line accumulation
+ */
+type LineState = {
+  fromRun: number;
+  fromChar: number;
+  toRun: number;
+  toChar: number;
+  width: number;
+  /** Width of collapsible ASCII whitespace at the current line tail. */
+  trailingWhitespaceWidth: number;
+  /** Spaces the layout may compress while justifying this line. */
+  regularSpaceWidth: number;
+  /** Paint plan set only when final-text contraction admits a candidate. */
+  justificationPaint?: NonNullable<MeasuredLine["justificationPaint"]>;
+  maxFontSize: number;
+  maxFontMetrics: FontMetrics | null;
+  /**
+   * Largest tab font on the line. Tabs are whitespace: their font sizes the
+   * line only when no other run on it does (a line of nothing but tabs).
+   */
+  maxTabFontSize: number;
+  maxTabFontMetrics: FontMetrics | null;
+  /** Maximum inline image height in pixels (already in px, not points) */
+  maxImageHeightPx: number;
+  /** Maximum exact-height embedded-object preview on the line. */
+  maxExactImageHeightPx: number;
+  /** Maximum inline math height in pixels (already in px, not points) */
+  maxMathHeightPx: number;
+  availableWidth: number;
+  /** Left offset from floating images (pixels from content left edge) */
+  leftOffset: number;
+  /** Right offset from floating images (pixels from content right edge) */
+  rightOffset: number;
+  /** Optional split segment zones from centered floating exclusions */
+  segmentZones?: FloatingLineSegmentZone[];
+  discretionaryHyphen?: {
+    runIndex: number;
+  };
+  renderedPageBreakBefore?: boolean;
+};
+/**
+ * Extract FontStyle from a run that carries RunFormatting (text, tab, or
+ * field). All three share the same formatting shape, so they measure the
+ * same way; widening the parameter keeps tab-following measurement
+ * (FieldRun page numbers, etc.) consistent with TextRun handling.
+ */
+declare function runToFontStyle(run: TextRun | TabRun | FieldRun | MathRun): FontStyle;
+/**
+ * Check if a run is a text run
+ */
+declare function isTextRun(run: Run): run is TextRun;
+/**
+ * Check if a run is a tab run
+ */
+declare function isTabRun(run: Run): run is TabRun;
+/**
+ * Check if a run is an image run
+ */
+declare function isImageRun(run: Run): run is ImageRun;
+/**
+ * Check if a run is a line break run
+ */
+declare function isLineBreakRun(run: Run): run is LineBreakRun;
+/**
+ * Check if a run is a field run
+ */
+declare function isFieldRun(run: Run): run is FieldRun;
+/** Text a field run is measured at: its resolved value when known (so the
+ *  measurer agrees with the painter), else the cached fallback. */
+declare function fieldMeasureText(run: FieldRun, fieldValues: ReadonlyMap<number, string> | undefined): string;
+/**
+ * Check if a run is a math equation run
+ */
+declare function isMathRun(run: Run): run is MathRun;
+/**
+ * Check if text run is empty (only whitespace or no text)
+ */
+declare function isEmptyTextRun(run: TextRun): boolean;
+/**
+ * Sum the inline pixel widths of runs after a tab, up to (but not including)
+ * the next tab or line break. Measured per-run so widths reserved match what
+ * the painter draws even when trailing runs use different fonts/sizes.
+ *
+ * Floating/anchored images are skipped — the painter lifts them out of the
+ * paragraph flow (see `isFloatingImageRun`) and `measureFollowingContentWidth`
+ * in the painter already excludes them, so counting their width here would
+ * desync measurer and painter on tab advance for paragraphs with a tab
+ * preceding a floating image.
+ */
+declare function isBlockLayoutImageRun(run: ImageRun): boolean;
+declare function isSpaceOrTab(char: string | undefined): boolean;
+//#endregion
+export { DEFAULT_FONT_SIZE, DEFAULT_LINE_HEIGHT_MULTIPLIER, LineState, LineTypography, WIDTH_TOLERANCE, fieldMeasureText, isBlockLayoutImageRun, isEmptyTextRun, isFieldRun, isImageRun, isLineBreakRun, isMathRun, isSpaceOrTab, isTabRun, isTextRun, runToFontStyle };

package/dist/layout-engine/measure/paragraphMeasureShared.js

@@ -0,0 +1,82 @@
+import { isFloatingImageRun } from "../types.js";
+import { DEFAULT_FONT_FAMILY, buildRunFontStyle } from "./measureHelpers.js";
+//#region src/layout-engine/measure/paragraphMeasureShared.ts
+const DEFAULT_FONT_SIZE = 11;
+const DEFAULT_LINE_HEIGHT_MULTIPLIER = 1;
+const WIDTH_TOLERANCE = .5;
+/**
+* Extract FontStyle from a run that carries RunFormatting (text, tab, or
+* field). All three share the same formatting shape, so they measure the
+* same way; widening the parameter keeps tab-following measurement
+* (FieldRun page numbers, etc.) consistent with TextRun handling.
+*/
+function runToFontStyle(run) {
+	return buildRunFontStyle(run, DEFAULT_FONT_FAMILY, 11);
+}
+/**
+* Check if a run is a text run
+*/
+function isTextRun(run) {
+	return run.kind === "text";
+}
+/**
+* Check if a run is a tab run
+*/
+function isTabRun(run) {
+	return run.kind === "tab";
+}
+/**
+* Check if a run is an image run
+*/
+function isImageRun(run) {
+	return run.kind === "image";
+}
+/**
+* Check if a run is a line break run
+*/
+function isLineBreakRun(run) {
+	return run.kind === "lineBreak";
+}
+/**
+* Check if a run is a field run
+*/
+function isFieldRun(run) {
+	return run.kind === "field";
+}
+/** Text a field run is measured at: its resolved value when known (so the
+*  measurer agrees with the painter), else the cached fallback. */
+function fieldMeasureText(run, fieldValues) {
+	return (run.pmStart === void 0 ? void 0 : fieldValues?.get(run.pmStart)) ?? (run.fallback || "1");
+}
+/**
+* Check if a run is a math equation run
+*/
+function isMathRun(run) {
+	return run.kind === "math";
+}
+/**
+* Check if text run is empty (only whitespace or no text)
+*/
+function isEmptyTextRun(run) {
+	return !run.text || run.text.replace(/\u00a0/gu, " ").trim().length === 0;
+}
+/**
+* Sum the inline pixel widths of runs after a tab, up to (but not including)
+* the next tab or line break. Measured per-run so widths reserved match what
+* the painter draws even when trailing runs use different fonts/sizes.
+*
+* Floating/anchored images are skipped — the painter lifts them out of the
+* paragraph flow (see `isFloatingImageRun`) and `measureFollowingContentWidth`
+* in the painter already excludes them, so counting their width here would
+* desync measurer and painter on tab advance for paragraphs with a tab
+* preceding a floating image.
+*/
+function isBlockLayoutImageRun(run) {
+	if (isFloatingImageRun(run)) return false;
+	return run.wrapType === "topAndBottom" || run.displayMode === "block";
+}
+function isSpaceOrTab(char) {
+	return char === " " || char === "	";
+}
+//#endregion
+export { DEFAULT_FONT_SIZE, DEFAULT_LINE_HEIGHT_MULTIPLIER, WIDTH_TOLERANCE, fieldMeasureText, isBlockLayoutImageRun, isEmptyTextRun, isFieldRun, isImageRun, isLineBreakRun, isMathRun, isSpaceOrTab, isTabRun, isTextRun, runToFontStyle };

package/dist/layout-engine/measure/paragraphTabs.d.ts

@@ -0,0 +1,18 @@
+import { Run } from "../types.js";
+//#region src/layout-engine/measure/paragraphTabs.d.ts
+declare function measureInlineWidthAfterTab(runs: Run[], tabIndex: number, fieldValues?: ReadonlyMap<number, string>): number;
+declare function hasFollowingTabOnLine(runs: Run[], tabIndex: number): boolean;
+declare function hasPriorTabOnLine(runs: Run[], tabIndex: number): boolean;
+declare function canClampTabToRightEdge(alignment: string, currentLineWidth: number, hasPriorTab: boolean, followingWidth: number, availableWidth: number): boolean;
+/**
+ * Width of the inline content preceding the first `.` in the runs that follow
+ * a tab, used to anchor `decimal` tab stops. Mirrors `getTextAfterTab` +
+ * decimal-prefix measurement in the painter (`renderParagraph.ts`) so the
+ * measurer and painter agree on tab advance for decimal stops.
+ *
+ * Returns 0 when no decimal separator appears before the next tab / line
+ * break — `calculateTabWidth` treats that as "no anchor adjustment".
+ */
+declare function measureDecimalPrefixWidthAfterTab(runs: Run[], tabIndex: number, fieldValues?: ReadonlyMap<number, string>): number;
+//#endregion
+export { canClampTabToRightEdge, hasFollowingTabOnLine, hasPriorTabOnLine, measureDecimalPrefixWidthAfterTab, measureInlineWidthAfterTab };

package/dist/layout-engine/measure/paragraphTabs.js

@@ -0,0 +1,78 @@
+import { inlineImageBoundingBox } from "../../utils/rotationBoundingBox.js";
+import { isFloatingImageRun } from "../types.js";
+import { measureTextWidth } from "./measureProvider.js";
+import { fieldMeasureText, isBlockLayoutImageRun, isFieldRun, isImageRun, isLineBreakRun, isMathRun, isTabRun, isTextRun, runToFontStyle } from "./paragraphMeasureShared.js";
+//#region src/layout-engine/measure/paragraphTabs.ts
+/**
+* Tab measurement on a line: the width of content following a tab, decimal
+* tab prefixes, neighbouring tabs, and right-edge clamping.
+*/
+function measureInlineWidthAfterTab(runs, tabIndex, fieldValues) {
+	let width = 0;
+	for (let i = tabIndex + 1; i < runs.length; i++) {
+		const next = runs[i];
+		if (!next || isTabRun(next) || isLineBreakRun(next)) break;
+		if (isImageRun(next)) {
+			if (isBlockLayoutImageRun(next)) break;
+			if (!isFloatingImageRun(next)) width += inlineImageBoundingBox(next).width || 0;
+			continue;
+		}
+		if (isTextRun(next)) width += measureTextWidth(next.text || "", runToFontStyle(next));
+		else if (isFieldRun(next)) width += measureTextWidth(fieldMeasureText(next, fieldValues), runToFontStyle(next));
+		else if (isMathRun(next)) width += measureTextWidth(next.plainText || "[equation]", runToFontStyle(next));
+	}
+	return width;
+}
+function hasFollowingTabOnLine(runs, tabIndex) {
+	for (let i = tabIndex + 1; i < runs.length; i++) {
+		const next = runs[i];
+		if (!next || isLineBreakRun(next)) break;
+		if (isImageRun(next) && isBlockLayoutImageRun(next)) break;
+		if (isTabRun(next)) return true;
+	}
+	return false;
+}
+function hasPriorTabOnLine(runs, tabIndex) {
+	for (let i = tabIndex - 1; i >= 0; i--) {
+		const prior = runs[i];
+		if (!prior || isLineBreakRun(prior) || isImageRun(prior) && isBlockLayoutImageRun(prior)) break;
+		if (isTabRun(prior)) return true;
+	}
+	return false;
+}
+function canClampTabToRightEdge(alignment, currentLineWidth, hasPriorTab, followingWidth, availableWidth) {
+	if (alignment === "start" || alignment === "default") return currentLineWidth > .5 && (hasPriorTab || followingWidth <= availableWidth);
+	return true;
+}
+/**
+* Width of the inline content preceding the first `.` in the runs that follow
+* a tab, used to anchor `decimal` tab stops. Mirrors `getTextAfterTab` +
+* decimal-prefix measurement in the painter (`renderParagraph.ts`) so the
+* measurer and painter agree on tab advance for decimal stops.
+*
+* Returns 0 when no decimal separator appears before the next tab / line
+* break — `calculateTabWidth` treats that as "no anchor adjustment".
+*/
+function measureDecimalPrefixWidthAfterTab(runs, tabIndex, fieldValues) {
+	let text = "";
+	let firstRun;
+	for (let i = tabIndex + 1; i < runs.length; i++) {
+		const next = runs[i];
+		if (!next || isTabRun(next) || isLineBreakRun(next)) break;
+		if (isTextRun(next)) {
+			text += next.text || "";
+			firstRun ??= next;
+		} else if (isFieldRun(next)) {
+			text += fieldMeasureText(next, fieldValues);
+			firstRun ??= next;
+		} else if (isMathRun(next)) {
+			text += next.plainText || "[equation]";
+			firstRun ??= next;
+		}
+	}
+	const decimalIndex = text.indexOf(".");
+	if (decimalIndex === -1 || !firstRun) return 0;
+	return measureTextWidth(text.slice(0, decimalIndex), runToFontStyle(firstRun));
+}
+//#endregion
+export { canClampTabToRightEdge, hasFollowingTabOnLine, hasPriorTabOnLine, measureDecimalPrefixWidthAfterTab, measureInlineWidthAfterTab };

package/dist/layout-engine/paragraphLayout.d.ts

@@ -0,0 +1,23 @@
+import { ParagraphBlock, ParagraphMeasure } from "./types.js";
+import { createPaginator } from "./paginator.js";
+//#region src/layout-engine/paragraphLayout.d.ts
+/**
+ * Layout a paragraph block onto pages.
+ *
+ * When `footnoteHeightById` is provided, each line carrying a footnote
+ * ref additionally reserves space on its host page for the fn's
+ * content. Pagination decisions include only the reservation growth
+ * beyond any retry floor, so a line cannot land on a page that lacks
+ * room for both body and note content.
+ */
+type LayoutParagraphOptions = {
+  block: ParagraphBlock;
+  measure: ParagraphMeasure;
+  paginator: ReturnType<typeof createPaginator>;
+  contentWidth: number;
+  footnoteHeightById: Map<number, number> | undefined;
+  suppressSpaceBefore: boolean;
+};
+declare function layoutParagraph({ block, measure, paginator, contentWidth, footnoteHeightById, suppressSpaceBefore }: LayoutParagraphOptions): void;
+//#endregion
+export { layoutParagraph };

package/dist/layout-engine/paragraphLayout.js

@@ -0,0 +1,204 @@
+import { hasKeepLines } from "./keep-together.js";
+import { projectedFootnoteReserveGrowth } from "./layoutFlowShared.js";
+import { measuredLineAdvance, measuredLineRangeHeight } from "./lineFlow.js";
+import { getParagraphFragmentPmRange } from "./paragraphFragmentRange.js";
+import { collapseParagraphSpacing, getParagraphSpacingAfter, getParagraphSpacingBefore } from "./paragraphSpacing.js";
+import "./types.js";
+//#region src/layout-engine/paragraphLayout.ts
+/**
+* Places a measured paragraph's lines onto pages: keep rules, widow/orphan
+* control, rendered-break reconciliation, and per-line footnote reservation.
+*/
+function hasWidowControl(block) {
+	return block.attrs?.widowControl !== false;
+}
+/**
+* Footnote refs whose run sits in line `[fromRun..toRun]`, with their
+* pre-measured content heights. Empty when the engine isn't tracking
+* dynamic fn demand. Used by `layoutParagraph` to (a) reserve fn
+* height per line and (b) record the IDs on the host page so the
+* painter renders the fn on the page where the ref-bearing line
+* actually landed — even when the paragraph splits across pages
+* (fragment pmStart/pmEnd is paragraph-wide and cannot disambiguate
+* between split halves).
+*/
+function getLineFootnoteRefs(block, fromRun, toRun, fnHeights) {
+	if (!fnHeights) return {
+		ids: [],
+		height: 0
+	};
+	const ids = [];
+	let height = 0;
+	for (let r = fromRun; r <= toRun; r++) {
+		const run = block.runs[r];
+		if (!run || run.kind !== "text") continue;
+		const id = run.footnoteRefId;
+		if (id === void 0) continue;
+		const h = fnHeights.get(id);
+		if (h !== void 0) {
+			ids.push(id);
+			height += h;
+		}
+	}
+	return {
+		ids,
+		height
+	};
+}
+function layoutParagraph({ block, measure, paginator, contentWidth, footnoteHeightById, suppressSpaceBefore }) {
+	const lines = measure.lines;
+	if (lines.length === 0) {
+		const spaceBefore = suppressSpaceBefore ? 0 : getParagraphSpacingBefore(block);
+		const spaceAfter = getParagraphSpacingAfter(block);
+		const state = paginator.getCurrentState();
+		const fragment = {
+			kind: "paragraph",
+			...block.attrs?.suppressEmptyParagraphHeight === true ? { paginationRole: "empty-carrier" } : {},
+			blockId: block.id,
+			x: paginator.getColumnX(state.columnIndex),
+			y: state.cursorY + spaceBefore,
+			width: contentWidth,
+			height: 0,
+			fromLine: 0,
+			toLine: 0,
+			...block.pmStart !== void 0 ? { pmStart: block.pmStart } : {},
+			...block.pmEnd !== void 0 ? { pmEnd: block.pmEnd } : {},
+			...block.sdtGroups ? { sdtGroups: block.sdtGroups } : {}
+		};
+		paginator.addFragment(fragment, 0, spaceBefore, spaceAfter);
+		return;
+	}
+	const spaceBefore = suppressSpaceBefore ? 0 : getParagraphSpacingBefore(block);
+	const spaceAfter = getParagraphSpacingAfter(block);
+	let keepLinesDemand;
+	if (lines.length > 1 && hasKeepLines(block)) {
+		let footnoteHeight = 0;
+		for (const line of lines) footnoteHeight += getLineFootnoteRefs(block, line.fromRun, line.toRun, footnoteHeightById).height;
+		keepLinesDemand = {
+			linesHeight: measuredLineRangeHeight(lines, 0, lines.length),
+			footnoteHeight
+		};
+	}
+	let keepLinesMoveAttempted = false;
+	let currentLineIndex = 0;
+	while (currentLineIndex < lines.length) {
+		const state = paginator.getCurrentState();
+		const availableHeight = paginator.getAvailableHeight();
+		const currentLine = lines.at(currentLineIndex);
+		const markerAlreadySatisfied = state.columnIndex === 0 && state.cursorY === state.topMargin && state.page.fragments.length === 0;
+		if (currentLine?.renderedPageBreakBefore === true && !markerAlreadySatisfied && availableHeight <= measuredLineAdvance(currentLine) * 3) {
+			paginator.forcePageBreak();
+			continue;
+		}
+		if (currentLineIndex === 0 && state.trailingSpacing > 0 && state.cursorY !== state.topMargin) {
+			const firstLine = lines[0];
+			const firstLineRefs = getLineFootnoteRefs(block, firstLine.fromRun, firstLine.toRun, footnoteHeightById);
+			const firstLineHeight = measuredLineAdvance(firstLine) + projectedFootnoteReserveGrowth(state, firstLineRefs.height);
+			const collapsedLead = collapseParagraphSpacing({
+				before: spaceBefore,
+				after: state.trailingSpacing
+			});
+			const columnCapacity = state.contentBottom - state.topMargin;
+			if (collapsedLead + firstLineHeight > availableHeight && spaceBefore + firstLineHeight <= columnCapacity) {
+				paginator.ensureFits(collapsedLead + firstLineHeight);
+				continue;
+			}
+		}
+		if (keepLinesDemand !== void 0 && !keepLinesMoveAttempted && currentLineIndex === 0 && state.cursorY !== state.topMargin) {
+			const wholeHeight = keepLinesDemand.linesHeight + projectedFootnoteReserveGrowth(state, keepLinesDemand.footnoteHeight);
+			const collapsedLead = collapseParagraphSpacing({
+				before: spaceBefore,
+				after: state.trailingSpacing
+			});
+			const columnCapacity = state.contentBottom - state.topMargin;
+			if (collapsedLead + wholeHeight > availableHeight && spaceBefore + wholeHeight <= columnCapacity) {
+				keepLinesMoveAttempted = true;
+				paginator.ensureFits(collapsedLead + wholeHeight);
+				continue;
+			}
+		}
+		let linesHeight = 0;
+		let linesFnHeight = 0;
+		const linesFnIds = [];
+		let fittingLines = 0;
+		let forcePageBreakAfterFragment = false;
+		const firstFragmentSpaceBefore = currentLineIndex === 0 ? collapseParagraphSpacing({
+			before: spaceBefore,
+			after: state.trailingSpacing
+		}) : 0;
+		for (let j = currentLineIndex; j < lines.length; j++) {
+			const line = lines[j];
+			const lineAdvance = measuredLineAdvance(line);
+			if (j > currentLineIndex && line.renderedPageBreakBefore === true && availableHeight - (linesHeight + firstFragmentSpaceBefore + linesFnHeight) <= lineAdvance * 3) {
+				forcePageBreakAfterFragment = true;
+				break;
+			}
+			const lineRefs = getLineFootnoteRefs(block, line.fromRun, line.toRun, footnoteHeightById);
+			const totalWithLine = linesHeight + lineAdvance;
+			const footnoteGrowth = projectedFootnoteReserveGrowth(state, linesFnHeight + lineRefs.height);
+			if (totalWithLine + firstFragmentSpaceBefore + footnoteGrowth <= availableHeight || fittingLines === 0) {
+				linesHeight = totalWithLine;
+				linesFnHeight += lineRefs.height;
+				for (const id of lineRefs.ids) linesFnIds.push(id);
+				fittingLines++;
+			} else break;
+		}
+		let forceBreakAfterFragment = false;
+		if (hasWidowControl(block)) {
+			const remainingAfter = lines.length - (currentLineIndex + fittingLines);
+			if (fittingLines > 1 && remainingAfter === 1) {
+				if (currentLineIndex === 0 && fittingLines === 2 && state.cursorY !== state.topMargin) {
+					paginator.forceColumnBreak();
+					continue;
+				}
+				fittingLines -= 1;
+				forceBreakAfterFragment = true;
+				linesHeight = 0;
+				linesFnHeight = 0;
+				linesFnIds.length = 0;
+				for (let j = currentLineIndex; j < currentLineIndex + fittingLines; j++) {
+					const line = lines[j];
+					linesHeight += measuredLineAdvance(line);
+					const lineRefs = getLineFootnoteRefs(block, line.fromRun, line.toRun, footnoteHeightById);
+					linesFnHeight += lineRefs.height;
+					for (const id of lineRefs.ids) linesFnIds.push(id);
+				}
+			}
+		}
+		const isFirstFragment = currentLineIndex === 0;
+		const isLastFragment = currentLineIndex + fittingLines >= lines.length;
+		const effectiveSpaceBefore = isFirstFragment ? spaceBefore : 0;
+		const effectiveSpaceAfter = isLastFragment ? spaceAfter : 0;
+		const pmRange = getParagraphFragmentPmRange(block, measure, currentLineIndex, currentLineIndex + fittingLines);
+		const fragment = {
+			kind: "paragraph",
+			...block.attrs?.suppressEmptyParagraphHeight === true ? { paginationRole: "empty-carrier" } : {},
+			blockId: block.id,
+			x: paginator.getColumnX(state.columnIndex),
+			y: 0,
+			width: contentWidth,
+			height: linesHeight,
+			fromLine: currentLineIndex,
+			toLine: currentLineIndex + fittingLines,
+			...pmRange.pmStart !== void 0 ? { pmStart: pmRange.pmStart } : {},
+			...pmRange.pmEnd !== void 0 ? { pmEnd: pmRange.pmEnd } : {},
+			...!isFirstFragment ? { continuesFromPrev: true } : {},
+			...!isLastFragment ? { continuesOnNext: true } : {},
+			...block.sdtGroups ? { sdtGroups: block.sdtGroups } : {}
+		};
+		if (linesFnHeight > 0) {
+			const stateBefore = paginator.getCurrentState();
+			paginator.ensureFits(effectiveSpaceBefore + linesHeight + projectedFootnoteReserveGrowth(stateBefore, linesFnHeight));
+			const stateAfter = paginator.getCurrentState();
+			if (stateAfter.footnoteDemandHeight === 0) paginator.ensureFits(effectiveSpaceBefore + linesHeight + projectedFootnoteReserveGrowth(stateAfter, linesFnHeight + 12));
+		}
+		fragment.y = paginator.addFragment(fragment, linesHeight, effectiveSpaceBefore, effectiveSpaceAfter).y;
+		if (linesFnHeight > 0) paginator.addFootnoteHeight(linesFnHeight, linesFnIds);
+		currentLineIndex += fittingLines;
+		if (currentLineIndex < lines.length) if (forcePageBreakAfterFragment) paginator.forcePageBreak();
+		else if (forceBreakAfterFragment) paginator.forceColumnBreak();
+		else paginator.ensureFits(measuredLineAdvance(lines[currentLineIndex]));
+	}
+}
+//#endregion
+export { layoutParagraph };

package/dist/layout-engine/sectionLayout.d.ts

@@ -0,0 +1,45 @@
+import { ColumnLayout, FlowBlock, Measure, PageMargins, SectionBreakBlock, SectionPageNumbering } from "./types.js";
+import { createPaginator } from "./paginator.js";
+import { SectionStart } from "@stll/docx-core/model";
+//#region src/layout-engine/sectionLayout.d.ts
+type SectionLayoutConfig = {
+  pageSize: {
+    w: number;
+    h: number;
+  };
+  margins: PageMargins;
+  pageNumbering: SectionPageNumbering;
+  columns?: ColumnLayout;
+};
+declare const DEFAULT_COLUMNS: ColumnLayout;
+declare const CONTINUE_PAGE_NUMBERING: SectionPageNumbering;
+declare function collectSectionConfigs(blocks: FlowBlock[], initialConfig: SectionLayoutConfig, finalConfig: SectionLayoutConfig): {
+  configs: SectionLayoutConfig[];
+  breakIndices: number[];
+};
+/**
+ * Estimate the height of a short paragraph-only multi-column section so its
+ * final page can use Word-style balanced columns. Sections containing tables,
+ * floating blocks, or authored breaks keep the normal bottom-up pagination;
+ * those need structure-aware balancing rather than a height estimate.
+ */
+type BalancedParagraphSectionHeightOptions = {
+  blocks: FlowBlock[];
+  measures: Measure[];
+  startIndex: number;
+  endIndex: number;
+  incomingSpacing: number;
+  columnCount: number;
+  availableHeight: number;
+};
+declare function balancedParagraphSectionHeight({ blocks, measures, startIndex, endIndex, incomingSpacing, columnCount, availableHeight }: BalancedParagraphSectionHeightOptions): number | undefined;
+/**
+ * Handle a section break block.
+ * @param block - The section break block (current section's properties)
+ * @param paginator - The paginator instance
+ * @param nextSectionConfig - Page layout for the NEXT section
+ * @param nextSectionType - Break type of the NEXT section (how it starts relative to current)
+ */
+declare function handleSectionBreak(_block: SectionBreakBlock, paginator: ReturnType<typeof createPaginator>, nextSectionConfig: SectionLayoutConfig, nextSectionType: SectionStart, nextSectionIndex?: number): void;
+//#endregion
+export { CONTINUE_PAGE_NUMBERING, DEFAULT_COLUMNS, SectionLayoutConfig, balancedParagraphSectionHeight, collectSectionConfigs, handleSectionBreak };