@stll/folio-core 0.49.0 → 0.50.0

package/dist/ai-edits/headless.d.ts

@@ -35,6 +35,34 @@ type FolioApplyOperationsOptions = {
 };
 /** Options for {@link FolioDocxReviewer.applyDocumentOperations}. */
 type FolioApplyDocumentOperationsOptions = Omit<FolioApplyOperationsOptions, "mode">;
+/**
+ * Why a save rewrote the whole package instead of patching the edited
+ * paragraphs into the original: `structuralChange` (paragraphs added or
+ * removed, or styles, headers, footers or final section properties staged),
+ * `untrackedChange` (an edit the change tracker cannot key to a paragraph), or
+ * `selectiveDeclined` (the patch could not express the edit safely).
+ */
+type FolioReviewerRepackReason = "structuralChange" | "untrackedChange" | "selectiveDeclined";
+/** Options for {@link FolioDocxReviewer.save}. */
+type FolioReviewerSaveOptions = {
+  /**
+   * `"allow"` (default) falls back to a full repack when the selective patch
+   * does not apply; `"refuse"` reports the reason and writes nothing.
+   */
+  repack?: "allow" | "refuse";
+};
+/** Result of {@link FolioDocxReviewer.save}. */
+type FolioReviewerSaveResult = {
+  type: "selective";
+  buffer: ArrayBuffer;
+} | {
+  type: "full-repack";
+  reason: FolioReviewerRepackReason;
+  buffer: ArrayBuffer;
+} | {
+  type: "repackRefused";
+  reason: FolioReviewerRepackReason;
+};
 /** Options for {@link FolioDocxReviewer.getContentAsText}. */
 type FolioGetContentAsTextOptions = {
   /**
@@ -248,6 +276,8 @@ type FolioReviewReplyInput = {
   /** Reply author; defaults to the reviewer's author. */
   author?: string;
   initials?: string;
+  /** ISO-8601 reply date; defaults to the wall clock. */
+  date?: string;
 };
 /** A comment thread discovered in the document. */
 type FolioReviewComment = {
@@ -506,6 +536,12 @@ declare class FolioDocxReviewer {
    * structural edits — the same two-tier path the editor's save uses.
    */
   toBuffer(): Promise<ArrayBuffer>;
+  /**
+   * Serialise like {@link toBuffer} and report which path wrote the package.
+   * With `repack: "refuse"`, a save the selective patch cannot express
+   * returns the reason instead of rewriting every part.
+   */
+  save({ repack: repackPolicy }?: FolioReviewerSaveOptions): Promise<FolioReviewerSaveResult>;
   private assertResolvedStoriesSerialized;
   /**
    * Attempt the selective patch, treating a throw the same as a decline. Odd
@@ -580,4 +616,4 @@ type ApplyFolioAIEditsToBufferResult = FolioAIEditApplyResult & {
  */
 declare const applyFolioAIEditsToBuffer: (buffer: ArrayBuffer, operations: FolioAIEditOperation[], options?: ApplyFolioAIEditsToBufferOptions) => Promise<ApplyFolioAIEditsToBufferResult>;
 //#endregion
-export { ApplyFolioAIEditsToBufferOptions, ApplyFolioAIEditsToBufferResult, FOLIO_RESOLVED_REVIEWED_VIEWS, FOLIO_REVIEWED_VIEWS, FolioApplyDocumentOperationsOptions, FolioApplyDocumentOperationsToStoryOptions, FolioApplyOperationsOptions, FolioDocumentStory, FolioDocumentStoryHandle, FolioDocumentStoryNotFoundError, FolioDocxReviewer, FolioDocxReviewerOptions, FolioEditableDocumentStoryHandle, FolioGetContentAsTextOptions, FolioMatchStoryTableGeometryOptions, FolioNumberingLevel, FolioReadReviewedStoryOptions, FolioResolveReviewedStoryOptions, FolioResolvedReviewedView, type FolioReviewChange, FolioReviewChangeFilter, type FolioReviewChangeKind, FolioReviewComment, FolioReviewCommentFilter, FolioReviewCommentReply, FolioReviewReplyInput, FolioReviewedStory, FolioReviewedView, type FolioRevisionStamp, UnsupportedFolioReviewedViewError, applyFolioAIEditsToBuffer, getFolioDocxComparisonAccess, isFolioResolvedReviewedView, isFolioReviewedView };
+export { ApplyFolioAIEditsToBufferOptions, ApplyFolioAIEditsToBufferResult, FOLIO_RESOLVED_REVIEWED_VIEWS, FOLIO_REVIEWED_VIEWS, FolioApplyDocumentOperationsOptions, FolioApplyDocumentOperationsToStoryOptions, FolioApplyOperationsOptions, FolioDocumentStory, FolioDocumentStoryHandle, FolioDocumentStoryNotFoundError, FolioDocxReviewer, FolioDocxReviewerOptions, FolioEditableDocumentStoryHandle, FolioGetContentAsTextOptions, FolioMatchStoryTableGeometryOptions, FolioNumberingLevel, FolioReadReviewedStoryOptions, FolioResolveReviewedStoryOptions, FolioResolvedReviewedView, type FolioReviewChange, FolioReviewChangeFilter, type FolioReviewChangeKind, FolioReviewComment, FolioReviewCommentFilter, FolioReviewCommentReply, FolioReviewReplyInput, FolioReviewedStory, FolioReviewedView, FolioReviewerRepackReason, FolioReviewerSaveOptions, FolioReviewerSaveResult, type FolioRevisionStamp, UnsupportedFolioReviewedViewError, applyFolioAIEditsToBuffer, getFolioDocxComparisonAccess, isFolioResolvedReviewedView, isFolioReviewedView };

package/dist/ai-edits/headless.js

@@ -68,16 +68,10 @@ import JSZip from "jszip";
 */
 let commentIdCursor = Date.now();
 let undoHandleCursor = Date.now();
-/**
-* Build the note-free comment thread the apply layer references by id.
-* Mirrors `commentsHelpers.createComment` (a pure object literal there) so a
-* headless `commentOnBlock` / `comment` op serialises the same `comments.xml`
-* shape the editor produces.
-*/
-const createReviewerComment = (id, text, author) => ({
+const createReviewerComment = ({ id, text, author, date }) => ({
 	id,
 	author,
-	date: (/* @__PURE__ */ new Date()).toISOString(),
+	date: date ?? (/* @__PURE__ */ new Date()).toISOString(),
 	content: [{
 		type: "paragraph",
 		formatting: {},
@@ -848,7 +842,12 @@ var FolioDocxReviewer = class FolioDocxReviewer {
 			...tableTemplates !== void 0 && { tableTemplates },
 			...replacementBackground !== void 0 && { replacementBackground },
 			createCommentId: (text) => {
-				const comment = createReviewerComment(this.nextCommentId(), text, this.author);
+				const comment = createReviewerComment({
+					id: this.nextCommentId(),
+					text,
+					author: this.author,
+					date: revisionStamp?.date
+				});
 				this.createdComments.push(comment);
 				return comment.id;
 			},
@@ -1080,7 +1079,8 @@ var FolioDocxReviewer = class FolioDocxReviewer {
 		const reply = createReply([...this.baseDocument.package.document.comments ?? [], ...this.createdComments], parentId, {
 			author: input.author ?? this.author,
 			text: input.text,
-			...input.initials !== void 0 ? { initials: input.initials } : {}
+			...input.initials !== void 0 ? { initials: input.initials } : {},
+			...input.date !== void 0 && { date: input.date }
 		});
 		if (!reply) return null;
 		this.createdComments.push(reply);
@@ -1344,12 +1344,21 @@ var FolioDocxReviewer = class FolioDocxReviewer {
 			structuralChange ||= hasStructuralChanges(entry.state);
 			untrackedChanges ||= hasUntrackedChanges(entry.state);
 		}
+		let path = {
+			type: "selective-first",
+			changedParaIds
+		};
+		if (structuralChange) path = {
+			type: "full-repack",
+			reason: "structuralChange"
+		};
+		else if (untrackedChanges) path = {
+			type: "full-repack",
+			reason: "untrackedChange"
+		};
 		return {
 			document: this.documentFromStateSnapshot(snapshot),
-			path: structuralChange || untrackedChanges ? { type: "full-repack" } : {
-				type: "selective-first",
-				changedParaIds
-			},
+			path,
 			changedNoteParaIds,
 			sectionReferenceRemovals: snapshot.sectionReferenceRemovals,
 			sectionEndpointRemoval: getTrackedSectionEndpointRemoval(snapshot.mainState),
@@ -1363,12 +1372,30 @@ var FolioDocxReviewer = class FolioDocxReviewer {
 	* structural edits — the same two-tier path the editor's save uses.
 	*/
 	async toBuffer() {
+		const result = await this.save();
+		if (result.type === "repackRefused") return panic("A save that allows a full repack refused to repack", { result });
+		return result.buffer;
+	}
+	/**
+	* Serialise like {@link toBuffer} and report which path wrote the package.
+	* With `repack: "refuse"`, a save the selective patch cannot express
+	* returns the reason instead of rewriting every part.
+	*/
+	async save({ repack: repackPolicy = "allow" } = {}) {
 		const save = this.captureSaveSnapshot();
 		const selective = save.path.type === "selective-first" ? await this.trySelectiveSave(save.document, save.path.changedParaIds) : null;
 		if (selective) {
 			await this.assertResolvedStoriesSerialized(selective, save.resolvedStoryExpectations);
-			return selective;
+			return {
+				type: "selective",
+				buffer: selective
+			};
 		}
+		const reason = save.path.type === "full-repack" ? save.path.reason : "selectiveDeclined";
+		if (repackPolicy === "refuse") return {
+			type: "repackRefused",
+			reason
+		};
 		const repackDocument = {
 			...save.document,
 			originalBuffer: this.originalBuffer
@@ -1385,7 +1412,11 @@ var FolioDocxReviewer = class FolioDocxReviewer {
 			repack: repackReferences
 		}) : await repackReferences();
 		await this.assertResolvedStoriesSerialized(buffer, save.resolvedStoryExpectations);
-		return buffer;
+		return {
+			type: "full-repack",
+			reason,
+			buffer
+		};
 	}
 	async assertResolvedStoriesSerialized(buffer, expectations) {
 		if (expectations.length === 0) return;

package/dist/display-list/dom/renderDisplayListToDom.d.ts

@@ -1,10 +1,19 @@
 import { DisplayColor, DisplayFontFace, DisplayImageSource, DisplayList, DisplayPage } from "../types.js";
 //#region src/display-list/dom/renderDisplayListToDom.d.ts
+/**
+ * How the backend addresses image and embedded-font bytes: `objectUrl` mints
+ * a `blob:` URL where the runtime can (a live page, which revokes them), and
+ * `dataUrl` always inlines the bytes (markup that leaves the process, such as
+ * a serialized page, where a `blob:` URL would resolve to nothing).
+ */
+type DisplayBinaryUrls = "objectUrl" | "dataUrl";
 type RenderDisplayListOptions = {
   /** Document to create elements in. */
   readonly doc: Document;
   /** Page background, painted before any primitive. */
   readonly pageBackground?: DisplayColor;
+  /** Defaults to `objectUrl`. */
+  readonly binaryUrls?: DisplayBinaryUrls;
 };
 /**
  * A page's glyph runs and images index tables that live on the list, and an
@@ -23,4 +32,4 @@ declare const renderDisplayPageToDom: (page: DisplayPage, options: RenderDisplay
 /** One `div.layout-page` per display page, in page order. */
 declare const renderDisplayListToDom: (list: DisplayList, options: RenderDisplayListOptions) => HTMLElement[];
 //#endregion
-export { RenderDisplayListOptions, RenderDisplayPageOptions, renderDisplayListToDom, renderDisplayPageToDom };
+export { DisplayBinaryUrls, RenderDisplayListOptions, RenderDisplayPageOptions, renderDisplayListToDom, renderDisplayPageToDom };

package/dist/display-list/dom/renderDisplayListToDom.js

@@ -103,8 +103,8 @@ const resolveImage = (ref, images) => {
 };
 /** A `Blob` part cannot be backed by shared memory, so prove it is not. */
 const isBlobPart = (bytes) => bytes.buffer instanceof ArrayBuffer;
-const binarySrc = (bytes, mimeType) => {
-	if (isBlobPart(bytes) && typeof Blob === "function" && typeof URL !== "undefined" && typeof URL.createObjectURL === "function") return URL.createObjectURL(new Blob([bytes], { type: mimeType }));
+const binarySrc = (bytes, mimeType, urls) => {
+	if (urls === "objectUrl" && isBlobPart(bytes) && typeof Blob === "function" && typeof URL !== "undefined" && typeof URL.createObjectURL === "function") return URL.createObjectURL(new Blob([bytes], { type: mimeType }));
 	return bytesToDataUrl(bytes, mimeType);
 };
 const fontFaceRule = (face, embedded, src) => `@font-face { font-family: ${quoteFontFamily(embedded.id)}; src: url("${src}"); font-weight: ${face.weight}; font-style: ${face.italic ? "italic" : "normal"}; }`;
@@ -113,14 +113,14 @@ const fontFaceRule = (face, embedded, src) => `@font-face { font-family: ${quote
 * once per render and shared by every page: an id maps to one blob, so the
 * bytes are held once and one revoke releases them.
 */
-const embeddedFontFaceCss = (fonts) => {
+const embeddedFontFaceCss = (fonts, urls) => {
 	const srcById = /* @__PURE__ */ new Map();
 	const rules = [];
 	for (const face of fonts) {
 		const embedded = face.embedded;
 		if (embedded === void 0) continue;
 		const cached = srcById.get(embedded.id);
-		const src = cached ?? binarySrc(embedded.bytes, FONT_MIME_TYPE);
+		const src = cached ?? binarySrc(embedded.bytes, FONT_MIME_TYPE, urls);
 		if (cached === void 0) srcById.set(embedded.id, src);
 		rules.push(fontFaceRule(face, embedded, src));
 	}
@@ -399,7 +399,7 @@ const paintImage = ({ image, rect, crop, opacity, brightness, contrast }, contex
 		element.style.height = px(fullHeight);
 	}
 	element.alt = "";
-	element.src = binarySrc(source.bytes, IMAGE_MIME_TYPES[source.format]);
+	element.src = binarySrc(source.bytes, IMAGE_MIME_TYPES[source.format], context.binaryUrls);
 	clip.append(element);
 	context.parent.append(clip);
 };
@@ -497,6 +497,7 @@ const renderPage = (page, options) => {
 	}
 	const context = {
 		doc: options.doc,
+		binaryUrls: options.binaryUrls ?? "objectUrl",
 		fonts: options.fonts,
 		images: options.images,
 		parent: element,
@@ -595,11 +596,11 @@ const paintRegionTree = ({ primitives, regions }, context) => {
 };
 const renderDisplayPageToDom = (page, options) => renderPage(page, {
 	...options,
-	fontFaceCss: embeddedFontFaceCss(options.fonts)
+	fontFaceCss: embeddedFontFaceCss(options.fonts, options.binaryUrls ?? "objectUrl")
 });
 /** One `div.layout-page` per display page, in page order. */
 const renderDisplayListToDom = (list, options) => {
-	const fontFaceCss = embeddedFontFaceCss(list.fonts);
+	const fontFaceCss = embeddedFontFaceCss(list.fonts, options.binaryUrls ?? "objectUrl");
 	return list.pages.map((page, pageIndex) => renderPage(page, {
 		...options,
 		fonts: list.fonts,

package/dist/display-list/html/renderDisplayListToHtml.d.ts

@@ -0,0 +1,21 @@
+import { DisplayColor, DisplayList } from "../types.js";
+//#region src/display-list/html/renderDisplayListToHtml.d.ts
+declare const escapeHtmlText: (value: string) => string;
+type RenderDisplayListToHtmlOptions = {
+  /** `@font-face` rules for the families the list names, placed in the head. */
+  readonly fontFaceCss?: string;
+  /** The document title. */
+  readonly title?: string;
+  /** Space between pages. Defaults to 0: pages stack flush. */
+  readonly pageGapPx?: number;
+  /** CSS color behind the pages. Defaults to white. */
+  readonly canvasColor?: string;
+  /** Page background, painted before any primitive. */
+  readonly pageBackground?: DisplayColor;
+};
+/** The pages' markup, one slot per display page, in page order. */
+declare const renderDisplayListPagesToHtml: (list: DisplayList, options?: Pick<RenderDisplayListToHtmlOptions, "pageBackground">) => string[];
+/** A complete HTML document showing every page of the list. */
+declare const renderDisplayListToHtml: (list: DisplayList, options?: RenderDisplayListToHtmlOptions) => string;
+//#endregion
+export { RenderDisplayListToHtmlOptions, escapeHtmlText, renderDisplayListPagesToHtml, renderDisplayListToHtml };

package/dist/display-list/html/renderDisplayListToHtml.js

@@ -0,0 +1,126 @@
+import { renderDisplayListToDom } from "../dom/renderDisplayListToDom.js";
+//#region src/display-list/html/renderDisplayListToHtml.ts
+/**
+* A display list as one HTML document, with no browser and no DOM.
+*
+* The DOM backend paints into whatever `Document` it is handed. This module
+* hands it a document with only what the backend reaches for and serializes
+* the result, so a server, a CLI or a harness can produce the page a browser
+* would show from the same painter the editor uses. Binary data (images,
+* embedded faces) is inlined as `data:` URLs, because a `blob:` URL minted in
+* this process resolves to nothing once the markup leaves it.
+*/
+const VOID_TAGS = /* @__PURE__ */ new Set([
+	"img",
+	"br",
+	"hr"
+]);
+const createStubElement = (tagName) => {
+	const children = [];
+	const attributes = {};
+	return {
+		tagName,
+		style: {},
+		dataset: {},
+		attributes,
+		children,
+		className: "",
+		id: "",
+		textContent: "",
+		alt: "",
+		src: "",
+		href: "",
+		title: "",
+		append: (...nodes) => {
+			children.push(...nodes);
+		},
+		appendChild: (node) => {
+			children.push(node);
+			return node;
+		},
+		setAttribute: (name, value) => {
+			attributes[name] = value;
+		}
+	};
+};
+/**
+* A `Document` with only what the DOM backend reaches for. A backend that
+* grows a new requirement throws on the missing property here rather than
+* silently serializing less than it painted.
+*/
+const stubDocument = () => {
+	return { createElement: createStubElement };
+};
+const asStub = (element) => element;
+/** A vendor property is camelCase with no leading capital, so its leading dash is explicit. */
+const VENDOR_PREFIXES = [
+	"webkit-",
+	"moz-",
+	"ms-",
+	"o-"
+];
+const toKebabCase = (name) => {
+	const hyphenated = name.replaceAll(/[A-Z]/gu, (letter) => `-${letter.toLowerCase()}`);
+	return VENDOR_PREFIXES.some((prefix) => hyphenated.startsWith(prefix)) ? `-${hyphenated}` : hyphenated;
+};
+const escapeHtmlText = (value) => value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;");
+const escapeAttribute = (value) => escapeHtmlText(value).replaceAll("\"", "&quot;");
+const serializeStyle = (style) => Object.entries(style).map(([property, value]) => `${toKebabCase(property)}: ${value}`).join("; ");
+/**
+* Serialized without one character of added whitespace: the backend sets
+* `white-space: pre` on every run, so an indentation newline would be painted.
+*/
+const RAW_TEXT_TAGS = /* @__PURE__ */ new Set(["style", "script"]);
+/** Text placed inside a `<style>` or `<script>`: a `</` cannot close the element early. */
+const rawElementText = (text) => text.replaceAll("</", "<\\/");
+const serializeElement = (element) => {
+	const attributes = [];
+	if (element.className !== "") attributes.push(`class="${escapeAttribute(element.className)}"`);
+	if (element.id !== "") attributes.push(`id="${escapeAttribute(element.id)}"`);
+	if (element.href !== "") attributes.push(`href="${escapeAttribute(element.href)}"`);
+	if (element.src !== "") attributes.push(`src="${escapeAttribute(element.src)}"`);
+	if (element.title !== "") attributes.push(`title="${escapeAttribute(element.title)}"`);
+	if (element.tagName === "img") attributes.push(`alt="${escapeAttribute(element.alt)}"`);
+	for (const [name, value] of Object.entries(element.attributes)) attributes.push(`${name}="${escapeAttribute(value)}"`);
+	for (const [key, value] of Object.entries(element.dataset)) attributes.push(`data-${toKebabCase(key)}="${escapeAttribute(value)}"`);
+	const style = serializeStyle(element.style);
+	if (style !== "") attributes.push(`style="${escapeAttribute(style)}"`);
+	const open = [element.tagName, ...attributes].join(" ");
+	if (VOID_TAGS.has(element.tagName)) return `<${open} />`;
+	if (element.children.length > 0) return `<${open}>${element.children.map(serializeElement).join("")}</${element.tagName}>`;
+	return `<${open}>${RAW_TEXT_TAGS.has(element.tagName) ? rawElementText(element.textContent) : escapeHtmlText(element.textContent)}</${element.tagName}>`;
+};
+/**
+* Each page sits in a slot of whole pixels. A page height is fractional (A4 is
+* 1122.52 px), so pages stacked in normal flow would start at fractional
+* offsets; the slot rounds the offset while the page keeps its exact size.
+*/
+const pageSlot = (markup, page) => `<div class="layout-page-slot" style="position: relative; overflow: hidden; width: ${String(Math.ceil(page.widthPx))}px; height: ${String(Math.ceil(page.heightPx))}px">${markup}</div>`;
+/** The pages' markup, one slot per display page, in page order. */
+const renderDisplayListPagesToHtml = (list, options = {}) => renderDisplayListToDom(list, {
+	doc: stubDocument(),
+	binaryUrls: "dataUrl",
+	...options.pageBackground !== void 0 && { pageBackground: options.pageBackground }
+}).map((element, index) => {
+	const markup = serializeElement(asStub(element));
+	const page = list.pages.at(index);
+	return page === void 0 ? markup : pageSlot(markup, page);
+});
+/** A complete HTML document showing every page of the list. */
+const renderDisplayListToHtml = (list, options = {}) => {
+	const gap = options.pageGapPx ?? 0;
+	const canvas = rawElementText(options.canvasColor ?? "#fff");
+	const layout = gap > 0 ? `body { display: flex; flex-direction: column; align-items: center; gap: ${String(gap)}px; padding: ${String(gap)}px 0; }` : "";
+	return [
+		"<!doctype html>",
+		`<html><head><meta charset="utf-8"><title>${escapeHtmlText(options.title ?? "")}</title><style>`,
+		rawElementText(options.fontFaceCss ?? ""),
+		`html, body { margin: 0; padding: 0; background: ${canvas}; }`,
+		layout,
+		"</style></head><body>",
+		renderDisplayListPagesToHtml(list, options).join(""),
+		"</body></html>"
+	].join("\n");
+};
+//#endregion
+export { escapeHtmlText, renderDisplayListPagesToHtml, renderDisplayListToHtml };

package/dist/display-list/selectDisplayPages.d.ts

@@ -0,0 +1,6 @@
+import { DisplayList } from "./types.js";
+//#region src/display-list/selectDisplayPages.d.ts
+/** Keep `pageIndices` (0-based, in the order given; duplicates are dropped). */
+declare const selectDisplayPages: (list: DisplayList, pageIndices: readonly number[]) => DisplayList;
+//#endregion
+export { selectDisplayPages };

package/dist/display-list/selectDisplayPages.js

@@ -0,0 +1,44 @@
+//#region src/display-list/selectDisplayPages.ts
+/** Keep `pageIndices` (0-based, in the order given; duplicates are dropped). */
+const selectDisplayPages = (list, pageIndices) => {
+	const kept = [...new Set(pageIndices)].filter((index) => Number.isInteger(index) && index >= 0 && index < list.pages.length);
+	const remap = new Map(kept.map((original, next) => [original, next]));
+	const relink = (link) => {
+		if (link.target.kind !== "page") return [link];
+		const pageIndex = remap.get(link.target.pageIndex);
+		return pageIndex === void 0 ? [] : [{
+			...link,
+			target: {
+				...link.target,
+				pageIndex
+			}
+		}];
+	};
+	const pages = kept.flatMap((index) => {
+		const page = list.pages[index];
+		return page === void 0 ? [] : [{
+			...page,
+			links: page.links.flatMap(relink)
+		}];
+	});
+	return {
+		...list,
+		pages,
+		outline: list.outline.flatMap((entry) => {
+			const pageIndex = remap.get(entry.pageIndex);
+			return pageIndex === void 0 ? [] : [{
+				...entry,
+				pageIndex
+			}];
+		}),
+		unsupported: list.unsupported.flatMap((entry) => {
+			const pageIndex = remap.get(entry.pageIndex);
+			return pageIndex === void 0 ? [] : [{
+				...entry,
+				pageIndex
+			}];
+		})
+	};
+};
+//#endregion
+export { selectDisplayPages };

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 };