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

package/dist/docx/paragraphTraversal.d.ts

@@ -0,0 +1,19 @@
+import { document_d_exports } from "../types/document.js";
+
+//#region src/docx/paragraphTraversal.d.ts
+type VisitDocxParagraphsInput = {
+  documentBody: document_d_exports.DocumentBody;
+  headers?: Map<string, document_d_exports.HeaderFooter> | undefined;
+  footers?: Map<string, document_d_exports.HeaderFooter> | undefined;
+  footnotes?: readonly document_d_exports.Footnote[] | undefined;
+  endnotes?: readonly document_d_exports.Endnote[] | undefined;
+};
+declare const visitDocxParagraphs: ({
+  documentBody,
+  headers,
+  footers,
+  footnotes,
+  endnotes
+}: VisitDocxParagraphsInput, visit: (paragraph: document_d_exports.Paragraph) => void) => void;
+//#endregion
+export { visitDocxParagraphs };

package/dist/docx/paragraphTraversal.js

@@ -0,0 +1,76 @@
+//#region src/docx/paragraphTraversal.ts
+const visitDocxParagraphs = ({ documentBody, headers, footers, footnotes, endnotes }, visit) => {
+	const seenParagraphs = /* @__PURE__ */ new WeakSet();
+	const visitParagraph = (paragraph) => {
+		if (seenParagraphs.has(paragraph)) return;
+		seenParagraphs.add(paragraph);
+		visit(paragraph);
+		for (const content of paragraph.content) visitParagraphContent(content);
+	};
+	const visitRun = (run) => {
+		for (const content of run.content) {
+			if (content.type !== "shape" || !content.shape.textBody) continue;
+			for (const paragraph of content.shape.textBody.content) visitParagraph(paragraph);
+		}
+	};
+	const visitHyperlink = (hyperlink) => {
+		for (const child of hyperlink.children) if (child.type === "run") visitRun(child);
+	};
+	const visitInlineContent = (content) => {
+		for (const child of content) {
+			if (child.type === "run") {
+				visitRun(child);
+				continue;
+			}
+			visitHyperlink(child);
+		}
+	};
+	const visitParagraphContent = (content) => {
+		if (content.type === "run") {
+			visitRun(content);
+			return;
+		}
+		if (content.type === "hyperlink") {
+			visitHyperlink(content);
+			return;
+		}
+		if (content.type === "simpleField" || content.type === "insertion" || content.type === "deletion" || content.type === "moveFrom" || content.type === "moveTo") {
+			visitInlineContent(content.content);
+			return;
+		}
+		if (content.type === "inlineSdt") {
+			for (const child of content.content) visitParagraphContent(child);
+			return;
+		}
+		if (content.type === "complexField") {
+			for (const run of content.fieldCode) visitRun(run);
+			for (const run of content.fieldResult) visitRun(run);
+		}
+	};
+	const visitTable = (table) => {
+		for (const row of table.rows) for (const cell of row.cells) visitBlocks(cell.content);
+	};
+	const visitBlock = (block) => {
+		if (block.type === "paragraph") {
+			visitParagraph(block);
+			return;
+		}
+		if (block.type === "table") {
+			visitTable(block);
+			return;
+		}
+		visitBlocks(block.content);
+	};
+	const visitBlocks = (blocks) => {
+		for (const block of blocks) visitBlock(block);
+	};
+	visitBlocks(documentBody.content);
+	for (const section of documentBody.sections ?? []) visitBlocks(section.content);
+	for (const header of headers?.values() ?? []) visitBlocks(header.content);
+	for (const footer of footers?.values() ?? []) visitBlocks(footer.content);
+	for (const footnote of footnotes ?? []) visitBlocks(footnote.content);
+	for (const endnote of endnotes ?? []) visitBlocks(endnote.content);
+	for (const comment of documentBody.comments ?? []) for (const paragraph of comment.content) visitParagraph(paragraph);
+};
+//#endregion
+export { visitDocxParagraphs };

package/dist/docx/parser.d.ts

@@ -0,0 +1,67 @@
+import { document_d_exports } from "../types/document.js";
+import { DocxInput } from "../utils/docxInput.js";
+import { DocxUnzipLimits } from "./unzip.js";
+
+//#region src/docx/parser.d.ts
+/**
+ * Progress callback for tracking parsing stages
+ */
+type ProgressCallback = (stage: string, percent: number) => void;
+/**
+ * Parsing options
+ */
+type ParseOptions = {
+  /** Progress callback for tracking parsing stages */onProgress?: ProgressCallback; /** Whether to preload fonts (default: true) */
+  preloadFonts?: boolean; /** Whether to parse headers/footers (default: true) */
+  parseHeadersFooters?: boolean; /** Whether to parse footnotes/endnotes (default: true) */
+  parseNotes?: boolean; /** Whether to detect template variables (default: true) */
+  detectVariables?: boolean; /** Security limits for DOCX ZIP extraction */
+  unzipLimits?: Partial<Omit<DocxUnzipLimits, "allowedMediaMimeTypes">> & {
+    allowedMediaMimeTypes?: Iterable<string>;
+  };
+};
+/**
+ * Parse a DOCX file into a complete Document model
+ *
+ * @param input - DOCX file as ArrayBuffer, Uint8Array, Blob, or File
+ * @param options - Parsing options
+ * @returns Promise resolving to Document
+ * @throws {Error} if parsing fails
+ */
+declare function parseDocx(input: DocxInput, options?: ParseOptions): Promise<document_d_exports.Document>;
+declare const DocxParseError_base: import("better-result").TaggedErrorClass<"DocxParseError", {
+  message: string;
+  cause?: unknown;
+}>;
+/** DOCX parsing failure: malformed package, unsupported feature, or
+ *  upstream parser exception. Wraps the original cause for diagnostics. */
+declare class DocxParseError extends DocxParseError_base {}
+/**
+ * Quick parse - parse a DOCX without font loading
+ * Useful for quick content extraction or when fonts aren't needed
+ */
+declare function quickParseDocx(buffer: ArrayBuffer): Promise<document_d_exports.Document>;
+/**
+ * Full parse - parse everything including fonts
+ */
+declare function fullParseDocx(buffer: ArrayBuffer, onProgress?: ProgressCallback): Promise<document_d_exports.Document>;
+/**
+ * Get template variables from a DOCX without full parsing
+ * Faster than full parse when you only need variables
+ */
+declare function getDocxVariables(buffer: ArrayBuffer): Promise<string[]>;
+/**
+ * Get document summary without full parsing
+ */
+declare function getDocxSummary(buffer: ArrayBuffer): Promise<{
+  hasDocument: boolean;
+  hasStyles: boolean;
+  hasTheme: boolean;
+  hasNumbering: boolean;
+  headerCount: number;
+  footerCount: number;
+  mediaCount: number;
+  variableCount: number;
+}>;
+//#endregion
+export { DocxParseError, ParseOptions, ProgressCallback, fullParseDocx, getDocxSummary, getDocxVariables, parseDocx, quickParseDocx };

package/dist/docx/parser.js

@@ -0,0 +1,391 @@
+import { RELATIONSHIP_TYPES, parseRelationships, resolveRelativePath } from "./relsParser.js";
+import { applyThemeFontLang, parseTheme } from "./themeParser.js";
+import { parseEndnotes, parseFootnotes } from "./footnoteParser.js";
+import { DocxModelValidationError, formatDocumentModelIssues, validateFolioDocumentModel } from "./modelValidation.js";
+import { parseNumbering } from "./numberingParser.js";
+import { getMediaMimeType, mediaToDataUrl, unzipDocx } from "./unzip.js";
+import { parseComments } from "./commentParser.js";
+import { toArrayBuffer } from "../utils/docxInput.js";
+import { loadFontsWithMapping } from "../utils/fontLoader.js";
+import { convertTiffToPngDataUrl, isTiffMimeType } from "../utils/tiffConverter.js";
+import { normalizeCommentReferences } from "./commentReferenceNormalization.js";
+import { extractAllTemplateVariables, parseDocumentBody } from "./documentParser.js";
+import { parseFooter, parseHeader } from "./headerFooterParser.js";
+import { normalizeHeaderFooterReferences } from "./headerFooterReferenceNormalization.js";
+import { normalizeNumberingReferences } from "./numberingReferenceNormalization.js";
+import { parseSettings } from "./settingsParser.js";
+import { parseStylesPackage } from "./styleParser.js";
+import { normalizeTrackedMoveRanges } from "./trackedMoveRangeNormalization.js";
+import { TaggedError } from "better-result";
+//#region src/docx/parser.ts
+/**
+* Main Parser Orchestrator - Unified parseDocx function
+*
+* Coordinates all sub-parsers to produce a complete Document model.
+* Handles loading order, dependency resolution, and font preloading.
+*
+* Parsing order:
+* 1. Unzip DOCX package
+* 2. Parse relationships
+* 3. Parse theme (needed for style color/font resolution)
+* 4. Parse styles (depends on theme)
+* 5. Parse numbering
+* 6. Parse document body (depends on styles, theme, numbering, rels)
+* 7. Parse headers/footers (depends on styles, theme, numbering, rels)
+* 8. Parse footnotes/endnotes (depends on styles, theme, numbering, rels)
+* 9. Extract and load fonts
+* 10. Build media file map
+* 11. Assemble final Document
+*/
+/**
+* Parse a DOCX file into a complete Document model
+*
+* @param input - DOCX file as ArrayBuffer, Uint8Array, Blob, or File
+* @param options - Parsing options
+* @returns Promise resolving to Document
+* @throws {Error} if parsing fails
+*/
+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 warnings = [];
+	try {
+		const timeStage = (_name, fn) => fn();
+		const timeStageAsync = async (_name, fn) => await fn();
+		onProgress("Extracting DOCX...", 0);
+		const raw = await timeStageAsync("unzip", () => unzipDocx(buffer, unzipLimits));
+		warnings.push(...raw.warnings);
+		onProgress("Extracted DOCX", 10);
+		onProgress("Parsing relationships...", 10);
+		const rels = timeStage("relationships", () => raw.documentRels ? parseRelationships(raw.documentRels) : /* @__PURE__ */ new Map());
+		onProgress("Parsed relationships", 15);
+		onProgress("Parsing theme...", 15);
+		const theme = timeStage("theme", () => parseTheme(raw.themeXml));
+		const settings = timeStage("settings", () => parseSettings(raw.settingsXml));
+		applyThemeFontLang(theme, settings.themeFontLang);
+		onProgress("Parsed theme", 20);
+		onProgress("Parsing styles...", 20);
+		let styles = null;
+		let styleDefinitions;
+		timeStage("styles", () => {
+			if (raw.stylesXml) {
+				const parsedStyles = parseStylesPackage(raw.stylesXml, theme);
+				styles = parsedStyles.styles;
+				styleDefinitions = parsedStyles.styleDefinitions;
+			}
+		});
+		onProgress("Parsed styles", 30);
+		onProgress("Parsing numbering...", 30);
+		const numbering = timeStage("numbering", () => parseNumbering(raw.numberingXml));
+		onProgress("Parsed numbering", 35);
+		onProgress("Processing media files...", 35);
+		const media = await timeStageAsync("media", () => buildMediaMap(raw, rels));
+		onProgress("Processed media", 40);
+		onProgress("Parsing document body...", 40);
+		let documentBody = { content: [] };
+		timeStage("documentBody", () => {
+			if (raw.documentXml) documentBody = parseDocumentBody(raw.documentXml, styles, theme, numbering, rels, media);
+			else warnings.push("No document.xml found in DOCX");
+		});
+		onProgress("Parsed document body", 55);
+		let headers;
+		let footers;
+		if (parseHeadersFooters) {
+			onProgress("Parsing headers/footers...", 55);
+			const hf = timeStage("headersFooters", () => parseHeadersAndFooters(raw, styles, theme, numbering, rels, media));
+			headers = hf.headers;
+			footers = hf.footers;
+			onProgress("Parsed headers/footers", 65);
+		} else onProgress("Skipping headers/footers", 65);
+		let footnotes;
+		let endnotes;
+		if (parseNotes) {
+			onProgress("Parsing footnotes/endnotes...", 65);
+			const notes = timeStage("footnotesEndnotes", () => parseNotesContent(raw, styles, theme, numbering, rels, media));
+			footnotes = notes.footnotes;
+			endnotes = notes.endnotes;
+			onProgress("Parsed footnotes/endnotes", 75);
+		} else onProgress("Skipping footnotes/endnotes", 75);
+		onProgress("Parsing comments...", 75);
+		const comments = timeStage("comments", () => parseComments(raw.commentsXml, styles, theme, rels, media, raw.commentsExtensibleXml, raw.commentsExtendedXml));
+		if (comments.length > 0) documentBody.comments = comments;
+		const commentReferenceNormalization = normalizeCommentReferences({
+			documentBody,
+			comments,
+			...headers !== void 0 ? { headers } : {},
+			...footers !== void 0 ? { footers } : {},
+			...footnotes !== void 0 ? { footnotes } : {},
+			...endnotes !== void 0 ? { endnotes } : {}
+		});
+		if (commentReferenceNormalization.removedDanglingReferences > 0) warnings.push(`Removed ${commentReferenceNormalization.removedDanglingReferences} dangling comment reference marker(s) whose comments.xml entries are missing.`);
+		if (commentReferenceNormalization.reanchoredUnbalancedRanges > 0) warnings.push(`Re-anchored ${commentReferenceNormalization.reanchoredUnbalancedRanges} unbalanced comment range marker(s) as point comments.`);
+		const headerFooterReferenceNormalization = normalizeHeaderFooterReferences({
+			documentBody,
+			...headers !== void 0 ? { headers } : {},
+			...footers !== void 0 ? { footers } : {}
+		});
+		if (headerFooterReferenceNormalization.removedDanglingHeaderReferences > 0) warnings.push(`Removed ${headerFooterReferenceNormalization.removedDanglingHeaderReferences} dangling header reference(s) whose header parts are missing.`);
+		if (headerFooterReferenceNormalization.removedDanglingFooterReferences > 0) warnings.push(`Removed ${headerFooterReferenceNormalization.removedDanglingFooterReferences} dangling footer reference(s) whose footer parts are missing.`);
+		const numberingReferenceNormalization = normalizeNumberingReferences({
+			documentBody,
+			numbering,
+			...headers !== void 0 ? { headers } : {},
+			...footers !== void 0 ? { footers } : {},
+			...footnotes !== void 0 ? { footnotes } : {},
+			...endnotes !== void 0 ? { endnotes } : {}
+		});
+		if (numberingReferenceNormalization.removedMissingNumberingReferences > 0) warnings.push(`Removed ${numberingReferenceNormalization.removedMissingNumberingReferences} numbering reference(s) whose numbering definitions are missing.`);
+		const trackedMoveRangeNormalization = normalizeTrackedMoveRanges({
+			documentBody,
+			...headers !== void 0 ? { headers } : {},
+			...footers !== void 0 ? { footers } : {},
+			...footnotes !== void 0 ? { footnotes } : {},
+			...endnotes !== void 0 ? { endnotes } : {}
+		});
+		if (trackedMoveRangeNormalization.removedUnbalancedMoveRangeMarkers > 0) warnings.push(`Removed ${trackedMoveRangeNormalization.removedUnbalancedMoveRangeMarkers} unbalanced tracked move range marker(s).`);
+		let templateVariables;
+		if (detectVariables) {
+			onProgress("Detecting template variables...", 75);
+			templateVariables = timeStage("variables", () => extractAllTemplateVariables(documentBody.content));
+			onProgress("Detected variables", 80);
+		} else onProgress("Skipping variable detection", 80);
+		onProgress("Extracting fonts...", 80);
+		const requiredFonts = timeStage("fontExtract", () => extractDocumentFontNames(theme, styleDefinitions, documentBody));
+		onProgress("Extracted fonts", 90);
+		if (preloadFonts) {
+			onProgress("Loading fonts...", 90);
+			await timeStageAsync("fonts", () => loadFontsWithMapping(requiredFonts));
+			onProgress("Loaded fonts", 95);
+		} else onProgress("Skipping font loading", 95);
+		onProgress("Assembling document...", 95);
+		const document = {
+			package: {
+				document: documentBody,
+				settings,
+				...styleDefinitions !== void 0 ? { styles: styleDefinitions } : {},
+				theme,
+				numbering: numbering.definitions,
+				...headers !== void 0 ? { headers } : {},
+				...footers !== void 0 ? { footers } : {},
+				...footnotes !== void 0 ? { footnotes } : {},
+				...endnotes !== void 0 ? { endnotes } : {},
+				relationships: rels,
+				media
+			},
+			originalBuffer: raw.originalBuffer,
+			...templateVariables !== void 0 ? { templateVariables } : {},
+			...requiredFonts.length > 0 ? { requiredFonts } : {}
+		};
+		const validation = validateFolioDocumentModel(document);
+		const parsedCompleteModel = parseHeadersFooters && parseNotes;
+		if (!validation.valid && parsedCompleteModel) throw new DocxModelValidationError("Parsed DOCX produced an invalid document model", validation.issues);
+		warnings.push(...formatDocumentModelIssues(validation.issues));
+		if (warnings.length > 0) document.warnings = warnings;
+		onProgress("Complete", 100);
+		return document;
+	} catch (error) {
+		throw new DocxParseError({
+			message: `Failed to parse DOCX: ${error instanceof Error ? error.message : String(error)}`,
+			cause: error
+		});
+	}
+}
+/** DOCX parsing failure: malformed package, unsupported feature, or
+*  upstream parser exception. Wraps the original cause for diagnostics. */
+var DocxParseError = class extends TaggedError("DocxParseError")() {};
+/**
+* Build media file map from raw content and relationships
+*/
+async function buildMediaMap(raw, _rels) {
+	const media = /* @__PURE__ */ new Map();
+	for (const [path, data] of raw.media.entries()) {
+		const filename = path.split("/").pop() || path;
+		const mimeType = getMediaMimeType(path);
+		if (isTiffMimeType(mimeType)) {
+			const converted = await convertTiffToPngDataUrl(data);
+			if (converted) {
+				const mediaFile = {
+					path,
+					filename: filename.replace(/\.tiff?$/iu, ".png"),
+					mimeType: "image/png",
+					data: converted.data,
+					dataUrl: converted.dataUrl
+				};
+				media.set(path, mediaFile);
+				const normalizedPath = path.replace(/^word\//u, "");
+				if (normalizedPath !== path) media.set(normalizedPath, mediaFile);
+				continue;
+			}
+		}
+		const mediaFile = {
+			path,
+			filename,
+			mimeType,
+			data
+		};
+		attachLazyDataUrl(mediaFile);
+		media.set(path, mediaFile);
+		const normalizedPath = path.replace(/^word\//u, "");
+		if (normalizedPath !== path) media.set(normalizedPath, mediaFile);
+	}
+	return media;
+}
+function attachLazyDataUrl(mediaFile) {
+	let cachedDataUrl;
+	Object.defineProperty(mediaFile, "dataUrl", {
+		configurable: true,
+		enumerable: false,
+		get() {
+			cachedDataUrl ??= mediaToDataUrl(mediaFile.data, mediaFile.mimeType);
+			return cachedDataUrl;
+		}
+	});
+}
+/**
+* Parse headers and footers from raw content
+*/
+/**
+* Case-insensitive lookup in a Map
+* ZIP files may have inconsistent casing for paths/filenames
+*/
+function getMapCaseInsensitive(map, targetKey) {
+	const lowerTarget = targetKey.toLowerCase();
+	for (const [key, value] of map.entries()) if (key.toLowerCase() === lowerTarget) return value;
+}
+const DOCUMENT_RELATIONSHIPS_PATH = "word/_rels/document.xml.rels";
+function getRelationshipPartPath(target) {
+	return resolveRelativePath(DOCUMENT_RELATIONSHIPS_PATH, target);
+}
+function getRelationshipsPathForPart(partPath) {
+	const lastSlash = partPath.lastIndexOf("/");
+	const directory = lastSlash === -1 ? "" : partPath.slice(0, lastSlash);
+	const filename = lastSlash === -1 ? partPath : partPath.slice(lastSlash + 1);
+	return `${directory ? `${directory}/` : ""}_rels/${filename}.rels`;
+}
+function getHeaderFooterXml(raw, partPath, indexedParts) {
+	const filename = partPath.split("/").pop() ?? partPath;
+	return getMapCaseInsensitive(raw.allXml, partPath) ?? getMapCaseInsensitive(indexedParts, filename);
+}
+function parseHeadersAndFooters(raw, styles, theme, numbering, rels, media) {
+	const headers = /* @__PURE__ */ new Map();
+	const footers = /* @__PURE__ */ new Map();
+	for (const [rId, rel] of rels.entries()) if (rel.type === RELATIONSHIP_TYPES.header && rel.target) {
+		const partPath = getRelationshipPartPath(rel.target);
+		const headerXml = getHeaderFooterXml(raw, partPath, raw.headers);
+		if (headerXml) {
+			const headerRelsPath = getRelationshipsPathForPart(partPath);
+			const headerRelsXml = getMapCaseInsensitive(raw.allXml, headerRelsPath);
+			const headerRels = headerRelsXml ? parseRelationships(headerRelsXml) : rels;
+			const header = parseHeader(headerXml, "default", styles, theme, numbering, headerRels, media);
+			const watermark = header.watermark;
+			if (watermark?.kind === "picture") {
+				const imageRel = headerRels.get(watermark.imageRId);
+				if (imageRel?.type === RELATIONSHIP_TYPES.image && imageRel.target) if (imageRel.targetMode === "External") {
+					watermark.imageTarget = imageRel.target;
+					watermark.imageTargetExternal = true;
+				} else watermark.imageTarget = resolveRelativePath(headerRelsPath, imageRel.target);
+			}
+			headers.set(rId, header);
+		}
+	} else if (rel.type === RELATIONSHIP_TYPES.footer && rel.target) {
+		const partPath = getRelationshipPartPath(rel.target);
+		const footerXml = getHeaderFooterXml(raw, partPath, raw.footers);
+		if (footerXml) {
+			const footerRelsPath = getRelationshipsPathForPart(partPath);
+			const footerRelsXml = getMapCaseInsensitive(raw.allXml, footerRelsPath);
+			const footer = parseFooter(footerXml, "default", styles, theme, numbering, footerRelsXml ? parseRelationships(footerRelsXml) : rels, media);
+			footers.set(rId, footer);
+		}
+	}
+	return {
+		headers,
+		footers
+	};
+}
+/**
+* Parse footnotes and endnotes from raw content
+*/
+function parseNotesContent(raw, styles, theme, numbering, rels, media) {
+	const footnoteMap = parseFootnotes(raw.footnotesXml, styles, theme, numbering, rels, media);
+	const endnoteMap = parseEndnotes(raw.endnotesXml, styles, theme, numbering, rels, media);
+	return {
+		footnotes: footnoteMap.getNormalFootnotes(),
+		endnotes: endnoteMap.getNormalEndnotes()
+	};
+}
+/**
+* Extract all font family names referenced in the document (synchronous, no network).
+* Returns a deduplicated array suitable for passing to `loadFontsWithMapping`.
+*/
+function extractDocumentFontNames(theme, styleDefinitions, documentBody) {
+	const docxFonts = /* @__PURE__ */ new Set();
+	if (theme?.fontScheme) {
+		const { majorFont, minorFont } = theme.fontScheme;
+		if (majorFont?.latin) docxFonts.add(majorFont.latin);
+		if (minorFont?.latin) docxFonts.add(minorFont.latin);
+	}
+	if (styleDefinitions?.docDefaults?.rPr?.fontFamily?.ascii) docxFonts.add(styleDefinitions.docDefaults.rPr.fontFamily.ascii);
+	if (styleDefinitions?.styles) for (const style of styleDefinitions.styles) {
+		if (style.rPr?.fontFamily?.ascii) docxFonts.add(style.rPr.fontFamily.ascii);
+		if (style.rPr?.fontFamily?.hAnsi) docxFonts.add(style.rPr.fontFamily.hAnsi);
+	}
+	for (const block of documentBody.content) if (block.type === "paragraph") {
+		for (const item of block.content) if (item.type === "run" && item.formatting?.fontFamily) {
+			if (item.formatting.fontFamily.ascii) docxFonts.add(item.formatting.fontFamily.ascii);
+			if (item.formatting.fontFamily.hAnsi) docxFonts.add(item.formatting.fontFamily.hAnsi);
+		}
+	}
+	return Array.from(docxFonts);
+}
+/**
+* Quick parse - parse a DOCX without font loading
+* Useful for quick content extraction or when fonts aren't needed
+*/
+function quickParseDocx(buffer) {
+	return parseDocx(buffer, {
+		preloadFonts: false,
+		parseHeadersFooters: false,
+		parseNotes: false,
+		detectVariables: true
+	});
+}
+/**
+* Full parse - parse everything including fonts
+*/
+function fullParseDocx(buffer, onProgress) {
+	return parseDocx(buffer, {
+		...onProgress !== void 0 ? { onProgress } : {},
+		preloadFonts: true,
+		parseHeadersFooters: true,
+		parseNotes: true,
+		detectVariables: true
+	});
+}
+/**
+* Get template variables from a DOCX without full parsing
+* Faster than full parse when you only need variables
+*/
+async function getDocxVariables(buffer) {
+	const raw = await unzipDocx(buffer);
+	if (!raw.documentXml) return [];
+	return extractAllTemplateVariables(parseDocumentBody(raw.documentXml).content);
+}
+/**
+* Get document summary without full parsing
+*/
+async function getDocxSummary(buffer) {
+	const raw = await unzipDocx(buffer);
+	const variables = raw.documentXml ? extractAllTemplateVariables(parseDocumentBody(raw.documentXml).content) : [];
+	return {
+		hasDocument: raw.documentXml !== null,
+		hasStyles: raw.stylesXml !== null,
+		hasTheme: raw.themeXml !== null,
+		hasNumbering: raw.numberingXml !== null,
+		headerCount: raw.headers.size,
+		footerCount: raw.footers.size,
+		mediaCount: raw.media.size,
+		variableCount: variables.length
+	};
+}
+//#endregion
+export { DocxParseError, fullParseDocx, getDocxSummary, getDocxVariables, parseDocx, quickParseDocx };

package/dist/docx/parserEnums.d.ts

@@ -0,0 +1,45 @@
+import * as v from "valibot";
+
+//#region src/docx/parserEnums.d.ts
+/**
+ * Narrow a raw attribute string to a picklist member, or `undefined`
+ * if the value isn't recognised. The cast lives once inside the
+ * valibot output type; callers receive a properly-typed value with
+ * no `as` at the call site.
+ */
+declare const narrowEnum: <T extends string>(value: string | null | undefined, schema: v.PicklistSchema<readonly T[], undefined>) => T | undefined;
+declare const ThemeColorSlotSchema: v.PicklistSchema<readonly ["dk1", "lt1", "dk2", "lt2", "accent1", "accent2", "accent3", "accent4", "accent5", "accent6", "hlink", "folHlink", "background1", "text1", "background2", "text2"], undefined>;
+declare const BorderStyleSchema: v.PicklistSchema<readonly ["none", "single", "double", "dotted", "dashed", "thick", "triple", "thinThickSmallGap", "thickThinSmallGap", "thinThickMediumGap", "thickThinMediumGap", "thinThickLargeGap", "thickThinLargeGap", "wave", "doubleWave", "dashSmallGap", "dashDotStroked", "threeDEmboss", "threeDEngrave", "outset", "inset", "nil"], undefined>;
+declare const UnderlineStyleSchema: v.PicklistSchema<readonly ["none", "single", "words", "double", "thick", "dotted", "dottedHeavy", "dash", "dashedHeavy", "dashLong", "dashLongHeavy", "dotDash", "dashDotHeavy", "dotDotDash", "dashDotDotHeavy", "wave", "wavyHeavy", "wavyDouble"], undefined>;
+declare const HighlightColorSchema: v.PicklistSchema<readonly ["black", "blue", "cyan", "darkBlue", "darkCyan", "darkGray", "darkGreen", "darkMagenta", "darkRed", "darkYellow", "green", "lightGray", "magenta", "none", "red", "white", "yellow"], undefined>;
+declare const TextEffectSchema: v.PicklistSchema<readonly ["none", "blinkBackground", "lights", "antsBlack", "antsRed", "shimmer", "sparkle"], undefined>;
+declare const EmphasisMarkSchema: v.PicklistSchema<readonly ["none", "dot", "comma", "circle", "underDot"], undefined>;
+declare const FontThemeSchema: v.PicklistSchema<readonly ["majorAscii", "majorHAnsi", "majorEastAsia", "majorBidi", "minorAscii", "minorHAnsi", "minorEastAsia", "minorBidi"], undefined>;
+declare const ParagraphAlignmentSchema: v.PicklistSchema<readonly ["left", "center", "right", "both", "distribute", "mediumKashida", "highKashida", "lowKashida", "thaiDistribute"], undefined>;
+declare const LineSpacingRuleSchema: v.PicklistSchema<readonly ["auto", "exact", "atLeast"], undefined>;
+declare const TabStopAlignmentSchema: v.PicklistSchema<readonly ["left", "center", "right", "decimal", "bar", "clear", "num"], undefined>;
+declare const TabLeaderSchema: v.PicklistSchema<readonly ["none", "dot", "hyphen", "underscore", "heavy", "middleDot"], undefined>;
+declare const FrameXAlignSchema: v.PicklistSchema<readonly ["left", "center", "right", "inside", "outside"], undefined>;
+declare const FrameYAlignSchema: v.PicklistSchema<readonly ["top", "center", "bottom", "inside", "outside", "inline"], undefined>;
+declare const FrameWrapSchema: v.PicklistSchema<readonly ["around", "auto", "none", "notBeside", "through", "tight"], undefined>;
+declare const SdtLockSchema: v.PicklistSchema<readonly ["sdtLocked", "contentLocked", "sdtContentLocked", "unlocked"], undefined>;
+declare const FieldTypeSchema: v.PicklistSchema<readonly ["PAGE", "NUMPAGES", "NUMWORDS", "NUMCHARS", "DATE", "TIME", "CREATEDATE", "SAVEDATE", "PRINTDATE", "AUTHOR", "TITLE", "SUBJECT", "KEYWORDS", "COMMENTS", "FILENAME", "FILESIZE", "TEMPLATE", "DOCPROPERTY", "DOCVARIABLE", "REF", "PAGEREF", "NOTEREF", "HYPERLINK", "TOC", "TOA", "INDEX", "SEQ", "STYLEREF", "AUTONUM", "AUTONUMLGL", "AUTONUMOUT", "LISTNUM", "IF", "MERGEFIELD", "NEXT", "NEXTIF", "ASK", "SET", "QUOTE", "INCLUDETEXT", "INCLUDEPICTURE", "SYMBOL", "ADVANCE", "EDITTIME", "REVNUM", "SECTION", "SECTIONPAGES", "USERADDRESS", "USERNAME", "USERINITIALS", "UNKNOWN"], undefined>;
+declare const StyleTypeSchema: v.PicklistSchema<readonly ["paragraph", "character", "numbering", "table"], undefined>;
+declare const ConditionalStyleTypeSchema: v.PicklistSchema<readonly ["band1Horz", "band1Vert", "band2Horz", "band2Vert", "firstCol", "firstRow", "lastCol", "lastRow", "neCell", "nwCell", "seCell", "swCell", "wholeTable"], undefined>;
+declare const TableWidthTypeSchema: v.PicklistSchema<readonly ["auto", "dxa", "nil", "pct"], undefined>;
+declare const TableRowHeightRuleSchema: v.PicklistSchema<readonly ["auto", "atLeast", "exact"], undefined>;
+declare const TableCellTextDirectionSchema: v.PicklistSchema<readonly ["lr", "lrV", "rl", "rlV", "tb", "tbV", "tbRl", "tbRlV", "btLr"], undefined>;
+declare const ShadingPatternSchema: v.PicklistSchema<readonly ["clear", "solid", "horzStripe", "vertStripe", "reverseDiagStripe", "diagStripe", "horzCross", "diagCross", "thinHorzStripe", "thinVertStripe", "thinReverseDiagStripe", "thinDiagStripe", "thinHorzCross", "thinDiagCross", "pct5", "pct10", "pct12", "pct15", "pct20", "pct25", "pct30", "pct35", "pct37", "pct40", "pct45", "pct50", "pct55", "pct60", "pct62", "pct65", "pct70", "pct75", "pct80", "pct85", "pct87", "pct90", "pct95", "nil"], undefined>;
+declare const FloatingTableXSpecSchema: v.PicklistSchema<readonly ["left", "center", "right", "inside", "outside"], undefined>;
+declare const FloatingTableYSpecSchema: v.PicklistSchema<readonly ["top", "center", "bottom", "inside", "outside", "inline"], undefined>;
+declare const ImageHorizontalRelativeToSchema: v.PicklistSchema<readonly ["character", "column", "insideMargin", "leftMargin", "margin", "outsideMargin", "page", "rightMargin"], undefined>;
+declare const ImageHorizontalAlignmentSchema: v.PicklistSchema<readonly ["left", "right", "center", "inside", "outside"], undefined>;
+declare const ImageVerticalRelativeToSchema: v.PicklistSchema<readonly ["insideMargin", "line", "margin", "outsideMargin", "page", "paragraph", "topMargin", "bottomMargin"], undefined>;
+declare const ImageVerticalAlignmentSchema: v.PicklistSchema<readonly ["top", "bottom", "center", "inside", "outside"], undefined>;
+declare const ImageWrapTextSchema: v.PicklistSchema<readonly ["bothSides", "left", "right", "largest"], undefined>;
+declare const ShapeOutlineStyleSchema: v.PicklistSchema<readonly ["solid", "dot", "dash", "lgDash", "dashDot", "lgDashDot", "lgDashDotDot", "sysDot", "sysDash", "sysDashDot", "sysDashDotDot"], undefined>;
+declare const ShapeTypeSchema: v.PicklistSchema<readonly ["rect", "roundRect", "ellipse", "triangle", "rtTriangle", "parallelogram", "trapezoid", "pentagon", "hexagon", "heptagon", "octagon", "decagon", "dodecagon", "star4", "star5", "star6", "star7", "star8", "star10", "star12", "star16", "star24", "star32", "line", "straightConnector1", "bentConnector2", "bentConnector3", "bentConnector4", "bentConnector5", "curvedConnector2", "curvedConnector3", "curvedConnector4", "curvedConnector5", "rightArrow", "leftArrow", "upArrow", "downArrow", "leftRightArrow", "upDownArrow", "quadArrow", "leftRightUpArrow", "bentArrow", "uturnArrow", "leftUpArrow", "bentUpArrow", "curvedRightArrow", "curvedLeftArrow", "curvedUpArrow", "curvedDownArrow", "stripedRightArrow", "notchedRightArrow", "homePlate", "chevron", "rightArrowCallout", "downArrowCallout", "leftArrowCallout", "upArrowCallout", "leftRightArrowCallout", "quadArrowCallout", "circularArrow", "flowChartProcess", "flowChartAlternateProcess", "flowChartDecision", "flowChartInputOutput", "flowChartPredefinedProcess", "flowChartInternalStorage", "flowChartDocument", "flowChartMultidocument", "flowChartTerminator", "flowChartPreparation", "flowChartManualInput", "flowChartManualOperation", "flowChartConnector", "flowChartOffpageConnector", "flowChartPunchedCard", "flowChartPunchedTape", "flowChartSummingJunction", "flowChartOr", "flowChartCollate", "flowChartSort", "flowChartExtract", "flowChartMerge", "flowChartOnlineStorage", "flowChartDelay", "flowChartMagneticTape", "flowChartMagneticDisk", "flowChartMagneticDrum", "flowChartDisplay", "wedgeRectCallout", "wedgeRoundRectCallout", "wedgeEllipseCallout", "cloudCallout", "borderCallout1", "borderCallout2", "borderCallout3", "accentCallout1", "accentCallout2", "accentCallout3", "callout1", "callout2", "callout3", "accentBorderCallout1", "accentBorderCallout2", "accentBorderCallout3", "actionButtonBlank", "actionButtonHome", "actionButtonHelp", "actionButtonInformation", "actionButtonBackPrevious", "actionButtonForwardNext", "actionButtonBeginning", "actionButtonEnd", "actionButtonReturn", "actionButtonDocument", "actionButtonSound", "actionButtonMovie", "irregularSeal1", "irregularSeal2", "frame", "halfFrame", "corner", "diagStripe", "chord", "arc", "bracketPair", "bracePair", "leftBracket", "rightBracket", "leftBrace", "rightBrace", "can", "cube", "bevel", "donut", "noSmoking", "blockArc", "foldedCorner", "smileyFace", "heart", "lightningBolt", "sun", "moon", "cloud", "snip1Rect", "snip2SameRect", "snip2DiagRect", "snipRoundRect", "round1Rect", "round2SameRect", "round2DiagRect", "plaque", "teardrop", "mathPlus", "mathMinus", "mathMultiply", "mathDivide", "mathEqual", "mathNotEqual", "gear6", "gear9", "funnel", "pieWedge", "pie", "leftCircularArrow", "leftRightCircularArrow", "swooshArrow", "textBox"], undefined>;
+declare const NumberFormatSchema: v.PicklistSchema<readonly ["decimal", "upperRoman", "lowerRoman", "upperLetter", "lowerLetter", "ordinal", "cardinalText", "ordinalText", "hex", "chicago", "ideographDigital", "japaneseCounting", "aiueo", "iroha", "decimalFullWidth", "decimalHalfWidth", "japaneseLegal", "japaneseDigitalTenThousand", "decimalEnclosedCircle", "decimalFullWidth2", "aiueoFullWidth", "irohaFullWidth", "decimalZero", "decimalZero3", "decimalZero4", "decimalZero5", "bullet", "ganada", "chosung", "decimalEnclosedFullstop", "decimalEnclosedParen", "decimalEnclosedCircleChinese", "ideographEnclosedCircle", "ideographTraditional", "ideographZodiac", "ideographZodiacTraditional", "taiwaneseCounting", "ideographLegalTraditional", "taiwaneseCountingThousand", "taiwaneseDigital", "chineseCounting", "chineseLegalSimplified", "chineseCountingThousand", "koreanDigital", "koreanCounting", "koreanLegal", "koreanDigital2", "vietnameseCounting", "russianLower", "russianUpper", "none", "numberInDash", "hebrew1", "hebrew2", "arabicAlpha", "arabicAbjad", "hindiVowels", "hindiConsonants", "hindiNumbers", "hindiCounting", "thaiLetters", "thaiNumbers", "thaiCounting"], undefined>;
+declare const LevelSuffixSchema: v.PicklistSchema<readonly ["tab", "space", "nothing"], undefined>;
+//#endregion
+export { BorderStyleSchema, ConditionalStyleTypeSchema, EmphasisMarkSchema, FieldTypeSchema, FloatingTableXSpecSchema, FloatingTableYSpecSchema, FontThemeSchema, FrameWrapSchema, FrameXAlignSchema, FrameYAlignSchema, HighlightColorSchema, ImageHorizontalAlignmentSchema, ImageHorizontalRelativeToSchema, ImageVerticalAlignmentSchema, ImageVerticalRelativeToSchema, ImageWrapTextSchema, LevelSuffixSchema, LineSpacingRuleSchema, NumberFormatSchema, ParagraphAlignmentSchema, SdtLockSchema, ShadingPatternSchema, ShapeOutlineStyleSchema, ShapeTypeSchema, StyleTypeSchema, TabLeaderSchema, TabStopAlignmentSchema, TableCellTextDirectionSchema, TableRowHeightRuleSchema, TableWidthTypeSchema, TextEffectSchema, ThemeColorSlotSchema, UnderlineStyleSchema, narrowEnum };