@stll/folio-core 0.1.1 → 0.1.3

package/dist/docx/headerFooterParser.js

@@ -1,6 +1,7 @@
 import { collectXmlnsDeclarations, parseXml } from "./xmlParser.js";
 import { parseWatermark } from "./watermarkParser.js";
 import { parseFooterReference, parseFooterReferences, parseHeaderReference, parseHeaderReferences } from "./headerFooterRefParser.js";
+import { assignHeaderFooterVerbatimXml } from "./headerFooterVerbatim.js";
 import { parseBlockContent } from "./blockContentParser.js";
 //#region src/docx/headerFooterParser.ts
 /**
@@ -34,6 +35,7 @@ function parseHeader(headerXml, hdrFtrType = "default", styles = null, theme = n
 		inHeaderFooter: true,
 		rootXmlns: collectXmlnsDeclarations(rootElement)
 	});
+	assignHeaderFooterVerbatimXml(result, headerXml);
 	return result;
 }
 /**
@@ -74,6 +76,7 @@ function parseFooter(footerXml, hdrFtrType = "default", styles = null, theme = n
 		inHeaderFooter: true,
 		rootXmlns: collectXmlnsDeclarations(rootElement)
 	});
+	assignHeaderFooterVerbatimXml(result, footerXml);
 	return result;
 }
 /**

package/dist/docx/headerFooterVerbatim.d.ts

@@ -0,0 +1,19 @@
+import { document_d_exports } from "../types/document.js";
+
+//#region src/docx/headerFooterVerbatim.d.ts
+/**
+ * Folio extension on {@link HeaderFooter}: original part XML captured at parse
+ * time so unedited headers/footers re-emit byte-identically on save (VML OLE
+ * wrappers, smart tags, and other constructs the model cannot fully represent).
+ * Cleared on first edit.
+ */
+type HeaderFooterWithVerbatim = document_d_exports.HeaderFooter & {
+  verbatimXml?: string; /** Fingerprint of modeled fields at parse time; verbatim replay is safe only while it matches. */
+  verbatimFingerprint?: string;
+};
+declare const getHeaderFooterVerbatimXml: (hf: document_d_exports.HeaderFooter) => string | undefined;
+declare const canReplayHeaderFooterVerbatim: (hf: document_d_exports.HeaderFooter) => boolean;
+declare const assignHeaderFooterVerbatimXml: (hf: document_d_exports.HeaderFooter, xml: string) => void;
+declare const clearHeaderFooterVerbatimXml: (hf: document_d_exports.HeaderFooter) => void;
+//#endregion
+export { HeaderFooterWithVerbatim, assignHeaderFooterVerbatimXml, canReplayHeaderFooterVerbatim, clearHeaderFooterVerbatimXml, getHeaderFooterVerbatimXml };

package/dist/docx/headerFooterVerbatim.js

@@ -0,0 +1,25 @@
+//#region src/docx/headerFooterVerbatim.ts
+const headerFooterSerializationFingerprint = (hf) => JSON.stringify({
+	content: hf.content,
+	watermark: hf.watermark,
+	watermarkBlockIndex: hf.watermarkBlockIndex,
+	rawWatermarkXml: hf.rawWatermarkXml
+});
+const getHeaderFooterVerbatimXml = (hf) => hf.verbatimXml;
+const canReplayHeaderFooterVerbatim = (hf) => {
+	const ext = hf;
+	if (!ext.verbatimXml || !ext.verbatimFingerprint) return false;
+	return ext.verbatimFingerprint === headerFooterSerializationFingerprint(hf);
+};
+const assignHeaderFooterVerbatimXml = (hf, xml) => {
+	const ext = hf;
+	ext.verbatimXml = xml;
+	ext.verbatimFingerprint = headerFooterSerializationFingerprint(hf);
+};
+const clearHeaderFooterVerbatimXml = (hf) => {
+	const ext = hf;
+	delete ext.verbatimXml;
+	delete ext.verbatimFingerprint;
+};
+//#endregion
+export { assignHeaderFooterVerbatimXml, canReplayHeaderFooterVerbatim, clearHeaderFooterVerbatimXml, getHeaderFooterVerbatimXml };

package/dist/docx/metafileRaster.d.ts

@@ -0,0 +1,30 @@
+//#region src/docx/metafileRaster.d.ts
+/**
+ * Extract a browser-renderable raster (PNG/JPEG) embedded inside an
+ * EMF/WMF metafile.
+ *
+ * Word frequently stores header logos / OLE preview pictures as EMF — a
+ * Windows GDI metafile browsers cannot decode. In practice such an EMF almost
+ * always carries the actual artwork as a single embedded PNG or JPEG (an
+ * `EmfPlusObject` bitmap record, or a `StretchDIBits` payload). Rather than
+ * implement a GDI renderer, this scans the byte stream for a raster signature,
+ * brackets it to its container's end marker, and returns the slice. The caller
+ * uses it as the media entry's `dataUrl` so `<img>` just works; the original
+ * EMF bytes stay on `MediaFile.data` for round-trip.
+ *
+ * When no embedded raster is found this returns `null`; callers fall back to a
+ * sized placeholder and/or the host-supplied `mediaResolver` hook.
+ */
+type ExtractedRaster = {
+  bytes: Uint8Array;
+  mimeType: "image/png" | "image/jpeg";
+};
+/**
+ * Scan a metafile (EMF or WMF) for an embedded browser-renderable raster.
+ * Returns the first PNG, else first JPEG found; `null` when none is present.
+ */
+declare function extractMetafileRaster(data: ArrayBuffer | Uint8Array): ExtractedRaster | null;
+/** True for EMF/WMF MIME types — the formats browsers cannot render natively. */
+declare function isMetafileMimeType(mimeType: string | undefined): boolean;
+//#endregion
+export { ExtractedRaster, extractMetafileRaster, isMetafileMimeType };

package/dist/docx/metafileRaster.js

@@ -0,0 +1,80 @@
+//#region src/docx/metafileRaster.ts
+function indexOfBytes(haystack, needle, from = 0) {
+	outer: for (let i = from; i + needle.length <= haystack.length; i++) {
+		for (let j = 0; j < needle.length; j++) if (haystack[i + j] !== needle[j]) continue outer;
+		return i;
+	}
+	return -1;
+}
+function extractPng(bytes) {
+	const start = indexOfBytes(bytes, [
+		137,
+		80,
+		78,
+		71,
+		13,
+		10,
+		26,
+		10
+	]);
+	if (start < 0) return null;
+	let off = start + 8;
+	while (off + 12 <= bytes.length) {
+		const b0 = bytes[off];
+		const b1 = bytes[off + 1];
+		const b2 = bytes[off + 2];
+		const b3 = bytes[off + 3];
+		const len = b0 << 24 | b1 << 16 | b2 << 8 | b3;
+		const type = String.fromCharCode(bytes[off + 4], bytes[off + 5], bytes[off + 6], bytes[off + 7]);
+		const next = off + 12 + (len >>> 0);
+		if (type === "IEND") return bytes.slice(start, off + 12);
+		if (next <= off || next > bytes.length) break;
+		off = next;
+	}
+	return null;
+}
+function extractJpeg(bytes) {
+	const start = indexOfBytes(bytes, [
+		255,
+		216,
+		255
+	]);
+	if (start < 0) return null;
+	let end = -1;
+	for (let i = bytes.length - 2; i > start + 1; i--) if (bytes[i] === 255 && bytes[i + 1] === 217) {
+		end = i + 2;
+		break;
+	}
+	return end > start ? bytes.slice(start, end) : null;
+}
+/**
+* Scan a metafile (EMF or WMF) for an embedded browser-renderable raster.
+* Returns the first PNG, else first JPEG found; `null` when none is present.
+*/
+function extractMetafileRaster(data) {
+	const bytes = data instanceof Uint8Array ? data : new Uint8Array(data);
+	if (bytes.length < 32) return null;
+	const png = extractPng(bytes);
+	if (png) return {
+		bytes: png,
+		mimeType: "image/png"
+	};
+	const jpeg = extractJpeg(bytes);
+	if (jpeg) return {
+		bytes: jpeg,
+		mimeType: "image/jpeg"
+	};
+	return null;
+}
+const METAFILE_MIME = /* @__PURE__ */ new Set([
+	"image/x-emf",
+	"image/emf",
+	"image/x-wmf",
+	"image/wmf"
+]);
+/** True for EMF/WMF MIME types — the formats browsers cannot render natively. */
+function isMetafileMimeType(mimeType) {
+	return !!mimeType && METAFILE_MIME.has(mimeType);
+}
+//#endregion
+export { extractMetafileRaster, isMetafileMimeType };

package/dist/docx/paragraphParser.js

@@ -815,7 +815,11 @@ function parseParagraphContents(paraElement, styles, theme, _numbering, rels, me
 					parsedContent: parseParagraphContents(child, styles, theme, null, rels, media, "default", inScopeXmlns)
 				});
 				break;
-			case "smartTag": break;
+			case "smartTag": {
+				const inner = parseParagraphContents(child, styles, theme, null, rels, media, trackedContext, mergeXmlnsDeclarations(inScopeXmlns, child));
+				contents.push(...inner);
+				break;
+			}
 			case "moveFromRangeStart": {
 				const id = Number.parseInt(getAttribute(child, "w", "id") ?? "0", 10);
 				const name = getAttribute(child, "w", "name") ?? "";

package/dist/docx/parser.d.ts

@@ -7,6 +7,15 @@ import { DocxUnzipLimits } from "./unzip.js";
  * Progress callback for tracking parsing stages
  */
 type ProgressCallback = (stage: string, percent: number) => void;
+/**
+ * Host hook for converting media the browser cannot render natively
+ * (EMF/WMF/TIFF) into a displayable `data:` or `blob:` URL. Receives the
+ * parsed {@link MediaFile} (original bytes on `.data`); return the replacement
+ * URL, or `null`/`undefined` to keep the built-in handling. Built-in handling
+ * already extracts an embedded PNG/JPEG from EMF/WMF when one exists; this
+ * hook is for vector-only metafiles where the host rasterizes server-side.
+ */
+type MediaResolver = (file: document_d_exports.MediaFile) => Promise<string | null | undefined>;
 /**
  * Parsing options
  */
@@ -18,7 +27,8 @@ type ParseOptions = {
   detectVariables?: boolean; /** Security limits for DOCX ZIP extraction */
   unzipLimits?: Partial<Omit<DocxUnzipLimits, "allowedMediaMimeTypes">> & {
     allowedMediaMimeTypes?: Iterable<string>;
-  };
+  }; /** Optional async hook to override display URLs for non-browser media. */
+  mediaResolver?: MediaResolver;
 };
 /**
  * Parse a DOCX file into a complete Document model
@@ -64,4 +74,4 @@ declare function getDocxSummary(buffer: ArrayBuffer): Promise<{
   variableCount: number;
 }>;
 //#endregion
-export { DocxParseError, ParseOptions, ProgressCallback, fullParseDocx, getDocxSummary, getDocxVariables, parseDocx, quickParseDocx };
+export { DocxParseError, MediaResolver, ParseOptions, ProgressCallback, fullParseDocx, getDocxSummary, getDocxVariables, parseDocx, quickParseDocx };

package/dist/docx/parser.js

@@ -12,6 +12,7 @@ import { normalizeCommentReferences } from "./commentReferenceNormalization.js";
 import { extractAllTemplateVariables, parseDocumentBody } from "./documentParser.js";
 import { parseFooter, parseHeader } from "./headerFooterParser.js";
 import { normalizeHeaderFooterReferences } from "./headerFooterReferenceNormalization.js";
+import { extractMetafileRaster, isMetafileMimeType } from "./metafileRaster.js";
 import { normalizeNumberingReferences } from "./numberingReferenceNormalization.js";
 import { parseSettings } from "./settingsParser.js";
 import { parseStylesPackage } from "./styleParser.js";
@@ -47,7 +48,7 @@ import { TaggedError } from "better-result";
 */
 async function parseDocx(input, options = {}) {
 	const buffer = input instanceof ArrayBuffer ? input : await toArrayBuffer(input);
-	const { onProgress = () => {}, preloadFonts = true, parseHeadersFooters = true, parseNotes = true, detectVariables = true, unzipLimits } = options;
+	const { onProgress = () => {}, preloadFonts = true, parseHeadersFooters = true, parseNotes = true, detectVariables = true, unzipLimits, mediaResolver } = options;
 	const warnings = [];
 	try {
 		const timeStage = (_name, fn) => fn();
@@ -80,6 +81,7 @@ async function parseDocx(input, options = {}) {
 		onProgress("Parsed numbering", 35);
 		onProgress("Processing media files...", 35);
 		const media = await timeStageAsync("media", () => buildMediaMap(raw, rels));
+		if (mediaResolver) await timeStageAsync("mediaResolver", () => applyMediaResolver(media, mediaResolver));
 		onProgress("Processed media", 40);
 		onProgress("Parsing document body...", 40);
 		let documentBody = { content: [] };
@@ -196,6 +198,11 @@ var DocxParseError = class extends TaggedError("DocxParseError")() {};
 /**
 * Build media file map from raw content and relationships
 */
+function copyBytesToArrayBuffer(bytes) {
+	const buffer = new ArrayBuffer(bytes.byteLength);
+	new Uint8Array(buffer).set(bytes);
+	return buffer;
+}
 async function buildMediaMap(raw, _rels) {
 	const media = /* @__PURE__ */ new Map();
 	for (const [path, data] of raw.media.entries()) {
@@ -217,6 +224,20 @@ async function buildMediaMap(raw, _rels) {
 				continue;
 			}
 		}
+		const raster = isMetafileMimeType(mimeType) ? extractMetafileRaster(data) : null;
+		if (raster) {
+			const mediaFile = {
+				path,
+				filename,
+				mimeType,
+				data,
+				dataUrl: mediaToDataUrl(copyBytesToArrayBuffer(raster.bytes), raster.mimeType)
+			};
+			media.set(path, mediaFile);
+			const normalizedPath = path.replace(/^word\//u, "");
+			if (normalizedPath !== path) media.set(normalizedPath, mediaFile);
+			continue;
+		}
 		const mediaFile = {
 			path,
 			filename,
@@ -230,6 +251,15 @@ async function buildMediaMap(raw, _rels) {
 	}
 	return media;
 }
+async function applyMediaResolver(media, resolver) {
+	const files = [...new Set(media.values())];
+	await Promise.all(files.map(async (file) => {
+		try {
+			const url = await resolver(file);
+			if (url) file.dataUrl = url;
+		} catch {}
+	}));
+}
 function attachLazyDataUrl(mediaFile) {
 	let cachedDataUrl;
 	Object.defineProperty(mediaFile, "dataUrl", {

package/dist/docx/serializer/headerFooterSerializer.js

@@ -2,6 +2,7 @@ import { escapeXml } from "./xmlUtils.js";
 import { serializeBlockSdt } from "./blockSdtSerializer.js";
 import { serializeParagraph } from "./paragraphSerializer.js";
 import { serializeTable } from "./tableSerializer.js";
+import { canReplayHeaderFooterVerbatim, getHeaderFooterVerbatimXml } from "../headerFooterVerbatim.js";
 //#region src/docx/serializer/headerFooterSerializer.ts
 const NAMESPACES = {
 	wpc: "http://schemas.microsoft.com/office/word/2010/wordprocessingCanvas",
@@ -45,6 +46,8 @@ function serializeBlock(block) {
 * @returns Complete XML string for header*.xml or footer*.xml
 */
 function serializeHeaderFooter(hf) {
+	const verbatim = getHeaderFooterVerbatimXml(hf);
+	if (verbatim && canReplayHeaderFooterVerbatim(hf)) return verbatim;
 	const rootTag = hf.type === "header" ? "w:hdr" : "w:ftr";
 	const nsDecl = buildNamespaceDeclarations();
 	const watermarkXml = serializeWatermarkParagraph(hf);

package/dist/docx/styleParser.js

@@ -1,4 +1,4 @@
-import { findChild, findChildren, getAttribute, getLocalName, parseBooleanElement, parseNumericAttribute, parseXmlDocument } from "./xmlParser.js";
+import { findChild, findChildren, getAttribute, getLocalName, parseBooleanElement, parseNumericAttribute, parseTableMeasurementValue, parseXmlDocument } from "./xmlParser.js";
 import { BorderStyleSchema, ConditionalStyleTypeSchema, EmphasisMarkSchema, FontThemeSchema, HighlightColorSchema, LineSpacingRuleSchema, ParagraphAlignmentSchema, ShadingPatternSchema, StyleTypeSchema, TabLeaderSchema, TabStopAlignmentSchema, TableCellTextDirectionSchema, TableRowHeightRuleSchema, TableWidthTypeSchema, TextEffectSchema, ThemeColorSlotSchema, UnderlineStyleSchema, narrowEnum } from "./parserEnums.js";
 import { resolveThemeFontRef } from "./themeParser.js";
 import { mergeTextFormatting } from "../utils/textFormattingMerge.js";
@@ -360,9 +360,9 @@ function parseParagraphProperties(pPr, theme) {
 */
 function parseTableMeasurement(element) {
 	if (!element) return;
-	const w = parseNumericAttribute(element, "w", "w");
 	const rawType = getAttribute(element, "w", "type");
 	const type = rawType === null ? "dxa" : narrowEnum(rawType, TableWidthTypeSchema);
+	const w = type ? parseTableMeasurementValue(element, type) : void 0;
 	if (w !== void 0 && type) return {
 		value: w,
 		type

package/dist/docx/tableParser.js

@@ -1,4 +1,4 @@
-import { findChild, findChildByLocalName, findChildren, getAttribute, getChildElements, mergeXmlnsDeclarations, parseBooleanElement, parseNumericAttribute } from "./xmlParser.js";
+import { findChild, findChildByLocalName, findChildren, getAttribute, getChildElements, mergeXmlnsDeclarations, parseBooleanElement, parseNumericAttribute, parseTableMeasurementValue } from "./xmlParser.js";
 import { parseBookmarkEnd, parseBookmarkStart } from "./bookmarkParser.js";
 import { BorderStyleSchema, FloatingTableXSpecSchema, FloatingTableYSpecSchema, ShadingPatternSchema, TableCellTextDirectionSchema, ThemeColorSlotSchema, narrowEnum } from "./parserEnums.js";
 import { parseParagraph } from "./paragraphParser.js";
@@ -12,12 +12,11 @@ import { appendBookmarkMarkerToLastParagraphInBlocks, appendBookmarkMarkerToLast
 */
 function parseTableMeasurement(element) {
 	if (!element) return;
-	const value = parseNumericAttribute(element, "w", "w") ?? 0;
 	const typeStr = getAttribute(element, "w", "type") ?? "dxa";
 	let type = "dxa";
 	if (typeStr === "auto" || typeStr === "dxa" || typeStr === "nil" || typeStr === "pct") type = typeStr;
 	return {
-		value,
+		value: parseTableMeasurementValue(element, type) ?? 0,
 		type
 	};
 }

package/dist/docx/unzip.js

@@ -37,7 +37,9 @@ const DEFAULT_ALLOWED_MEDIA_MIME_TYPES = /* @__PURE__ */ new Set([
 	"image/gif",
 	"image/bmp",
 	"image/tiff",
-	"image/webp"
+	"image/webp",
+	"image/x-emf",
+	"image/x-wmf"
 ]);
 const PRESERVABLE_MEDIA_MIME_TYPES = /* @__PURE__ */ new Set([
 	...DEFAULT_ALLOWED_MEDIA_MIME_TYPES,
@@ -279,6 +281,10 @@ function isMediaContentAllowed(data, mimeType) {
 		case "image/bmp": return bytes[0] === 66 && bytes[1] === 77;
 		case "image/webp": return bytes[0] === 82 && bytes[1] === 73 && bytes[2] === 70 && bytes[3] === 70 && bytes[8] === 87 && bytes[9] === 69 && bytes[10] === 66 && bytes[11] === 80;
 		case "image/tiff": return bytes[0] === 73 && bytes[1] === 73 || bytes[0] === 77 && bytes[1] === 77;
+		case "image/x-emf":
+		case "image/emf": return bytes.length >= 44 && bytes[0] === 1 && bytes[40] === 32 && bytes[41] === 69 && bytes[42] === 77 && bytes[43] === 70;
+		case "image/x-wmf":
+		case "image/wmf": return bytes.length >= 4 && (bytes[0] === 215 && bytes[1] === 205 && bytes[2] === 198 && bytes[3] === 154 || (bytes[0] === 1 || bytes[0] === 2) && bytes[1] === 0 && bytes[2] === 9 && bytes[3] === 0);
 		default: return false;
 	}
 }

package/dist/docx/xmlParser.d.ts

@@ -237,6 +237,12 @@ declare function parseColorElement(element: XmlElement | null | undefined): {
  * @returns Parsed number or undefined
  */
 declare function parseNumericAttribute(element: XmlElement | null | undefined, namespace: string | null, name: string, scale?: number): number | undefined;
+/**
+ * Parse `w:w` on a table width/height element. For `w:type="pct"`, producers
+ * sometimes emit human-readable percentages (`100%`) instead of 50ths-of-percent
+ * (`5000`); normalize those to the ECMA-376 unit the layout engine expects.
+ */
+declare function parseTableMeasurementValue(element: XmlElement | null | undefined, widthType: string): number | undefined;
 /**
  * Parse a boolean value from an attribute or element presence
  *
@@ -294,4 +300,4 @@ declare function mergeXmlnsDeclarations(inherited: Record<string, string>, eleme
  */
 declare function cloneWithXmlnsDeclarations(element: XmlElement, xmlnsDecls: Record<string, string>): XmlElement;
 //#endregion
-export { NAMESPACES, XmlElement, cloneWithXmlnsDeclarations, collectXmlnsDeclarations, elementToXml, findAllDeep, findByFullName, findChild, findChildByLocalName, findChildren, findChildrenByLocalName, findDeep, getAttribute, getAttributeAny, getAttributeAnyPrefix, getAttributes, getChildElements, getLocalName, getNamespacePrefix, getTextContent, hasChild, hasFlag, matchesName, mergeXmlnsDeclarations, parseBooleanElement, parseColorElement, parseNumericAttribute, parseXml, parseXmlDocument };
+export { NAMESPACES, XmlElement, cloneWithXmlnsDeclarations, collectXmlnsDeclarations, elementToXml, findAllDeep, findByFullName, findChild, findChildByLocalName, findChildren, findChildrenByLocalName, findDeep, getAttribute, getAttributeAny, getAttributeAnyPrefix, getAttributes, getChildElements, getLocalName, getNamespacePrefix, getTextContent, hasChild, hasFlag, matchesName, mergeXmlnsDeclarations, parseBooleanElement, parseColorElement, parseNumericAttribute, parseTableMeasurementValue, parseXml, parseXmlDocument };

package/dist/docx/xmlParser.js

@@ -409,6 +409,22 @@ function parseNumericAttribute(element, namespace, name, scale = 1) {
 	return num * scale;
 }
 /**
+* Parse `w:w` on a table width/height element. For `w:type="pct"`, producers
+* sometimes emit human-readable percentages (`100%`) instead of 50ths-of-percent
+* (`5000`); normalize those to the ECMA-376 unit the layout engine expects.
+*/
+function parseTableMeasurementValue(element, widthType) {
+	const raw = getAttribute(element, "w", "w");
+	if (raw === null) return;
+	const trimmed = raw.trim();
+	if (widthType === "pct" && trimmed.endsWith("%")) {
+		const pct = Number.parseFloat(trimmed.slice(0, -1));
+		if (!Number.isNaN(pct)) return Math.round(pct * 50);
+	}
+	const num = Number.parseInt(trimmed, 10);
+	return Number.isNaN(num) ? void 0 : num;
+}
+/**
 * Parse a boolean value from an attribute or element presence
 *
 * OOXML boolean conventions:
@@ -524,4 +540,4 @@ function cloneWithXmlnsDeclarations(element, xmlnsDecls) {
 	};
 }
 //#endregion
-export { NAMESPACES, cloneWithXmlnsDeclarations, collectXmlnsDeclarations, elementToXml, findAllDeep, findByFullName, findChild, findChildByLocalName, findChildren, findChildrenByLocalName, findDeep, getAttribute, getAttributeAny, getAttributeAnyPrefix, getAttributes, getChildElements, getLocalName, getNamespacePrefix, getTextContent, hasChild, hasFlag, matchesName, mergeXmlnsDeclarations, parseBooleanElement, parseColorElement, parseNumericAttribute, parseXml, parseXmlDocument };
+export { NAMESPACES, cloneWithXmlnsDeclarations, collectXmlnsDeclarations, elementToXml, findAllDeep, findByFullName, findChild, findChildByLocalName, findChildren, findChildrenByLocalName, findDeep, getAttribute, getAttributeAny, getAttributeAnyPrefix, getAttributes, getChildElements, getLocalName, getNamespacePrefix, getTextContent, hasChild, hasFlag, matchesName, mergeXmlnsDeclarations, parseBooleanElement, parseColorElement, parseNumericAttribute, parseTableMeasurementValue, parseXml, parseXmlDocument };

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

@@ -1,5 +1,5 @@
 import { document_d_exports } from "../../types/document.js";
-import { FlowBlock, HeaderFooterContent, ImageRun, Measure, PageMargins } from "../../layout-engine/types.js";
+import { FlowBlock, HeaderFooterContent, ImageRun, ImageRunPosition, Measure, PageMargins } from "../../layout-engine/types.js";
 import { MeasureBlocksFn } from "./footnoteLayout.js";
 import { Node } from "prosemirror-model";
 
@@ -13,6 +13,7 @@ type HeaderFooterMetrics = {
   margins: PageMargins;
 };
 declare function normalizeHeaderFooterMeasureBlocks(blocks: FlowBlock[]): FlowBlock[];
+declare function resolveHeaderFooterPositionedVisualTop(position: ImageRunPosition | undefined, elementHeight: number, sourceY: number, flowHeight: number, metrics: HeaderFooterMetrics): number;
 declare function resolveHeaderFooterVisualTop(run: ImageRun, paragraphY: number, flowHeight: number, metrics: HeaderFooterMetrics): number;
 declare function calculateHeaderFooterVisualBounds(blocks: FlowBlock[], measures: Measure[], flowHeight: number, metrics: HeaderFooterMetrics): {
   visualTop: number;
@@ -71,4 +72,4 @@ declare function convertHeaderFooterToContent(headerFooter: document_d_exports.H
  */
 declare function convertHeaderFooterPmDocToContent(pmDoc: Node | null | undefined, contentWidth: number, metrics: HeaderFooterMetrics, options: Omit<ConvertHeaderFooterOptions, "styles">): HeaderFooterContent | undefined;
 //#endregion
-export { ConvertHeaderFooterOptions, HeaderFooterMetrics, calculateHeaderFooterMarginPushBounds, calculateHeaderFooterVisualBounds, convertHeaderFooterPmDocToContent, convertHeaderFooterToContent, normalizeHeaderFooterMeasureBlocks, resolveHeaderFooterVisualTop };
+export { ConvertHeaderFooterOptions, HeaderFooterMetrics, calculateHeaderFooterMarginPushBounds, calculateHeaderFooterVisualBounds, convertHeaderFooterPmDocToContent, convertHeaderFooterToContent, normalizeHeaderFooterMeasureBlocks, resolveHeaderFooterPositionedVisualTop, resolveHeaderFooterVisualTop };

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

@@ -98,28 +98,43 @@ function normalizeTableBlock(block) {
 function getPositionAlignment(axis) {
 	return axis?.align ?? axis?.alignment;
 }
-function resolveHeaderFooterVisualTop(run, paragraphY, flowHeight, metrics) {
+function resolveHeaderFooterPositionedVisualTop(position, elementHeight, sourceY, flowHeight, metrics) {
 	const flowTop = metrics.section === "header" ? metrics.margins.header ?? 48 : metrics.pageSize.h - (metrics.margins.footer ?? 48) - flowHeight;
-	const vertical = run.position?.vertical;
-	if (!vertical) return paragraphY;
+	const vertical = position?.vertical;
+	if (!vertical) return sourceY;
 	const align = getPositionAlignment(vertical);
 	const offsetPx = vertical.posOffset !== void 0 ? emuToPixels(vertical.posOffset) : void 0;
 	if (vertical.relativeTo === "page") {
 		if (offsetPx !== void 0) return offsetPx - flowTop;
 		if (align === "top") return -flowTop;
-		if (align === "bottom") return metrics.pageSize.h - run.height - flowTop;
-		if (align === "center") return (metrics.pageSize.h - run.height) / 2 - flowTop;
+		if (align === "bottom") return metrics.pageSize.h - elementHeight - flowTop;
+		if (align === "center") return (metrics.pageSize.h - elementHeight) / 2 - flowTop;
 	}
 	if (vertical.relativeTo === "margin") {
 		const marginTop = metrics.margins.top;
 		const marginHeight = metrics.pageSize.h - metrics.margins.top - metrics.margins.bottom;
 		if (offsetPx !== void 0) return marginTop + offsetPx - flowTop;
 		if (align === "top") return marginTop - flowTop;
-		if (align === "bottom") return marginTop + marginHeight - run.height - flowTop;
-		if (align === "center") return marginTop + (marginHeight - run.height) / 2 - flowTop;
+		if (align === "bottom") return marginTop + marginHeight - elementHeight - flowTop;
+		if (align === "center") return marginTop + (marginHeight - elementHeight) / 2 - flowTop;
 	}
-	if (offsetPx !== void 0) return paragraphY + offsetPx;
-	return paragraphY;
+	if (offsetPx !== void 0) return sourceY + offsetPx;
+	return sourceY;
+}
+function resolveHeaderFooterVisualTop(run, paragraphY, flowHeight, metrics) {
+	return resolveHeaderFooterPositionedVisualTop(run.position, run.height, paragraphY, flowHeight, metrics);
+}
+function pageBandInHeaderFooterCoords(metrics, flowHeight) {
+	const flowTop = metrics.section === "header" ? metrics.margins.header ?? 48 : metrics.pageSize.h - (metrics.margins.footer ?? 48) - flowHeight;
+	return {
+		top: -flowTop,
+		bottom: metrics.pageSize.h - flowTop
+	};
+}
+/** True when a float's box overlaps the page band in header/footer coordinates. */
+function floatIntersectsPageBand(blockTop, blockBottom, metrics, flowHeight) {
+	const band = pageBandInHeaderFooterCoords(metrics, flowHeight);
+	return blockBottom > band.top && blockTop < band.bottom;
 }
 function resolveHeaderFooterFloatingTableVisualTop(floating, measure, sourceY, flowHeight, metrics) {
 	const flowTop = metrics.section === "header" ? metrics.margins.header ?? 48 : metrics.pageSize.h - (metrics.margins.footer ?? 48) - flowHeight;
@@ -156,8 +171,10 @@ function calculateHeaderFooterVisualBounds(blocks, measures, flowHeight, metrics
 				if (run.kind !== "image") continue;
 				if (!run.position && !isFloatingImageRun(run)) continue;
 				const runTop = resolveHeaderFooterVisualTop(run, paragraphStartY, flowHeight, metrics);
+				const runBottom = runTop + run.height;
+				if (!floatIntersectsPageBand(runTop, runBottom, metrics, flowHeight)) continue;
 				visualTop = Math.min(visualTop, runTop);
-				visualBottom = Math.max(visualBottom, runTop + run.height);
+				visualBottom = Math.max(visualBottom, runBottom);
 			}
 			cursorY = paragraphBottomY;
 		} else {
@@ -178,11 +195,18 @@ function calculateHeaderFooterVisualBounds(blocks, measures, flowHeight, metrics
 				cursorY = blockBottomY;
 			} else if (block.kind === "table" && block.floating && measure.kind === "table") {
 				const blockTop = resolveHeaderFooterFloatingTableVisualTop(block.floating, measure, cursorY, flowHeight, metrics);
-				visualTop = Math.min(visualTop, blockTop);
-				visualBottom = Math.max(visualBottom, blockTop + blockHeight);
+				const blockBottom = blockTop + blockHeight;
+				if (floatIntersectsPageBand(blockTop, blockBottom, metrics, flowHeight)) {
+					visualTop = Math.min(visualTop, blockTop);
+					visualBottom = Math.max(visualBottom, blockBottom);
+				}
 			} else if (block.kind === "textBox" && isPositionedHeaderFooterTextBoxBlock(block) && measure.kind === "textBox") {
-				visualTop = Math.min(visualTop, cursorY);
-				visualBottom = Math.max(visualBottom, cursorY + measure.height);
+				const blockTop = resolveHeaderFooterPositionedVisualTop(block.position, measure.height, cursorY, flowHeight, metrics);
+				const blockBottom = blockTop + measure.height;
+				if (floatIntersectsPageBand(blockTop, blockBottom, metrics, flowHeight)) {
+					visualTop = Math.min(visualTop, blockTop);
+					visualBottom = Math.max(visualBottom, blockBottom);
+				}
 			}
 		}
 	}
@@ -429,4 +453,4 @@ function serializeRunFmt(run) {
 	return JSON.stringify(out);
 }
 //#endregion
-export { calculateHeaderFooterMarginPushBounds, calculateHeaderFooterVisualBounds, convertHeaderFooterPmDocToContent, convertHeaderFooterToContent, normalizeHeaderFooterMeasureBlocks, resolveHeaderFooterVisualTop };
+export { calculateHeaderFooterMarginPushBounds, calculateHeaderFooterVisualBounds, convertHeaderFooterPmDocToContent, convertHeaderFooterToContent, normalizeHeaderFooterMeasureBlocks, resolveHeaderFooterPositionedVisualTop, resolveHeaderFooterVisualTop };

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

@@ -814,6 +814,7 @@ function convertParagraph(node, startPos, options) {
 		id: nextBlockId(),
 		runs,
 		attrs,
+		...pmAttrs.paraId ? { paraId: pmAttrs.paraId } : {},
 		...bookmarkNames && bookmarkNames.length > 0 ? { bookmarks: bookmarkNames } : {},
 		pmStart: startPos,
 		pmEnd: startPos + node.nodeSize

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

@@ -0,0 +1,10 @@
+//#region src/layout-engine/measure/lineBreaks.d.ts
+/**
+ * Indices in `text` where a line may end. Latin text breaks after
+ * whitespace or hyphen; CJK text can break after every ideograph so a
+ * partial line is filled instead of pushing the whole run to the next line.
+ */
+declare function findWordBreaks(text: string): number[];
+declare function isBreakChar(char: string | undefined): boolean;
+//#endregion
+export { findWordBreaks, isBreakChar };

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

@@ -0,0 +1,30 @@
+import { isCjkCodePoint } from "../../utils/scriptSegments.js";
+//#region src/layout-engine/measure/lineBreaks.ts
+/**
+* Indices in `text` where a line may end. Latin text breaks after
+* whitespace or hyphen; CJK text can break after every ideograph so a
+* partial line is filled instead of pushing the whole run to the next line.
+*/
+function findWordBreaks(text) {
+	const breaks = [];
+	for (let index = 0; index < text.length;) {
+		const codePoint = text.codePointAt(index);
+		if (codePoint === void 0) break;
+		const charLength = codePoint > 65535 ? 2 : 1;
+		const char = text[index];
+		if (char === " " || char === "-" || char === "	") breaks.push(index + charLength);
+		else if (isCjkCodePoint(codePoint)) breaks.push(index + charLength);
+		index += charLength;
+	}
+	return breaks;
+}
+function isBreakChar(char) {
+	if (char === void 0) return false;
+	if (char === " " || char === "-" || char === "	") return true;
+	const codePoint = char.codePointAt(0);
+	if (codePoint === void 0) return false;
+	if (char >= "\udc00" && char <= "\udfff") return true;
+	return isCjkCodePoint(codePoint);
+}
+//#endregion
+export { findWordBreaks, isBreakChar };

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

@@ -1,7 +1,7 @@
 import { setMeasureProvider } from "./measureProvider.js";
 import { buildFontString, getResolvedData, ptToPx } from "./measureHelpers.js";
-import { getCachedFontMetrics, getCachedTextWidth, getTextWidthCacheGeneration, setCachedFontMetrics, setCachedTextWidth } from "./cache.js";
 import { hasCjk, isCjkCodePoint, segmentByScript } from "../../utils/scriptSegments.js";
+import { getCachedFontMetrics, getCachedTextWidth, getTextWidthCacheGeneration, setCachedFontMetrics, setCachedTextWidth } from "./cache.js";
 import { canPrefetchMeasurement, prefetchMeasurement } from "./measureWorker.js";
 import { WORKER_FONT_FINGERPRINT_TEXT, countCodePoints } from "./measureWorkerProtocol.js";
 import { panic } from "better-result";

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

@@ -8,6 +8,7 @@ import { isFloatingImageRun } from "../types.js";
 import { clampFloatingWrapMargins } from "./clampFloatingWrapMargins.js";
 import { getFloatingAvailableWidth, getFloatingMargins } from "./floatingZones.js";
 import { getListMarkerInlineWidth } from "./listMarkerWidth.js";
+import { findWordBreaks, isBreakChar } from "./lineBreaks.js";
 //#region src/layout-engine/measure/measureParagraph.ts
 /**
 * Paragraph measurement module
@@ -207,18 +208,34 @@ function isEmptyTextRun(run) {
 * desync measurer and painter on tab advance for paragraphs with a tab
 * preceding a floating image.
 */
+function isBlockLayoutImageRun(run) {
+	return run.wrapType === "topAndBottom" || run.displayMode === "block";
+}
 function measureInlineWidthAfterTab(runs, tabIndex, fieldValues) {
 	let width = 0;
 	for (let i = tabIndex + 1; i < runs.length; i++) {
 		const next = runs[i];
 		if (!next || isTabRun(next) || isLineBreakRun(next)) break;
+		if (isImageRun(next)) {
+			if (isBlockLayoutImageRun(next)) break;
+			if (!isFloatingImageRun(next)) width += inlineImageBoundingBox(next).width || 0;
+			continue;
+		}
 		if (isTextRun(next)) width += measureTextWidth(next.text || "", runToFontStyle(next));
 		else if (isFieldRun(next)) width += measureTextWidth(fieldMeasureText(next, fieldValues), runToFontStyle(next));
-		else if (isImageRun(next) && !isFloatingImageRun(next)) width += next.width || 0;
 		else if (isMathRun(next)) width += measureTextWidth(next.plainText || "[equation]", runToFontStyle(next));
 	}
 	return width;
 }
+function hasFollowingTabOnLine(runs, tabIndex) {
+	for (let i = tabIndex + 1; i < runs.length; i++) {
+		const next = runs[i];
+		if (!next || isLineBreakRun(next)) break;
+		if (isImageRun(next) && isBlockLayoutImageRun(next)) break;
+		if (isTabRun(next)) return true;
+	}
+	return false;
+}
 /**
 * Width of the inline content preceding the first `.` in the runs that follow
 * a tab, used to anchor `decimal` tab stops. Mirrors `getTextAfterTab` +
@@ -249,21 +266,6 @@ function measureDecimalPrefixWidthAfterTab(runs, tabIndex, fieldValues) {
 	if (decimalIndex === -1 || !firstRun) return 0;
 	return measureTextWidth(text.slice(0, decimalIndex), runToFontStyle(firstRun));
 }
-/**
-* Find word break points in text
-* Returns array of indices where words end (after space/punctuation)
-*/
-function findWordBreaks(text) {
-	const breaks = [];
-	for (let i = 0; i < text.length; i++) {
-		const char = text[i];
-		if (char === " " || char === "-" || char === "	") breaks.push(i + 1);
-	}
-	return breaks;
-}
-function isBreakChar(char) {
-	return char === " " || char === "-" || char === "	";
-}
 function isSpaceOrTab(char) {
 	return char === " " || char === "	";
 }
@@ -551,13 +553,17 @@ function measureParagraph(block, maxWidth, options) {
 			const followingWidth = measureInlineWidthAfterTab(runs, runIndex, options?.fieldValues);
 			const decimalPrefixWidth = measureDecimalPrefixWidthAfterTab(runs, runIndex, options?.fieldValues);
 			const lineX = currentLine.width + currentLine.leftOffset;
-			const tabWidth = calculateTabWidth(indentLeft + (lines.length === 0 ? firstLineOffset + markerInlineWidth : 0) + lineX, {
+			const isFirstLine = lines.length === 0;
+			const contentX = indentLeft + (isFirstLine ? firstLineOffset + markerInlineWidth : 0) + lineX;
+			let tabWidth = calculateTabWidth(contentX, {
 				...attrs?.tabs !== void 0 ? { explicitStops: attrs.tabs } : {},
 				leftIndent: pixelsToTwips(indentLeft)
 			}, {
 				followingWidth,
 				decimalPrefixWidth
 			}).width;
+			const lineRightEdgeX = indentLeft + (isFirstLine ? firstLineOffset + markerInlineWidth : 0) + currentLine.availableWidth + currentLine.leftOffset;
+			if (!hasFollowingTabOnLine(runs, runIndex) && (tabWidth > 0 || followingWidth > 0) && contentX + tabWidth + followingWidth > lineRightEdgeX + WIDTH_TOLERANCE) tabWidth = Math.max(1, lineRightEdgeX - contentX - followingWidth);
 			if (currentLine.width + tabWidth > currentLine.availableWidth + WIDTH_TOLERANCE) {
 				startNewLine(runIndex, 0);
 				updateMaxFont(style);

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

@@ -82,7 +82,7 @@ function createTransport() {
 		return null;
 	}
 	try {
-		return new Worker(new URL("font-metrics.worker.ts", import.meta.url), { type: "module" });
+		return new Worker(new URL("font-metrics.worker.js", import.meta.url), { type: "module" });
 	} catch {
 		return null;
 	}

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

@@ -365,7 +365,8 @@ type ParagraphAttrs = {
  */
 type ParagraphBlock = {
   kind: "paragraph";
-  id: BlockId;
+  id: BlockId; /** Stable Word `w14:paraId` / PM `paraId`, when available. */
+  paraId?: string;
   runs: Run[];
   attrs?: ParagraphAttrs;
   /** Names of bookmarks anchored to this paragraph; used to map a bookmark to

package/dist/layout-painter/renderParagraph.js

@@ -5,13 +5,13 @@ import { calculateTabWidth } from "../prosemirror/utils/tabCalculator.js";
 import { inlineImageBoundingBox, parseRotationDegrees, rotatedBoundingBox } from "../utils/rotationBoundingBox.js";
 import { isFloatingImageRun } from "../layout-engine/types.js";
 import { getListMarkerInlineWidth } from "../layout-engine/measure/listMarkerWidth.js";
+import { hasCjk, segmentByScript } from "../utils/scriptSegments.js";
 import { applySdtDataAttrs } from "./sdtBoundary.js";
 import { applyImageVisualAttrs, hasImageVisualAttrs, wrapImageWithCrop } from "./renderImage.js";
 import { ommlToMathml } from "../docx/mathToMathml.js";
 import { evaluateFieldInstruction } from "../fields/evaluateField.js";
 import { AUTHOR_COLORS, getAuthorColorIdx } from "../utils/authorColors.js";
 import { detectBaseDirection } from "../utils/baseDirection.js";
-import { hasCjk, segmentByScript } from "../utils/scriptSegments.js";
 import { getAutomaticTextColorForBackground } from "./documentColors.js";
 import { resolveImageLineAlign } from "./renderUtils.js";
 //#region src/layout-painter/renderParagraph.ts
@@ -1075,6 +1075,7 @@ function renderParagraphFragment(fragment, block, measure, context, options = {}
 	fragmentEl.className = PARAGRAPH_CLASS_NAMES.fragment;
 	fragmentEl.style.position = "relative";
 	fragmentEl.dataset["blockId"] = String(fragment.blockId);
+	if (block.paraId) fragmentEl.dataset["paraId"] = block.paraId;
 	fragmentEl.dataset["fromLine"] = String(fragment.fromLine);
 	fragmentEl.dataset["toLine"] = String(fragment.toLine);
 	applyPmPositions(fragmentEl, fragment.pmStart, fragment.pmEnd);

package/dist/paged-layout/paragraphFlash.d.ts

@@ -0,0 +1,17 @@
+import { ParagraphHighlightOptions, ScrollToParaIdOptions } from "./paragraphFlashTypes.js";
+
+//#region src/paged-layout/paragraphFlash.d.ts
+/** Default color used by paragraph flashes. */
+declare const DEFAULT_PARAGRAPH_FLASH_COLOR = "rgba(255, 235, 59, 0.55)";
+/** Default duration for paragraph flashes. */
+declare const DEFAULT_PARAGRAPH_FLASH_DURATION_MS = 1200;
+/** CSS class applied to paragraph fragments during a transient flash. */
+declare const PARAGRAPH_FLASH_CLASS_NAME = "folio-paragraph-flash";
+/** Find all painted paragraph fragments with a stable `data-para-id`. */
+declare const findParagraphFragmentsByParaId: (root: ParentNode, paraId: string) => HTMLElement[];
+/** Apply a transient flash to a collection of paragraph elements. */
+declare const flashParagraphElements: (elements: Iterable<HTMLElement>, options?: ParagraphHighlightOptions) => number;
+/** Find paragraph fragments by `paraId` and flash them. */
+declare const flashParagraphFragmentsByParaId: (root: ParentNode, paraId: string, options?: ParagraphHighlightOptions) => boolean;
+//#endregion
+export { DEFAULT_PARAGRAPH_FLASH_COLOR, DEFAULT_PARAGRAPH_FLASH_DURATION_MS, PARAGRAPH_FLASH_CLASS_NAME, type ParagraphHighlightOptions, type ScrollToParaIdOptions, findParagraphFragmentsByParaId, flashParagraphElements, flashParagraphFragmentsByParaId };

package/dist/paged-layout/paragraphFlash.js

@@ -0,0 +1,56 @@
+//#region src/paged-layout/paragraphFlash.ts
+/** Default color used by paragraph flashes. */
+const DEFAULT_PARAGRAPH_FLASH_COLOR = "rgba(255, 235, 59, 0.55)";
+/** Default duration for paragraph flashes. */
+const DEFAULT_PARAGRAPH_FLASH_DURATION_MS = 1200;
+/** CSS class applied to paragraph fragments during a transient flash. */
+const PARAGRAPH_FLASH_CLASS_NAME = "folio-paragraph-flash";
+const timers = /* @__PURE__ */ new WeakMap();
+const escapeAttributeValue = (value) => {
+	const cssGlobal = globalThis;
+	if (typeof cssGlobal.CSS?.escape === "function") return cssGlobal.CSS.escape(value);
+	return value.replace(/\\/g, "\\\\").replace(/"/g, "\\\"");
+};
+const normalizedColor = (options) => {
+	return options?.color?.trim() || "rgba(255, 235, 59, 0.55)";
+};
+const normalizedDurationMs = (options) => {
+	const duration = options?.durationMs;
+	if (duration == null) return DEFAULT_PARAGRAPH_FLASH_DURATION_MS;
+	if (!Number.isFinite(duration) || duration < 0) return DEFAULT_PARAGRAPH_FLASH_DURATION_MS;
+	return duration;
+};
+/** Find all painted paragraph fragments with a stable `data-para-id`. */
+const findParagraphFragmentsByParaId = (root, paraId) => {
+	if (!paraId || !paraId.trim()) return [];
+	const escaped = escapeAttributeValue(paraId);
+	return Array.from(root.querySelectorAll(`.layout-paragraph[data-para-id="${escaped}"]`));
+};
+/** Apply a transient flash to a collection of paragraph elements. */
+const flashParagraphElements = (elements, options) => {
+	let count = 0;
+	const color = normalizedColor(options);
+	const durationMs = normalizedDurationMs(options);
+	for (const el of elements) {
+		count++;
+		const existingTimer = timers.get(el);
+		if (existingTimer !== void 0) clearTimeout(existingTimer);
+		el.classList.remove(PARAGRAPH_FLASH_CLASS_NAME);
+		el.offsetWidth;
+		el.style.setProperty("--folio-paragraph-flash-color", color);
+		el.style.setProperty("--folio-paragraph-flash-duration", `${durationMs}ms`);
+		el.classList.add(PARAGRAPH_FLASH_CLASS_NAME);
+		const timer = setTimeout(() => {
+			el.classList.remove(PARAGRAPH_FLASH_CLASS_NAME);
+			el.style.removeProperty("--folio-paragraph-flash-color");
+			el.style.removeProperty("--folio-paragraph-flash-duration");
+			timers.delete(el);
+		}, durationMs);
+		timers.set(el, timer);
+	}
+	return count;
+};
+/** Find paragraph fragments by `paraId` and flash them. */
+const flashParagraphFragmentsByParaId = (root, paraId, options) => flashParagraphElements(findParagraphFragmentsByParaId(root, paraId), options) > 0;
+//#endregion
+export { DEFAULT_PARAGRAPH_FLASH_COLOR, DEFAULT_PARAGRAPH_FLASH_DURATION_MS, PARAGRAPH_FLASH_CLASS_NAME, findParagraphFragmentsByParaId, flashParagraphElements, flashParagraphFragmentsByParaId };

package/dist/paged-layout/paragraphFlashTypes.d.ts

@@ -0,0 +1,18 @@
+//#region src/paged-layout/paragraphFlashTypes.d.ts
+/**
+ * Option shapes for `scrollToParaId(paraId, { highlight })`.
+ *
+ * DOM-free so non-browser consumers can type-import without pulling in
+ * paragraph-flash DOM helpers.
+ */
+/** Customization for the transient paragraph flash applied by `scrollToParaId`. */
+type ParagraphHighlightOptions = {
+  /** CSS color used for the transient paragraph flash. Defaults to yellow. */color?: string; /** How long the flash remains visible before it is removed. Defaults to 1200ms. */
+  durationMs?: number;
+};
+/** Optional reveal behavior for `scrollToParaId`. */
+type ScrollToParaIdOptions = {
+  /** Flash rendered paragraph fragments after scrolling to the paragraph. */highlight?: ParagraphHighlightOptions;
+};
+//#endregion
+export { ParagraphHighlightOptions, ScrollToParaIdOptions };

package/dist/utils/headerFooter.js

@@ -1,3 +1,4 @@
+import { clearHeaderFooterVerbatimXml } from "../docx/headerFooterVerbatim.js";
 //#region src/utils/headerFooter.ts
 const EMPTY_RESOLUTION = {
 	headerContent: null,
@@ -206,6 +207,7 @@ const saveHeaderFooterContent = ({ document, position, isFirstPage, activeRId, b
 		hdrFtrType: isFirstPage ? "first" : "default",
 		content: blocks
 	};
+	clearHeaderFooterVerbatimXml(updated);
 	const newMap = new Map(map);
 	newMap.set(activeRId, updated);
 	return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stll/folio-core",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Headless, framework-neutral core of folio: the OOXML (.docx) parser, document model, ProseMirror integration, and page-layout engine. No React.",
   "keywords": [
     "document-model",