@stll/folio-core 0.49.0 → 0.51.0

package/dist/export-pdf.d.ts

@@ -1,5 +1,5 @@
 import { DocxInput } from "./utils/docxInput.js";
-import { DisplayMetadata, DisplayUnsupported } from "./display-list/types.js";
+import { DisplayList, DisplayMetadata, DisplayUnsupported } from "./display-list/types.js";
 import { HeadlessFontSource, HeadlessFontSubstitution } from "./fonts/headlessMeasure.js";
 import { HeadlessLayoutGap } from "./headless-layout.js";
 import { PdfSubstitution } from "./pdf/fonts.js";
@@ -23,6 +23,11 @@ type ExportDocxToPdfOptions = {
   readonly timestamp: string;
   readonly metadata?: DisplayMetadata;
   readonly producer?: string;
+  /**
+   * 0-based indices of the pages to write, in order. Links and outline
+   * entries to other pages are dropped. Omit for every page.
+   */
+  readonly pages?: readonly number[];
 };
 type ExportDocxToPdfResult = {
   readonly bytes: Uint8Array;
@@ -38,6 +43,34 @@ type ExportDocxToPdfResult = {
   /** Code points painted as `.notdef` because no supplied face covers them. */
   readonly unencodable: readonly PdfUnencodable[];
 };
+type BuildDocxDisplayListOptions = {
+  /** Supplies face binaries for measurement. */
+  readonly fonts: HeadlessFontSource;
+  readonly metadata?: DisplayMetadata;
+};
+type BuildDocxDisplayListResult = {
+  /** The pages every backend paints: the PDF writer, the DOM and HTML backends. */
+  readonly list: DisplayList;
+  /** Stories the headless pipeline does not paginate. */
+  readonly layoutGaps: readonly HeadlessLayoutGap[];
+  /** Faces measured with a stand-in. */
+  readonly measurementSubstitutions: readonly HeadlessFontSubstitution[];
+};
+/**
+ * Lay a package out headlessly and build its display list: the one structure
+ * the PDF writer and the DOM backend both paint. Runs one at a time with
+ * every other headless build and export, for the reason
+ * {@link runExclusively} gives.
+ */
+declare const buildDocxDisplayList: (input: DocxInput, options: BuildDocxDisplayListOptions) => Promise<Result<BuildDocxDisplayListResult, ExportPdfError>>;
 declare const exportDocxToPdf: (input: DocxInput, options: ExportDocxToPdfOptions) => Promise<Result<ExportDocxToPdfResult, ExportPdfError>>;
+type WriteDisplayListPdfOptions = Pick<ExportDocxToPdfOptions, "fonts" | "timestamp" | "producer">;
+type WriteDisplayListPdfResult = Pick<ExportDocxToPdfResult, "bytes" | "pageCount" | "embeddingSubstitutions" | "unencodable">;
+/**
+ * Write a display list built by {@link buildDocxDisplayList} (or narrowed by
+ * `selectDisplayPages`) as a PDF, embedding faces from the same source the
+ * layout measured with.
+ */
+declare const writeDisplayListPdf: (list: DisplayList, options: WriteDisplayListPdfOptions) => Promise<Result<WriteDisplayListPdfResult, ExportPdfError>>;
 //#endregion
-export { ExportDocxToPdfOptions, ExportDocxToPdfResult, ExportPdfError, exportDocxToPdf };
+export { BuildDocxDisplayListOptions, BuildDocxDisplayListResult, ExportDocxToPdfOptions, ExportDocxToPdfResult, ExportPdfError, WriteDisplayListPdfOptions, WriteDisplayListPdfResult, buildDocxDisplayList, exportDocxToPdf, writeDisplayListPdf };

package/dist/export-pdf.js

@@ -1,5 +1,6 @@
 import { buildDisplayList } from "./display-list/build/buildDisplayList.js";
 import { displayCommentsFrom } from "./display-list/build/commentAnnotations.js";
+import { selectDisplayPages } from "./display-list/selectDisplayPages.js";
 import { installHeadlessMeasureProvider } from "./fonts/headlessMeasure.js";
 import { layoutDocxHeadless } from "./headless-layout.js";
 import { getMeasureProvider, setMeasureProvider } from "./layout-engine/measure/measureProvider.js";
@@ -52,16 +53,59 @@ const runExclusively = (run) => {
 	exportQueue = current.then(() => void 0, () => void 0);
 	return current;
 };
-const exportDocxToPdf = (input, options) => runExclusively(() => exportOnce(input, options));
-const exportOnce = async (input, options) => {
+/**
+* Lay a package out headlessly and build its display list: the one structure
+* the PDF writer and the DOM backend both paint. Runs one at a time with
+* every other headless build and export, for the reason
+* {@link runExclusively} gives.
+*/
+const buildDocxDisplayList = (input, options) => runExclusively(async () => {
 	const callerProvider = getMeasureProvider();
 	try {
-		return await exportWithHeadlessProvider(input, options);
+		return await buildWithHeadlessProvider(input, options);
 	} finally {
 		setMeasureProvider(callerProvider);
 	}
+});
+const exportDocxToPdf = async (input, options) => {
+	const built = await buildDocxDisplayList(input, {
+		fonts: options.fonts,
+		...options.metadata === void 0 ? {} : { metadata: options.metadata }
+	});
+	if (built.isErr()) return Result.err(built.error);
+	const list = options.pages === void 0 ? built.value.list : selectDisplayPages(built.value.list, options.pages);
+	const written = await writeDisplayListPdf(list, options);
+	if (written.isErr()) return Result.err(written.error);
+	return Result.ok({
+		...written.value,
+		unsupported: list.unsupported,
+		layoutGaps: built.value.layoutGaps,
+		measurementSubstitutions: built.value.measurementSubstitutions
+	});
+};
+/**
+* Write a display list built by {@link buildDocxDisplayList} (or narrowed by
+* `selectDisplayPages`) as a PDF, embedding faces from the same source the
+* layout measured with.
+*/
+const writeDisplayListPdf = async (list, options) => {
+	const written = await writePdf(list, {
+		fonts: { load: (face) => options.fonts.load(toFontRequest(face)) },
+		timestamp: options.timestamp,
+		...options.producer === void 0 ? {} : { producer: options.producer }
+	});
+	if (written.isErr()) return Result.err(new ExportPdfError({
+		message: written.error.message,
+		cause: written.error
+	}));
+	return Result.ok({
+		bytes: written.value.bytes,
+		pageCount: list.pages.length,
+		embeddingSubstitutions: written.value.substitutions,
+		unencodable: written.value.unencodable
+	});
 };
-const exportWithHeadlessProvider = async (input, options) => {
+const buildWithHeadlessProvider = async (input, options) => {
 	const headless = installHeadlessMeasureProvider(options.fonts);
 	const laidOut = await layoutDocxHeadless(input, { pageGap: 0 });
 	if (laidOut.isErr()) return Result.err(new ExportPdfError({
@@ -77,24 +121,11 @@ const exportWithHeadlessProvider = async (input, options) => {
 		...laidOut.value.document.package.document.comments === void 0 ? {} : { comments: displayCommentsFrom(laidOut.value.document.package.document.comments) },
 		...options.metadata === void 0 ? {} : { metadata: options.metadata }
 	});
-	const written = await writePdf(list, {
-		fonts: { load: (face) => options.fonts.load(toFontRequest(face)) },
-		timestamp: options.timestamp,
-		...options.producer === void 0 ? {} : { producer: options.producer }
-	});
-	if (written.isErr()) return Result.err(new ExportPdfError({
-		message: written.error.message,
-		cause: written.error
-	}));
 	return Result.ok({
-		bytes: written.value.bytes,
-		pageCount: list.pages.length,
-		unsupported: list.unsupported,
+		list,
 		layoutGaps: laidOut.value.unsupported,
-		measurementSubstitutions: headless.substitutions(),
-		embeddingSubstitutions: written.value.substitutions,
-		unencodable: written.value.unencodable
+		measurementSubstitutions: headless.substitutions()
 	});
 };
 //#endregion
-export { ExportPdfError, exportDocxToPdf };
+export { ExportPdfError, buildDocxDisplayList, exportDocxToPdf, writeDisplayListPdf };

package/dist/fonts/fontsourceFaces.d.ts

@@ -0,0 +1,47 @@
+import { HeadlessFontSource } from "./headlessMeasure.js";
+//#region src/fonts/fontsourceFaces.d.ts
+/** Where `@fontsource` files come from: `null` when the package or file is absent. */
+type FontsourceFiles = {
+  /** Bytes of `@fontsource/<packageName>/<relativePath>`. */
+  readonly read: (packageName: string, relativePath: string) => Uint8Array | null;
+};
+/** Each bundled family and the `@fontsource` package that ships it. */
+declare const FONTSOURCE_PACKAGES: {
+  readonly Arimo: "arimo";
+  readonly Caladea: "caladea";
+  readonly Carlito: "carlito";
+  readonly Cousine: "cousine";
+  readonly Lato: "lato";
+  readonly "Noto Sans Arabic": "noto-sans-arabic";
+  readonly "Source Sans 3": "source-sans-3";
+  readonly Tinos: "tinos";
+};
+/**
+ * A CSS `<string>` token, quoted and escaped. A family name comes from an
+ * authored document and is emitted into a `<style>` element, so the
+ * backslash is escaped first, then the quote, and line terminators become hex
+ * escapes, which CSS strings require.
+ */
+declare const cssString: (value: string) => string;
+type FontsourceFontFaceCssOptions = {
+  /**
+   * Families to declare beyond the names the faces answer to directly. Pass a
+   * display list's own `fonts` families: a face reached through the fallback
+   * chain has no rule of its own, and the page names it by its authored name.
+   */
+  readonly families?: readonly string[];
+};
+type FontsourceFaces = {
+  /** Binaries for the headless measurer and the PDF writer. */
+  readonly source: HeadlessFontSource;
+  /**
+   * `@font-face` rules with the `.woff` bytes inlined as `data:` URLs, one
+   * rule per served subset of each face, so a browser paints each code point
+   * from the binary that was measured.
+   */
+  readonly fontFaceCss: (options?: FontsourceFontFaceCssOptions) => string;
+};
+/** The `@fontsource` faces, read through `files` and cached per face. */
+declare const createFontsourceFaces: (files: FontsourceFiles) => FontsourceFaces;
+//#endregion
+export { FONTSOURCE_PACKAGES, FontsourceFaces, FontsourceFiles, FontsourceFontFaceCssOptions, createFontsourceFaces, cssString };

package/dist/fonts/fontsourceFaces.js

@@ -0,0 +1,230 @@
+import { bytesToDataUrl } from "../utils/base64.js";
+import { FONT_MAPPING } from "../utils/fontLoader.js";
+import { parseFontFamilyList, resolveFontFamily } from "../utils/fontResolver.js";
+//#region src/fonts/fontsourceFaces.ts
+/**
+* The subsets served, in resolution priority: a code point two subsets cover
+* resolves to the earlier one on both sides.
+*/
+const SUBSET_PRIORITY = [
+	"latin",
+	"latin-ext",
+	"arabic"
+];
+/** Folio paints 400 and 700 only, as `DisplayFontFace` states. */
+const REGULAR_WEIGHT = 400;
+const BOLD_WEIGHT = 700;
+/** Each bundled family and the `@fontsource` package that ships it. */
+const FONTSOURCE_PACKAGES = {
+	Arimo: "arimo",
+	Caladea: "caladea",
+	Carlito: "carlito",
+	Cousine: "cousine",
+	Lato: "lato",
+	"Noto Sans Arabic": "noto-sans-arabic",
+	"Source Sans 3": "source-sans-3",
+	Tinos: "tinos"
+};
+/** A CSS stack ends in a generic, so a generic must resolve to a bundled family too. */
+const GENERIC_FAMILIES = {
+	serif: "Tinos",
+	"sans-serif": "Arimo",
+	monospace: "Cousine"
+};
+const isBundledFamily = (name) => Object.hasOwn(FONTSOURCE_PACKAGES, name);
+const isGenericFamily = (name) => Object.hasOwn(GENERIC_FAMILIES, name);
+/** Every name a bundled family answers to: its own, and the authored names mapped to it. */
+const familyIndexEntries = () => {
+	const entries = [];
+	for (const family of Object.keys(FONTSOURCE_PACKAGES)) if (isBundledFamily(family)) entries.push([family.toLowerCase(), family]);
+	for (const [authored, mapped] of Object.entries(FONT_MAPPING)) {
+		if (isBundledFamily(mapped)) {
+			entries.push([authored.toLowerCase(), mapped]);
+			continue;
+		}
+		if (isGenericFamily(mapped)) entries.push([authored.toLowerCase(), GENERIC_FAMILIES[mapped]]);
+	}
+	for (const [generic, bundled] of Object.entries(GENERIC_FAMILIES)) entries.push([generic, bundled]);
+	return entries;
+};
+const FAMILY_INDEX = new Map(familyIndexEntries());
+/** Every family name the faces answer to, in a stable order for the CSS. */
+const bundledFamilyAliases = () => [...Object.keys(FONTSOURCE_PACKAGES), ...Object.keys(FONT_MAPPING).filter((authored) => FAMILY_INDEX.has(authored.toLowerCase()))].sort((a, b) => a.localeCompare(b, "en"));
+/**
+* The bundled family a requested name resolves to: directly, or through the
+* same fallback chain the editor's font resolver walks.
+*/
+const resolveBundledFamily = (family) => {
+	const direct = FAMILY_INDEX.get(family.trim().toLowerCase());
+	if (direct !== void 0) return direct;
+	for (const candidate of parseFontFamilyList(resolveFontFamily(family).cssFallback)) {
+		const resolved = FAMILY_INDEX.get(candidate.trim().toLowerCase());
+		if (resolved !== void 0) return resolved;
+	}
+	return null;
+};
+const weightOf = (bold) => bold ? BOLD_WEIGHT : REGULAR_WEIGHT;
+/** `@fontsource` ships the ranges it cut each subset with, beside the files. */
+const UNICODE_RANGE_FILE = "unicode.json";
+const RANGE_TOKEN_RE = /^U\+([0-9A-Fa-f]+)(?:-([0-9A-Fa-f]+))?$/u;
+const parseRangeToken = (token) => {
+	const match = RANGE_TOKEN_RE.exec(token.trim());
+	if (match === null) return [];
+	const first = Number.parseInt(match[1] ?? "", 16);
+	const last = match[2] === void 0 ? first : Number.parseInt(match[2], 16);
+	if (Number.isNaN(first) || Number.isNaN(last)) return [];
+	return [[first, last]];
+};
+const parseRangeList = (declared) => declared.split(",").flatMap(parseRangeToken);
+const parseDeclaredRanges = (bytes) => {
+	const ranges = /* @__PURE__ */ new Map();
+	const parsed = JSON.parse(new TextDecoder().decode(bytes));
+	if (typeof parsed !== "object" || parsed === null) return ranges;
+	for (const [subset, declared] of Object.entries(parsed)) if (typeof declared === "string") ranges.set(subset, parseRangeList(declared));
+	return ranges;
+};
+const withoutRange = (range, [start, end]) => {
+	const [first, last] = range;
+	if (end < first || start > last) return [range];
+	const remainder = [];
+	if (start > first) remainder.push([first, start - 1]);
+	if (end < last) remainder.push([end + 1, last]);
+	return remainder;
+};
+/**
+* `subject` minus everything a higher-priority subset already serves. The
+* declared ranges overlap (`latin` and `latin-ext` both claim some combining
+* marks); cutting the overlap out of the lower-priority rule makes a browser,
+* which resolves an overlap by declaration order, agree with this table.
+*/
+const subtractRanges = (subject, taken) => {
+	let remaining = subject;
+	for (const range of taken) remaining = remaining.flatMap((candidate) => withoutRange(candidate, range));
+	return remaining;
+};
+const hex = (codePoint) => codePoint.toString(16).toUpperCase().padStart(4, "0");
+const formatRangeList = (ranges) => ranges.map(([first, last]) => first === last ? `U+${hex(first)}` : `U+${hex(first)}-${hex(last)}`).join(",");
+/**
+* A CSS `<string>` token, quoted and escaped. A family name comes from an
+* authored document and is emitted into a `<style>` element, so the
+* backslash is escaped first, then the quote, and line terminators become hex
+* escapes, which CSS strings require.
+*/
+const cssString = (value) => `"${value.replaceAll("\\", "\\\\").replaceAll("\"", "\\\"").replaceAll("\n", "\\A ").replaceAll("\r", "\\D ").replaceAll("\f", "\\C ")}"`;
+const FACE_VARIANTS = [
+	{
+		weight: REGULAR_WEIGHT,
+		italic: false
+	},
+	{
+		weight: REGULAR_WEIGHT,
+		italic: true
+	},
+	{
+		weight: BOLD_WEIGHT,
+		italic: false
+	},
+	{
+		weight: BOLD_WEIGHT,
+		italic: true
+	}
+];
+/** The media type a `.woff` face is inlined under. */
+const WOFF_MEDIA_TYPE = "font/woff";
+const fontFaceRule = ({ family, dataUrl, weight, italic, unicodeRange }) => [
+	"@font-face {",
+	`  font-family: ${cssString(family)};`,
+	`  src: url(${dataUrl}) format("woff");`,
+	`  font-weight: ${String(weight)};`,
+	`  font-style: ${italic ? "italic" : "normal"};`,
+	`  unicode-range: ${formatRangeList(unicodeRange)};`,
+	"  font-display: block;",
+	"}"
+].join("\n");
+/** The `@fontsource` faces, read through `files` and cached per face. */
+const createFontsourceFaces = (files) => {
+	const faceCache = /* @__PURE__ */ new Map();
+	const rangeCache = /* @__PURE__ */ new Map();
+	const dataUrlCache = /* @__PURE__ */ new Map();
+	const faceBinaries = ({ family, weight, italic }) => {
+		const bundled = resolveBundledFamily(family);
+		if (bundled === null) return [];
+		const packageName = FONTSOURCE_PACKAGES[bundled];
+		const style = italic ? "italic" : "normal";
+		const key = `${packageName}|${String(weight)}|${style}`;
+		const cached = faceCache.get(key);
+		if (cached !== void 0) return cached;
+		const binaries = SUBSET_PRIORITY.flatMap((subset) => {
+			const bytes = files.read(packageName, `files/${packageName}-${subset}-${String(weight)}-${style}.woff`);
+			return bytes === null ? [] : [{
+				subset,
+				bytes
+			}];
+		});
+		faceCache.set(key, binaries);
+		return binaries;
+	};
+	const declaredRanges = (packageName) => {
+		const cached = rangeCache.get(packageName);
+		if (cached !== void 0) return cached;
+		const bytes = files.read(packageName, UNICODE_RANGE_FILE);
+		const ranges = bytes === null ? /* @__PURE__ */ new Map() : parseDeclaredRanges(bytes);
+		rangeCache.set(packageName, ranges);
+		return ranges;
+	};
+	const dataUrlOf = (bytes) => {
+		const cached = dataUrlCache.get(bytes);
+		if (cached !== void 0) return cached;
+		const encoded = bytesToDataUrl(bytes, WOFF_MEDIA_TYPE);
+		dataUrlCache.set(bytes, encoded);
+		return encoded;
+	};
+	/**
+	* The rules for one variant of one family name. A subset whose range a
+	* higher-priority subset already serves, or that `unicode.json` does not
+	* describe, is not declared: a rule with no `unicode-range` would cover
+	* every code point.
+	*/
+	const variantRules = ({ family, weight, italic }) => {
+		const bundled = resolveBundledFamily(family);
+		if (bundled === null) return [];
+		const ranges = declaredRanges(FONTSOURCE_PACKAGES[bundled]);
+		const rules = [];
+		const taken = [];
+		for (const binary of faceBinaries({
+			family,
+			weight,
+			italic
+		})) {
+			const unicodeRange = subtractRanges(ranges.get(binary.subset) ?? [], taken);
+			if (unicodeRange.length === 0) continue;
+			rules.push(fontFaceRule({
+				family,
+				dataUrl: dataUrlOf(binary.bytes),
+				weight,
+				italic,
+				unicodeRange
+			}));
+			taken.push(...unicodeRange);
+		}
+		return rules;
+	};
+	return {
+		source: { load: ({ family, bold, italic }) => faceBinaries({
+			family,
+			weight: weightOf(bold),
+			italic
+		}).map(({ bytes }) => bytes) },
+		fontFaceCss: (options = {}) => {
+			const declared = /* @__PURE__ */ new Map();
+			for (const family of [...bundledFamilyAliases(), ...options.families ?? []]) declared.set(family.trim().toLowerCase(), family.trim());
+			return [...declared.values()].flatMap((family) => FACE_VARIANTS.flatMap(({ weight, italic }) => variantRules({
+				family,
+				weight,
+				italic
+			}))).join("\n");
+		}
+	};
+};
+//#endregion
+export { FONTSOURCE_PACKAGES, createFontsourceFaces, cssString };

package/dist/layout-bridge/convert/flowBlockPostprocessing.d.ts

@@ -0,0 +1,8 @@
+import { FlowBlock } from "../../layout-engine/types.js";
+//#region src/layout-bridge/convert/flowBlockPostprocessing.d.ts
+declare function suppressFinalEmptyParagraphAfterTable(blocks: FlowBlock[]): void;
+declare function suppressFinalParagraphInRepeatedEmptySuffix(blocks: FlowBlock[]): void;
+declare function reserveLeadingEmptyOutlineHeight(blocks: FlowBlock[]): void;
+declare function mergeRunInParagraphs(blocks: FlowBlock[]): FlowBlock[];
+//#endregion
+export { mergeRunInParagraphs, reserveLeadingEmptyOutlineHeight, suppressFinalEmptyParagraphAfterTable, suppressFinalParagraphInRepeatedEmptySuffix };

package/dist/layout-bridge/convert/flowBlockPostprocessing.js

@@ -0,0 +1,106 @@
+import { headingLevelOf } from "@stll/docx-core/model";
+//#region src/layout-bridge/convert/flowBlockPostprocessing.ts
+/**
+* Post-conversion passes over the flow block list: terminal empty-paragraph
+* suppression, leading empty outline reservation, and run-in paragraph
+* merging.
+*/
+/**
+* Word keeps a final empty body paragraph after a table as an editable anchor,
+* but that final anchor does not create a page of its own. Earlier authored
+* empty paragraphs retain their height and may carry the document onto a blank
+* page. Preserve every block and PM range while collapsing only the final one.
+*/
+function isPaintlessTerminalParagraph(block) {
+	if (block?.kind !== "paragraph" || block.runs.length !== 0) return false;
+	const attrs = block.attrs;
+	if (attrs?.suppressEmptyParagraphHeight === false) return false;
+	return !(attrs?.listMarker !== void 0 && !attrs.listMarkerHidden || attrs?.borders?.top || attrs?.borders?.bottom || attrs?.borders?.left || attrs?.borders?.right || attrs?.borders?.between || attrs?.borders?.bar || attrs?.shading || attrs?.spacingExplicit?.before || attrs?.spacingExplicit?.after || attrs?.pageBreakBefore || attrs?.renderedPageBreakBefore);
+}
+function suppressFinalEmptyParagraphAfterTable(blocks) {
+	let suffixStart = blocks.length;
+	while (suffixStart > 0 && isPaintlessTerminalParagraph(blocks[suffixStart - 1])) suffixStart -= 1;
+	if (suffixStart === blocks.length || suffixStart === 0 || blocks[suffixStart - 1]?.kind !== "table") return;
+	const finalBlock = blocks.at(-1);
+	if (isPaintlessTerminalParagraph(finalBlock)) finalBlock.attrs = {
+		...finalBlock.attrs,
+		suppressEmptyParagraphHeight: true
+	};
+}
+function suppressFinalParagraphInRepeatedEmptySuffix(blocks) {
+	let suffixStart = blocks.length;
+	while (suffixStart > 0 && isPaintlessTerminalParagraph(blocks[suffixStart - 1])) suffixStart -= 1;
+	if (suffixStart === 0 || blocks.length - suffixStart < 2 || blocks[suffixStart - 1]?.kind === "table") return;
+	const finalBlock = blocks.at(-1);
+	if (isPaintlessTerminalParagraph(finalBlock)) finalBlock.attrs = {
+		...finalBlock.attrs,
+		suppressEmptyParagraphHeight: true
+	};
+}
+function reserveLeadingEmptyOutlineHeight(blocks) {
+	const firstBlock = blocks.at(0);
+	if (firstBlock?.kind !== "paragraph" || firstBlock.runs.length !== 0 || headingLevelOf(firstBlock.attrs?.outlineLevel) !== 0) return;
+	firstBlock.attrs = {
+		...firstBlock.attrs,
+		reserveEmptyOutlineHeight: true
+	};
+}
+/**
+* Merge consecutive paragraph blocks where the first carries
+* `runInWithNext` (`<w:specVanish/>` on the paragraph mark).
+*
+* Word's run-in heading feature renders the next paragraph inline on
+* the same line, so for layout we collapse the pair into one
+* ParagraphBlock with combined runs. The merged block keeps the first
+* paragraph's attrs (heading formatting, list marker, indent) and
+* extends pmEnd to the second paragraph's range so click-to-position
+* resolution still maps both ranges back to body content.
+*
+* Chains: runInWithNext on the merged block is dropped because the
+* second paragraph's mark wasn't `specVanish`. If a chain of
+* specVanish paragraphs needs collapsing (rare in practice), the loop
+* naturally handles it by re-inspecting the merged block's flag (we
+* preserve runInWithNext only when the second paragraph itself has
+* specVanish).
+*/
+function sdtGroupStacksEqual(a, b) {
+	const lenA = a?.length ?? 0;
+	if (lenA !== (b?.length ?? 0)) return false;
+	if (lenA === 0) return true;
+	for (let i = 0; i < lenA; i++) if (a?.[i]?.pmPos !== b?.[i]?.pmPos) return false;
+	return true;
+}
+function mergeRunInParagraphs(blocks) {
+	const out = [];
+	for (let i = 0; i < blocks.length; i++) {
+		let current = blocks[i];
+		if (!current) continue;
+		while (current.kind === "paragraph" && current.attrs?.runInWithNext && i + 1 < blocks.length) {
+			const next = blocks[i + 1];
+			if (!next || next.kind !== "paragraph") break;
+			const a = current;
+			const b = next;
+			if (!sdtGroupStacksEqual(a.sdtGroups, b.sdtGroups)) break;
+			const mergedAttrs = { ...a.attrs };
+			if (b.attrs?.spacing?.after !== void 0) mergedAttrs.spacing = {
+				...mergedAttrs.spacing,
+				after: b.attrs.spacing.after
+			};
+			if (b.attrs?.runInWithNext) mergedAttrs.runInWithNext = true;
+			else delete mergedAttrs.runInWithNext;
+			const merged = {
+				...a,
+				runs: [...a.runs, ...b.runs],
+				attrs: mergedAttrs
+			};
+			const mergedPmEnd = b.pmEnd ?? a.pmEnd;
+			if (mergedPmEnd !== void 0) merged.pmEnd = mergedPmEnd;
+			current = merged;
+			i += 1;
+		}
+		out.push(current);
+	}
+	return out;
+}
+//#endregion
+export { mergeRunInParagraphs, reserveLeadingEmptyOutlineHeight, suppressFinalEmptyParagraphAfterTable, suppressFinalParagraphInRepeatedEmptySuffix };

package/dist/layout-bridge/convert/flowBorders.d.ts

@@ -0,0 +1,17 @@
+import { document_d_exports } from "../../types/document.js";
+import { BorderStyle } from "../../layout-engine/types.js";
+//#region src/layout-bridge/convert/flowBorders.d.ts
+/** A parsed border, or the same shape read off ProseMirror attributes. */
+type ConvertibleBorder = {
+  style?: document_d_exports.BorderStyleValue;
+  size?: number;
+  space?: number;
+  color?: document_d_exports.ColorValue;
+};
+/**
+ * Convert an OOXML BorderSpec to a layout-engine BorderStyle.
+ * Shared by paragraph borders, cell borders, and header/footer borders.
+ */
+declare function convertBorderSpecToLayout(border: ConvertibleBorder, theme?: document_d_exports.Theme | null): BorderStyle | undefined;
+//#endregion
+export { ConvertibleBorder, convertBorderSpecToLayout };

package/dist/layout-bridge/convert/flowBorders.js

@@ -0,0 +1,31 @@
+import { cssBorderStyle } from "../../utils/borderCss.js";
+import { resolveColor } from "../../utils/colorResolver.js";
+import { pointsToPixels } from "../../utils/units.js";
+import { statesNoBorder } from "@stll/docx-core/model";
+//#region src/layout-bridge/convert/flowBorders.ts
+/**
+* Converts document-model border specifications to layout BorderStyle.
+*/
+/**
+* Convert border width from eighths of a point to pixels.
+* OOXML stores border widths in eighths of a point.
+*/
+function borderWidthToPixels(eighthsOfPoint) {
+	return pointsToPixels(eighthsOfPoint / 8);
+}
+/**
+* Convert an OOXML BorderSpec to a layout-engine BorderStyle.
+* Shared by paragraph borders, cell borders, and header/footer borders.
+*/
+function convertBorderSpecToLayout(border, theme) {
+	if (border.style === void 0 || statesNoBorder(border.style)) return;
+	const result = {
+		style: cssBorderStyle(border.style),
+		width: border.size === void 0 ? 1 : borderWidthToPixels(border.size),
+		color: border.color ? resolveColor(border.color, theme) : "#000000"
+	};
+	if (border.space !== void 0) result.space = pointsToPixels(border.space);
+	return result;
+}
+//#endregion
+export { convertBorderSpecToLayout };