@stll/folio-core 0.49.0 → 0.50.0

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

@@ -0,0 +1,6 @@
+import { PageState } from "./paginator.js";
+//#region src/layout-engine/layoutFlowShared.d.ts
+declare const RENDERED_BREAK_REFLOW_TOLERANCE_LINES = 3;
+declare function projectedFootnoteReserveGrowth(state: PageState, additionalDemandHeight: number): number;
+//#endregion
+export { RENDERED_BREAK_REFLOW_TOLERANCE_LINES, projectedFootnoteReserveGrowth };

package/dist/layout-engine/layoutFlowShared.js

@@ -0,0 +1,8 @@
+//#region src/layout-engine/layoutFlowShared.ts
+const RENDERED_BREAK_REFLOW_TOLERANCE_LINES = 3;
+function projectedFootnoteReserveGrowth(state, additionalDemandHeight) {
+	const projectedDemand = state.footnoteDemandHeight + additionalDemandHeight;
+	return Math.max(state.footnoteHeightFloor, projectedDemand) - state.footnoteHeight;
+}
+//#endregion
+export { RENDERED_BREAK_REFLOW_TOLERANCE_LINES, projectedFootnoteReserveGrowth };

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

@@ -0,0 +1,45 @@
+import { ParagraphBlock, TextRun } from "../types.js";
+import { FontStyle } from "./measureTypes.js";
+//#region src/layout-engine/measure/crossRunWords.d.ts
+/**
+ * Width of the unbreakable text glued to the end of each run.
+ * A run boundary is not itself a wrap opportunity: adjacent note markers and
+ * format-only word splits must wrap as one cluster.
+ */
+declare function computeTrailingGlueWidths(block: ParagraphBlock): number[];
+/**
+ * First character of the text that follows each run, looking through empty
+ * text runs; undefined before a non-text run or at the paragraph end.
+ */
+declare function computeFollowingTextLeads(block: ParagraphBlock): (string | undefined)[];
+declare function computeProtectedCrossRunGlueWidths(block: ParagraphBlock): number[];
+type CrossRunWordSegment = {
+  runIndex: number;
+  startChar: number;
+  text: string;
+  run: TextRun;
+  style: FontStyle;
+};
+type CrossRunWord = {
+  text: string;
+  width: number;
+  breaks: number[];
+  segments: CrossRunWordSegment[];
+};
+type CollectCrossRunWordOptions = {
+  block: ParagraphBlock;
+  startRunIndex: number;
+  startChar: number;
+};
+/** Collect one lexical word continued through adjacent formatting runs. */
+declare function collectCrossRunWord({ block, startRunIndex, startChar }: CollectCrossRunWordOptions): CrossRunWord | undefined;
+type CrossRunPrefix = {
+  width: number;
+  endRunIndex: number;
+  endChar: number;
+  hyphenStyle: FontStyle;
+  segments: CrossRunWordSegment[];
+};
+declare function measureCrossRunPrefix(word: CrossRunWord, breakOffset: number): CrossRunPrefix | undefined;
+//#endregion
+export { CrossRunPrefix, collectCrossRunWord, computeFollowingTextLeads, computeProtectedCrossRunGlueWidths, computeTrailingGlueWidths, measureCrossRunPrefix };

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

@@ -0,0 +1,172 @@
+import { splitTrailingToken } from "../../utils/trailingText.js";
+import { resolveEffectiveLineBreakPolicy } from "./effectiveLineBreakPolicy.js";
+import "./lineBreakProvider.js";
+import { findHyphenationBreaks, findWordBreaks } from "./lineBreaks.js";
+import { trimTrailingSpacesAndTabs } from "./lineFitting.js";
+import { measureTextWidth } from "./measureProvider.js";
+import { isSpaceOrTab, isTextRun, runToFontStyle } from "./paragraphMeasureShared.js";
+//#region src/layout-engine/measure/crossRunWords.ts
+/**
+* Words that span runs: glue widths between differently formatted runs and
+* the segments of a word collected across several runs.
+*/
+/**
+* Width of the unbreakable text glued to the end of each run.
+* A run boundary is not itself a wrap opportunity: adjacent note markers and
+* format-only word splits must wrap as one cluster.
+*/
+function computeTrailingGlueWidths(block) {
+	const runs = block.runs;
+	const widths = Array.from({ length: runs.length }, () => 0);
+	for (let index = runs.length - 1; index >= 0; index--) {
+		const nextRun = runs[index + 1];
+		if (!nextRun || !isTextRun(nextRun)) continue;
+		const text = nextRun.text;
+		if (!text) {
+			widths[index] = widths[index + 1] ?? 0;
+			continue;
+		}
+		if (isSpaceOrTab(text.at(0))) continue;
+		const style = runToFontStyle(nextRun);
+		const firstBreak = findWordBreaks(text, resolveEffectiveLineBreakPolicy({
+			attrs: block.attrs,
+			run: nextRun
+		}).provider).at(0);
+		widths[index] = measureTextWidth(firstBreak === void 0 ? text : trimTrailingSpacesAndTabs(text.slice(0, firstBreak)), style) + (firstBreak === void 0 ? widths[index + 1] ?? 0 : 0);
+	}
+	return widths;
+}
+/**
+* First character of the text that follows each run, looking through empty
+* text runs; undefined before a non-text run or at the paragraph end.
+*/
+function computeFollowingTextLeads(block) {
+	const leads = Array.from({ length: block.runs.length }, () => void 0);
+	let lead;
+	for (let index = block.runs.length - 1; index >= 0; index--) {
+		leads[index] = lead;
+		const run = block.runs[index];
+		if (!run || !isTextRun(run)) lead = void 0;
+		else if (run.text) lead = run.text[0];
+	}
+	return leads;
+}
+function computeProtectedCrossRunGlueWidths(block) {
+	const widths = Array.from({ length: block.runs.length }, () => 0);
+	for (let index = 0; index < block.runs.length; index++) {
+		const run = block.runs[index];
+		if (!run || !isTextRun(run)) continue;
+		const policy = resolveEffectiveLineBreakPolicy({
+			attrs: block.attrs,
+			run
+		}).provider;
+		if (!policy.locale?.toLocaleLowerCase().startsWith("cs")) continue;
+		const trailing = splitTrailingToken(run.text ?? "");
+		if (!trailing || trailing.token.length !== 1) continue;
+		const { token } = trailing;
+		let separator = trailing.separator;
+		let glueWidth = separator.length > 0 ? measureTextWidth(separator, runToFontStyle(run)) : 0;
+		let followingWord = "";
+		let unseparatedFollowingText = false;
+		for (let nextIndex = index + 1; nextIndex < block.runs.length; nextIndex++) {
+			const nextRun = block.runs[nextIndex];
+			if (!nextRun || !isTextRun(nextRun)) break;
+			const text = nextRun.text ?? "";
+			let consumed = "";
+			for (const char of text) {
+				const isWhitespace = /\s/u.test(char);
+				if (followingWord.length > 0 && isWhitespace) break;
+				if (separator.length === 0 && !isWhitespace) {
+					unseparatedFollowingText = true;
+					break;
+				}
+				consumed += char;
+				if (isWhitespace) separator += char;
+				else followingWord += char;
+			}
+			if (consumed.length > 0) glueWidth += measureTextWidth(consumed, runToFontStyle(nextRun));
+			if (unseparatedFollowingText) break;
+			if (followingWord.length > 0 && consumed.length < text.length) break;
+		}
+		if (unseparatedFollowingText || separator.length === 0 || followingWord.length === 0) continue;
+		const boundary = token.length + separator.length;
+		if (!findWordBreaks(token + separator + followingWord, policy).includes(boundary)) widths[index] = glueWidth;
+	}
+	return widths;
+}
+/**
+* Cap on the number of runs `collectCrossRunWord` traverses per call. A
+* paragraph split into many tiny (including empty) runs would otherwise let
+* the search walk the full run list for every word-start position it is
+* invoked from, without the per-word text-length budget ever kicking in.
+*/
+const MAX_CROSS_RUN_SEGMENTS = 64;
+/** Collect one lexical word continued through adjacent formatting runs. */
+function collectCrossRunWord({ block, startRunIndex, startChar }) {
+	const segments = [];
+	let text = "";
+	let width = 0;
+	for (let runIndex = startRunIndex; runIndex < block.runs.length; runIndex++) {
+		if (runIndex - startRunIndex >= MAX_CROSS_RUN_SEGMENTS) return;
+		const run = block.runs[runIndex];
+		if (!run || !isTextRun(run)) break;
+		const start = runIndex === startRunIndex ? startChar : 0;
+		const remainder = run.text.slice(start);
+		if (remainder.length === 0) continue;
+		if (runIndex !== startRunIndex && isSpaceOrTab(remainder[0])) break;
+		const remainingBudget = 256 - text.length;
+		const boundedRemainder = remainder.slice(0, remainingBudget + 1);
+		const firstBreak = findWordBreaks(boundedRemainder, resolveEffectiveLineBreakPolicy({
+			attrs: block.attrs,
+			run
+		}).provider).at(0);
+		const segmentText = trimTrailingSpacesAndTabs(firstBreak === void 0 ? boundedRemainder : boundedRemainder.slice(0, firstBreak));
+		if (segmentText.length === 0) break;
+		if (segmentText.length > remainingBudget) return;
+		const style = runToFontStyle(run);
+		segments.push({
+			runIndex,
+			startChar: start,
+			text: segmentText,
+			run,
+			style
+		});
+		text += segmentText;
+		width += measureTextWidth(segmentText, style);
+		if (firstBreak !== void 0) break;
+	}
+	if (segments.length < 2) return;
+	const firstRun = segments[0]?.run;
+	if (!firstRun) return;
+	return {
+		text,
+		width,
+		breaks: findHyphenationBreaks(text, resolveEffectiveLineBreakPolicy({
+			attrs: block.attrs,
+			run: firstRun
+		}).provider),
+		segments
+	};
+}
+function measureCrossRunPrefix(word, breakOffset) {
+	let width = 0;
+	let remaining = breakOffset;
+	const measuredSegments = [];
+	for (const segment of word.segments) {
+		const length = Math.min(remaining, segment.text.length);
+		if (length > 0) {
+			width += measureTextWidth(segment.text.slice(0, length), segment.style);
+			measuredSegments.push(segment);
+		}
+		if (remaining <= segment.text.length) return {
+			width,
+			endRunIndex: segment.runIndex,
+			endChar: segment.startChar + remaining,
+			hyphenStyle: segment.style,
+			segments: measuredSegments
+		};
+		remaining -= segment.text.length;
+	}
+}
+//#endregion
+export { collectCrossRunWord, computeFollowingTextLeads, computeProtectedCrossRunGlueWidths, computeTrailingGlueWidths, measureCrossRunPrefix };

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

@@ -0,0 +1,24 @@
+import { FloatingImageZone } from "./floatingZones.js";
+//#region src/layout-engine/measure/floatingLineClearance.d.ts
+/**
+ * Minimum horizontal room a line must offer before we treat it as usable for
+ * body text. Below this threshold the line is bumped past obstructing floats
+ * via `findClearLineY` instead of being rendered into the unusable sliver.
+ * Without this guard, a near-full-width float (e.g. floating table) produces
+ * a ~2px segment that collapses every wrap line to one glyph per row.
+ */
+declare const MIN_WRAP_SEGMENT_WIDTH = 24;
+/**
+ * Find the next vertical position at or below `startY` where the available
+ * text width is at least `minWidth`. Used to skip lines past stacked floats
+ * when there is no horizontal room for meaningful text at the current Y.
+ *
+ * Returns `startY` if the current position already has enough room, otherwise
+ * the lowest `bottomY` of any zone currently obstructing the line. The caller
+ * is expected to re-query margins at the returned Y.
+ *
+ * Coordinates are absolute (i.e., already include any paragraphYOffset).
+ */
+declare function findClearLineY(startY: number, lineHeight: number, zones: FloatingImageZone[] | undefined, contentWidth: number, minWidth: number): number;
+//#endregion
+export { MIN_WRAP_SEGMENT_WIDTH, findClearLineY };

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

@@ -0,0 +1,44 @@
+import { getFloatingAvailableWidth, getFloatingMargins } from "./floatingZones.js";
+//#region src/layout-engine/measure/floatingLineClearance.ts
+/**
+* Finds where a line clears floating objects that leave too little width
+* beside them.
+*/
+/**
+* Minimum horizontal room a line must offer before we treat it as usable for
+* body text. Below this threshold the line is bumped past obstructing floats
+* via `findClearLineY` instead of being rendered into the unusable sliver.
+* Without this guard, a near-full-width float (e.g. floating table) produces
+* a ~2px segment that collapses every wrap line to one glyph per row.
+*/
+const MIN_WRAP_SEGMENT_WIDTH = 24;
+/**
+* Find the next vertical position at or below `startY` where the available
+* text width is at least `minWidth`. Used to skip lines past stacked floats
+* when there is no horizontal room for meaningful text at the current Y.
+*
+* Returns `startY` if the current position already has enough room, otherwise
+* the lowest `bottomY` of any zone currently obstructing the line. The caller
+* is expected to re-query margins at the returned Y.
+*
+* Coordinates are absolute (i.e., already include any paragraphYOffset).
+*/
+function findClearLineY(startY, lineHeight, zones, contentWidth, minWidth) {
+	if (!zones || zones.length === 0) return startY;
+	let y = startY;
+	for (let i = 0; i < zones.length + 2; i++) {
+		const margins = getFloatingMargins(y, lineHeight, zones, 0);
+		if (Math.max(0, getFloatingAvailableWidth(margins, contentWidth)) >= minWidth) return y;
+		const lineBottom = y + lineHeight;
+		let nextY = Number.POSITIVE_INFINITY;
+		for (const zone of zones) {
+			if (lineBottom <= zone.topY || y >= zone.bottomY) continue;
+			if (zone.bottomY > y && zone.bottomY < nextY) nextY = zone.bottomY;
+		}
+		if (!Number.isFinite(nextY) || nextY <= y) return y;
+		y = nextY;
+	}
+	return y;
+}
+//#endregion
+export { MIN_WRAP_SEGMENT_WIDTH, findClearLineY };

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

@@ -0,0 +1,6 @@
+import { ImageRun, MathRun } from "../types.js";
+//#region src/layout-engine/measure/inlineObjectMetrics.d.ts
+declare function rotatedBlockImageHeight(run: ImageRun): number;
+declare function estimateMathFootprintPx(run: MathRun): number;
+//#endregion
+export { estimateMathFootprintPx, rotatedBlockImageHeight };

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

@@ -0,0 +1,52 @@
+import { ptToPx } from "./measureHelpers.js";
+import "./paragraphMeasureShared.js";
+//#region src/layout-engine/measure/inlineObjectMetrics.ts
+function parseRotationDegrees(transform) {
+	if (!transform) return 0;
+	const match = /rotate\(\s*(?<degrees>[-\d.]+)\s*deg\s*\)/u.exec(transform);
+	if (!match) return 0;
+	const raw = Number.parseFloat(match.groups["degrees"]);
+	if (!Number.isFinite(raw)) return 0;
+	return (raw % 360 + 360) % 360;
+}
+function rotatedBlockImageHeight(run) {
+	const deg = parseRotationDegrees(run.transform);
+	if (deg === 0 || deg === 180) return run.height;
+	if (deg === 90 || deg === 270) return run.width;
+	const rad = deg * Math.PI / 180;
+	const sinA = Math.abs(Math.sin(rad));
+	const cosA = Math.abs(Math.cos(rad));
+	return run.width * sinA + run.height * cosA;
+}
+function isStackedMathLocalName(localName) {
+	switch (localName) {
+		case "bar":
+		case "d":
+		case "eqArr":
+		case "f":
+		case "groupChr":
+		case "limLow":
+		case "limUpp":
+		case "m":
+		case "nary":
+		case "rad":
+		case "sPre":
+		case "sSubSup": return true;
+		default: return false;
+	}
+}
+function hasStackedMathLayout(run) {
+	if (run.display === "block") return true;
+	for (const match of run.ommlXml.matchAll(/<(?<tag>[A-Za-z_][\w.-]*(?::[A-Za-z_][\w.-]*)?)(?:\s|\/|>)/gu)) {
+		const tagName = match.groups?.["tag"];
+		if (!tagName) continue;
+		const colonIndex = tagName.indexOf(":");
+		if (isStackedMathLocalName(colonIndex === -1 ? tagName : tagName.slice(colonIndex + 1))) return true;
+	}
+	return false;
+}
+function estimateMathFootprintPx(run) {
+	return ptToPx(run.fontSize ?? 11) * (hasStackedMathLayout(run) ? 2.4 : 1.25);
+}
+//#endregion
+export { estimateMathFootprintPx, rotatedBlockImageHeight };

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

@@ -0,0 +1,32 @@
+import { ParagraphBlock } from "../types.js";
+import { FontStyle } from "./measureTypes.js";
+import { LineState } from "./paragraphMeasureShared.js";
+//#region src/layout-engine/measure/justification.d.ts
+declare function uppercaseLetterRatio(text: string): number;
+type JustifyFitStrategy = {
+  type: "rounding";
+} | {
+  type: "space";
+  ratio: number;
+} | {
+  type: "width";
+  ratio: number;
+};
+type JustificationProfile = {
+  hasTabRuns: boolean;
+  uppercaseRatio: number;
+};
+declare function resolveJustifyFitStrategy(block: ParagraphBlock, isFirstLine: boolean, profile: JustificationProfile): JustifyFitStrategy;
+declare function compressibleSpaceWidth(text: string, style: FontStyle): number;
+/**
+ * Content being fitted onto a justified line: the line width with it added,
+ * and the width of spaces inside it that stay on the line (an atomic field
+ * result). A word's own trailing space hangs instead, so it is not counted.
+ */
+type JustifyCandidate = {
+  width: number;
+  innerSpaceWidth: number;
+};
+declare function justifyFitTolerance(line: LineState, strategy: JustifyFitStrategy, candidateSpaceWidth: number, candidate?: JustifyCandidate): number;
+//#endregion
+export { JustificationProfile, compressibleSpaceWidth, justifyFitTolerance, resolveJustifyFitStrategy, uppercaseLetterRatio };

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

@@ -0,0 +1,83 @@
+import { measureTextWidth } from "./measureProvider.js";
+import { WIDTH_TOLERANCE } from "./paragraphMeasureShared.js";
+import { countCompressibleSpaces } from "./textMeasurementPolicy.js";
+//#region src/layout-engine/measure/justification.ts
+const JUSTIFY_SHRINK_TOLERANCE_RATIO = .016;
+const JUSTIFY_SPACE_CONTRACTION_RATIO = .25;
+const JUSTIFY_STRETCH_PER_SHRINK = 1.7;
+const JUSTIFY_ALWAYS_SHRINK_STRETCH = 1.5;
+const JUSTIFY_LITERAL_TAB_CONTINUATION_SHRINK_TOLERANCE_RATIO = .017;
+const JUSTIFY_HANGING_TAB_SHRINK_TOLERANCE_RATIO = .021;
+const ALL_CAPS_RATIO_THRESHOLD = .8;
+function uppercaseLetterRatio(text) {
+	let letters = 0;
+	let uppercase = 0;
+	for (const char of text) {
+		const lower = char.toLocaleLowerCase();
+		const upper = char.toLocaleUpperCase();
+		if (lower === upper) continue;
+		letters++;
+		if (char === upper) uppercase++;
+	}
+	return letters === 0 ? 0 : uppercase / letters;
+}
+function resolveJustifyFitStrategy(block, isFirstLine, profile) {
+	if (block.attrs?.justificationCompatibility?.type === "legacy") return { type: "rounding" };
+	const hasTabStops = (block.attrs?.tabs?.length ?? 0) > 0;
+	if (isFirstLine && profile.hasTabRuns && (block.attrs?.indent?.hanging ?? 0) > 0) return {
+		type: "width",
+		ratio: JUSTIFY_SHRINK_TOLERANCE_RATIO
+	};
+	if (!isFirstLine && profile.hasTabRuns && !hasTabStops) return {
+		type: "width",
+		ratio: JUSTIFY_LITERAL_TAB_CONTINUATION_SHRINK_TOLERANCE_RATIO
+	};
+	if (profile.hasTabRuns && (isFirstLine || hasTabStops)) return {
+		type: "width",
+		ratio: (block.attrs?.indent?.firstLine ?? 0) === 0 ? JUSTIFY_HANGING_TAB_SHRINK_TOLERANCE_RATIO : JUSTIFY_SHRINK_TOLERANCE_RATIO
+	};
+	if (profile.uppercaseRatio > ALL_CAPS_RATIO_THRESHOLD) return {
+		type: "width",
+		ratio: JUSTIFY_SHRINK_TOLERANCE_RATIO
+	};
+	return {
+		type: "space",
+		ratio: JUSTIFY_SPACE_CONTRACTION_RATIO
+	};
+}
+function compressibleSpaceWidth(text, style) {
+	const count = countCompressibleSpaces(text);
+	return count === 0 ? 0 : count * measureTextWidth(" ", style);
+}
+function justifyFitTolerance(line, strategy, candidateSpaceWidth, candidate) {
+	if (strategy.type === "rounding") return WIDTH_TOLERANCE;
+	if (strategy.type === "width") return Math.max(WIDTH_TOLERANCE, line.availableWidth * strategy.ratio);
+	if (candidate !== void 0 && !prefersSpaceShrink(line, candidate)) return WIDTH_TOLERANCE;
+	return Math.max(WIDTH_TOLERANCE, (line.regularSpaceWidth + candidateSpaceWidth) * strategy.ratio);
+}
+/**
+* A justified line whose next word overflows the measure has two outcomes:
+* keep the word and shrink the line's spaces, or wrap it and stretch the
+* spaces left on the shorter line. Shrinking wins only when the stretch it
+* avoids is large compared with the shrink it costs: the shrink factor may
+* not exceed `1 + (stretch - 1) / JUSTIFY_STRETCH_PER_SHRINK`, and a stretch
+* beyond `JUSTIFY_ALWAYS_SHRINK_STRETCH` always prefers shrinking. The space
+* before the wrapped word hangs at the line end, so it does not stretch; a
+* line left with nothing to stretch defers to the shrink budget alone.
+*/
+function prefersSpaceShrink(line, candidate) {
+	const overflow = candidate.width - line.availableWidth;
+	if (overflow <= .5) return true;
+	const shrinkableSpaceWidth = line.regularSpaceWidth + candidate.innerSpaceWidth;
+	if (shrinkableSpaceWidth <= overflow) return false;
+	const hangingSpaceWidth = Math.min(line.trailingWhitespaceWidth, line.regularSpaceWidth);
+	const stretchableSpaceWidth = line.regularSpaceWidth - hangingSpaceWidth;
+	if (stretchableSpaceWidth <= 0) return true;
+	const visibleWidth = line.width - line.trailingWhitespaceWidth;
+	const stretch = 1 + Math.max(0, line.availableWidth - visibleWidth) / stretchableSpaceWidth;
+	if (stretch > JUSTIFY_ALWAYS_SHRINK_STRETCH) return true;
+	const shrink = shrinkableSpaceWidth / (shrinkableSpaceWidth - overflow);
+	return 1 + (stretch - 1) / JUSTIFY_STRETCH_PER_SHRINK >= shrink;
+}
+//#endregion
+export { compressibleSpaceWidth, justifyFitTolerance, resolveJustifyFitStrategy, uppercaseLetterRatio };

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

@@ -0,0 +1,48 @@
+import { MeasuredLine, ParagraphBlock, Run } from "../types.js";
+import { FontStyle } from "./measureTypes.js";
+import { LineBreakPolicy } from "./lineBreakProvider.js";
+import { LineState } from "./paragraphMeasureShared.js";
+//#region src/layout-engine/measure/lineFitting.d.ts
+/**
+ * Find the longest prefix of `text` that fits within `maxWidth` pixels.
+ * Returns the number of characters that fit (at least 1 if `forceMin` is true).
+ */
+declare function findMaxFittingLength(text: string, style: FontStyle, maxWidth: number, forceMin?: boolean, policy?: LineBreakPolicy): number;
+declare function exceedsHyphenationZone(line: LineState, zoneTwips: number): boolean;
+declare const isIgnorableFinalTailRun: (run: Run) => boolean;
+declare function isFinalTextCandidate(block: ParagraphBlock, runIndex: number, nextBreak: number): boolean;
+type TextCandidateFit = {
+  type: "ordinary";
+  tolerancePx: number;
+} | {
+  type: "final-contraction-admitted";
+  tolerancePx: number;
+  paint: NonNullable<MeasuredLine["justificationPaint"]>;
+};
+/**
+ * Fit of a text candidate on a justified line: the paragraph's final word may
+ * be admitted by shrinking spaces, which then needs a paint plan.
+ */
+declare function resolveTextCandidateFit(isFinalCandidate: boolean, candidateWidth: number, availableWidth: number, tolerancePx: number): TextCandidateFit;
+declare function trimTrailingSpacesAndTabs(text: string): string;
+declare function measureWordWithTrailingWhitespace(word: string, style: FontStyle): {
+  measuredWord: string;
+  wordWidth: number;
+  fullWordWidth: number;
+};
+/**
+ * Character spacing still owed after the last character placed on the line,
+ * or 0 when the line has no preceding character at `charIndex` of `runIndex`.
+ * Within a run it is the run's own spacing; at a boundary between two text
+ * runs it is the preceding run's spacing on its final character.
+ */
+declare function precedingLetterSpacing({ block, line, runIndex, charIndex, runStyle }: {
+  block: ParagraphBlock;
+  line: LineState;
+  runIndex: number;
+  charIndex: number;
+  runStyle: FontStyle;
+}): number;
+declare function trailingHangingPunctuationWidth(text: string, style: FontStyle, policy: LineBreakPolicy, enabled: boolean): number;
+//#endregion
+export { exceedsHyphenationZone, findMaxFittingLength, isFinalTextCandidate, isIgnorableFinalTailRun, measureWordWithTrailingWhitespace, precedingLetterSpacing, resolveTextCandidateFit, trailingHangingPunctuationWidth, trimTrailingSpacesAndTabs };

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

@@ -0,0 +1,145 @@
+import { getHorizontalScaleFactor } from "../../utils/horizontalScale.js";
+import { defaultLineBreakProvider, getLineBreakProvider } from "./lineBreakProvider.js";
+import { findGraphemeBreaks, isHangingPunctuation } from "./lineBreaks.js";
+import { twipsToPx } from "./measureHelpers.js";
+import { measureTextWidth } from "./measureProvider.js";
+import { WIDTH_TOLERANCE, isTextRun, runToFontStyle } from "./paragraphMeasureShared.js";
+//#region src/layout-engine/measure/lineFitting.ts
+/**
+* Line-fitting helpers: character-level fit search, the hyphenation zone,
+* final-candidate admission, and the trailing whitespace, letter-spacing and
+* hanging-punctuation widths a line break may exclude.
+*/
+/**
+* Find the longest prefix of `text` that fits within `maxWidth` pixels.
+* Returns the number of characters that fit (at least 1 if `forceMin` is true).
+*/
+function findMaxFittingLength(text, style, maxWidth, forceMin = false, policy) {
+	const boundaries = findGraphemeBreaks(text, policy);
+	let lo = 0;
+	let hi = boundaries.length - 1;
+	let best = 0;
+	while (lo <= hi) {
+		const mid = Math.floor((lo + hi) / 2);
+		const boundary = boundaries[mid];
+		if (measureTextWidth(text.slice(0, boundary), style) <= maxWidth) {
+			best = boundary;
+			lo = mid + 1;
+		} else hi = mid - 1;
+	}
+	return forceMin && best === 0 ? boundaries.at(0) ?? 0 : best;
+}
+function exceedsHyphenationZone(line, zoneTwips) {
+	if (line.width <= 0) return true;
+	const visibleWidth = Math.max(0, line.width - line.trailingWhitespaceWidth);
+	return Math.max(0, line.availableWidth - visibleWidth) > twipsToPx(zoneTwips) + WIDTH_TOLERANCE;
+}
+const isIgnorableFinalTailRun = (run) => run.kind === "renderedPageBreak" || isTextRun(run) && run.text.length === 0;
+function isFinalTextCandidate(block, runIndex, nextBreak) {
+	const currentRun = block.runs[runIndex];
+	if (!currentRun || !isTextRun(currentRun) || nextBreak !== currentRun.text.length) return false;
+	for (let index = runIndex + 1; index < block.runs.length; index += 1) {
+		const run = block.runs[index];
+		if (run && isIgnorableFinalTailRun(run)) continue;
+		return false;
+	}
+	return true;
+}
+/**
+* Fit of a text candidate on a justified line: the paragraph's final word may
+* be admitted by shrinking spaces, which then needs a paint plan.
+*/
+function resolveTextCandidateFit(isFinalCandidate, candidateWidth, availableWidth, tolerancePx) {
+	if (!isFinalCandidate) return {
+		type: "ordinary",
+		tolerancePx
+	};
+	return admitFinalCandidate(candidateWidth, availableWidth, tolerancePx);
+}
+/**
+* A paragraph's last line is not stretched, so a final word admitted by space
+* contraction needs an explicit paint plan; otherwise it would paint past the
+* measure. Sub-pixel rounding overflow stays on the ordinary path.
+*/
+function admitFinalCandidate(candidateWidth, availableWidth, tolerancePx) {
+	const contractionPx = candidateWidth - availableWidth;
+	if (contractionPx <= .5 || contractionPx > tolerancePx) return {
+		type: "ordinary",
+		tolerancePx
+	};
+	return {
+		type: "final-contraction-admitted",
+		tolerancePx,
+		paint: {
+			type: "space-contraction",
+			contractionPx
+		}
+	};
+}
+function trimTrailingSpacesAndTabs(text) {
+	let end = text.length;
+	while (end > 0) {
+		const char = text[end - 1];
+		if (char !== " " && char !== "	") break;
+		end--;
+	}
+	return text.slice(0, end);
+}
+function measureWordWithTrailingWhitespace(word, style) {
+	const measuredWord = trimTrailingSpacesAndTabs(word);
+	const wordWidth = measureTextWidth(measuredWord, style);
+	const trailingWhitespace = word.slice(measuredWord.length);
+	if (trailingWhitespace.length === 0) return {
+		measuredWord,
+		wordWidth,
+		fullWordWidth: wordWidth
+	};
+	if (style.kerning || trailingWhitespace.includes("	")) return {
+		measuredWord,
+		wordWidth,
+		fullWordWidth: measureTextWidth(word, style)
+	};
+	const trailingWhitespaceWidth = measureTextWidth(trailingWhitespace, style);
+	const boundarySpacing = measuredWord.length > 0 ? (style.letterSpacing ?? 0) * getHorizontalScaleFactor(style.horizontalScale) : 0;
+	return {
+		measuredWord,
+		wordWidth,
+		fullWordWidth: wordWidth + trailingWhitespaceWidth + boundarySpacing
+	};
+}
+const scaledLetterSpacing = (style) => (style.letterSpacing ?? 0) * getHorizontalScaleFactor(style.horizontalScale);
+/**
+* Character spacing still owed after the last character placed on the line,
+* or 0 when the line has no preceding character at `charIndex` of `runIndex`.
+* Within a run it is the run's own spacing; at a boundary between two text
+* runs it is the preceding run's spacing on its final character.
+*/
+function precedingLetterSpacing({ block, line, runIndex, charIndex, runStyle }) {
+	if (line.fromRun === line.toRun && line.fromChar === line.toChar) return 0;
+	if (line.toRun === runIndex && line.toChar === charIndex) return scaledLetterSpacing(runStyle);
+	if (charIndex !== 0 || line.toRun !== runIndex - 1) return 0;
+	const previousRun = block.runs[runIndex - 1];
+	if (!previousRun || !isTextRun(previousRun) || previousRun.text.length === 0 || line.toChar !== previousRun.text.length) return 0;
+	return scaledLetterSpacing(runToFontStyle(previousRun));
+}
+function trailingCodePoint(text) {
+	if (text.length === 0) return;
+	const trailing = text.charCodeAt(text.length - 1);
+	const preceding = text.charCodeAt(text.length - 2);
+	const start = trailing >= 56320 && trailing <= 57343 && preceding >= 55296 && preceding <= 56319 ? text.length - 2 : text.length - 1;
+	return text.slice(start);
+}
+const usesDefaultHangingPunctuationClassifier = () => {
+	return (getLineBreakProvider().isHangingPunctuation ?? defaultLineBreakProvider.isHangingPunctuation) === defaultLineBreakProvider.isHangingPunctuation;
+};
+function trailingHangingPunctuationWidth(text, style, policy, enabled) {
+	if (!enabled || text.length === 0) return 0;
+	const trailing = trailingCodePoint(text);
+	if (usesDefaultHangingPunctuationClassifier() && !isHangingPunctuation(trailing ?? "", policy)) return 0;
+	const lastStart = findGraphemeBreaks(text, policy).at(-2) ?? 0;
+	const lastGrapheme = text.slice(lastStart);
+	if (!isHangingPunctuation(lastGrapheme, policy)) return 0;
+	return measureTextWidth(lastGrapheme, style);
+}
+//#endregion
+export { exceedsHyphenationZone, findMaxFittingLength, isFinalTextCandidate, isIgnorableFinalTailRun, measureWordWithTrailingWhitespace, precedingLetterSpacing, resolveTextCandidateFit, trailingHangingPunctuationWidth, trimTrailingSpacesAndTabs };