@stll/folio-core 0.0.1-placeholder.0 → 0.1.0

package/dist/fields/evaluateField.d.ts

@@ -0,0 +1,23 @@
+import { ParsedFieldInstruction } from "../docx/fieldParser.js";
+import { FieldContext } from "./fieldContext.js";
+
+//#region src/fields/evaluateField.d.ts
+type EvaluateFieldOptions = {
+  /** Shown for unsupported field types and unresolved references. */fallback?: string; /** Run identity (`pmStart`) used to look up a precomputed SEQ value. */
+  instanceId?: number; /** Locked fields preserve their cached result instead of recalculating. */
+  locked?: boolean;
+};
+/**
+ * Evaluate a parsed field instruction to its display string for `ctx`.
+ *
+ * Returns `options.fallback` (default empty) for field types this engine does
+ * not compute and for references that do not resolve in the current layout, so
+ * an unsupported or dangling field keeps its last-known cached text rather than
+ * vanishing. Pure: all position-dependent inputs come from `ctx`.
+ */
+declare function evaluateField(parsed: ParsedFieldInstruction, ctx: FieldContext, options?: EvaluateFieldOptions): string;
+/** Parse `instruction` then evaluate it; convenience for callers holding the
+ *  raw instruction string rather than a pre-parsed instruction. */
+declare function evaluateFieldInstruction(instruction: string, ctx: FieldContext, options?: EvaluateFieldOptions): string;
+//#endregion
+export { evaluateField, evaluateFieldInstruction };

package/dist/fields/evaluateField.js

@@ -0,0 +1,77 @@
+import { computePageNumber, formatDate, parseFieldInstruction } from "../docx/fieldParser.js";
+//#region src/fields/evaluateField.ts
+/** The `\@` date picture, or undefined. Unlike the general format switch, this
+*  must NOT match `\*` (e.g. `\* MERGEFORMAT`), which is not a date format. */
+function dateFormatSwitch(parsed) {
+	return parsed.switches.find((s) => s.switch === "@")?.value;
+}
+function hasRefNumberingSwitch(parsed) {
+	return hasAnySwitch(parsed, [
+		"n",
+		"r",
+		"w"
+	]);
+}
+function hasPageRefPositionSwitch(parsed) {
+	return hasAnySwitch(parsed, ["p"]);
+}
+function hasSeqHiddenSwitch(parsed) {
+	return hasAnySwitch(parsed, ["h"]);
+}
+function hasAnySwitch(parsed, names) {
+	return names.some((name) => hasSwitch(parsed, name));
+}
+function hasSwitch(parsed, name) {
+	const normalized = name.toLowerCase();
+	if (parsed.switches.some((s) => s.switch.toLowerCase() === normalized)) return true;
+	return new RegExp(`\\\\${normalized}\\b`, "iu").test(parsed.raw);
+}
+/**
+* Evaluate a parsed field instruction to its display string for `ctx`.
+*
+* Returns `options.fallback` (default empty) for field types this engine does
+* not compute and for references that do not resolve in the current layout, so
+* an unsupported or dangling field keeps its last-known cached text rather than
+* vanishing. Pure: all position-dependent inputs come from `ctx`.
+*/
+function evaluateField(parsed, ctx, options = {}) {
+	const fallback = options.fallback ?? "";
+	if (options.locked) return fallback;
+	switch (parsed.type) {
+		case "PAGE": return computePageNumber(ctx.pageNumber, parsed);
+		case "NUMPAGES": return computePageNumber(ctx.totalPages, parsed);
+		case "SECTIONPAGES": return ctx.sectionPages === void 0 ? fallback : computePageNumber(ctx.sectionPages, parsed);
+		case "TIME": {
+			const format = dateFormatSwitch(parsed);
+			return format ? formatDate(ctx.now, format) : ctx.now.toLocaleTimeString();
+		}
+		case "DATE": {
+			const format = dateFormatSwitch(parsed);
+			return format ? formatDate(ctx.now, format) : ctx.now.toLocaleDateString();
+		}
+		case "CREATEDATE":
+		case "SAVEDATE":
+		case "PRINTDATE": return fallback;
+		case "PAGEREF": {
+			if (hasPageRefPositionSwitch(parsed)) return fallback;
+			const page = parsed.argument ? ctx.bookmarkPages.get(parsed.argument) : void 0;
+			return page === void 0 ? fallback : computePageNumber(page, parsed);
+		}
+		case "REF":
+			if (hasRefNumberingSwitch(parsed)) return fallback;
+			return (parsed.argument ? ctx.bookmarkText.get(parsed.argument) : void 0) ?? fallback;
+		case "SEQ": {
+			if (hasSeqHiddenSwitch(parsed)) return fallback;
+			const value = options.instanceId === void 0 ? void 0 : ctx.seqValues.get(options.instanceId);
+			return value === void 0 ? fallback : computePageNumber(value, parsed);
+		}
+		default: return fallback;
+	}
+}
+/** Parse `instruction` then evaluate it; convenience for callers holding the
+*  raw instruction string rather than a pre-parsed instruction. */
+function evaluateFieldInstruction(instruction, ctx, options = {}) {
+	return evaluateField(parseFieldInstruction(instruction), ctx, options);
+}
+//#endregion
+export { evaluateField, evaluateFieldInstruction };

package/dist/fields/fieldContext.d.ts

@@ -0,0 +1,21 @@
+//#region src/fields/fieldContext.d.ts
+/**
+ * Resolution context for evaluating dynamic DOCX fields against a laid-out
+ * document. Built once per layout pass (see the field-resolution pass) and
+ * consumed by {@link evaluateField}. All position-dependent values
+ * (page numbers, bookmark pages, SEQ counters) are resolved against the current
+ * layout so a field paints the same value its width was measured against.
+ */
+type FieldContext = {
+  /** 1-indexed page the field is on (PAGE). */pageNumber: number; /** Total pages in the document (NUMPAGES). */
+  totalPages: number;
+  /** Pages in the field's current section (SECTIONPAGES); omit until the
+   *  per-section page counts are available, in which case the field falls back. */
+  sectionPages?: number; /** Bookmark name -> 1-indexed page it lands on (PAGEREF). */
+  bookmarkPages: ReadonlyMap<string, number>; /** Bookmark name -> resolved display text (REF). */
+  bookmarkText: ReadonlyMap<string, string>; /** Field instance id (the run's `pmStart`) -> precomputed SEQ value. */
+  seqValues: ReadonlyMap<number, number>; /** Clock for DATE/TIME-family fields; passed in so evaluation stays pure. */
+  now: Date;
+};
+//#endregion
+export { FieldContext };

package/dist/fields/resolveFieldValues.d.ts

@@ -0,0 +1,44 @@
+import { FlowBlock, Page } from "../layout-engine/types.js";
+
+//#region src/fields/resolveFieldValues.d.ts
+/** Layout-derived inputs shared by every field, regardless of its position. */
+type SharedFieldInputs = {
+  totalPages: number;
+  bookmarkPages: ReadonlyMap<string, number>;
+  bookmarkText: ReadonlyMap<string, string>;
+  seqValues: ReadonlyMap<number, number>; /** Section index -> page count, for SECTIONPAGES. */
+  sectionPageCounts: ReadonlyMap<number, number>;
+  now: Date;
+};
+type HeaderFooterFieldInputs = Pick<SharedFieldInputs, "bookmarkPages" | "bookmarkText" | "seqValues" | "sectionPageCounts">;
+type ResolvedFieldValues = {
+  /** Field run `pmStart` -> resolved display text. */values: Map<number, string>;
+  /**
+   * True when at least one field resolved to a string that differs from the
+   * text it was measured at (`fallback || "1"`), i.e. a re-measure would change
+   * line widths. The driver uses this to skip re-layout when nothing moved.
+   */
+  changed: boolean;
+};
+/**
+ * Resolve every field run to its display value against a finished layout, keyed
+ * by the run's `pmStart`. Each field is evaluated for the page its top-level
+ * block lands on (fields inside a table/text box take that container's page).
+ * Feed `values` back into `measureBlocks({ fieldValues })` so fields measure at
+ * their painted width.
+ */
+declare function resolveFieldValues(blocks: readonly FlowBlock[], pages: readonly Page[], shared: SharedFieldInputs): ResolvedFieldValues;
+/**
+ * Field values for measuring header/footer blocks, which are laid out once but
+ * painted on every page with a different page number. Page-number fields
+ * (PAGE/NUMPAGES/SECTIONPAGES) are reserved at the width of the largest page
+ * (`pageCount`) so a multi-digit number on a later page can't wrap differently
+ * than the single layout; other fields keep their fallback (resolved per-page at
+ * paint). `pageCount` is the document's page count — a prior render's count is a
+ * fine estimate, since headers are measured before the body is re-laid-out.
+ */
+declare function buildHeaderFooterFieldValues(blocks: readonly FlowBlock[], pageCount: number, now: Date, inputs?: Partial<HeaderFooterFieldInputs>): Map<number, string>;
+/** Whether two resolved-value maps are identical, for loop convergence. */
+declare function fieldValuesEqual(a: ReadonlyMap<number, string>, b: ReadonlyMap<number, string>): boolean;
+//#endregion
+export { HeaderFooterFieldInputs, ResolvedFieldValues, SharedFieldInputs, buildHeaderFooterFieldValues, fieldValuesEqual, resolveFieldValues };

package/dist/fields/resolveFieldValues.js

@@ -0,0 +1,204 @@
+import { computePageNumber, getFormatSwitch, parseFieldInstruction } from "../docx/fieldParser.js";
+import { evaluateField } from "./evaluateField.js";
+//#region src/fields/resolveFieldValues.ts
+/**
+* Resolve every field run to its display value against a finished layout, keyed
+* by the run's `pmStart`. Each field is evaluated for the page its top-level
+* block lands on (fields inside a table/text box take that container's page).
+* Feed `values` back into `measureBlocks({ fieldValues })` so fields measure at
+* their painted width.
+*/
+function resolveFieldValues(blocks, pages, shared) {
+	const blockPage = buildBlockPageMap(pages);
+	const tableRowPage = buildTableRowPageMap(pages);
+	const fields = [];
+	for (const block of blocks) collectFieldAnchors(block, block.id, fields);
+	const values = /* @__PURE__ */ new Map();
+	let changed = false;
+	for (const field of fields) {
+		const run = field.run;
+		if (run.pmStart === void 0) continue;
+		const location = resolveAnchorLocation(field, blockPage, tableRowPage);
+		const sectionPages = location ? shared.sectionPageCounts.get(location.sectionIndex) : void 0;
+		const context = {
+			pageNumber: location?.page ?? 1,
+			totalPages: shared.totalPages,
+			bookmarkPages: shared.bookmarkPages,
+			bookmarkText: shared.bookmarkText,
+			seqValues: shared.seqValues,
+			now: shared.now,
+			...sectionPages === void 0 ? {} : { sectionPages }
+		};
+		const value = evaluateField(parseFieldInstruction(run.instruction || run.fieldType), context, {
+			fallback: run.fallback ?? "",
+			instanceId: run.pmStart,
+			...run.fldLock ? { locked: true } : {}
+		});
+		values.set(run.pmStart, value);
+		if (value !== (run.fallback || "1")) changed = true;
+	}
+	return {
+		values,
+		changed
+	};
+}
+const EMPTY_STRING_NUMBER = /* @__PURE__ */ new Map();
+const EMPTY_STRING_STRING = /* @__PURE__ */ new Map();
+const EMPTY_NUMBER_NUMBER = /* @__PURE__ */ new Map();
+/**
+* Field values for measuring header/footer blocks, which are laid out once but
+* painted on every page with a different page number. Page-number fields
+* (PAGE/NUMPAGES/SECTIONPAGES) are reserved at the width of the largest page
+* (`pageCount`) so a multi-digit number on a later page can't wrap differently
+* than the single layout; other fields keep their fallback (resolved per-page at
+* paint). `pageCount` is the document's page count — a prior render's count is a
+* fine estimate, since headers are measured before the body is re-laid-out.
+*/
+function buildHeaderFooterFieldValues(blocks, pageCount, now, inputs) {
+	const values = /* @__PURE__ */ new Map();
+	const fields = [];
+	for (const block of blocks) collectFieldRuns(block, fields);
+	if (fields.length === 0) return values;
+	const context = {
+		pageNumber: pageCount,
+		totalPages: pageCount,
+		sectionPages: pageCount,
+		bookmarkPages: inputs?.bookmarkPages ?? EMPTY_STRING_NUMBER,
+		bookmarkText: inputs?.bookmarkText ?? EMPTY_STRING_STRING,
+		seqValues: inputs?.seqValues ?? EMPTY_NUMBER_NUMBER,
+		now
+	};
+	for (const run of fields) {
+		if (run.pmStart === void 0) continue;
+		const parsed = parseFieldInstruction(run.instruction || run.fieldType);
+		const fieldContext = {
+			...context,
+			...parsed.type === "PAGE" ? { pageNumber: widestFormattedPageNumber(parsed, pageCount) } : {},
+			...parsed.type === "SECTIONPAGES" ? { sectionPages: widestSectionPageCount(parsed, pageCount, inputs?.sectionPageCounts) } : {}
+		};
+		values.set(run.pmStart, evaluateField(parsed, fieldContext, {
+			fallback: run.fallback ?? "",
+			instanceId: run.pmStart,
+			...run.fldLock ? { locked: true } : {}
+		}));
+	}
+	return values;
+}
+function widestSectionPageCount(parsed, fallbackPageCount, sectionPageCounts) {
+	if (!sectionPageCounts || sectionPageCounts.size === 0) return fallbackPageCount;
+	return widestFormattedCount(parsed, Array.from(sectionPageCounts.values()));
+}
+function widestFormattedPageNumber(parsed, pageCount) {
+	return widestFormattedCount(parsed, Array.from({ length: pageCount }, (_, index) => index + 1));
+}
+function widestFormattedCount(parsed, counts) {
+	const format = getFormatSwitch(parsed)?.toUpperCase();
+	if (format !== "ROMAN" && format !== "ALPHABETIC") return Math.max(...counts, 1);
+	const first = counts.at(0) ?? 1;
+	let widestPage = first;
+	let widestWidth = formattedPageWidthScore(computePageNumber(first, parsed));
+	for (const page of counts.slice(1)) {
+		const width = formattedPageWidthScore(computePageNumber(page, parsed));
+		if (width > widestWidth) {
+			widestPage = page;
+			widestWidth = width;
+		}
+	}
+	return widestPage;
+}
+function formattedPageWidthScore(value) {
+	let score = 0;
+	for (const char of value) score += PAGE_WIDTH_SCORE[char] ?? 3;
+	return score;
+}
+const PAGE_WIDTH_SCORE = {
+	I: 1,
+	L: 3,
+	V: 4,
+	X: 4,
+	C: 5,
+	D: 5,
+	M: 5,
+	W: 5
+};
+/** Whether two resolved-value maps are identical, for loop convergence. */
+function fieldValuesEqual(a, b) {
+	if (a.size !== b.size) return false;
+	for (const [key, value] of a) if (b.get(key) !== value) return false;
+	return true;
+}
+/** First page (and its section) each top-level block lands on. */
+function buildBlockPageMap(pages) {
+	const map = /* @__PURE__ */ new Map();
+	for (const page of pages) for (const fragment of page.fragments) if (!map.has(fragment.blockId)) map.set(fragment.blockId, {
+		page: page.number,
+		sectionIndex: page.sectionIndex ?? 0
+	});
+	return map;
+}
+function buildTableRowPageMap(pages) {
+	const map = /* @__PURE__ */ new Map();
+	for (const page of pages) for (const fragment of page.fragments) {
+		if (fragment.kind !== "table") continue;
+		for (let rowIndex = fragment.fromRow; rowIndex < fragment.toRow; rowIndex++) {
+			const key = tableRowKey(fragment.blockId, rowIndex);
+			if (!map.has(key)) map.set(key, {
+				page: page.number,
+				sectionIndex: page.sectionIndex ?? 0
+			});
+		}
+	}
+	return map;
+}
+function tableRowKey(blockId, rowIndex) {
+	return `${blockId}:${rowIndex}`;
+}
+function resolveAnchorLocation(field, blockPage, tableRowPage) {
+	if (field.type === "block") return blockPage.get(field.blockId);
+	return tableRowPage.get(tableRowKey(field.blockId, field.rowIndex)) ?? blockPage.get(field.blockId);
+}
+function collectFieldAnchors(block, topLevelId, out) {
+	if (block.kind === "paragraph") {
+		for (const run of block.runs) if (run.kind === "field") out.push({
+			type: "block",
+			blockId: topLevelId,
+			run
+		});
+		return;
+	}
+	if (block.kind === "table") {
+		for (let rowIndex = 0; rowIndex < block.rows.length; rowIndex++) {
+			const row = block.rows[rowIndex];
+			if (!row) continue;
+			for (const cell of row.cells) for (const child of cell.blocks) collectTableRowFieldAnchors(child, block.id, rowIndex, out);
+		}
+		return;
+	}
+	if (block.kind === "textBox") for (const child of block.content) collectFieldAnchors(child, topLevelId, out);
+}
+function collectTableRowFieldAnchors(block, tableId, rowIndex, out) {
+	if (block.kind === "paragraph") {
+		for (const run of block.runs) if (run.kind === "field") out.push({
+			type: "tableRow",
+			blockId: tableId,
+			rowIndex,
+			run
+		});
+		return;
+	}
+	if (block.kind === "table") {
+		for (const row of block.rows) for (const cell of row.cells) for (const child of cell.blocks) collectTableRowFieldAnchors(child, tableId, rowIndex, out);
+		return;
+	}
+	if (block.kind === "textBox") for (const child of block.content) collectTableRowFieldAnchors(child, tableId, rowIndex, out);
+}
+function collectFieldRuns(block, out) {
+	if (block.kind === "paragraph") {
+		for (const run of block.runs) if (run.kind === "field") out.push(run);
+	} else if (block.kind === "table") for (const row of block.rows) for (const cell of row.cells) for (const cellBlock of cell.blocks) collectFieldRuns(cellBlock, out);
+	else if (block.kind === "textBox") {
+		for (const paragraph of block.content) for (const run of paragraph.runs) if (run.kind === "field") out.push(run);
+	}
+}
+//#endregion
+export { buildHeaderFooterFieldValues, fieldValuesEqual, resolveFieldValues };

package/dist/fields/sectionPageCounts.d.ts

@@ -0,0 +1,11 @@
+import { Page } from "../layout-engine/types.js";
+
+//#region src/fields/sectionPageCounts.d.ts
+/**
+ * Count how many pages belong to each section (by `Page.sectionIndex`, defaulting
+ * to 0 for single-section documents), for resolving SECTIONPAGES. A field on a
+ * page reads the count for that page's section.
+ */
+declare function buildSectionPageCounts(pages: readonly Page[]): Map<number, number>;
+//#endregion
+export { buildSectionPageCounts };

package/dist/fields/sectionPageCounts.js

@@ -0,0 +1,16 @@
+//#region src/fields/sectionPageCounts.ts
+/**
+* Count how many pages belong to each section (by `Page.sectionIndex`, defaulting
+* to 0 for single-section documents), for resolving SECTIONPAGES. A field on a
+* page reads the count for that page's section.
+*/
+function buildSectionPageCounts(pages) {
+	const counts = /* @__PURE__ */ new Map();
+	for (const page of pages) {
+		const index = page.sectionIndex ?? 0;
+		counts.set(index, (counts.get(index) ?? 0) + 1);
+	}
+	return counts;
+}
+//#endregion
+export { buildSectionPageCounts };

package/dist/fields/seqValues.d.ts

@@ -0,0 +1,14 @@
+import { FlowBlock } from "../layout-engine/types.js";
+
+//#region src/fields/seqValues.d.ts
+/**
+ * Assign each SEQ field instance its sequence number in document order, keyed by
+ * the field run's `pmStart`. SEQ counters are per identifier (the field
+ * argument, e.g. `Figure`), so `SEQ Figure` and `SEQ Table` count
+ * independently. Honours `\r n` (reset to n) and `\c` (repeat current without
+ * advancing); every other SEQ advances its counter by one. Independent of
+ * pagination, so it runs once per document, not per layout pass.
+ */
+declare function buildSeqValues(blocks: readonly FlowBlock[]): Map<number, number>;
+//#endregion
+export { buildSeqValues };

package/dist/fields/seqValues.js

@@ -0,0 +1,36 @@
+import { parseFieldInstruction } from "../docx/fieldParser.js";
+//#region src/fields/seqValues.ts
+/**
+* Assign each SEQ field instance its sequence number in document order, keyed by
+* the field run's `pmStart`. SEQ counters are per identifier (the field
+* argument, e.g. `Figure`), so `SEQ Figure` and `SEQ Table` count
+* independently. Honours `\r n` (reset to n) and `\c` (repeat current without
+* advancing); every other SEQ advances its counter by one. Independent of
+* pagination, so it runs once per document, not per layout pass.
+*/
+function buildSeqValues(blocks) {
+	const counters = /* @__PURE__ */ new Map();
+	const values = /* @__PURE__ */ new Map();
+	walkBlocks(blocks, counters, values);
+	return values;
+}
+function walkBlocks(blocks, counters, values) {
+	for (const block of blocks) if (block.kind === "paragraph") for (const run of block.runs) {
+		if (run.kind !== "field" || run.pmStart === void 0) continue;
+		const parsed = parseFieldInstruction(run.instruction || run.fieldType);
+		if (parsed.type !== "SEQ") continue;
+		const id = parsed.argument ?? "";
+		const reset = parsed.switches.find((s) => s.switch.toLowerCase() === "r")?.value;
+		const repeat = parsed.switches.some((s) => s.switch.toLowerCase() === "c");
+		let value;
+		if (reset !== void 0) value = Number.parseInt(reset, 10) || 1;
+		else if (repeat) value = counters.get(id) ?? 0;
+		else value = (counters.get(id) ?? 0) + 1;
+		counters.set(id, value);
+		values.set(run.pmStart, value);
+	}
+	else if (block.kind === "table") for (const row of block.rows) for (const cell of row.cells) walkBlocks(cell.blocks, counters, values);
+	else if (block.kind === "textBox") walkBlocks(block.content, counters, values);
+}
+//#endregion
+export { buildSeqValues };

package/dist/fonts/embeddedFontTable.d.ts

@@ -0,0 +1,42 @@
+//#region src/fonts/embeddedFontTable.d.ts
+/**
+ * Parses the embedded-font references out of `word/fontTable.xml`.
+ *
+ * The shared docx model (`@stll/docx-core`) keeps only the embed relationship
+ * ids and drops the `w:fontKey` GUID, which is exactly the value needed to
+ * de-obfuscate the `.odttf` binary. This parser therefore reads the font table
+ * directly and keeps the full embed reference (rel id, key, subsetted flag).
+ *
+ * Structure:
+ * ```xml
+ * <w:fonts>
+ *   <w:font w:name="My Brand Sans">
+ *     <w:embedRegular r:id="rId1" w:fontKey="{GUID}" w:subsetted="true"/>
+ *   </w:font>
+ * </w:fonts>
+ * ```
+ *
+ * Ported from eigenpal/docx-editor (see NOTICE.md).
+ */
+/** A single embedded face referenced from a `w:embed*` element. */
+type EmbeddedFontFaceRef = {
+  /** Relationship id (`r:id`) resolved via `word/_rels/fontTable.xml.rels`. */relId: string; /** Obfuscation key GUID (`w:fontKey`), e.g. `{XXXXXXXX-...}`. */
+  fontKey?: string; /** Whether the embedded face is subsetted (`w:subsetted`). */
+  subsetted?: boolean;
+};
+/** One `<w:font>` entry with whichever of the four embed faces it declares. */
+type EmbeddedFontEntry = {
+  name: string;
+  embedRegular?: EmbeddedFontFaceRef;
+  embedBold?: EmbeddedFontFaceRef;
+  embedItalic?: EmbeddedFontFaceRef;
+  embedBoldItalic?: EmbeddedFontFaceRef;
+};
+/**
+ * Parse `word/fontTable.xml` into the list of font entries that declare at
+ * least one embedded face. Entries with no embeds are still returned (callers
+ * filter), and missing/unparseable input yields an empty list.
+ */
+declare function parseEmbeddedFontTable(fontTableXml: string | null | undefined): EmbeddedFontEntry[];
+//#endregion
+export { EmbeddedFontEntry, EmbeddedFontFaceRef, parseEmbeddedFontTable };

package/dist/fonts/embeddedFontTable.js

@@ -0,0 +1,80 @@
+import { findChild, findChildren, getAttribute, parseXmlDocument } from "../docx/xmlParser.js";
+//#region src/fonts/embeddedFontTable.ts
+/**
+* Parses the embedded-font references out of `word/fontTable.xml`.
+*
+* The shared docx model (`@stll/docx-core`) keeps only the embed relationship
+* ids and drops the `w:fontKey` GUID, which is exactly the value needed to
+* de-obfuscate the `.odttf` binary. This parser therefore reads the font table
+* directly and keeps the full embed reference (rel id, key, subsetted flag).
+*
+* Structure:
+* ```xml
+* <w:fonts>
+*   <w:font w:name="My Brand Sans">
+*     <w:embedRegular r:id="rId1" w:fontKey="{GUID}" w:subsetted="true"/>
+*   </w:font>
+* </w:fonts>
+* ```
+*
+* Ported from eigenpal/docx-editor (see NOTICE.md).
+*/
+/** The four `w:embed*` local names paired with the entry field they populate. */
+const EMBED_ELEMENTS = [
+	{
+		element: "embedRegular",
+		field: "embedRegular"
+	},
+	{
+		element: "embedBold",
+		field: "embedBold"
+	},
+	{
+		element: "embedItalic",
+		field: "embedItalic"
+	},
+	{
+		element: "embedBoldItalic",
+		field: "embedBoldItalic"
+	}
+];
+function parseEmbed(font, localName) {
+	const el = findChild(font, "w", localName);
+	if (!el) return;
+	const relId = getAttribute(el, "r", "id");
+	if (!relId) return;
+	const ref = { relId };
+	const fontKey = getAttribute(el, "w", "fontKey");
+	if (fontKey) ref.fontKey = fontKey;
+	const subsetted = getAttribute(el, "w", "subsetted");
+	if (subsetted === "true" || subsetted === "1") ref.subsetted = true;
+	return ref;
+}
+function parseFontEntry(font) {
+	const name = getAttribute(font, "w", "name");
+	if (!name) return null;
+	const entry = { name };
+	for (const { element, field } of EMBED_ELEMENTS) {
+		const ref = parseEmbed(font, element);
+		if (ref) entry[field] = ref;
+	}
+	return entry;
+}
+/**
+* Parse `word/fontTable.xml` into the list of font entries that declare at
+* least one embedded face. Entries with no embeds are still returned (callers
+* filter), and missing/unparseable input yields an empty list.
+*/
+function parseEmbeddedFontTable(fontTableXml) {
+	if (!fontTableXml || fontTableXml.trim().length === 0) return [];
+	const root = parseXmlDocument(fontTableXml);
+	if (!root) return [];
+	const entries = [];
+	for (const font of findChildren(root, "w", "font")) {
+		const entry = parseFontEntry(font);
+		if (entry) entries.push(entry);
+	}
+	return entries;
+}
+//#endregion
+export { parseEmbeddedFontTable };

package/dist/fonts/embeddedFonts.d.ts

@@ -0,0 +1,46 @@
+//#region src/fonts/embeddedFonts.d.ts
+/**
+ * Embedded-font extraction.
+ *
+ * Turns the obfuscated `word/fonts/*.odttf` binaries a `.docx` carries into
+ * de-obfuscated OpenType/TrueType faces the renderer can register as
+ * `@font-face`s, so documents whose fonts are embedded (rather than installed)
+ * render in their authored fonts instead of a fallback.
+ *
+ * The core is pure and framework-free: {@link getEmbeddedFontFaces} works over
+ * already-unzipped package parts; {@link extractEmbeddedFonts} is the buffer
+ * convenience that unzips first. Neither touches the DOM. Round-trip
+ * preservation is unaffected: the serializer copies `word/fonts/*` and
+ * `fontTable.xml` from the original ZIP untouched, so this is a read-only view.
+ *
+ * Ported from eigenpal/docx-editor (see NOTICE.md).
+ */
+/** A single de-obfuscated embedded font face, ready to register as `@font-face`. */
+type EmbeddedFont = {
+  /** Word font name to register the face under (`w:font w:name`). */family: string; /** CSS `font-style` the face maps to (`embed*Italic` → `italic`). */
+  style: "normal" | "italic"; /** CSS `font-weight` the face maps to (`embedBold*` → `700`). */
+  weight: 400 | 700; /** De-obfuscated OpenType/TrueType bytes (backed by a fresh, non-shared buffer). */
+  bytes: Uint8Array<ArrayBuffer>; /** Whether the source face was subsetted (`w:subsetted`). */
+  subsetted: boolean;
+};
+/** Already-unzipped package parts the pure extractor needs. */
+type EmbeddedFontParts = {
+  /** Raw `word/fontTable.xml`. */fontTableXml: string | null | undefined; /** Raw `word/_rels/fontTable.xml.rels`. */
+  fontTableRelsXml: string | null | undefined; /** Unzipped font binaries keyed by package path (e.g. `word/fonts/font1.odttf`). */
+  fonts: ReadonlyMap<string, ArrayBuffer>;
+};
+/**
+ * Resolve and de-obfuscate every embedded font face declared in a font table.
+ * Pure and DOM-free. Faces whose relationship or binary is missing are skipped,
+ * so the result only contains faces that produced usable bytes.
+ */
+declare function getEmbeddedFontFaces(parts: EmbeddedFontParts): EmbeddedFont[];
+/**
+ * Extract every embedded font face from a raw `.docx` buffer. Unzips the
+ * package, then resolves + de-obfuscates the faces via
+ * {@link getEmbeddedFontFaces}. Returns an empty list for documents with no
+ * embedded fonts.
+ */
+declare function extractEmbeddedFonts(buffer: ArrayBuffer): Promise<EmbeddedFont[]>;
+//#endregion
+export { EmbeddedFont, EmbeddedFontParts, extractEmbeddedFonts, getEmbeddedFontFaces };