@stll/folio-core 0.29.0 → 0.31.0

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

@@ -1,12 +1,13 @@
-import { calculateTabWidth, pixelsToTwips } from "../../prosemirror/utils/tabCalculator.js";
 import { CJK_FALLBACK_FONT_FAMILY, isCjkFont } from "../../utils/fontResolver.js";
+import { getHorizontalScaleFactor } from "../../utils/horizontalScale.js";
 import { isRtlParagraph } from "../../utils/paragraphBaseDirection.js";
 import { inlineImageBoundingBox } from "../../utils/rotationBoundingBox.js";
 import { hasCjk, hasComplexScript } from "../../utils/scriptSegments.js";
+import { JUSTIFIED_LIST_FINAL_LINE_MAX_SHRINK_RATIO, JUSTIFIED_LIST_SPACE_CONTRACTION_RATIO, supportsJustifiedListFinalLineContraction } from "../justifiedLineFit.js";
 import { measuredLineAdvance } from "../lineFlow.js";
 import { isFloatingImageRun } from "../types.js";
 import { clampFloatingWrapMargins } from "./clampFloatingWrapMargins.js";
-import { hasComplexScriptFormatting, resolveComplexScriptFormatting } from "./complexScriptFormatting.js";
+import { applyComplexScriptFormatting, hasComplexScriptFormatting } from "./complexScriptFormatting.js";
 import { resolveEffectiveLineBreakPolicy } from "./effectiveLineBreakPolicy.js";
 import { getFloatingAvailableWidth, getFloatingMargins } from "./floatingZones.js";
 import { defaultLineBreakProvider, getLineBreakProvider } from "./lineBreakProvider.js";
@@ -14,6 +15,7 @@ import { findGraphemeBreaks, findHyphenationBreaks, findWordBreaks, isBreakChar,
 import { getListMarkerInlineWidth } from "./listMarkerWidth.js";
 import { buildRunFontStyle, ptToPx, twipsToPx } from "./measureHelpers.js";
 import { getFontMetrics, measureRun, measureTextWidth } from "./measureProvider.js";
+import { calculateTabWidth, pixelsToTwips } from "./tabCalculator.js";
 import { countCompressibleSpaces } from "./textMeasurementPolicy.js";
 //#region src/layout-engine/measure/measureParagraph.ts
 /**
@@ -30,9 +32,6 @@ const JUSTIFY_SHRINK_TOLERANCE_RATIO = .016;
 const JUSTIFY_SPACE_CONTRACTION_RATIO = .075;
 const JUSTIFY_LIST_MARKER_SPACE_CONTRACTION_RATIO = .195;
 const JUSTIFY_DEEP_HANGING_LIST_MARKER_SHRINK_TOLERANCE_RATIO = .022;
-const JUSTIFY_LIST_CONTINUATION_SPACE_CONTRACTION_RATIO = .32;
-const JUSTIFY_LIST_CONTINUATION_MAX_SHRINK_TOLERANCE_RATIO = .015;
-const JUSTIFY_INSET_LIST_SHRINK_TOLERANCE_RATIO = .015;
 const JUSTIFY_LITERAL_TAB_CONTINUATION_SHRINK_TOLERANCE_RATIO = .017;
 const JUSTIFY_HANGING_TAB_SHRINK_TOLERANCE_RATIO = .021;
 const DEFAULT_LIST_HANGING_INDENT_PX = 24;
@@ -89,10 +88,15 @@ function runToFontStyle(run) {
 function cjkLineHeightStyle(run, baseStyle) {
 	if (!run.text || !hasCjk(run.text)) return baseStyle;
 	const eastAsia = baseStyle.eastAsiaFontFamily;
-	if (eastAsia !== void 0 && isCjkFont(eastAsia)) return {
-		...baseStyle,
-		fontFamily: eastAsia
-	};
+	if (eastAsia !== void 0 && isCjkFont(eastAsia)) {
+		const result = {
+			...baseStyle,
+			fontFamily: eastAsia
+		};
+		delete result.alternateFontFamily;
+		if (baseStyle.eastAsiaAlternateFontFamily !== void 0) result.alternateFontFamily = baseStyle.eastAsiaAlternateFontFamily;
+		return result;
+	}
 	if (isCjkFont(baseStyle.fontFamily ?? DEFAULT_FONT_FAMILY)) return baseStyle;
 	return {
 		...baseStyle,
@@ -102,10 +106,7 @@ function cjkLineHeightStyle(run, baseStyle) {
 /** Pick the dominant typography metrics for a run containing complex script. */
 function complexScriptLineHeightStyle(run, baseStyle) {
 	if (!hasComplexScriptFormatting(run) || !run.forceComplexScript && !hasComplexScript(run.text)) return baseStyle;
-	const complexStyle = {
-		...baseStyle,
-		...resolveComplexScriptFormatting(run)
-	};
+	const complexStyle = applyComplexScriptFormatting(baseStyle, run);
 	return (complexStyle.fontSize ?? DEFAULT_FONT_SIZE) >= (baseStyle.fontSize ?? DEFAULT_FONT_SIZE) ? complexStyle : baseStyle;
 }
 /**
@@ -153,7 +154,8 @@ const WORD_SINGLE_LINE_FLOOR = 1.15;
 function calculateEmptyParagraphMetrics(fontSize, spacing, fontFamily, attrs) {
 	const result = calculateTypographyMetrics(fontSize, spacing, getFontMetrics({
 		fontSize,
-		fontFamily: fontFamily ?? DEFAULT_FONT_FAMILY
+		fontFamily: fontFamily ?? DEFAULT_FONT_FAMILY,
+		...attrs?.defaultAlternateFontFamily !== void 0 ? { alternateFontFamily: attrs.defaultAlternateFontFamily } : {}
 	}));
 	const lineRule = spacing?.lineRule ?? "auto";
 	if (lineRule === "auto" || lineRule === "atLeast") {
@@ -378,15 +380,10 @@ function resolveJustifyFitStrategy(block, isFirstLine, profile) {
 			type: "width",
 			ratio: JUSTIFY_DEEP_HANGING_LIST_MARKER_SHRINK_TOLERANCE_RATIO
 		};
-		const left = block.attrs.indent?.left ?? 0;
-		if (hanging > 0 && left > hanging) return {
-			type: "width",
-			ratio: JUSTIFY_INSET_LIST_SHRINK_TOLERANCE_RATIO
-		};
 		return {
 			type: "space",
-			ratio: JUSTIFY_LIST_CONTINUATION_SPACE_CONTRACTION_RATIO,
-			maxWidthRatio: JUSTIFY_LIST_CONTINUATION_MAX_SHRINK_TOLERANCE_RATIO
+			ratio: JUSTIFIED_LIST_SPACE_CONTRACTION_RATIO,
+			maxWidthRatio: JUSTIFY_SHRINK_TOLERANCE_RATIO
 		};
 	}
 	const hasTabStops = (block.attrs?.tabs?.length ?? 0) > 0;
@@ -411,6 +408,54 @@ function resolveJustifyFitStrategy(block, isFirstLine, profile) {
 		ratio: JUSTIFY_SPACE_CONTRACTION_RATIO
 	};
 }
+function resolveFinalLineJustifyFitStrategy(block, profile) {
+	if (supportsJustifiedListFinalLineContraction(block)) return {
+		type: "space",
+		ratio: JUSTIFIED_LIST_SPACE_CONTRACTION_RATIO,
+		maxWidthRatio: JUSTIFIED_LIST_FINAL_LINE_MAX_SHRINK_RATIO
+	};
+	return resolveJustifyFitStrategy(block, false, profile);
+}
+function resolveCandidateJustifyFitStrategy({ isFirstLine, isFinalCandidate, firstLineStrategy, continuationStrategy, finalLineStrategy }) {
+	if (isFirstLine) return firstLineStrategy;
+	if (isFinalCandidate) return finalLineStrategy;
+	return continuationStrategy;
+}
+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;
+}
+function resolveTextCandidateFit({ block, line, isFirstLine, isFinalCandidate, candidateWidth, candidateSpaceWidth, fallbackTolerancePx, continuationStrategy, finalStrategy }) {
+	if (isFirstLine || !isFinalCandidate || !supportsJustifiedListFinalLineContraction(block)) return {
+		type: "ordinary",
+		tolerancePx: fallbackTolerancePx
+	};
+	const ordinaryTolerancePx = justifyFitTolerance(line, continuationStrategy, candidateSpaceWidth);
+	if (candidateWidth <= line.availableWidth + ordinaryTolerancePx) return {
+		type: "ordinary",
+		tolerancePx: ordinaryTolerancePx
+	};
+	const finalTolerancePx = justifyFitTolerance(line, finalStrategy, candidateSpaceWidth);
+	if (candidateWidth > line.availableWidth + finalTolerancePx) return {
+		type: "final-contraction-rejected",
+		tolerancePx: finalTolerancePx
+	};
+	return {
+		type: "final-contraction-admitted",
+		tolerancePx: finalTolerancePx,
+		paint: {
+			type: "space-contraction",
+			contractionPx: candidateWidth - line.availableWidth
+		}
+	};
+}
 function compressibleSpaceWidth(text, style) {
 	const count = countCompressibleSpaces(text);
 	return count === 0 ? 0 : count * measureTextWidth(" ", style);
@@ -453,7 +498,7 @@ function measureWordWithTrailingWhitespace(word, style) {
 		fullWordWidth: measureTextWidth(word, style)
 	};
 	const trailingWhitespaceWidth = measureTextWidth(trailingWhitespace, style);
-	const boundarySpacing = measuredWord.length > 0 ? (style.letterSpacing ?? 0) * ((style.horizontalScale ?? 100) / 100) : 0;
+	const boundarySpacing = measuredWord.length > 0 ? (style.letterSpacing ?? 0) * getHorizontalScaleFactor(style.horizontalScale) : 0;
 	return {
 		measuredWord,
 		wordWidth,
@@ -678,6 +723,7 @@ function measureParagraph(block, maxWidth, options) {
 	};
 	const firstLineJustifyFitStrategy = resolveJustifyFitStrategy(block, true, justificationProfile);
 	const continuationJustifyFitStrategy = resolveJustifyFitStrategy(block, false, justificationProfile);
+	const finalLineJustifyFitStrategy = resolveFinalLineJustifyFitStrategy(block, justificationProfile);
 	const floatingZones = options?.floatingZones;
 	const paragraphYOffset = options?.paragraphYOffset ?? 0;
 	const indent = attrs?.indent;
@@ -792,7 +838,8 @@ function measureParagraph(block, maxWidth, options) {
 		const fontSize = line.maxFontMetrics ? line.maxFontSize : paragraphFontSize;
 		const metrics = line.maxFontMetrics ?? getFontMetrics({
 			fontSize: paragraphFontSize,
-			fontFamily: paragraphFontFamily
+			fontFamily: paragraphFontFamily,
+			...attrs?.defaultAlternateFontFamily !== void 0 ? { alternateFontFamily: attrs.defaultAlternateFontFamily } : {}
 		});
 		const finalTypography = { ...calculateTypographyMetrics(fontSize, spacing, metrics) };
 		const inlineObjectHeight = Math.max(line.maxImageHeightPx, line.maxMathHeightPx);
@@ -840,6 +887,7 @@ function measureParagraph(block, maxWidth, options) {
 			toChar: currentLine.toChar,
 			width: Math.max(0, currentLine.width - currentLine.trailingWhitespaceWidth),
 			...finalTypography,
+			...currentLine.justificationPaint !== void 0 ? { justificationPaint: currentLine.justificationPaint } : {},
 			...currentLine.discretionaryHyphen ? { discretionaryHyphen: currentLine.discretionaryHyphen } : {},
 			...currentLine.renderedPageBreakBefore ? { renderedPageBreakBefore: true } : {}
 		};
@@ -900,7 +948,7 @@ function measureParagraph(block, maxWidth, options) {
 		if (crossRunResume && runIndex < crossRunResume.runIndex) continue;
 		const run = runs[runIndex];
 		if (run.kind === "renderedPageBreak") {
-			if (!runs.slice(runIndex + 1).some((followingRun) => followingRun.kind !== "renderedPageBreak")) {
+			if (!runs.slice(runIndex + 1).some((followingRun) => !isIgnorableFinalTailRun(followingRun))) {
 				currentLine.toRun = runIndex;
 				currentLine.toChar = 0;
 				continue;
@@ -1051,10 +1099,18 @@ function measureParagraph(block, maxWidth, options) {
 				const nextBreak = wordBreaks[wordBreakIndex] ?? text.length;
 				const word = text.slice(charIndex, nextBreak);
 				const { measuredWord, wordWidth, fullWordWidth } = measureWordWithTrailingWhitespace(word, style);
+				let leadingLetterSpacing = (currentLine.fromRun !== currentLine.toRun || currentLine.fromChar !== currentLine.toChar) && currentLine.toRun === runIndex && currentLine.toChar === charIndex ? (style.letterSpacing ?? 0) * ((style.horizontalScale ?? 100) / 100) : 0;
 				const hangingPunctuationWidth = trailingHangingPunctuationWidth(measuredWord, style, breakPolicy, effectiveLineBreakPolicy.hangingPunctuation);
 				const isFirstLine = lines.length === 0;
 				const regularSpaceWidth = compressibleSpaceWidth(measuredWord, style);
-				const widthTolerance = isJustifiedParagraph ? justifyFitTolerance(currentLine, isFirstLine ? firstLineJustifyFitStrategy : continuationJustifyFitStrategy, regularSpaceWidth) : WIDTH_TOLERANCE;
+				const justifyFitStrategy = resolveCandidateJustifyFitStrategy({
+					isFirstLine,
+					isFinalCandidate: isFinalTextCandidate(block, runIndex, nextBreak),
+					firstLineStrategy: firstLineJustifyFitStrategy,
+					continuationStrategy: continuationJustifyFitStrategy,
+					finalLineStrategy: finalLineJustifyFitStrategy
+				});
+				const widthTolerance = isJustifiedParagraph ? justifyFitTolerance(currentLine, justifyFitStrategy, regularSpaceWidth) : WIDTH_TOLERANCE;
 				const automaticHyphenation = effectiveLineBreakPolicy.automaticHyphenation;
 				const mayHyphenateLine = automaticHyphenation.type === "enabled" && (automaticHyphenation.consecutiveLineLimit === 0 || consecutiveHyphenatedLines < automaticHyphenation.consecutiveLineLimit) && exceedsHyphenationZone(currentLine, automaticHyphenation.hyphenationZoneTwips);
 				const isRunTail = nextBreak === text.length;
@@ -1073,10 +1129,10 @@ function measureParagraph(block, maxWidth, options) {
 						breaks: findHyphenationBreaks(fullWordText, breakPolicy)
 					};
 				}
-				const overflowsCurrentLine = wordWidth > 0 && currentLine.width + wordWidth > currentLine.availableWidth + widthTolerance;
+				const overflowsCurrentLine = wordWidth > 0 && currentLine.width + leadingLetterSpacing + wordWidth > currentLine.availableWidth + widthTolerance;
 				if (mayHyphenateLine && overflowsCurrentLine && activeHyphenationWord) {
 					const consumed = charIndex - activeHyphenationWord.start;
-					const spaceLeft = currentLine.availableWidth - currentLine.width + widthTolerance;
+					const spaceLeft = currentLine.availableWidth - currentLine.width - leadingLetterSpacing + widthTolerance;
 					const hyphenWidth = measureTextWidth("-", style);
 					let fittingBreak;
 					for (const breakOffset of activeHyphenationWord.breaks) {
@@ -1086,7 +1142,7 @@ function measureParagraph(block, maxWidth, options) {
 					if (fittingBreak !== void 0) {
 						const absoluteBreak = activeHyphenationWord.start + fittingBreak;
 						const prefix = text.slice(charIndex, absoluteBreak);
-						currentLine.width += measureTextWidth(prefix, style) + hyphenWidth;
+						currentLine.width += leadingLetterSpacing + measureTextWidth(prefix, style) + hyphenWidth;
 						currentLine.trailingWhitespaceWidth = 0;
 						currentLine.toRun = runIndex;
 						currentLine.toChar = absoluteBreak;
@@ -1097,8 +1153,8 @@ function measureParagraph(block, maxWidth, options) {
 						continue;
 					}
 				}
-				if (crossRunWord && currentLine.width + crossRunWord.width > currentLine.availableWidth + widthTolerance) {
-					const spaceLeft = currentLine.availableWidth - currentLine.width + widthTolerance;
+				if (crossRunWord && currentLine.width + leadingLetterSpacing + crossRunWord.width > currentLine.availableWidth + widthTolerance) {
+					const spaceLeft = currentLine.availableWidth - currentLine.width - leadingLetterSpacing + widthTolerance;
 					let fittingPrefix;
 					for (let breakIndex = crossRunWord.breaks.length - 1; breakIndex >= 0; breakIndex -= 1) {
 						const breakOffset = crossRunWord.breaks[breakIndex];
@@ -1112,7 +1168,7 @@ function measureParagraph(block, maxWidth, options) {
 					}
 					if (fittingPrefix) {
 						for (const segment of fittingPrefix.segments) updateMaxFont(cjkLineHeightStyle(segment.run, complexScriptLineHeightStyle(segment.run, segment.style)));
-						currentLine.width += fittingPrefix.width + measureTextWidth("-", fittingPrefix.hyphenStyle);
+						currentLine.width += leadingLetterSpacing + fittingPrefix.width + measureTextWidth("-", fittingPrefix.hyphenStyle);
 						currentLine.trailingWhitespaceWidth = 0;
 						currentLine.toRun = fittingPrefix.endRunIndex;
 						currentLine.toChar = fittingPrefix.endChar;
@@ -1133,18 +1189,21 @@ function measureParagraph(block, maxWidth, options) {
 				}
 				if (wordWidth - hangingPunctuationWidth > currentLine.availableWidth + widthTolerance) {
 					let chunkStart = 0;
+					let chunkLeadingLetterSpacing = leadingLetterSpacing;
 					while (chunkStart < measuredWord.length) {
-						const spaceLeft = currentLine.availableWidth - currentLine.width + WIDTH_TOLERANCE;
+						const spaceLeft = currentLine.availableWidth - currentLine.width - chunkLeadingLetterSpacing + WIDTH_TOLERANCE;
 						let bestEnd = findMaxFittingLength(measuredWord.slice(chunkStart), style, spaceLeft, currentLine.width === 0, breakPolicy);
 						if (bestEnd === 0) {
 							startNewLine(runIndex, charIndex + chunkStart);
+							chunkLeadingLetterSpacing = 0;
 							updateMaxFont(lineHeightStyle);
 							continue;
 						}
 						const chunkEnd = chunkStart + bestEnd;
 						const chunk = measuredWord.slice(chunkStart, chunkEnd);
 						const chunkWidth = measureTextWidth(chunk, style);
-						currentLine.width += chunkWidth;
+						currentLine.width += chunkLeadingLetterSpacing + chunkWidth;
+						chunkLeadingLetterSpacing = 0;
 						currentLine.trailingWhitespaceWidth = chunkWidth - measureTextWidth(trimTrailingSpacesAndTabs(chunk), style);
 						currentLine.regularSpaceWidth += compressibleSpaceWidth(chunk, style);
 						currentLine.toRun = runIndex;
@@ -1168,13 +1227,27 @@ function measureParagraph(block, maxWidth, options) {
 				const rawGlueWidth = isRunTail && wordTail !== void 0 && (!isBreakChar(wordTail) || protectedGlueWidth > 0) ? Math.max(trailingGlueWidths[runIndex] ?? 0, protectedGlueWidth) : 0;
 				const glueWidth = rawGlueWidth > 0 && wordWidth + rawGlueWidth <= getPostWrapAvailableWidth() + widthTolerance ? rawGlueWidth : 0;
 				const hangingAllowance = glueWidth === 0 ? hangingPunctuationWidth : 0;
-				if (wordWidth > 0 && currentLine.width > 0 && currentLine.width + wordWidth + glueWidth > currentLine.availableWidth + widthTolerance + hangingAllowance) {
+				const candidateFit = isJustifiedParagraph ? resolveTextCandidateFit({
+					block,
+					line: currentLine,
+					isFirstLine,
+					isFinalCandidate: isFinalTextCandidate(block, runIndex, nextBreak),
+					candidateWidth: currentLine.width + leadingLetterSpacing + wordWidth + glueWidth - hangingAllowance,
+					candidateSpaceWidth: regularSpaceWidth,
+					fallbackTolerancePx: widthTolerance,
+					continuationStrategy: continuationJustifyFitStrategy,
+					finalStrategy: finalLineJustifyFitStrategy
+				}) : void 0;
+				const finalWrapTolerance = candidateFit?.tolerancePx ?? widthTolerance;
+				if (wordWidth > 0 && currentLine.width > 0 && currentLine.width + leadingLetterSpacing + wordWidth + glueWidth > currentLine.availableWidth + finalWrapTolerance + hangingAllowance) {
 					startNewLine(runIndex, charIndex);
+					leadingLetterSpacing = 0;
 					updateMaxFont(lineHeightStyle);
 				}
-				currentLine.width += fullWordWidth;
+				if (candidateFit?.type === "final-contraction-admitted") currentLine.justificationPaint = candidateFit.paint;
+				currentLine.width += leadingLetterSpacing + fullWordWidth;
 				const wordTrailingWhitespaceWidth = fullWordWidth - wordWidth;
-				currentLine.trailingWhitespaceWidth = wordWidth === 0 ? currentLine.trailingWhitespaceWidth + wordTrailingWhitespaceWidth : wordTrailingWhitespaceWidth;
+				currentLine.trailingWhitespaceWidth = wordWidth === 0 ? currentLine.trailingWhitespaceWidth + leadingLetterSpacing + wordTrailingWhitespaceWidth : wordTrailingWhitespaceWidth;
 				currentLine.regularSpaceWidth += compressibleSpaceWidth(word, style);
 				currentLine.toRun = runIndex;
 				currentLine.toChar = nextBreak;
@@ -1187,7 +1260,8 @@ function measureParagraph(block, maxWidth, options) {
 		const fontFamily = currentLine.maxFontMetrics?.fontFamily ?? attrs?.defaultFontFamily;
 		updateMaxFont({
 			fontSize: listParagraphMarkFontSize,
-			...fontFamily === void 0 ? {} : { fontFamily }
+			...fontFamily === void 0 ? {} : { fontFamily },
+			...currentLine.maxFontMetrics === null && attrs?.defaultAlternateFontFamily !== void 0 ? { alternateFontFamily: attrs.defaultAlternateFontFamily } : {}
 		});
 	}
 	finalizeLine();

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

@@ -14,6 +14,7 @@ declare namespace measureTypes_d_exports {
  */
 type FontStyle = {
   fontFamily?: string;
+  alternateFontFamily?: string;
   /**
    * East-Asian font for CJK code points. When set, `measureTextWidth` /
    * `measureRun` measure CJK code points with this font and the rest with
@@ -21,11 +22,13 @@ type FontStyle = {
    * and click positioning stay in sync.
    */
   eastAsiaFontFamily?: string;
+  eastAsiaAlternateFontFamily?: string;
   /**
    * Complex-script font for Arabic, Hebrew, Indic and South-East Asian code
    * points. Same contract as `eastAsiaFontFamily`, over a different slot.
    */
   complexScriptFontFamily?: string;
+  complexScriptAlternateFontFamily?: string;
   complexScriptFontSize?: number;
   complexScriptBold?: boolean;
   complexScriptItalic?: boolean;

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

@@ -0,0 +1,123 @@
+//#region src/layout-engine/measure/tabCalculator.d.ts
+/**
+ * Tab Width Calculator
+ *
+ * Computes tab widths based on position and tab stops.
+ * Follows OOXML tab stop semantics:
+ * - Default tab interval: 720 twips (0.5 inch, 48px at 96dpi)
+ * - Tab stops can be start (left), end (right), center, decimal, or bar
+ * - Explicit tab stops override default stops
+ *
+ * Based on ECMA-376 specification and clean-room understanding of tab layout.
+ */
+/**
+ * Tab alignment types
+ */
+type TabAlignment = "start" | "end" | "center" | "decimal" | "bar" | "clear";
+/**
+ * Tab leader (fill character) types
+ */
+type TabLeader = "none" | "dot" | "hyphen" | "underscore" | "middleDot" | "heavy";
+/**
+ * Tab stop definition
+ */
+type TabStop = {
+  /** Tab alignment mode */
+  val: TabAlignment;
+  /** Position in twips from left margin */
+  pos: number;
+  /** Optional leader character */
+  leader?: TabLeader;
+};
+/**
+ * Context for tab calculations
+ */
+type TabContext = {
+  /** Explicit tab stops from paragraph or style */
+  explicitStops?: TabStop[];
+  /** Default tab interval in twips (default: 720 = 0.5 inch) */
+  defaultTabInterval?: number;
+  /** Left indent in twips */
+  leftIndent?: number;
+};
+/**
+ * Result of tab width calculation
+ */
+type TabWidthResult = {
+  /** Width of the tab in pixels */
+  width: number;
+  /** Leader character to render (if any) */
+  leader?: TabLeader;
+  /** Alignment that was applied */
+  alignment: TabAlignment | "default";
+};
+/** Default tab interval: 720 twips = 0.5 inch */
+declare const DEFAULT_TAB_INTERVAL_TWIPS = 720;
+/** Twips per inch */
+declare const TWIPS_PER_INCH = 1440;
+/** Pixels per inch (96 dpi standard for CSS) */
+declare const PIXELS_PER_INCH = 96;
+/**
+ * Convert twips to pixels
+ * @param twips - Value in twips (1/1440 inch)
+ * @returns Value in pixels (at 96 dpi)
+ */
+declare function twipsToPixels(twips: number): number;
+/**
+ * Convert pixels to twips
+ * @param pixels - Value in pixels (at 96 dpi)
+ * @returns Value in twips (1/1440 inch)
+ */
+declare function pixelsToTwips(pixels: number): number;
+/**
+ * Compute the list of effective tab stops for a paragraph
+ *
+ * Merges explicit stops with default stops at regular intervals.
+ * Explicit stops before the left indent remain available to a hanging first
+ * line. Continuation lines naturally skip them because their cursor already
+ * starts at the left indent.
+ *
+ * @param context - Tab context with explicit stops and settings
+ * @returns Sorted array of tab stops in twips
+ */
+declare function computeTabStops(context: TabContext): TabStop[];
+/**
+ * Pixel widths of the content after a tab, needed to position non-left stops.
+ *
+ * Caller measures its own runs (the painter and the layout measurer have
+ * different run models and measurement paths) and passes the result here, so
+ * this module owns the stop grid + alignment math without owning measurement.
+ */
+type TabFollowingContent = {
+  /** Total width of the runs after the tab. Used for `end` and `center` stops. */
+  followingWidth?: number;
+  /** Width of the content before the decimal separator. Used for `decimal` stops. */
+  decimalPrefixWidth?: number;
+};
+/**
+ * Calculate the width of a tab character.
+ *
+ * Finds the next tab stop after the current position and computes the width
+ * needed to reach it. For `end`/`center`/`decimal` stops the content after the
+ * tab is anchored against the stop, so the caller supplies its measured width
+ * via {@link TabFollowingContent}.
+ *
+ * @param currentXPx - Current horizontal position in pixels (from the content
+ *   area's left edge — the same origin tab stop positions are measured from)
+ * @param context - Tab context with stops and settings
+ * @param following - Measured widths of the content after the tab
+ * @returns Tab width result with width in pixels
+ */
+declare function calculateTabWidth(currentXPx: number, context: TabContext, following?: TabFollowingContent): TabWidthResult;
+/**
+ * Calculate tab width with simple default stops
+ *
+ * Simplified version for basic tab rendering without explicit stops.
+ * Uses the default 0.5 inch (48px) tab interval.
+ *
+ * @param currentXPx - Current horizontal position in pixels
+ * @returns Width of the tab in pixels
+ */
+declare function calculateSimpleTabWidth(currentXPx: number): number;
+//#endregion
+export { DEFAULT_TAB_INTERVAL_TWIPS, PIXELS_PER_INCH, TWIPS_PER_INCH, TabAlignment, TabContext, TabFollowingContent, TabLeader, TabStop, TabWidthResult, calculateSimpleTabWidth, calculateTabWidth, computeTabStops, pixelsToTwips, twipsToPixels };

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

@@ -0,0 +1,144 @@
+//#region src/layout-engine/measure/tabCalculator.ts
+/** Default tab interval: 720 twips = 0.5 inch */
+const DEFAULT_TAB_INTERVAL_TWIPS = 720;
+/** Twips per inch */
+const TWIPS_PER_INCH = 1440;
+/** Pixels per inch (96 dpi standard for CSS) */
+const PIXELS_PER_INCH = 96;
+/** Ignore sub-twip round trips when the cursor already occupies a tab stop. */
+const TAB_POSITION_EPSILON_TWIPS = .01;
+/** Positions closer than this are treated as the same tab stop. */
+const TAB_STOP_MATCH_TOLERANCE_TWIPS = 20;
+/**
+* Convert twips to pixels
+* @param twips - Value in twips (1/1440 inch)
+* @returns Value in pixels (at 96 dpi)
+*/
+function twipsToPixels(twips) {
+	return twips / TWIPS_PER_INCH * 96;
+}
+/**
+* Convert pixels to twips
+* @param pixels - Value in pixels (at 96 dpi)
+* @returns Value in twips (1/1440 inch)
+*/
+function pixelsToTwips(pixels) {
+	return pixels / 96 * TWIPS_PER_INCH;
+}
+/**
+* Compute the list of effective tab stops for a paragraph
+*
+* Merges explicit stops with default stops at regular intervals.
+* Explicit stops before the left indent remain available to a hanging first
+* line. Continuation lines naturally skip them because their cursor already
+* starts at the left indent.
+*
+* @param context - Tab context with explicit stops and settings
+* @returns Sorted array of tab stops in twips
+*/
+function computeTabStops(context) {
+	const { explicitStops = [], defaultTabInterval = 720, leftIndent = 0 } = context;
+	const tabInterval = Number.isFinite(defaultTabInterval) && defaultTabInterval >= TAB_STOP_MATCH_TOLERANCE_TWIPS ? defaultTabInterval : 720;
+	const validExplicitStops = explicitStops.filter((stop) => stop.val !== "clear" && stop.val !== "bar");
+	const clearPositions = explicitStops.filter((stop) => stop.val === "clear").map((stop) => stop.pos);
+	let maxExplicit = 0;
+	for (const stop of validExplicitStops) maxExplicit = Math.max(maxExplicit, stop.pos);
+	const stops = explicitStops.filter((stop) => stop.val !== "clear");
+	const hasLeftIndentClear = clearPositions.some((p) => Math.abs(p - leftIndent) < TAB_STOP_MATCH_TOLERANCE_TWIPS);
+	const addsImplicitLeftIndent = leftIndent > 0 && !hasLeftIndentClear && !validExplicitStops.some((stop) => stop.pos <= leftIndent);
+	if (addsImplicitLeftIndent) stops.push({
+		val: "start",
+		pos: leftIndent,
+		leader: "none"
+	});
+	let pos = Math.floor(Math.max(maxExplicit, leftIndent) / tabInterval) * tabInterval;
+	const limitPos = leftIndent + 14400;
+	while (pos < limitPos) {
+		pos += tabInterval;
+		let hasExplicitStop = false;
+		for (const stop of stops) if (Math.abs(stop.pos - pos) < TAB_STOP_MATCH_TOLERANCE_TWIPS) {
+			hasExplicitStop = true;
+			break;
+		}
+		let hasClearStop = false;
+		for (const clearPos of clearPositions) if (Math.abs(clearPos - pos) < TAB_STOP_MATCH_TOLERANCE_TWIPS) {
+			hasClearStop = true;
+			break;
+		}
+		const isAtLeftIndent = addsImplicitLeftIndent && Math.abs(pos - leftIndent) < TAB_STOP_MATCH_TOLERANCE_TWIPS;
+		if (!hasExplicitStop && !hasClearStop && !isAtLeftIndent) stops.push({
+			val: "start",
+			pos,
+			leader: "none"
+		});
+	}
+	return stops.toSorted((a, b) => a.pos - b.pos);
+}
+/**
+* Calculate the width of a tab character.
+*
+* Finds the next tab stop after the current position and computes the width
+* needed to reach it. For `end`/`center`/`decimal` stops the content after the
+* tab is anchored against the stop, so the caller supplies its measured width
+* via {@link TabFollowingContent}.
+*
+* @param currentXPx - Current horizontal position in pixels (from the content
+*   area's left edge — the same origin tab stop positions are measured from)
+* @param context - Tab context with stops and settings
+* @param following - Measured widths of the content after the tab
+* @returns Tab width result with width in pixels
+*/
+function calculateTabWidth(currentXPx, context, following = {}) {
+	const { defaultTabInterval = 720 } = context;
+	const currentXTwips = pixelsToTwips(currentXPx);
+	const nextStop = computeTabStops(context).find((stop) => stop.pos > currentXTwips + TAB_POSITION_EPSILON_TWIPS);
+	if (!nextStop) {
+		const defaultTabPx = twipsToPixels(defaultTabInterval);
+		let tabWidth = defaultTabPx - currentXPx % defaultTabPx;
+		if (tabWidth <= 0) tabWidth = defaultTabPx;
+		return {
+			width: tabWidth,
+			alignment: "default"
+		};
+	}
+	let width = twipsToPixels(nextStop.pos) - currentXPx;
+	if (nextStop.val === "center") width -= (following.followingWidth ?? 0) / 2;
+	else if (nextStop.val === "end") width -= following.followingWidth ?? 0;
+	else if (nextStop.val === "decimal") width -= following.decimalPrefixWidth ?? 0;
+	else if (nextStop.val === "bar") return {
+		width: 0,
+		...nextStop.leader !== void 0 ? { leader: nextStop.leader } : {},
+		alignment: "bar"
+	};
+	if (width <= 0) {
+		const defaultTabPx = twipsToPixels(defaultTabInterval);
+		let fallbackWidth = defaultTabPx - currentXPx % defaultTabPx;
+		if (fallbackWidth <= 0) fallbackWidth = defaultTabPx;
+		return {
+			width: fallbackWidth,
+			alignment: "default"
+		};
+	}
+	return {
+		width,
+		...nextStop.leader !== void 0 ? { leader: nextStop.leader } : {},
+		alignment: nextStop.val
+	};
+}
+/**
+* Calculate tab width with simple default stops
+*
+* Simplified version for basic tab rendering without explicit stops.
+* Uses the default 0.5 inch (48px) tab interval.
+*
+* @param currentXPx - Current horizontal position in pixels
+* @returns Width of the tab in pixels
+*/
+function calculateSimpleTabWidth(currentXPx) {
+	const defaultTabPx = twipsToPixels(720);
+	let tabWidth = defaultTabPx - currentXPx % defaultTabPx;
+	if (tabWidth < defaultTabPx / 4) tabWidth += defaultTabPx;
+	return tabWidth;
+}
+//#endregion
+export { DEFAULT_TAB_INTERVAL_TWIPS, PIXELS_PER_INCH, TWIPS_PER_INCH, calculateSimpleTabWidth, calculateTabWidth, computeTabStops, pixelsToTwips, twipsToPixels };

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

@@ -6,10 +6,30 @@ type TableCellBlockPlacement = {
   contentHeight: number;
   leadingSpacing: number;
 };
+declare const TABLE_CELL_FLOW_POSITION: {
+  readonly start: "start";
+  readonly interior: "interior";
+};
+type TableCellFlowPosition = (typeof TABLE_CELL_FLOW_POSITION)[keyof typeof TABLE_CELL_FLOW_POSITION];
+declare const TABLE_CELL_TRAILING_SPACING_TYPE: {
+  readonly none: "none";
+  readonly authored: "authored";
+  readonly automatic: "automatic";
+};
+type TableCellTrailingSpacing = {
+  type: typeof TABLE_CELL_TRAILING_SPACING_TYPE.none;
+} | {
+  type: typeof TABLE_CELL_TRAILING_SPACING_TYPE.authored;
+  value: number;
+} | {
+  type: typeof TABLE_CELL_TRAILING_SPACING_TYPE.automatic;
+  value: number;
+};
 type TableCellFlowState = {
   height: number;
+  position: TableCellFlowPosition;
   previousParagraphWasEmpty: boolean;
-  trailingSpacing: number;
+  trailingSpacing: TableCellTrailingSpacing;
 };
 declare const createTableCellFlowState: () => TableCellFlowState;
 declare const finishTableCellFlow: (state: TableCellFlowState) => number;