@stll/folio-core 0.32.2 → 0.33.0

package/dist/docx/xmlParser.js

@@ -64,6 +64,37 @@ const resolveNamespaceUri = (scope, prefix) => {
 		current = current.parent;
 	}
 };
+/** Attach the element's resolved namespace metadata from its in-scope declarations. */
+const attachXmlNamespaceContext = (element, inheritedNamespaceScope = EMPTY_NAMESPACE_SCOPE) => {
+	let localBindings = null;
+	if (element.attributes) for (const [attribute, value] of Object.entries(element.attributes)) {
+		if (typeof value !== "string" || attribute !== "xmlns" && !attribute.startsWith("xmlns:")) continue;
+		localBindings ??= /* @__PURE__ */ new Map();
+		const prefix = attribute === "xmlns" ? "" : attribute.slice(6);
+		localBindings.set(prefix, value);
+	}
+	const namespaceScope = localBindings === null ? inheritedNamespaceScope : {
+		bindings: localBindings,
+		parent: inheritedNamespaceScope
+	};
+	Object.defineProperty(element, "namespaceScope", {
+		configurable: false,
+		enumerable: false,
+		value: namespaceScope,
+		writable: false
+	});
+	const name = element.name ?? "";
+	const colonIndex = name.indexOf(":");
+	const prefix = colonIndex === -1 ? "" : name.slice(0, colonIndex);
+	const namespaceUri = resolveNamespaceUri(namespaceScope, prefix);
+	if (namespaceUri !== void 0) Object.defineProperty(element, "namespaceUri", {
+		configurable: false,
+		enumerable: false,
+		value: namespaceUri,
+		writable: false
+	});
+	return namespaceScope;
+};
 /**
 * Convert a fast-xml-parser preserveOrder node into an XmlElement.
 *
@@ -85,32 +116,7 @@ function fxpNodeToElement(node, inheritedNamespaceScope = EMPTY_NAMESPACE_SCOPE)
 			name: key
 		};
 		if (attrs) element.attributes = attrs;
-		let localBindings = null;
-		if (attrs) for (const [attribute, value] of Object.entries(attrs)) {
-			if (attribute !== "xmlns" && !attribute.startsWith("xmlns:")) continue;
-			localBindings ??= /* @__PURE__ */ new Map();
-			const prefix = attribute === "xmlns" ? "" : attribute.slice(6);
-			localBindings.set(prefix, value);
-		}
-		const namespaceScope = localBindings === null ? inheritedNamespaceScope : {
-			bindings: localBindings,
-			parent: inheritedNamespaceScope
-		};
-		Object.defineProperty(element, "namespaceScope", {
-			configurable: false,
-			enumerable: false,
-			value: namespaceScope,
-			writable: false
-		});
-		const colonIndex = key.indexOf(":");
-		const prefix = colonIndex === -1 ? "" : key.slice(0, colonIndex);
-		const namespaceUri = resolveNamespaceUri(namespaceScope, prefix);
-		if (namespaceUri !== void 0) Object.defineProperty(element, "namespaceUri", {
-			configurable: false,
-			enumerable: false,
-			value: namespaceUri,
-			writable: false
-		});
+		const namespaceScope = attachXmlNamespaceContext(element, inheritedNamespaceScope);
 		if (children.length > 0) {
 			for (let index = 0; index < children.length; index += 1) children[index] = fxpNodeToElement(children[index], namespaceScope);
 			element.elements = children;
@@ -745,4 +751,4 @@ function cloneWithXmlnsDeclarations(element, xmlnsDecls) {
 	return element;
 }
 //#endregion
-export { NAMESPACES, WORDPROCESSINGML_NAMESPACE_URIS, cloneWithXmlnsDeclarations, collectXmlnsDeclarations, elementToXml, findAllDeep, findAttributeByNamespaceUri, findByFullName, findChild, findChildByLocalName, findChildByNamespaceUri, findChildren, findChildrenByLocalName, findDeep, getAttribute, getAttributeAny, getAttributeAnyPrefix, getAttributeByNamespaceUri, getAttributes, getChildElements, getLocalName, getNamespacePrefix, getNamespaceUri, getTextContent, hasChild, hasFlag, matchesName, mergeXmlnsDeclarations, parseBooleanElement, parseColorElement, parseNumberingLevelAttribute, parseNumericAttribute, parseOnOffValue, parseTableMeasurementValue, parseXml, parseXmlDocument };
+export { NAMESPACES, WORDPROCESSINGML_NAMESPACE_URIS, attachXmlNamespaceContext, cloneWithXmlnsDeclarations, collectXmlnsDeclarations, elementToXml, findAllDeep, findAttributeByNamespaceUri, findByFullName, findChild, findChildByLocalName, findChildByNamespaceUri, findChildren, findChildrenByLocalName, findDeep, getAttribute, getAttributeAny, getAttributeAnyPrefix, getAttributeByNamespaceUri, getAttributes, getChildElements, getLocalName, getNamespacePrefix, getNamespaceUri, getTextContent, hasChild, hasFlag, matchesName, mergeXmlnsDeclarations, parseBooleanElement, parseColorElement, parseNumberingLevelAttribute, parseNumericAttribute, parseOnOffValue, parseTableMeasurementValue, parseXml, parseXmlDocument };

package/dist/export-pdf.d.ts

@@ -0,0 +1,43 @@
+import { DocxInput } from "./utils/docxInput.js";
+import { 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";
+import { PdfUnencodable } from "./pdf/writePdf.js";
+import { Result } from "better-result";
+//#region src/export-pdf.d.ts
+declare const ExportPdfError_base: import("better-result").TaggedErrorClass<"ExportPdfError">;
+declare class ExportPdfError extends ExportPdfError_base<{
+  message: string;
+  cause?: unknown;
+}> {}
+type ExportDocxToPdfOptions = {
+  /** Supplies face binaries for measurement and for embedding alike. */
+  readonly fonts: HeadlessFontSource;
+  /**
+   * ISO-8601 instant stamped as the PDF's creation and modification date.
+   * Required rather than defaulted so a caller cannot get a nondeterministic
+   * document by omission; pass the source package's own timestamp or a fixed
+   * epoch.
+   */
+  readonly timestamp: string;
+  readonly metadata?: DisplayMetadata;
+  readonly producer?: string;
+};
+type ExportDocxToPdfResult = {
+  readonly bytes: Uint8Array;
+  readonly pageCount: number;
+  /** Constructs the display list could not represent. */
+  readonly unsupported: readonly DisplayUnsupported[];
+  /** Stories the headless pipeline does not paginate. */
+  readonly layoutGaps: readonly HeadlessLayoutGap[];
+  /** Faces measured with a stand-in. */
+  readonly measurementSubstitutions: readonly HeadlessFontSubstitution[];
+  /** Faces embedded as a stand-in. */
+  readonly embeddingSubstitutions: readonly PdfSubstitution[];
+  /** Code points painted as `.notdef` because no supplied face covers them. */
+  readonly unencodable: readonly PdfUnencodable[];
+};
+declare const exportDocxToPdf: (input: DocxInput, options: ExportDocxToPdfOptions) => Promise<Result<ExportDocxToPdfResult, ExportPdfError>>;
+//#endregion
+export { ExportDocxToPdfOptions, ExportDocxToPdfResult, ExportPdfError, exportDocxToPdf };

package/dist/export-pdf.js

@@ -0,0 +1,98 @@
+import { buildDisplayList } from "./display-list/build/buildDisplayList.js";
+import { installHeadlessMeasureProvider } from "./fonts/headlessMeasure.js";
+import { layoutDocxHeadless } from "./headless-layout.js";
+import { getMeasureProvider, setMeasureProvider } from "./layout-engine/measure/measureProvider.js";
+import { writePdf } from "./pdf/writePdf.js";
+import { Result, TaggedError } from "better-result";
+//#region src/export-pdf.ts
+/**
+* `.docx` to PDF, with no browser and no second painter.
+*
+* The chain is four steps and no shortcuts: paginate headlessly, build the
+* display list, hand the display list to the PDF backend, return the bytes.
+* The editor's DOM backend consumes the same display list from the same
+* builder, so the exported page and the displayed page cannot be laid out by
+* two different sets of rules.
+*
+* ## One font source, two consumers
+*
+* Measurement and embedding read the same {@link HeadlessFontSource}. Laying
+* out against one face and embedding another is the subtle version of the
+* divergence this design exists to prevent: the pagination would be right for
+* a font the reader never sees.
+*
+* ## Determinism
+*
+* `exportDocxToPdf(bytes, options)` is a pure function of its arguments.
+* `options.timestamp` is required rather than defaulted, the same contract
+* `compareDocx` uses, so a caller cannot get nondeterministic output by
+* omission.
+*/
+var ExportPdfError = class extends TaggedError("ExportPdfError") {};
+const toFontRequest = ({ family, weight, italic }) => ({
+	family,
+	bold: weight >= 700,
+	italic
+});
+/**
+* Exports run one at a time.
+*
+* The measurement provider is process-wide, and an export must install its own
+* fonts across an `await`. Two overlapping exports would otherwise interleave:
+* the second replaces the first's provider, the first resumes and measures
+* against the second's fonts, then restores the provider while the second is
+* still running. Serialising is the honest fix while the provider is ambient;
+* threading it explicitly through the layout call would remove the need, and
+* is the larger change this defers to.
+*/
+let exportQueue = Promise.resolve();
+const runExclusively = (run) => {
+	const current = exportQueue.then(run, run);
+	exportQueue = current.then(() => void 0, () => void 0);
+	return current;
+};
+const exportDocxToPdf = (input, options) => runExclusively(() => exportOnce(input, options));
+const exportOnce = async (input, options) => {
+	const callerProvider = getMeasureProvider();
+	try {
+		return await exportWithHeadlessProvider(input, options);
+	} finally {
+		setMeasureProvider(callerProvider);
+	}
+};
+const exportWithHeadlessProvider = async (input, options) => {
+	const headless = installHeadlessMeasureProvider(options.fonts);
+	const laidOut = await layoutDocxHeadless(input, { pageGap: 0 });
+	if (laidOut.isErr()) return Result.err(new ExportPdfError({
+		message: laidOut.error.message,
+		cause: laidOut.error
+	}));
+	const list = buildDisplayList({
+		layout: laidOut.value.layout,
+		blockLookup: laidOut.value.blockLookup,
+		documentFeatures: laidOut.value.documentFeatures,
+		...laidOut.value.furniture,
+		embeddedFonts: laidOut.value.embeddedFonts,
+		...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,
+		layoutGaps: laidOut.value.unsupported,
+		measurementSubstitutions: headless.substitutions(),
+		embeddingSubstitutions: written.value.substitutions,
+		unencodable: written.value.unencodable
+	});
+};
+//#endregion
+export { ExportPdfError, exportDocxToPdf };

package/dist/fonts/headlessMeasure.d.ts

@@ -0,0 +1,76 @@
+import { MeasureProvider } from "../layout-engine/measure/measureProvider.js";
+import { Shaper } from "../shaping/shaper.js";
+import { Result } from "better-result";
+//#region src/fonts/headlessMeasure.d.ts
+/** One concrete face, as a font source is asked for it. */
+type HeadlessFontRequest = {
+  readonly family: string;
+  readonly bold: boolean;
+  readonly italic: boolean;
+};
+/**
+ * Where face binaries come from. A server reads them from disk, a browser
+ * fetches them, a package supplies its own embedded faces; none of that is
+ * this module's business.
+ *
+ * A face is a *list* of binaries rather than one, because a family is
+ * routinely shipped split by script: `@fontsource` cuts every family into
+ * disjoint `latin`, `latin-ext`, `cyrillic` and `greek` subsets, and a Czech
+ * or Polish document needs two of them at once. Returning one binary per face
+ * would mean picking a subset per document and painting `.notdef` for
+ * everything outside it. The list is in priority order, and a code point is
+ * served by the first binary whose `cmap` covers it.
+ */
+type HeadlessFontSource = {
+  /** Plain sfnt or WOFF binaries, empty when the source has no such face. */
+  readonly load: (request: HeadlessFontRequest) => readonly Uint8Array[];
+};
+/** A face the source could not supply, measured with a stand-in instead. */
+type HeadlessFontSubstitution = {
+  readonly requested: HeadlessFontRequest;
+  readonly reason: string;
+};
+declare const HeadlessMeasureError_base: import("better-result").TaggedErrorClass<"HeadlessMeasureError">;
+declare class HeadlessMeasureError extends HeadlessMeasureError_base<{
+  message: string;
+}> {}
+type HeadlessMeasureOptions = {
+  /**
+   * The shaper to measure shaping scripts with.
+   *
+   * Omitted, the provider uses whichever shaper has been loaded, which is what
+   * the layout entry points resolve once they find a document that needs one.
+   * Pass one explicitly to measure against a shaper of your own; pass `null` to
+   * measure as if none existed.
+   */
+  readonly shaper?: Shaper | null;
+};
+type HeadlessMeasureProvider = {
+  readonly provider: MeasureProvider;
+  /**
+   * Faces measured with a stand-in, in first-request order. A caller that
+   * ships the result to a user must surface these: a substituted face
+   * measures differently, so the pagination is not the authored one.
+   */
+  readonly substitutions: () => readonly HeadlessFontSubstitution[];
+};
+/**
+ * Build a provider over a font source. The provider is stateful only in its
+ * face cache and its substitution log, both scoped to the returned object, so
+ * two providers never contaminate each other.
+ */
+declare const createHeadlessMeasureProvider: (source: HeadlessFontSource, options?: HeadlessMeasureOptions) => HeadlessMeasureProvider;
+/**
+ * Install a headless backend as the active provider. An explicit call, never a
+ * module side effect, so importing this module cannot silently change how a
+ * document measures.
+ */
+declare const installHeadlessMeasureProvider: (source: HeadlessFontSource, options?: HeadlessMeasureOptions) => HeadlessMeasureProvider;
+/**
+ * Refuse to measure when a source cannot supply a face that the document
+ * actually uses. Callers that would rather fail than paginate against a
+ * stand-in call this after layout.
+ */
+declare const assertNoSubstitutions: (headless: HeadlessMeasureProvider) => Result<void, HeadlessMeasureError>;
+//#endregion
+export { HeadlessFontRequest, HeadlessFontSource, HeadlessFontSubstitution, HeadlessMeasureError, HeadlessMeasureOptions, HeadlessMeasureProvider, assertNoSubstitutions, createHeadlessMeasureProvider, installHeadlessMeasureProvider };

package/dist/fonts/sfnt/parse.d.ts

@@ -0,0 +1,51 @@
+import { Result } from "better-result";
+//#region src/fonts/sfnt/parse.d.ts
+type SfntFont = {
+  readonly unitsPerEm: number;
+  /** hhea ascender/descender/lineGap, in font units; descender is negative. */
+  readonly ascender: number;
+  readonly descender: number;
+  readonly lineGap: number;
+  /** OS/2 sCapHeight and sxHeight when version >= 2, else derived from glyph bounds. */
+  readonly capHeight: number;
+  readonly xHeight: number;
+  /** post table italicAngle, degrees, negative for forward slant. */
+  readonly italicAngle: number;
+  /** head glyph bounding box: [xMin, yMin, xMax, yMax] in font units. */
+  readonly bbox: readonly [number, number, number, number];
+  readonly postScriptName: string;
+  /** true when outlines live in a `CFF ` table rather than `glyf`. */
+  readonly isCff: boolean;
+  readonly numGlyphs: number;
+  /** OS/2 fsType embedding permission bits, for the caller to police. */
+  readonly fsType: number;
+  /** The decoded sfnt bytes this font was parsed from. */
+  readonly bytes: Uint8Array;
+  /** Best-available cmap lookup. Returns 0 (.notdef) when unmapped. */
+  readonly glyphIdFor: (codePoint: number) => number;
+  /** hmtx advance in font units. Clamped to the last entry, per spec. */
+  readonly advanceWidthFor: (glyphId: number) => number;
+  /**
+   * Ink bounding box of one glyph in font units, or null when the glyph is
+   * empty (a space) or has no outline this reader can measure.
+   *
+   * This is what a canvas backend reports as `actualBoundingBox*`, and it is
+   * not the hhea metrics: a headless measure provider needs the ink extent to
+   * place baselines the way canvas does.
+   */
+  readonly glyphBoundsFor: (glyphId: number) => SfntGlyphBounds | null;
+};
+/** Ink extent of a single glyph, in font units. */
+type SfntGlyphBounds = {
+  readonly xMin: number;
+  readonly yMin: number;
+  readonly xMax: number;
+  readonly yMax: number;
+};
+declare const SfntParseError_base: import("better-result").TaggedErrorClass<"SfntParseError">;
+declare class SfntParseError extends SfntParseError_base<{
+  message: string;
+}> {}
+declare const parseSfnt: (bytes: Uint8Array) => Result<SfntFont, SfntParseError>;
+//#endregion
+export { SfntFont, SfntGlyphBounds, SfntParseError, parseSfnt };