@stll/folio-core 0.48.0 → 0.49.0

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

@@ -6,6 +6,7 @@ import { buildFontString, getResolvedData, ptToPx } from "./measureHelpers.js";
 import { setMeasureProvider } from "./measureProvider.js";
 import { canPrefetchMeasurement, prefetchMeasurement } from "./measureWorker.js";
 import { WORKER_FONT_FINGERPRINT_TEXT, countCodePoints } from "./measureWorkerProtocol.js";
+import { SMALL_CAPS_SCALE, smallCapsMask, smallCapsSegments } from "./smallCapsCasing.js";
 import { getFontKerningMode } from "./textMeasurementPolicy.js";
 import { panic } from "better-result";
 //#region src/layout-engine/measure/measureContainer.ts
@@ -136,6 +137,7 @@ function canvasMeasureTextWidth(text, sourceStyle) {
 	if (!text) return 0;
 	const style = sourceStyle.forceComplexScript ? applyComplexScriptFormatting(sourceStyle, sourceStyle) : sourceStyle;
 	const measuredText = applyTextTransform(text, style);
+	if (!sourceStyle.forceComplexScript && style.fontVariant === "small-caps") return measureSmallCapsWidth(measuredText, style);
 	if (!sourceStyle.forceComplexScript && !style.letterSpacing && needsPerScriptFonts(style, measuredText)) return measureMixedScriptWidth(measuredText, style);
 	const ctx = getCanvasContext();
 	const font = buildFontString(style);
@@ -228,6 +230,38 @@ function measureMixedScriptWidth(measuredText, style) {
 	return width * horizontalScale;
 }
 /**
+* Width of a `w:smallCaps` run: its lowercase letters (and the whitespace
+* that follows them — see smallCapsCasing.ts) draw at `SMALL_CAPS_SCALE` of
+* the run's size, everything else at full size. A small segment is measured
+* at that literal, smaller font string — not the full-size advance scaled by
+* arithmetic — so hinting and sub-pixel snapping agree with the painted DOM
+* span, which sets this same font-size. Each segment still recurses into
+* {@link canvasMeasureTextWidth} (so one that itself needs the East-Asian or
+* complex-script font still gets it); letter spacing and horizontal scale
+* apply once over the whole string, as {@link measureMixedScriptWidth} does
+* for a script split.
+*/
+function measureSmallCapsWidth(measuredText, style) {
+	const letterSpacing = style.letterSpacing ?? 0;
+	const horizontalScale = getHorizontalScaleFactor(style.horizontalScale);
+	const segmentStyle = { ...style };
+	delete segmentStyle.fontVariant;
+	delete segmentStyle.letterSpacing;
+	delete segmentStyle.horizontalScale;
+	const smallSegmentStyle = {
+		...segmentStyle,
+		fontSize: (segmentStyle.fontSize ?? 11) * SMALL_CAPS_SCALE
+	};
+	let glyphWidth = 0;
+	for (const segment of smallCapsSegments(measuredText)) glyphWidth += canvasMeasureTextWidth(segment.text, segment.small ? smallSegmentStyle : segmentStyle);
+	let width = glyphWidth;
+	if (letterSpacing) {
+		const codePoints = countCodePoints(measuredText);
+		if (codePoints > 1) width += letterSpacing * (codePoints - 1);
+	}
+	return width * horizontalScale;
+}
+/**
 * Speculatively enqueue the slice lengths that a subsequent
 * `findMaxFittingLength` binary search is likely to probe. We pick the
 * geometric series (full, half, quarter, eighth) which covers the
@@ -293,18 +327,26 @@ function canvasMeasureRun(text, sourceStyle) {
 		...style.eastAsiaAlternateFontFamily !== void 0 ? { alternateFontFamily: style.eastAsiaAlternateFontFamily } : {}
 	}) : void 0;
 	const complexScriptFont = hasComplexScriptFormatting(style) && !style.letterSpacing ? buildFontString(scriptStyle(style, SCRIPT_CLASS.complex)) : void 0;
+	const smallCapsFont = style.fontVariant === "small-caps" ? buildFontString({
+		...style,
+		fontSize: (style.fontSize ?? 11) * SMALL_CAPS_SCALE
+	}) : void 0;
 	const letterSpacing = style.letterSpacing ?? 0;
 	const scale = getHorizontalScaleFactor(style.horizontalScale);
 	const charWidths = [];
 	let totalWidth = 0;
+	const smallCapsAt = smallCapsFont !== void 0 ? smallCapsMask(text) : void 0;
 	let offset = 0;
+	let codePointIndex = 0;
 	for (const char of text) {
 		const cp = char.codePointAt(0);
-		const measured = applyTextTransform(char, style);
-		if (eastAsiaFont !== void 0 || complexScriptFont !== void 0) {
+		const isSmallCap = smallCapsAt?.[codePointIndex] ?? false;
+		const measured = isSmallCap ? char.toLocaleUpperCase() : applyTextTransform(char, style);
+		if (isSmallCap && smallCapsFont !== void 0) ctx.font = smallCapsFont;
+		else if (eastAsiaFont !== void 0 || complexScriptFont !== void 0) {
 			const script = scriptClassOf(cp, style.eastAsiaHint);
 			ctx.font = (script === SCRIPT_CLASS.eastAsia ? eastAsiaFont : void 0) ?? (script === SCRIPT_CLASS.complex ? complexScriptFont : void 0) ?? baseFont;
-		}
+		} else if (smallCapsFont !== void 0) ctx.font = baseFont;
 		let charWidth = ctx.measureText(measured).width;
 		if (letterSpacing && offset + char.length < text.length) charWidth += letterSpacing;
 		charWidth *= scale;
@@ -312,6 +354,7 @@ function canvasMeasureRun(text, sourceStyle) {
 		if (char.length === 2) charWidths.push(0);
 		totalWidth += charWidth;
 		offset += char.length;
+		codePointIndex += 1;
 	}
 	return {
 		width: totalWidth,

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

@@ -34,6 +34,18 @@ function docxScriptFontSize(fontSize) {
 	return Math.max(1, Math.floor(fontSize * 2 * 2 / 3)) / 2;
 }
 /**
+* The `textTransform`/`fontVariant` a run's caps toggles contribute.
+*
+* `w:caps` wins when both are set: full-size capitals, never synthesized
+* small ones (matching the else-if in formatToStyle.ts's live editor
+* styling).
+*/
+function capsStyleOf(run) {
+	if (run.allCaps) return { textTransform: "uppercase" };
+	if (run.smallCaps) return { fontVariant: "small-caps" };
+	return {};
+}
+/**
 * Build a measurement `FontStyle` from a run's formatting. Single source of
 * truth for run → FontStyle so every measurement path (layout line-breaking,
 * click-to-position, selection rects) carries the same fields — notably
@@ -61,8 +73,7 @@ function buildRunFontStyle(run, fallbackFontFamily, fallbackFontSize) {
 		...run.bold !== void 0 ? { bold: run.bold } : {},
 		...run.italic !== void 0 ? { italic: run.italic } : {},
 		...run.letterSpacing !== void 0 ? { letterSpacing: run.letterSpacing } : {},
-		...run.allCaps ? { textTransform: "uppercase" } : {},
-		...run.smallCaps ? { fontVariant: "small-caps" } : {},
+		...capsStyleOf(run),
 		...horizontalScale !== void 0 ? { horizontalScale } : {},
 		kerning: getRunFontKerningMode(run, fallbackFontSize) === FONT_KERNING_MODE.enabled
 	};
@@ -119,7 +130,6 @@ function clearFontResolvedCache() {
 function buildFontString(style) {
 	const parts = [];
 	if (style.italic) parts.push("italic");
-	if (style.fontVariant) parts.push(style.fontVariant);
 	if (style.bold) parts.push("700");
 	const fontSizePx = ptToPx(style.fontSize ?? 11);
 	parts.push(`${fontSizePx}px`);

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

@@ -3,7 +3,6 @@ import { getHorizontalScaleFactor } from "../../utils/horizontalScale.js";
 import { inlineImageBoundingBox } from "../../utils/rotationBoundingBox.js";
 import { hasCjk, hasComplexScript, hasEastAsiaSlotText } from "../../utils/scriptSegments.js";
 import { splitTrailingToken } from "../../utils/trailingText.js";
-import { JUSTIFIED_FINAL_LINE_MAX_SHRINK_RATIO, JUSTIFIED_FINAL_LINE_SPACE_CONTRACTION_RATIO, supportsJustifiedFinalLineContraction } from "../justifiedLineFit.js";
 import { measuredLineAdvance } from "../lineFlow.js";
 import { isFloatingImageRun } from "../types.js";
 import { clampFloatingWrapMargins } from "./clampFloatingWrapMargins.js";
@@ -29,11 +28,10 @@ const DEFAULT_LINE_HEIGHT_MULTIPLIER = 1;
 const WIDTH_TOLERANCE = .5;
 const JUSTIFY_SHRINK_TOLERANCE_RATIO = .016;
 const JUSTIFY_SPACE_CONTRACTION_RATIO = .25;
-const JUSTIFY_LIST_MARKER_SPACE_CONTRACTION_RATIO = .195;
-const JUSTIFY_DEEP_HANGING_LIST_MARKER_SHRINK_TOLERANCE_RATIO = .022;
+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 DEFAULT_LIST_HANGING_INDENT_PX = 24;
 const ALL_CAPS_RATIO_THRESHOLD = .8;
 /**
 * Find the longest prefix of `text` that fits within `maxWidth` pixels.
@@ -371,22 +369,6 @@ function uppercaseLetterRatio(text) {
 }
 function resolveJustifyFitStrategy(block, isFirstLine, profile) {
 	if (block.attrs?.justificationCompatibility?.type === "legacy") return { type: "rounding" };
-	if (isShallowFullHangingListContinuation(block, isFirstLine)) return { type: "rounding" };
-	if (block.attrs?.listMarker !== void 0) {
-		const hanging = block.attrs.indent?.hanging ?? 0;
-		if (isFirstLine) return hanging <= DEFAULT_LIST_HANGING_INDENT_PX ? {
-			type: "space",
-			ratio: JUSTIFY_LIST_MARKER_SPACE_CONTRACTION_RATIO
-		} : {
-			type: "width",
-			ratio: JUSTIFY_DEEP_HANGING_LIST_MARKER_SHRINK_TOLERANCE_RATIO
-		};
-		return {
-			type: "space",
-			ratio: JUSTIFIED_FINAL_LINE_SPACE_CONTRACTION_RATIO,
-			maxWidthRatio: JUSTIFY_SHRINK_TOLERANCE_RATIO
-		};
-	}
 	const hasTabStops = (block.attrs?.tabs?.length ?? 0) > 0;
 	if (isFirstLine && profile.hasTabRuns && (block.attrs?.indent?.hanging ?? 0) > 0) return {
 		type: "width",
@@ -409,19 +391,6 @@ function resolveJustifyFitStrategy(block, isFirstLine, profile) {
 		ratio: JUSTIFY_SPACE_CONTRACTION_RATIO
 	};
 }
-function resolveFinalLineJustifyFitStrategy(block, profile) {
-	if (supportsJustifiedFinalLineContraction(block)) return {
-		type: "space",
-		ratio: JUSTIFIED_FINAL_LINE_SPACE_CONTRACTION_RATIO,
-		maxWidthRatio: JUSTIFIED_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];
@@ -433,27 +402,16 @@ function isFinalTextCandidate(block, runIndex, nextBreak) {
 	}
 	return true;
 }
-function resolveTextCandidateFit({ block, line, isFirstLine, isFinalCandidate, candidateWidth, candidateSpaceWidth, fallbackTolerancePx, continuationStrategy, finalStrategy }) {
+/**
+* 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: fallbackTolerancePx
-	};
-	if (!supportsJustifiedFinalLineContraction(block)) return admitFinalCandidate(candidateWidth, line.availableWidth, fallbackTolerancePx);
-	const ordinaryTolerancePx = isFirstLine ? fallbackTolerancePx : justifyFitTolerance(line, continuationStrategy, candidateSpaceWidth);
-	if (candidateWidth <= line.availableWidth + ordinaryTolerancePx) return admitFinalCandidate(candidateWidth, line.availableWidth, 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
-		}
+		tolerancePx
 	};
+	return admitFinalCandidate(candidateWidth, availableWidth, tolerancePx);
 }
 /**
 * A paragraph's last line is not stretched, so a final word admitted by space
@@ -479,18 +437,35 @@ function compressibleSpaceWidth(text, style) {
 	const count = countCompressibleSpaces(text);
 	return count === 0 ? 0 : count * measureTextWidth(" ", style);
 }
-function justifyFitTolerance(line, strategy, candidateSpaceWidth) {
+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);
-	const spaceTolerance = (line.regularSpaceWidth + candidateSpaceWidth) * strategy.ratio;
-	const boundedTolerance = strategy.maxWidthRatio === void 0 ? spaceTolerance : Math.min(spaceTolerance, line.availableWidth * strategy.maxWidthRatio);
-	return Math.max(WIDTH_TOLERANCE, boundedTolerance);
+	if (candidate !== void 0 && !prefersSpaceShrink(line, candidate)) return WIDTH_TOLERANCE;
+	return Math.max(WIDTH_TOLERANCE, (line.regularSpaceWidth + candidateSpaceWidth) * strategy.ratio);
 }
-function isShallowFullHangingListContinuation(block, isFirstLine) {
-	if (isFirstLine || block.attrs?.listMarker === void 0) return false;
-	const hanging = block.attrs.indent?.hanging ?? 0;
-	const left = block.attrs.indent?.left ?? 0;
-	return hanging > 0 && hanging < DEFAULT_LIST_HANGING_INDENT_PX && Math.abs(left - hanging) <= WIDTH_TOLERANCE;
+/**
+* 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 <= WIDTH_TOLERANCE) 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;
 }
 function trimTrailingSpacesAndTabs(text) {
 	let end = text.length;
@@ -770,7 +745,6 @@ 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;
@@ -1112,7 +1086,10 @@ function measureParagraph(block, maxWidth, options) {
 			updateMaxFont(style);
 			const fieldWidth = measureTextWidth(fallback, style);
 			const fieldSpaceWidth = compressibleSpaceWidth(fallback, style);
-			const fieldTolerance = isJustifiedParagraph ? justifyFitTolerance(currentLine, lines.length === 0 ? firstLineJustifyFitStrategy : continuationJustifyFitStrategy, fieldSpaceWidth) : WIDTH_TOLERANCE;
+			const fieldTolerance = isJustifiedParagraph ? justifyFitTolerance(currentLine, lines.length === 0 ? firstLineJustifyFitStrategy : continuationJustifyFitStrategy, fieldSpaceWidth, {
+				width: currentLine.width + fieldWidth,
+				innerSpaceWidth: fieldSpaceWidth
+			}) : WIDTH_TOLERANCE;
 			if (currentLine.width > 0 && currentLine.width + fieldWidth > currentLine.availableWidth + fieldTolerance) {
 				startNewLine(runIndex, 0);
 				updateMaxFont(style);
@@ -1181,14 +1158,10 @@ function measureParagraph(block, maxWidth, options) {
 				const hangingPunctuationWidth = trailingHangingPunctuationWidth(measuredWord, style, breakPolicy, effectiveLineBreakPolicy.hangingPunctuation);
 				const isFirstLine = lines.length === 0;
 				const regularSpaceWidth = compressibleSpaceWidth(measuredWord, style);
-				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 widthTolerance = isJustifiedParagraph ? justifyFitTolerance(currentLine, isFirstLine ? firstLineJustifyFitStrategy : continuationJustifyFitStrategy, regularSpaceWidth, {
+					width: currentLine.width + leadingLetterSpacing + wordWidth,
+					innerSpaceWidth: 0
+				}) : 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;
@@ -1305,17 +1278,7 @@ function measureParagraph(block, maxWidth, options) {
 				const rawGlueWidth = isRunTail && wordTail !== void 0 && (!isBreakBetween(wordTail, followingTextLeads[runIndex]) || 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;
-				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 candidateFit = isJustifiedParagraph ? resolveTextCandidateFit(isFinalTextCandidate(block, runIndex, nextBreak), currentLine.width + leadingLetterSpacing + wordWidth + glueWidth - hangingAllowance, currentLine.availableWidth, widthTolerance) : 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);

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

@@ -0,0 +1,56 @@
+//#region src/layout-engine/measure/smallCapsCasing.d.ts
+/**
+ * Casing rules for synthesized `w:smallCaps` glyphs.
+ *
+ * A face that carries no `smcp`/`c2sc` substitution has no true small-capital
+ * glyph, so it is faked: a lowercase letter is drawn as its uppercase form at
+ * a smaller point size, on the run's own baseline, at a fixed fraction of the
+ * run's declared size — 0.8, an exact ratio observed to repeat across mixed
+ * two-size runs at every point size and never round to a half-point `w:sz`
+ * step. That is not a canvas or DOM backend's own `font-variant: small-caps`,
+ * which synthesizes at its own, uncontrollable, narrower ratio (Blink and
+ * WebKit use 0.7).
+ *
+ * Pure: no canvas, no DOM. Shared by every measurement and paint backend so a
+ * run's advances and its glyphs agree on which characters shrink.
+ */
+/** Fraction of the run's declared size a synthesized small capital draws at. */
+declare const SMALL_CAPS_SCALE = 0.8;
+/**
+ * Whether `char` is a cased letter in its lowercase form — the class
+ * `w:smallCaps` draws as a shrunken, uppercased capital. Digits, punctuation,
+ * symbols and already-uppercase letters keep the run's full size; combining
+ * `char`'s upper and lower forms this way (rather than comparing to a
+ * separate "is uppercase" test) is what correctly leaves caseless scripts
+ * (CJK, most punctuation) at full size too, since neither form differs from
+ * the character itself there.
+ */
+declare function isSmallCapsLetter(char: string): boolean;
+/**
+ * Per-code-point small-caps classification for `text`, one entry per code
+ * point (iterated the same way `[...text]`/`for...of` does, so it lines up
+ * with any other code-point walk of the same string).
+ *
+ * Whitespace carries no case of its own; a run's space draws at the size of
+ * the character immediately before it — the trailing space after a
+ * synthesized word is itself synthesized — so a whitespace code point here
+ * takes the previous code point's class, and only falls back to full size
+ * when it opens the string (nothing to inherit from).
+ */
+declare function smallCapsMask(text: string): boolean[];
+/** A maximal run of `text` drawn at one size: `small` selects which. */
+type SmallCapsSegment = {
+  readonly text: string;
+  readonly small: boolean;
+};
+/**
+ * `text` split into maximal same-size segments for painting, each already
+ * uppercased where `small` — the shrunken capital a `smcp`-less face
+ * substitutes for the source lowercase letter. A run with no lowercase letter
+ * at all (already-uppercase headings, digits, punctuation) comes back as one
+ * `small: false` segment, so a caller can skip the extra painting work its
+ * mixed-size runs need.
+ */
+declare function smallCapsSegments(text: string): SmallCapsSegment[];
+//#endregion
+export { SMALL_CAPS_SCALE, SmallCapsSegment, isSmallCapsLetter, smallCapsMask, smallCapsSegments };

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

@@ -0,0 +1,88 @@
+//#region src/layout-engine/measure/smallCapsCasing.ts
+/**
+* Casing rules for synthesized `w:smallCaps` glyphs.
+*
+* A face that carries no `smcp`/`c2sc` substitution has no true small-capital
+* glyph, so it is faked: a lowercase letter is drawn as its uppercase form at
+* a smaller point size, on the run's own baseline, at a fixed fraction of the
+* run's declared size — 0.8, an exact ratio observed to repeat across mixed
+* two-size runs at every point size and never round to a half-point `w:sz`
+* step. That is not a canvas or DOM backend's own `font-variant: small-caps`,
+* which synthesizes at its own, uncontrollable, narrower ratio (Blink and
+* WebKit use 0.7).
+*
+* Pure: no canvas, no DOM. Shared by every measurement and paint backend so a
+* run's advances and its glyphs agree on which characters shrink.
+*/
+/** Fraction of the run's declared size a synthesized small capital draws at. */
+const SMALL_CAPS_SCALE = .8;
+/** Whitespace never gets its own small-caps class; see `smallCapsMask`. */
+const WHITESPACE_PATTERN = /\s/u;
+/**
+* Whether `char` is a cased letter in its lowercase form — the class
+* `w:smallCaps` draws as a shrunken, uppercased capital. Digits, punctuation,
+* symbols and already-uppercase letters keep the run's full size; combining
+* `char`'s upper and lower forms this way (rather than comparing to a
+* separate "is uppercase" test) is what correctly leaves caseless scripts
+* (CJK, most punctuation) at full size too, since neither form differs from
+* the character itself there.
+*/
+function isSmallCapsLetter(char) {
+	return char.toLocaleUpperCase() !== char;
+}
+/**
+* Per-code-point small-caps classification for `text`, one entry per code
+* point (iterated the same way `[...text]`/`for...of` does, so it lines up
+* with any other code-point walk of the same string).
+*
+* Whitespace carries no case of its own; a run's space draws at the size of
+* the character immediately before it — the trailing space after a
+* synthesized word is itself synthesized — so a whitespace code point here
+* takes the previous code point's class, and only falls back to full size
+* when it opens the string (nothing to inherit from).
+*/
+function smallCapsMask(text) {
+	const mask = [];
+	let previous = false;
+	for (const char of text) {
+		const small = WHITESPACE_PATTERN.test(char) ? previous : isSmallCapsLetter(char);
+		mask.push(small);
+		previous = small;
+	}
+	return mask;
+}
+/**
+* `text` split into maximal same-size segments for painting, each already
+* uppercased where `small` — the shrunken capital a `smcp`-less face
+* substitutes for the source lowercase letter. A run with no lowercase letter
+* at all (already-uppercase headings, digits, punctuation) comes back as one
+* `small: false` segment, so a caller can skip the extra painting work its
+* mixed-size runs need.
+*/
+function smallCapsSegments(text) {
+	const mask = smallCapsMask(text);
+	const segments = [];
+	let current = "";
+	let currentSmall;
+	let index = 0;
+	for (const char of text) {
+		const small = mask[index] ?? false;
+		if (currentSmall !== void 0 && small !== currentSmall) {
+			segments.push({
+				text: current,
+				small: currentSmall
+			});
+			current = "";
+		}
+		current += small ? char.toLocaleUpperCase() : char;
+		currentSmall = small;
+		index += 1;
+	}
+	if (current) segments.push({
+		text: current,
+		small: currentSmall ?? false
+	});
+	return segments;
+}
+//#endregion
+export { SMALL_CAPS_SCALE, isSmallCapsLetter, smallCapsMask, smallCapsSegments };

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

@@ -51,6 +51,8 @@ type PaginatorOptions = {
   firstPageMargins?: PageMargins;
   /** Per-section body margins used on even authored page numbers. */
   sectionEvenPageMargins?: (PageMargins | undefined)[];
+  /** Per-section body margins used on the first page of a `w:titlePg` section. */
+  sectionFirstPageMargins?: (PageMargins | undefined)[];
   /** Page-number policy for the initial section. */
   pageNumbering?: SectionPageNumbering;
   /** Column configuration (optional). */

package/dist/layout-engine/paginator.js

@@ -94,7 +94,11 @@ function createPaginator(options) {
 	}
 	function getPageMargins(pageNumber, logicalPageNumber) {
 		const evenMargins = logicalPageNumber % 2 === 0 ? options.sectionEvenPageMargins?.[currentSectionIndex] : void 0;
-		const pageMargins = pageNumber === 1 && options.firstPageMargins ? { ...options.firstPageMargins } : { ...evenMargins ?? margins };
+		const titlePageMargins = currentSectionPageNumber === 1 ? options.sectionFirstPageMargins?.[currentSectionIndex] : void 0;
+		let pageMargins;
+		if (titlePageMargins) pageMargins = { ...titlePageMargins };
+		else if (pageNumber === 1 && options.firstPageMargins) pageMargins = { ...options.firstPageMargins };
+		else pageMargins = { ...evenMargins ?? margins };
 		if (options.mirrorMargins === true && pageNumber % 2 === 0) return {
 			...pageMargins,
 			left: pageMargins.right,

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

@@ -1,4 +1,4 @@
-import { FlowBlock, ParagraphBlock } from "./types.js";
+import { FlowBlock, ParagraphBlock, TableBlock } from "./types.js";
 //#region src/layout-engine/paragraphSpacing.d.ts
 type EffectiveParagraphSpacing = Readonly<{
   before: number;
@@ -35,5 +35,7 @@ declare const resolveEffectiveParagraphSpacing: (block: ParagraphBlock) => Effec
  */
 declare const resolveEffectiveParagraphSpacingTree: (blocks: FlowBlock[]) => FlowBlock[];
 declare const paragraphsShareStyle: (previous: ParagraphBlock, current: ParagraphBlock) => boolean;
+/** Derive the effective paragraph spacing of every cell story in a table. */
+declare const resolveTableSpacing: (block: TableBlock) => TableBlock;
 //#endregion
-export { collapseParagraphSpacing, getParagraphSpacingAfter, getParagraphSpacingBefore, isAuthoredEmptyParagraph, isEmptyParagraph, paragraphsShareStyle, resolveEffectiveParagraphSpacing, resolveEffectiveParagraphSpacingTree };
+export { collapseParagraphSpacing, getParagraphSpacingAfter, getParagraphSpacingBefore, isAuthoredEmptyParagraph, isEmptyParagraph, paragraphsShareStyle, resolveEffectiveParagraphSpacing, resolveEffectiveParagraphSpacingTree, resolveTableSpacing };

package/dist/layout-engine/paragraphSpacing.js

@@ -88,6 +88,7 @@ const resolveTextBoxContentSpacing = (blocks) => {
 	});
 	return changed ? resolved : blocks;
 };
+/** Derive the effective paragraph spacing of every cell story in a table. */
 const resolveTableSpacing = (block) => {
 	let changed = false;
 	const rows = block.rows.map((row) => {
@@ -122,4 +123,4 @@ const resolveTextBoxSpacing = (block) => {
 	};
 };
 //#endregion
-export { collapseParagraphSpacing, getParagraphSpacingAfter, getParagraphSpacingBefore, isAuthoredEmptyParagraph, isEmptyParagraph, paragraphsShareStyle, resolveEffectiveParagraphSpacing, resolveEffectiveParagraphSpacingTree };
+export { collapseParagraphSpacing, getParagraphSpacingAfter, getParagraphSpacingBefore, isAuthoredEmptyParagraph, isEmptyParagraph, paragraphsShareStyle, resolveEffectiveParagraphSpacing, resolveEffectiveParagraphSpacingTree, resolveTableSpacing };

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

@@ -19,6 +19,13 @@ type TableRowBreakInfo = {
   /** Suppressible leading paragraph whitespace after each matching break offset. */
   continuationSkips: number[][];
 };
+/**
+ * Height of the start of a table that a preceding `w:keepNext` paragraph
+ * (§17.3.1.15) must share a page with: the leading header rows (§17.4.49) and
+ * the first body row. A row that may break across pages (no `w:cantSplit`,
+ * §17.4.6) needs only its first line there; an unbreakable row needs all of it.
+ */
+declare function tableKeepNextOpeningHeight(block: TableBlock, measure: TableMeasure): number;
 /** Build break geometry for a table from its block + measure. */
 declare function buildTableRowBreakInfo(block: TableBlock, measure: TableMeasure): TableRowBreakInfo;
 /** Leading empty-paragraph whitespace to consume when a row resumes after `offset`. */
@@ -30,4 +37,4 @@ declare function getRowContinuationSkip(info: TableRowBreakInfo, rowIndex: numbe
  */
 declare function snapRowBreak(info: TableRowBreakInfo, rowIndex: number, fromOffset: number, maxSlice: number): number;
 //#endregion
-export { TableRowBreakInfo, buildTableRowBreakInfo, getRowContinuationSkip, snapRowBreak };
+export { TableRowBreakInfo, buildTableRowBreakInfo, getRowContinuationSkip, snapRowBreak, tableKeepNextOpeningHeight };

package/dist/layout-engine/tableRowBreak.js

@@ -141,6 +141,27 @@ const continuationSkipAfter = (geometries, offset) => {
 	if (skips.length === 0 || skips.some((skip) => skip <= BREAK_OFFSET_EPSILON)) return 0;
 	return Math.min(...skips);
 };
+/**
+* Height of the start of a table that a preceding `w:keepNext` paragraph
+* (§17.3.1.15) must share a page with: the leading header rows (§17.4.49) and
+* the first body row. A row that may break across pages (no `w:cantSplit`,
+* §17.4.6) needs only its first line there; an unbreakable row needs all of it.
+*/
+function tableKeepNextOpeningHeight(block, measure) {
+	let height = 0;
+	let rowIndex = 0;
+	while (rowIndex < measure.rows.length && block.rows[rowIndex]?.isHeader === true) {
+		height += measure.rows[rowIndex]?.height ?? 0;
+		rowIndex += 1;
+	}
+	const row = measure.rows[rowIndex];
+	const sourceRow = block.rows[rowIndex];
+	if (!row || !sourceRow) return height;
+	const breakOffsets = buildTableRowBreakInfo(block, measure).breakOffsets[rowIndex] ?? [];
+	const firstBreak = breakOffsets.at(0);
+	const rowMayBreak = sourceRow.cantSplit !== true && breakOffsets.length > 1;
+	return height + (rowMayBreak && firstBreak !== void 0 ? firstBreak : row.height);
+}
 /** Build break geometry for a table from its block + measure. */
 function buildTableRowBreakInfo(block, measure) {
 	const rowCount = measure.rows.length;
@@ -208,4 +229,4 @@ function snapRowBreak(info, rowIndex, fromOffset, maxSlice) {
 	return best;
 }
 //#endregion
-export { buildTableRowBreakInfo, getRowContinuationSkip, snapRowBreak };
+export { buildTableRowBreakInfo, getRowContinuationSkip, snapRowBreak, tableKeepNextOpeningHeight };

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

@@ -2,7 +2,7 @@ import { OutlineStyleAttr } from "../types/documentEnumValues.js";
 import { CssBorderStyle } from "../utils/borderCss.js";
 import { ImagePosition, ImageWrap, InlineWrapper, NumberFormat, OutlineLevel, ParagraphNumberingOverride, PreviewDescriptor, SdtProperties, SdtType, SectionStart, ShapeTextBody, TableCellFormatting, TableWidthType, UnderlineStyle, VerticalAlign } from "@stll/docx-core/model";
 declare namespace types_d_exports {
-  export { BlockId, BorderStyle, CellBorderSpec, CellBorders, ColumnBreakBlock, ColumnBreakMeasure, ColumnLayout, DEFAULT_TEXTBOX_MARGINS, DEFAULT_TEXTBOX_WIDTH, DocumentPosition, FOOTNOTE_ENTRY_MARGIN_BOTTOM, FOOTNOTE_FALLBACK_LINE_HEIGHT, FOOTNOTE_SEPARATOR_HEIGHT, FieldRun, FloatingTablePosition, FlowBlock, FootnoteContent, Fragment, FragmentBase, HeaderFooterContent, HeaderFooterContentHeights, HeaderFooterLayout, HitTestResult, HyperlinkInfo, ImageBlock, ImageFragment, ImageMeasure, ImageRun, ImageRunPosition, Layout, LayoutOptions, LineBreakRun, ListMarkerFormatting, MathRun, Measure, MeasuredLine, NOTE_SEPARATOR_RULE_THICKNESS, NOTE_SEPARATOR_WIDTH_FRACTION, NoteAreaLayout, NoteSeparatorKind, NoteSeparatorRule, Page, PageBreakBlock, PageBreakMeasure, PageHeaderFooterRefs, PageMargins, ParagraphAttrs, ParagraphBlock, ParagraphBorders, ParagraphFragment, ParagraphIndent, ParagraphMeasure, ParagraphSpacing, RenderedPageBreakRun, Run, RunFormatting, SdtGroup, SectionBreakBlock, SectionBreakMeasure, SectionPageNumbering, TabAlignment, TabRun, TabStop, TableBlock, TableCell, TableCellMeasure, TableFragment, TableMeasure, TableRow, TableRowMeasure, TextBoxBlock, TextBoxFlowAttrs, TextBoxFragment, TextBoxMeasure, TextRun, floatingTextBoxReservesBand, floatingTextBoxWrapsText, getTableRowLeadingWidth, isFloatingImageRun, isFloatingTextBoxBlock, isListNumPr, isTextWrappingFloatingImageRun, resolveTableCellPadding, resolveTableWidthPx, stripFlowBlockPmAnchors, tableColumnsArePinned };
+  export { BlockId, BorderStyle, CellBorderSpec, CellBorders, ColumnBreakBlock, ColumnBreakMeasure, ColumnLayout, DEFAULT_TEXTBOX_MARGINS, DEFAULT_TEXTBOX_WIDTH, DocumentPosition, FOOTNOTE_ENTRY_MARGIN_BOTTOM, FOOTNOTE_FALLBACK_LINE_HEIGHT, FOOTNOTE_SEPARATOR_HEIGHT, FieldRun, FloatingTablePosition, FlowBlock, FootnoteContent, Fragment, FragmentBase, HeaderFooterContent, HeaderFooterContentHeights, HeaderFooterLayout, HitTestResult, HyperlinkInfo, ImageBlock, ImageFragment, ImageMeasure, ImageRun, ImageRunPosition, Layout, LayoutOptions, LineBreakRun, ListMarkerFormatting, MathRun, Measure, MeasuredLine, NOTE_SEPARATOR_RULE_THICKNESS, NOTE_SEPARATOR_WIDTH_FRACTION, NoteAreaLayout, NoteSeparatorKind, NoteSeparatorRule, Page, PageBreakBlock, PageBreakMeasure, PageHeaderFooterRefs, PageMargins, ParagraphAttrs, ParagraphBlock, ParagraphBorders, ParagraphFragment, ParagraphIndent, ParagraphMeasure, ParagraphSpacing, RenderedPageBreakRun, Run, RunFormatting, SdtGroup, SectionBreakBlock, SectionBreakMeasure, SectionPageNumbering, TabAlignment, TabRun, TabStop, TableBlock, TableCell, TableCellMeasure, TableFragment, TableMeasure, TableRow, TableRowMeasure, TextBoxBlock, TextBoxFlowAttrs, TextBoxFragment, TextBoxGradientFill, TextBoxMeasure, TextRun, floatingTextBoxReservesBand, floatingTextBoxWrapsText, getTableRowLeadingWidth, isFloatingImageRun, isFloatingTextBoxBlock, isListNumPr, isTextWrappingFloatingImageRun, resolveTableCellPadding, resolveTableWidthPx, stripFlowBlockPmAnchors, tableColumnsArePinned };
 }
 /**
  * Unique identifier for a block in the document.
@@ -849,6 +849,21 @@ declare const DEFAULT_TEXTBOX_MARGINS: {
 };
 /** Default text box width in pixels when no width is specified */
 declare const DEFAULT_TEXTBOX_WIDTH = 200;
+/**
+ * A linear DrawingML gradient fill with its colors resolved (ECMA-376
+ * §20.1.8.33, §20.1.8.41). It runs along `angle`, in degrees clockwise from
+ * the positive x axis; when `scaled`, that angle is stated in the unit square
+ * and stretched with the box.
+ */
+type TextBoxGradientFill = {
+  angle: number;
+  scaled: boolean;
+  /** Stops in ascending order; `offset` runs 0 to 1. */
+  stops: {
+    offset: number;
+    color: string;
+  }[];
+};
 /**
  * Text box block — positioned container with block content.
  */
@@ -869,6 +884,8 @@ type TextBoxBlock = {
   verticalAlign?: ShapeTextBody["anchor"];
   /** Fill/background color */
   fillColor?: string;
+  /** Gradient fill, painted when no `fillColor` states a solid one. */
+  fillGradient?: TextBoxGradientFill;
   /** Border width in pixels */
   outlineWidth?: number;
   /** Border color */
@@ -1341,6 +1358,8 @@ type LayoutOptions = {
   firstPageMargins?: PageMargins;
   /** Per-section body margins used on even authored page numbers. */
   sectionEvenPageMargins?: (PageMargins | undefined)[];
+  /** Per-section body margins used on the first page of a `w:titlePg` section. */
+  sectionFirstPageMargins?: (PageMargins | undefined)[];
   /** Page-number policy for the initial section. */
   pageNumbering?: SectionPageNumbering;
   /** Body-level final section page size. */
@@ -1576,4 +1595,4 @@ declare const getTableRowLeadingWidth: (row: TableRow, columnWidths: readonly nu
  */
 declare function stripFlowBlockPmAnchors(block: FlowBlock): FlowBlock;
 //#endregion
-export { BlockId, BorderStyle, CellBorderSpec, CellBorders, ColumnBreakBlock, ColumnBreakMeasure, ColumnLayout, DEFAULT_TEXTBOX_MARGINS, DEFAULT_TEXTBOX_WIDTH, DocumentPosition, FOOTNOTE_ENTRY_MARGIN_BOTTOM, FOOTNOTE_FALLBACK_LINE_HEIGHT, FOOTNOTE_SEPARATOR_HEIGHT, FieldRun, FloatingTablePosition, FlowBlock, FootnoteContent, Fragment, FragmentBase, HeaderFooterContent, HeaderFooterContentHeights, HeaderFooterLayout, HitTestResult, HyperlinkInfo, ImageBlock, ImageFragment, ImageMeasure, ImageRun, ImageRunPosition, Layout, LayoutOptions, LineBreakRun, ListMarkerFormatting, MathRun, Measure, MeasuredLine, NOTE_SEPARATOR_RULE_THICKNESS, NOTE_SEPARATOR_WIDTH_FRACTION, NoteAreaLayout, NoteSeparatorKind, NoteSeparatorRule, Page, PageBreakBlock, PageBreakMeasure, PageHeaderFooterRefs, PageMargins, ParagraphAttrs, ParagraphBlock, ParagraphBorders, ParagraphFragment, ParagraphIndent, ParagraphMeasure, ParagraphSpacing, RenderedPageBreakRun, Run, RunFormatting, SdtGroup, SectionBreakBlock, SectionBreakMeasure, SectionPageNumbering, TabAlignment, TabRun, TabStop, TableBlock, TableCell, TableCellMeasure, TableFragment, TableMeasure, TableRow, TableRowMeasure, TextBoxBlock, TextBoxFlowAttrs, TextBoxFragment, TextBoxMeasure, TextRun, floatingTextBoxReservesBand, floatingTextBoxWrapsText, getTableRowLeadingWidth, isFloatingImageRun, isFloatingTextBoxBlock, isListNumPr, isTextWrappingFloatingImageRun, resolveTableCellPadding, resolveTableWidthPx, stripFlowBlockPmAnchors, tableColumnsArePinned, types_d_exports };
+export { BlockId, BorderStyle, CellBorderSpec, CellBorders, ColumnBreakBlock, ColumnBreakMeasure, ColumnLayout, DEFAULT_TEXTBOX_MARGINS, DEFAULT_TEXTBOX_WIDTH, DocumentPosition, FOOTNOTE_ENTRY_MARGIN_BOTTOM, FOOTNOTE_FALLBACK_LINE_HEIGHT, FOOTNOTE_SEPARATOR_HEIGHT, FieldRun, FloatingTablePosition, FlowBlock, FootnoteContent, Fragment, FragmentBase, HeaderFooterContent, HeaderFooterContentHeights, HeaderFooterLayout, HitTestResult, HyperlinkInfo, ImageBlock, ImageFragment, ImageMeasure, ImageRun, ImageRunPosition, Layout, LayoutOptions, LineBreakRun, ListMarkerFormatting, MathRun, Measure, MeasuredLine, NOTE_SEPARATOR_RULE_THICKNESS, NOTE_SEPARATOR_WIDTH_FRACTION, NoteAreaLayout, NoteSeparatorKind, NoteSeparatorRule, Page, PageBreakBlock, PageBreakMeasure, PageHeaderFooterRefs, PageMargins, ParagraphAttrs, ParagraphBlock, ParagraphBorders, ParagraphFragment, ParagraphIndent, ParagraphMeasure, ParagraphSpacing, RenderedPageBreakRun, Run, RunFormatting, SdtGroup, SectionBreakBlock, SectionBreakMeasure, SectionPageNumbering, TabAlignment, TabRun, TabStop, TableBlock, TableCell, TableCellMeasure, TableFragment, TableMeasure, TableRow, TableRowMeasure, TextBoxBlock, TextBoxFlowAttrs, TextBoxFragment, TextBoxGradientFill, TextBoxMeasure, TextRun, floatingTextBoxReservesBand, floatingTextBoxWrapsText, getTableRowLeadingWidth, isFloatingImageRun, isFloatingTextBoxBlock, isListNumPr, isTextWrappingFloatingImageRun, resolveTableCellPadding, resolveTableWidthPx, stripFlowBlockPmAnchors, tableColumnsArePinned, types_d_exports };