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

package/dist/docx/unzip.js

@@ -0,0 +1,383 @@
+import JSZip from "jszip";
+//#region src/docx/unzip.ts
+/**
+* DOCX Unzipper
+*
+* Extracts all files from a DOCX ZIP archive and organizes them
+* into a structured format for further processing.
+*
+* A DOCX file is a ZIP archive containing:
+* - [Content_Types].xml - Content type declarations
+* - word/document.xml - Main document content
+* - word/styles.xml - Style definitions
+* - word/theme/theme1.xml - Theme colors and fonts
+* - word/numbering.xml - List/numbering definitions
+* - word/fontTable.xml - Font declarations
+* - word/settings.xml - Document settings
+* - word/webSettings.xml - Web settings
+* - word/header*.xml - Header content
+* - word/footer*.xml - Footer content
+* - word/footnotes.xml - Footnotes
+* - word/endnotes.xml - Endnotes
+* - word/media/* - Embedded images and media
+* - word/_rels/document.xml.rels - Relationships
+* - _rels/.rels - Package relationships
+* - docProps/core.xml - Core properties
+* - docProps/app.xml - Application properties
+*/
+var DocxSecurityError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "DocxSecurityError";
+	}
+};
+const DEFAULT_ALLOWED_MEDIA_MIME_TYPES = /* @__PURE__ */ new Set([
+	"image/png",
+	"image/jpeg",
+	"image/gif",
+	"image/bmp",
+	"image/tiff",
+	"image/webp"
+]);
+const PRESERVABLE_MEDIA_MIME_TYPES = /* @__PURE__ */ new Set([
+	...DEFAULT_ALLOWED_MEDIA_MIME_TYPES,
+	"image/svg+xml",
+	"image/x-wmf",
+	"image/x-emf"
+]);
+const MEBIBYTE = 1024 * 1024;
+const DEFAULT_UNZIP_LIMITS = {
+	maxInputBytes: 50 * MEBIBYTE,
+	maxFiles: 5e3,
+	maxXmlBytes: 128 * MEBIBYTE,
+	maxMediaBytes: 25 * MEBIBYTE,
+	maxFontBytes: 10 * MEBIBYTE,
+	maxTotalUncompressedBytes: 250 * MEBIBYTE,
+	allowedMediaMimeTypes: DEFAULT_ALLOWED_MEDIA_MIME_TYPES
+};
+const ZIP_END_OF_CENTRAL_DIRECTORY_SIGNATURE = 101010256;
+const ZIP_CENTRAL_DIRECTORY_FILE_HEADER_SIGNATURE = 33639248;
+const ZIP_END_OF_CENTRAL_DIRECTORY_SIZE = 22;
+const ZIP_END_OF_CENTRAL_DIRECTORY_WITH_COUNTS_SIZE = 12;
+const ZIP_CENTRAL_DIRECTORY_FILE_HEADER_SIZE = 46;
+/**
+* Extract all content from a DOCX file
+*
+* @param buffer - DOCX file as ArrayBuffer
+* @returns Promise resolving to extracted content
+*/
+async function unzipDocx(buffer, options = {}) {
+	const limits = createUnzipLimits(options);
+	if (buffer.byteLength > limits.maxInputBytes) throw new DocxSecurityError("DOCX file exceeds the maximum allowed size");
+	const loaded = await loadDocxZip(buffer, limits.maxFiles);
+	if (loaded.buffer.byteLength > limits.maxInputBytes) throw new DocxSecurityError("DOCX file exceeds the maximum allowed size");
+	const { zip } = loaded;
+	const entries = Object.entries(zip.files).filter(([, file]) => !file.dir);
+	if (entries.length > limits.maxFiles) throw new DocxSecurityError("DOCX file contains too many entries");
+	const content = {
+		documentXml: null,
+		stylesXml: null,
+		themeXml: null,
+		numberingXml: null,
+		fontTableXml: null,
+		settingsXml: null,
+		webSettingsXml: null,
+		headers: /* @__PURE__ */ new Map(),
+		footers: /* @__PURE__ */ new Map(),
+		footnotesXml: null,
+		endnotesXml: null,
+		commentsXml: null,
+		commentsExtensibleXml: null,
+		commentsExtendedXml: null,
+		documentRels: null,
+		packageRels: null,
+		contentTypesXml: null,
+		corePropsXml: null,
+		appPropsXml: null,
+		customPropsXml: null,
+		media: /* @__PURE__ */ new Map(),
+		fonts: /* @__PURE__ */ new Map(),
+		allXml: /* @__PURE__ */ new Map(),
+		originalZip: zip,
+		originalBuffer: loaded.buffer,
+		warnings: []
+	};
+	let totalUncompressedBytes = 0;
+	for (const [path, file] of entries) {
+		if (!isSafeDocxPath(path)) throw new DocxSecurityError("DOCX file contains an unsafe entry path");
+		if (!isPreservableDocxEntry(path)) continue;
+		const lowerPath = path.toLowerCase();
+		const declaredSize = getEntryUncompressedSize(file);
+		if (declaredSize !== null) {
+			totalUncompressedBytes += declaredSize;
+			if (totalUncompressedBytes > limits.maxTotalUncompressedBytes) throw new DocxSecurityError("DOCX file expands beyond the maximum allowed size");
+		}
+		if (lowerPath.endsWith(".xml") || lowerPath.endsWith(".rels")) {
+			assertEntrySize(path, declaredSize, limits.maxXmlBytes);
+			const xmlContent = await file.async("text");
+			assertExtractedSize(path, xmlContent.length, limits.maxXmlBytes);
+			content.allXml.set(path, xmlContent);
+			if (lowerPath === "word/document.xml") content.documentXml = xmlContent;
+			else if (lowerPath === "word/styles.xml") content.stylesXml = xmlContent;
+			else if (lowerPath === "word/theme/theme1.xml") content.themeXml = xmlContent;
+			else if (lowerPath === "word/numbering.xml") content.numberingXml = xmlContent;
+			else if (lowerPath === "word/fonttable.xml") content.fontTableXml = xmlContent;
+			else if (lowerPath === "word/settings.xml") content.settingsXml = xmlContent;
+			else if (lowerPath === "word/websettings.xml") content.webSettingsXml = xmlContent;
+			else if (lowerPath === "word/footnotes.xml") content.footnotesXml = xmlContent;
+			else if (lowerPath === "word/endnotes.xml") content.endnotesXml = xmlContent;
+			else if (lowerPath === "word/comments.xml") content.commentsXml = xmlContent;
+			else if (lowerPath === "word/commentsextensible.xml") content.commentsExtensibleXml = xmlContent;
+			else if (lowerPath === "word/commentsextended.xml") content.commentsExtendedXml = xmlContent;
+			else if (lowerPath === "word/_rels/document.xml.rels") content.documentRels = xmlContent;
+			else if (lowerPath === "_rels/.rels") content.packageRels = xmlContent;
+			else if (lowerPath === "[content_types].xml") content.contentTypesXml = xmlContent;
+			else if (lowerPath === "docprops/core.xml") content.corePropsXml = xmlContent;
+			else if (lowerPath === "docprops/app.xml") content.appPropsXml = xmlContent;
+			else if (lowerPath === "docprops/custom.xml") content.customPropsXml = xmlContent;
+			else if (/^word\/header[^/]*\.xml$/u.test(lowerPath)) {
+				const filename = path.split("/").pop() || path;
+				content.headers.set(filename, xmlContent);
+			} else if (/^word\/footer[^/]*\.xml$/u.test(lowerPath)) {
+				const filename = path.split("/").pop() || path;
+				content.footers.set(filename, xmlContent);
+			}
+		} else if (lowerPath.startsWith("word/media/")) {
+			const mimeType = getMediaMimeType(path);
+			if (!limits.allowedMediaMimeTypes.has(mimeType)) continue;
+			if (isEntryTooLarge(declaredSize, limits.maxMediaBytes)) {
+				content.warnings.push(`Skipped oversized media file: ${path}; original entry preserved for round-trip.`);
+				continue;
+			}
+			const binaryContent = await file.async("arraybuffer");
+			if (binaryContent.byteLength > limits.maxMediaBytes) {
+				content.warnings.push(`Skipped oversized media file: ${path}; original entry preserved for round-trip.`);
+				continue;
+			}
+			if (!isMediaContentAllowed(binaryContent, mimeType)) continue;
+			content.media.set(path, binaryContent);
+		} else if (lowerPath.startsWith("word/fonts/")) {
+			if (isEntryTooLarge(declaredSize, limits.maxFontBytes)) continue;
+			const binaryContent = await file.async("arraybuffer");
+			if (binaryContent.byteLength > limits.maxFontBytes) continue;
+			content.fonts.set(path, binaryContent);
+		}
+	}
+	return content;
+}
+async function loadDocxZip(buffer, maxFiles) {
+	try {
+		return {
+			zip: await JSZip.loadAsync(buffer),
+			buffer
+		};
+	} catch (error) {
+		const repairedBuffer = repairTruncatedEndOfCentralDirectory(buffer, maxFiles);
+		if (!repairedBuffer) throw error;
+		try {
+			return {
+				zip: await JSZip.loadAsync(repairedBuffer),
+				buffer: repairedBuffer
+			};
+		} catch {
+			throw error;
+		}
+	}
+}
+function repairTruncatedEndOfCentralDirectory(buffer, maxFiles) {
+	const bytes = new Uint8Array(buffer);
+	const view = new DataView(buffer);
+	const eocdOffset = findLastSignature(view, bytes.byteLength, ZIP_END_OF_CENTRAL_DIRECTORY_SIGNATURE);
+	if (eocdOffset === -1) return null;
+	const eocdBytes = bytes.byteLength - eocdOffset;
+	if (eocdBytes >= ZIP_END_OF_CENTRAL_DIRECTORY_SIZE || eocdBytes < ZIP_END_OF_CENTRAL_DIRECTORY_WITH_COUNTS_SIZE) return null;
+	const diskNumber = view.getUint16(eocdOffset + 4, true);
+	const centralDirectoryDisk = view.getUint16(eocdOffset + 6, true);
+	const diskEntryCount = view.getUint16(eocdOffset + 8, true);
+	const totalEntryCount = view.getUint16(eocdOffset + 10, true);
+	if (diskNumber !== 0 || centralDirectoryDisk !== 0 || diskEntryCount !== totalEntryCount || totalEntryCount > maxFiles) return null;
+	const centralDirectory = findCentralDirectory(view, eocdOffset, totalEntryCount);
+	if (!centralDirectory) return null;
+	const repaired = new Uint8Array(eocdOffset + ZIP_END_OF_CENTRAL_DIRECTORY_SIZE);
+	repaired.set(bytes.subarray(0, eocdOffset));
+	const repairedView = new DataView(repaired.buffer);
+	repairedView.setUint32(eocdOffset, ZIP_END_OF_CENTRAL_DIRECTORY_SIGNATURE, true);
+	repairedView.setUint16(eocdOffset + 4, 0, true);
+	repairedView.setUint16(eocdOffset + 6, 0, true);
+	repairedView.setUint16(eocdOffset + 8, totalEntryCount, true);
+	repairedView.setUint16(eocdOffset + 10, totalEntryCount, true);
+	repairedView.setUint32(eocdOffset + 12, centralDirectory.size, true);
+	repairedView.setUint32(eocdOffset + 16, centralDirectory.offset, true);
+	repairedView.setUint16(eocdOffset + 20, 0, true);
+	return repaired.buffer;
+}
+function findCentralDirectory(view, eocdOffset, entryCount) {
+	for (let offset = 0; offset <= eocdOffset - ZIP_CENTRAL_DIRECTORY_FILE_HEADER_SIZE; offset += 1) {
+		if (view.getUint32(offset, true) !== ZIP_CENTRAL_DIRECTORY_FILE_HEADER_SIGNATURE) continue;
+		const parsed = parseCentralDirectoryAt(view, offset, eocdOffset, entryCount);
+		if (parsed) return parsed;
+	}
+	return null;
+}
+function parseCentralDirectoryAt(view, startOffset, eocdOffset, entryCount) {
+	let offset = startOffset;
+	for (let index = 0; index < entryCount; index += 1) {
+		if (offset + ZIP_CENTRAL_DIRECTORY_FILE_HEADER_SIZE > eocdOffset || view.getUint32(offset, true) !== ZIP_CENTRAL_DIRECTORY_FILE_HEADER_SIGNATURE) return null;
+		const filenameLength = view.getUint16(offset + 28, true);
+		const extraLength = view.getUint16(offset + 30, true);
+		const commentLength = view.getUint16(offset + 32, true);
+		offset += ZIP_CENTRAL_DIRECTORY_FILE_HEADER_SIZE + filenameLength + extraLength + commentLength;
+	}
+	if (offset !== eocdOffset) return null;
+	return {
+		offset: startOffset,
+		size: eocdOffset - startOffset
+	};
+}
+function findLastSignature(view, byteLength, signature) {
+	for (let offset = byteLength - ZIP_END_OF_CENTRAL_DIRECTORY_WITH_COUNTS_SIZE; offset >= 0; offset -= 1) if (view.getUint32(offset, true) === signature) return offset;
+	return -1;
+}
+function createUnzipLimits(options) {
+	return {
+		...DEFAULT_UNZIP_LIMITS,
+		...options,
+		allowedMediaMimeTypes: options.allowedMediaMimeTypes ? new Set(options.allowedMediaMimeTypes) : DEFAULT_UNZIP_LIMITS.allowedMediaMimeTypes
+	};
+}
+function isSafeDocxPath(path) {
+	if (!path || path.startsWith("/") || path.includes("\\")) return false;
+	return !path.split("/").some((part) => part === "..");
+}
+function isPreservableDocxEntry(path) {
+	if (!isSafeDocxPath(path)) return false;
+	const lowerPath = path.toLowerCase();
+	if (lowerPath.startsWith("word/media/")) return PRESERVABLE_MEDIA_MIME_TYPES.has(getMediaMimeType(path));
+	if (lowerPath.startsWith("word/fonts/")) return true;
+	if (!(lowerPath.endsWith(".xml") || lowerPath.endsWith(".rels"))) return false;
+	return lowerPath === "[content_types].xml" || lowerPath.startsWith("_rels/") || lowerPath.startsWith("docprops/") || lowerPath.startsWith("word/") || lowerPath.startsWith("customxml/");
+}
+function getEntryUncompressedSize(file) {
+	const metadata = file._data;
+	return typeof metadata?.uncompressedSize === "number" ? metadata.uncompressedSize : null;
+}
+function assertEntrySize(path, declaredSize, maxBytes) {
+	if (isEntryTooLarge(declaredSize, maxBytes)) throw new DocxSecurityError(`DOCX entry exceeds maximum size: ${path}`);
+}
+function isEntryTooLarge(declaredSize, maxBytes) {
+	return declaredSize !== null && declaredSize > maxBytes;
+}
+function assertExtractedSize(path, byteLength, maxBytes) {
+	if (byteLength > maxBytes) throw new DocxSecurityError(`DOCX entry exceeds maximum size: ${path}`);
+}
+function isMediaContentAllowed(data, mimeType) {
+	const bytes = new Uint8Array(data);
+	switch (mimeType) {
+		case "image/png": return bytes[0] === 137 && bytes[1] === 80 && bytes[2] === 78 && bytes[3] === 71;
+		case "image/jpeg": return bytes[0] === 255 && bytes[1] === 216;
+		case "image/gif": return bytes[0] === 71 && bytes[1] === 73 && bytes[2] === 70 && bytes[3] === 56;
+		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;
+		default: return false;
+	}
+}
+/**
+* Get a list of all files in the DOCX
+*
+* @param content - Extracted DOCX content
+* @returns Array of file paths
+*/
+function getFileList(content) {
+	const files = [];
+	for (const path of Object.keys(content.originalZip.files)) if (!content.originalZip.files[path]?.dir && isPreservableDocxEntry(path)) files.push(path);
+	return files.toSorted();
+}
+/**
+* Get the MIME type for a media file based on extension
+*
+* @param path - File path
+* @returns MIME type string
+*/
+function getMediaMimeType(path) {
+	switch (path.toLowerCase().split(".").pop()) {
+		case "png": return "image/png";
+		case "jpg":
+		case "jpeg": return "image/jpeg";
+		case "gif": return "image/gif";
+		case "bmp": return "image/bmp";
+		case "tif":
+		case "tiff": return "image/tiff";
+		case "wmf": return "image/x-wmf";
+		case "emf": return "image/x-emf";
+		case "svg": return "image/svg+xml";
+		case "webp": return "image/webp";
+		default: return "application/octet-stream";
+	}
+}
+/**
+* Convert media file to data URL
+*
+* @param data - Binary data
+* @param mimeType - MIME type
+* @returns Data URL string
+*/
+function mediaToDataUrl(data, mimeType) {
+	const bytes = new Uint8Array(data);
+	const chunks = [];
+	const chunkSize = 32768;
+	for (let offset = 0; offset < bytes.length; offset += chunkSize) {
+		const chunk = bytes.subarray(offset, offset + chunkSize);
+		chunks.push(String.fromCodePoint(...chunk));
+	}
+	return `data:${mimeType};base64,${btoa(chunks.join(""))}`;
+}
+/**
+* Extract a specific file from the original ZIP
+*
+* @param content - Extracted DOCX content
+* @param path - File path within the ZIP
+* @returns File content as string or ArrayBuffer, or null if not found
+*/
+function extractFile(content, path) {
+	const file = content.originalZip.file(path);
+	if (!file || !isPreservableDocxEntry(path)) return Promise.resolve(null);
+	const lowerPath = path.toLowerCase();
+	if (lowerPath.endsWith(".xml") || lowerPath.endsWith(".rels")) return file.async("text");
+	return file.async("arraybuffer");
+}
+/**
+* Check if a file exists in the DOCX
+*
+* @param content - Extracted DOCX content
+* @param path - File path to check
+* @returns true if file exists
+*/
+function hasFile(content, path) {
+	return content.originalZip.file(path) !== null;
+}
+/**
+* Get summary of DOCX content
+*
+* @param content - Extracted DOCX content
+* @returns Object with file counts and presence flags
+*/
+function getContentSummary(content) {
+	return {
+		hasDocument: content.documentXml !== null,
+		hasStyles: content.stylesXml !== null,
+		hasTheme: content.themeXml !== null,
+		hasNumbering: content.numberingXml !== null,
+		hasFontTable: content.fontTableXml !== null,
+		hasFootnotes: content.footnotesXml !== null,
+		hasEndnotes: content.endnotesXml !== null,
+		hasComments: content.commentsXml !== null,
+		headerCount: content.headers.size,
+		footerCount: content.footers.size,
+		mediaCount: content.media.size,
+		fontCount: content.fonts.size,
+		totalFiles: Object.keys(content.originalZip.files).filter((p) => !content.originalZip.files[p]?.dir).length
+	};
+}
+//#endregion
+export { DocxSecurityError, extractFile, getContentSummary, getFileList, getMediaMimeType, hasFile, isPreservableDocxEntry, mediaToDataUrl, unzipDocx };

package/dist/docx/vmlImageParser.d.ts

@@ -0,0 +1,16 @@
+import { document_d_exports } from "../types/document.js";
+import { XmlElement } from "./xmlParser.js";
+
+//#region src/docx/vmlImageParser.d.ts
+/**
+ * Parse a `w:pict` element into an inline image, or null when it carries no
+ * ordinary VML picture (no resolvable `<v:imagedata>`, or a watermark shape).
+ *
+ * `rootXmlns` carries the source document/header namespace declarations. They
+ * are injected onto the captured VML so the raw replay stays self-contained
+ * when the producer bound WordprocessingML / relationship / VML namespaces to
+ * non-canonical prefixes the serializer's root does not declare.
+ */
+declare function parseVmlImageContent(pictElement: XmlElement, rels: document_d_exports.RelationshipMap | null, media: Map<string, document_d_exports.MediaFile> | null, rootXmlns?: Record<string, string>): document_d_exports.DrawingContent | null;
+//#endregion
+export { parseVmlImageContent };

package/dist/docx/vmlImageParser.js

@@ -0,0 +1,100 @@
+import { cloneWithXmlnsDeclarations, elementToXml, findAllDeep, findChild, getAttribute } from "./xmlParser.js";
+import { pixelsToEmu } from "../utils/units.js";
+import { resolveImageData } from "./imageParser.js";
+import { isWatermarkShape } from "./watermarkParser.js";
+//#region src/docx/vmlImageParser.ts
+/**
+* Convert a CSS length (pt/in/px/cm/mm/pc, default px) to pixels. Units are
+* matched case-insensitively (`2IN`, `2Pt` are valid VML). The numeric part
+* must be a single well-formed decimal, so malformed input like `1.2.3` is
+* rejected rather than truncated to `1.2`.
+*/
+function cssLengthToPx(raw) {
+	if (!raw) return;
+	const match = /^(?<amount>-?(?:\d+(?:\.\d+)?|\.\d+))\s*(?<unit>pt|in|px|cm|mm|pc)?$/iu.exec(raw.trim());
+	const amountText = match?.groups?.["amount"];
+	if (amountText === void 0) return;
+	const value = Number.parseFloat(amountText);
+	if (Number.isNaN(value)) return;
+	switch (match?.groups?.["unit"]?.toLowerCase()) {
+		case "pt": return value / 72 * 96;
+		case "in": return value * 96;
+		case "cm": return value / 2.54 * 96;
+		case "mm": return value / 25.4 * 96;
+		case "pc": return value / 6 * 96;
+		case "px":
+		case void 0: return value;
+		default: return;
+	}
+}
+/** Read a `style="k1:v1;k2:v2"` attribute into a lowercased key/value record. */
+function parseStyleAttr(style) {
+	const out = {};
+	if (!style) return out;
+	for (const decl of style.split(";")) {
+		const colon = decl.indexOf(":");
+		if (colon < 0) continue;
+		const key = decl.slice(0, colon).trim().toLowerCase();
+		const value = decl.slice(colon + 1).trim();
+		if (key) out[key] = value;
+	}
+	return out;
+}
+/**
+* Read the relationship id off a `v:imagedata` element. Word writes `r:id`;
+* some legacy / third-party generators use `r:embed` or the office-namespace
+* `o:relid` instead, so fall back through those before the bare `id`.
+*/
+function readImageDataRId(imagedata) {
+	return getAttribute(imagedata, "r", "id") ?? getAttribute(imagedata, "r", "embed") ?? getAttribute(imagedata, "o", "relid") ?? getAttribute(imagedata, null, "id") ?? "";
+}
+/**
+* Parse a `w:pict` element into an inline image, or null when it carries no
+* ordinary VML picture (no resolvable `<v:imagedata>`, or a watermark shape).
+*
+* `rootXmlns` carries the source document/header namespace declarations. They
+* are injected onto the captured VML so the raw replay stays self-contained
+* when the producer bound WordprocessingML / relationship / VML namespaces to
+* non-canonical prefixes the serializer's root does not declare.
+*/
+function parseVmlImageContent(pictElement, rels, media, rootXmlns = {}) {
+	const shapes = [
+		...findAllDeep(pictElement, "v", "shape"),
+		...findAllDeep(pictElement, "v", "rect"),
+		...findAllDeep(pictElement, "v", "roundrect"),
+		...findAllDeep(pictElement, "v", "oval")
+	];
+	for (const shape of shapes) {
+		const imagedata = findChild(shape, "v", "imagedata");
+		if (!imagedata) continue;
+		const rId = readImageDataRId(imagedata);
+		if (!rId) continue;
+		if (isWatermarkShape(shape)) continue;
+		const { src, mimeType, filename } = resolveImageData(rId, rels ?? void 0, media ?? void 0);
+		const shapeStyle = parseStyleAttr(getAttribute(shape, null, "style"));
+		const widthPx = cssLengthToPx(shapeStyle["width"]);
+		const heightPx = cssLengthToPx(shapeStyle["height"]);
+		const image = {
+			type: "image",
+			rId,
+			size: {
+				width: widthPx != null ? pixelsToEmu(widthPx) : 0,
+				height: heightPx != null ? pixelsToEmu(heightPx) : 0
+			},
+			wrap: { type: "inline" }
+		};
+		if (src) image.src = src;
+		if (mimeType) image.mimeType = mimeType;
+		if (filename) image.filename = filename;
+		const title = getAttribute(imagedata, "o", "title");
+		if (title) image.title = title;
+		return {
+			type: "drawing",
+			image,
+			rawXml: elementToXml(cloneWithXmlnsDeclarations(pictElement, rootXmlns))
+		};
+	}
+	return null;
+}
+//#endregion
+export { parseVmlImageContent };

package/dist/docx/watermarkParser.d.ts

@@ -0,0 +1,45 @@
+import { document_d_exports } from "../types/document.js";
+import { XmlElement } from "./xmlParser.js";
+
+//#region src/docx/watermarkParser.d.ts
+/**
+ * Result of walking a header for its watermark. Carries the modeled
+ * `Watermark`, the verbatim XML of the paragraph that hosts the
+ * watermark shape (replayed on serialize so an untouched DOCX
+ * round-trips byte-exact), and a reference to that hosting paragraph
+ * so the regular body parser can skip it.
+ */
+type ParsedWatermark = {
+  watermark: document_d_exports.Watermark;
+  rawParagraphXml: string;
+  hostingParagraph: XmlElement;
+  /**
+   * Index where the watermark paragraph sat among block-level siblings
+   * (`w:p` / `w:tbl`) in the source header. After the host paragraph is
+   * filtered out of `content`, the serializer inserts the watermark
+   * back at this index so a header that originally placed the
+   * watermark after visible text rounds-trips with the same flow.
+   */
+  blockIndex: number;
+};
+/**
+ * Whether a VML `<v:shape>` is a watermark rather than ordinary inline
+ * imagery. Text watermarks use the WordArt shapetype; picture watermarks
+ * carry a `WordPictureWatermark…` id. The VML image parser uses this to
+ * leave watermark shapes to this module, so a header watermark is not also
+ * rendered as an inline picture.
+ */
+declare function isWatermarkShape(shape: XmlElement): boolean;
+/**
+ * Walk a parsed `<w:hdr>` element and return the watermark it carries,
+ * or `undefined` when none is present. Scans every candidate shape /
+ * anchor in the header so a non-watermark shape (e.g. a logo image)
+ * earlier in document order does not shadow the real watermark.
+ *
+ * Returns the modeled `Watermark`, the verbatim XML of the hosting
+ * paragraph (so the serializer can replay it byte-exact), and a
+ * reference to that paragraph so the regular body parser can skip it.
+ */
+declare function parseWatermark(header: XmlElement): ParsedWatermark | undefined;
+//#endregion
+export { ParsedWatermark, isWatermarkShape, parseWatermark };