@stll/folio-core 0.3.1 → 0.5.0

package/dist/docx/encryption/encryptionInfo.js

@@ -0,0 +1,128 @@
+import { decodeBase64 } from "./cryptoBytes.js";
+import { DOCX_ENCRYPTION_ERROR_CODES, DocxEncryptionError } from "./errors.js";
+//#region src/docx/encryption/encryptionInfo.ts
+/**
+* Parse the EncryptionInfo stream for Agile Encryption (Office 2010+).
+*
+* @see https://learn.microsoft.com/en-us/openspecs/office_file_formats/ms-offcrypto/87020a34-e73f-4139-99bc-bbdf6cf6fa55
+*/
+const AGILE_STREAM_VERSION = 4;
+const AGILE_STREAM_KIND = 4;
+const STANDARD_STREAM_KIND = 3;
+const STREAM_PREFIX_BYTES = 8;
+const readUint16Le = (bytes, offset) => bytes[offset] | bytes[offset + 1] << 8;
+const findElement = (xml, localName) => {
+	let index = 0;
+	while (index < xml.length) {
+		const hit = xml.indexOf(localName, index);
+		if (hit === -1) return null;
+		const tagStart = xml.lastIndexOf("<", hit);
+		if (tagStart === -1 || hit - tagStart > 24) {
+			index = hit + localName.length;
+			continue;
+		}
+		const tagEnd = xml.indexOf(">", hit);
+		if (tagEnd === -1) return null;
+		const tag = xml.slice(tagStart, tagEnd + 1);
+		if (tag.includes(localName)) return tag;
+		index = hit + localName.length;
+	}
+	return null;
+};
+const parseAttributes = (tag) => {
+	const attrs = {};
+	let i = tag.indexOf(" ");
+	if (i === -1) return attrs;
+	while (i < tag.length) {
+		while (i < tag.length && (tag[i] === " " || tag[i] === "\n" || tag[i] === "\r" || tag[i] === "	")) i++;
+		const nameStart = i;
+		while (i < tag.length && tag[i] !== "=" && tag[i] !== ">" && tag[i] !== "/") i++;
+		if (i >= tag.length || tag[i] !== "=") break;
+		const name = tag.slice(nameStart, i).trim();
+		i++;
+		const quote = tag[i];
+		if (quote !== "\"" && quote !== "'") break;
+		i++;
+		const valueStart = i;
+		while (i < tag.length && tag[i] !== quote) i++;
+		if (i >= tag.length) break;
+		attrs[name] = tag.slice(valueStart, i);
+		i++;
+	}
+	return attrs;
+};
+const requireAttr = (attrs, name, element) => {
+	const value = attrs[name];
+	if (value === void 0) throw new DocxEncryptionError({
+		code: DOCX_ENCRYPTION_ERROR_CODES.DECRYPTION_FAILED,
+		message: `EncryptionInfo <${element}> missing attribute "${name}"`
+	});
+	return value;
+};
+const requireInt = (attrs, name, element) => {
+	const parsed = Number.parseInt(requireAttr(attrs, name, element), 10);
+	if (Number.isNaN(parsed)) throw new DocxEncryptionError({
+		code: DOCX_ENCRYPTION_ERROR_CODES.DECRYPTION_FAILED,
+		message: `EncryptionInfo <${element}> attribute "${name}" is not an integer`
+	});
+	return parsed;
+};
+const requireBase64 = (attrs, name, element) => decodeBase64(requireAttr(attrs, name, element));
+const parseAgileXml = (xmlBytes) => {
+	const xml = new TextDecoder("utf-8").decode(xmlBytes);
+	const keyDataTag = findElement(xml, "keyData");
+	const integrityTag = findElement(xml, "dataIntegrity");
+	const encryptedKeyTag = findElement(xml, "encryptedKey");
+	if (!keyDataTag || !integrityTag || !encryptedKeyTag) throw new DocxEncryptionError({
+		code: DOCX_ENCRYPTION_ERROR_CODES.DECRYPTION_FAILED,
+		message: "EncryptionInfo XML is missing required agile encryption elements"
+	});
+	const keyData = parseAttributes(keyDataTag);
+	const integrity = parseAttributes(integrityTag);
+	const encryptedKey = parseAttributes(encryptedKeyTag);
+	return {
+		packageSalt: requireBase64(keyData, "saltValue", "keyData"),
+		packageKeyBits: requireInt(keyData, "keyBits", "keyData"),
+		packageHash: requireAttr(keyData, "hashAlgorithm", "keyData"),
+		packageHashBytes: requireInt(keyData, "hashSize", "keyData"),
+		cipherBlockBytes: requireInt(keyData, "blockSize", "keyData"),
+		cipherName: requireAttr(keyData, "cipherAlgorithm", "keyData"),
+		cipherMode: requireAttr(keyData, "cipherChaining", "keyData"),
+		passwordIterations: requireInt(encryptedKey, "spinCount", "encryptedKey"),
+		passwordSalt: requireBase64(encryptedKey, "saltValue", "encryptedKey"),
+		passwordHash: requireAttr(encryptedKey, "hashAlgorithm", "encryptedKey"),
+		passwordKeyBits: requireInt(encryptedKey, "keyBits", "encryptedKey"),
+		passwordBlockBytes: requireInt(encryptedKey, "blockSize", "encryptedKey"),
+		encryptedVerifierInput: requireBase64(encryptedKey, "encryptedVerifierHashInput", "encryptedKey"),
+		encryptedVerifierDigest: requireBase64(encryptedKey, "encryptedVerifierHashValue", "encryptedKey"),
+		encryptedIntermediateKey: requireBase64(encryptedKey, "encryptedKeyValue", "encryptedKey"),
+		encryptedIntegrityKey: requireBase64(integrity, "encryptedHmacKey", "dataIntegrity"),
+		encryptedIntegrityDigest: requireBase64(integrity, "encryptedHmacValue", "dataIntegrity")
+	};
+};
+const parseAgileEncryptionInfo = (stream) => {
+	if (stream.length < STREAM_PREFIX_BYTES) throw new DocxEncryptionError({
+		code: DOCX_ENCRYPTION_ERROR_CODES.DECRYPTION_FAILED,
+		message: `EncryptionInfo stream too short (${stream.length} bytes)`
+	});
+	const version = readUint16Le(stream, 0);
+	const kind = readUint16Le(stream, 2);
+	if (version === AGILE_STREAM_VERSION && kind === AGILE_STREAM_KIND) return {
+		scheme: "agile",
+		material: parseAgileXml(stream.subarray(STREAM_PREFIX_BYTES))
+	};
+	if ((version === 3 || version === AGILE_STREAM_VERSION) && kind === STANDARD_STREAM_KIND) throw new DocxEncryptionError({
+		code: DOCX_ENCRYPTION_ERROR_CODES.ENCRYPTION_UNSUPPORTED,
+		message: "Standard Encryption (Office 2007) is not supported. Only Agile Encryption (Office 2010+) is supported."
+	});
+	if (version <= 2) throw new DocxEncryptionError({
+		code: DOCX_ENCRYPTION_ERROR_CODES.ENCRYPTION_UNSUPPORTED,
+		message: "Legacy RC4 encryption is not supported. Only Agile Encryption (Office 2010+) is supported."
+	});
+	throw new DocxEncryptionError({
+		code: DOCX_ENCRYPTION_ERROR_CODES.ENCRYPTION_UNSUPPORTED,
+		message: `Unrecognized EncryptionInfo header version=${version} kind=${kind}`
+	});
+};
+//#endregion
+export { parseAgileEncryptionInfo };

package/dist/docx/encryption/errors.d.ts

@@ -0,0 +1,18 @@
+//#region src/docx/encryption/errors.d.ts
+/** Machine-readable codes for password-protected OOXML failures. */
+declare const DOCX_ENCRYPTION_ERROR_CODES: {
+  readonly PASSWORD_REQUIRED: "DOCX_PASSWORD_REQUIRED";
+  readonly PASSWORD_INVALID: "DOCX_PASSWORD_INVALID";
+  readonly ENCRYPTION_UNSUPPORTED: "DOCX_ENCRYPTION_UNSUPPORTED";
+  readonly DECRYPTION_FAILED: "DOCX_DECRYPTION_FAILED";
+};
+type DocxEncryptionErrorCode = (typeof DOCX_ENCRYPTION_ERROR_CODES)[keyof typeof DOCX_ENCRYPTION_ERROR_CODES];
+declare const DocxEncryptionError_base: import("better-result").TaggedErrorClass<"DocxEncryptionError", {
+  message: string;
+  code: DocxEncryptionErrorCode;
+  cause?: unknown;
+}>;
+declare class DocxEncryptionError extends DocxEncryptionError_base {}
+declare const isDocxEncryptionError: (error: unknown) => error is DocxEncryptionError;
+//#endregion
+export { DOCX_ENCRYPTION_ERROR_CODES, DocxEncryptionError, DocxEncryptionErrorCode, isDocxEncryptionError };

package/dist/docx/encryption/errors.js

@@ -0,0 +1,13 @@
+import { TaggedError } from "better-result";
+//#region src/docx/encryption/errors.ts
+/** Machine-readable codes for password-protected OOXML failures. */
+const DOCX_ENCRYPTION_ERROR_CODES = {
+	PASSWORD_REQUIRED: "DOCX_PASSWORD_REQUIRED",
+	PASSWORD_INVALID: "DOCX_PASSWORD_INVALID",
+	ENCRYPTION_UNSUPPORTED: "DOCX_ENCRYPTION_UNSUPPORTED",
+	DECRYPTION_FAILED: "DOCX_DECRYPTION_FAILED"
+};
+var DocxEncryptionError = class extends TaggedError("DocxEncryptionError")() {};
+const isDocxEncryptionError = (error) => error instanceof DocxEncryptionError;
+//#endregion
+export { DOCX_ENCRYPTION_ERROR_CODES, DocxEncryptionError, isDocxEncryptionError };

package/dist/docx/encryption/index.d.ts

@@ -0,0 +1,4 @@
+import { DOCX_CONTAINER_TYPES, DocxContainerType, detectDocxContainerType } from "./containerFormat.js";
+import { DOCX_ENCRYPTION_ERROR_CODES, DocxEncryptionError, DocxEncryptionErrorCode, isDocxEncryptionError } from "./errors.js";
+import { DecryptDocxOptions, DecryptDocxResult, decryptDocxIfNeeded, openDocxBuffer } from "./openEncryptedDocx.js";
+export { DOCX_CONTAINER_TYPES, DOCX_ENCRYPTION_ERROR_CODES, type DecryptDocxOptions, type DecryptDocxResult, type DocxContainerType, DocxEncryptionError, type DocxEncryptionErrorCode, decryptDocxIfNeeded, detectDocxContainerType, isDocxEncryptionError, openDocxBuffer };

package/dist/docx/encryption/index.js

@@ -0,0 +1,4 @@
+import { DOCX_ENCRYPTION_ERROR_CODES, DocxEncryptionError, isDocxEncryptionError } from "./errors.js";
+import { DOCX_CONTAINER_TYPES, detectDocxContainerType } from "./containerFormat.js";
+import { decryptDocxIfNeeded, openDocxBuffer } from "./openEncryptedDocx.js";
+export { DOCX_CONTAINER_TYPES, DOCX_ENCRYPTION_ERROR_CODES, DocxEncryptionError, decryptDocxIfNeeded, detectDocxContainerType, isDocxEncryptionError, openDocxBuffer };

package/dist/docx/encryption/openEncryptedDocx.d.ts

@@ -0,0 +1,28 @@
+//#region src/docx/encryption/openEncryptedDocx.d.ts
+/**
+ * Decrypt password-protected OOXML before ZIP extraction.
+ *
+ * Implementation is derived from [MS-OFFCRYPTO] and [MS-CFB] only.
+ *
+ * @see https://learn.microsoft.com/en-us/openspecs/office_file_formats/ms-offcrypto/
+ */
+type DecryptDocxOptions = {
+  /** Password for Agile-encrypted .docx files (Office 2010+). */password?: string | undefined;
+};
+type DecryptDocxResult = {
+  /** Plaintext OOXML ZIP bytes, or the original buffer when unencrypted. */data: ArrayBuffer; /** True when the input was an encrypted CFB container and decryption ran. */
+  wasEncrypted: boolean;
+};
+/**
+ * Decrypt a password-protected `.docx` when needed, or return the input unchanged.
+ *
+ * Supports Agile Encryption (Office 2010+). Standard Encryption and legacy RC4
+ * are rejected with `DOCX_ENCRYPTION_UNSUPPORTED`.
+ *
+ * Save produces a standard unencrypted OOXML ZIP; folio does not re-encrypt on export.
+ */
+declare const decryptDocxIfNeeded: (data: ArrayBuffer | Uint8Array, options?: DecryptDocxOptions) => Promise<DecryptDocxResult>;
+/** Open a `.docx` buffer for parsing: decrypt when encrypted, then return the ZIP bytes. */
+declare const openDocxBuffer: (data: ArrayBuffer | Uint8Array, options?: DecryptDocxOptions) => Promise<ArrayBuffer>;
+//#endregion
+export { DecryptDocxOptions, DecryptDocxResult, decryptDocxIfNeeded, openDocxBuffer };

package/dist/docx/encryption/openEncryptedDocx.js

@@ -0,0 +1,65 @@
+import { toArrayBuffer } from "./cryptoBytes.js";
+import { DOCX_ENCRYPTION_ERROR_CODES, DocxEncryptionError } from "./errors.js";
+import { decryptAgileEncryptedPackage } from "./agileDecryption.js";
+import { readEncryptedPackageStreams } from "./compoundFile.js";
+import { DOCX_CONTAINER_TYPES, detectDocxContainerType } from "./containerFormat.js";
+import { parseAgileEncryptionInfo } from "./encryptionInfo.js";
+//#region src/docx/encryption/openEncryptedDocx.ts
+/**
+* Decrypt password-protected OOXML before ZIP extraction.
+*
+* Implementation is derived from [MS-OFFCRYPTO] and [MS-CFB] only.
+*
+* @see https://learn.microsoft.com/en-us/openspecs/office_file_formats/ms-offcrypto/
+*/
+const assertZipPayload = (bytes) => {
+	if (detectDocxContainerType(bytes) !== DOCX_CONTAINER_TYPES.ZIP) throw new DocxEncryptionError({
+		code: DOCX_ENCRYPTION_ERROR_CODES.DECRYPTION_FAILED,
+		message: "Decrypted output is not a valid ZIP archive — the file may be corrupt"
+	});
+};
+/**
+* Decrypt a password-protected `.docx` when needed, or return the input unchanged.
+*
+* Supports Agile Encryption (Office 2010+). Standard Encryption and legacy RC4
+* are rejected with `DOCX_ENCRYPTION_UNSUPPORTED`.
+*
+* Save produces a standard unencrypted OOXML ZIP; folio does not re-encrypt on export.
+*/
+const decryptDocxIfNeeded = async (data, options = {}) => {
+	const bytes = data instanceof Uint8Array ? data : new Uint8Array(data);
+	const container = detectDocxContainerType(bytes);
+	if (container === DOCX_CONTAINER_TYPES.ZIP) return {
+		data: toArrayBuffer(bytes),
+		wasEncrypted: false
+	};
+	if (container !== DOCX_CONTAINER_TYPES.CFB) throw new DocxEncryptionError({
+		code: DOCX_ENCRYPTION_ERROR_CODES.DECRYPTION_FAILED,
+		message: "Unrecognized file format — expected a .docx (ZIP) or encrypted .docx (OLE/CFB)"
+	});
+	if (options.password == null) throw new DocxEncryptionError({
+		code: DOCX_ENCRYPTION_ERROR_CODES.PASSWORD_REQUIRED,
+		message: "This document is password-protected. A password is required to open it."
+	});
+	let streams;
+	try {
+		streams = readEncryptedPackageStreams(bytes);
+	} catch (cause) {
+		throw new DocxEncryptionError({
+			code: DOCX_ENCRYPTION_ERROR_CODES.DECRYPTION_FAILED,
+			message: "Failed to read encrypted OOXML streams",
+			cause
+		});
+	}
+	const descriptor = parseAgileEncryptionInfo(streams.encryptionInfo);
+	const decryptedZip = await decryptAgileEncryptedPackage(options.password, descriptor.material, streams.encryptedPackage);
+	assertZipPayload(decryptedZip);
+	return {
+		data: toArrayBuffer(decryptedZip),
+		wasEncrypted: true
+	};
+};
+/** Open a `.docx` buffer for parsing: decrypt when encrypted, then return the ZIP bytes. */
+const openDocxBuffer = async (data, options = {}) => (await decryptDocxIfNeeded(data, options)).data;
+//#endregion
+export { decryptDocxIfNeeded, openDocxBuffer };

package/dist/docx/footnoteParser.d.ts

@@ -73,22 +73,6 @@ declare function isSeparatorFootnote(footnote: document_d_exports.Footnote): boo
  * Check if an endnote is a separator (not regular content)
  */
 declare function isSeparatorEndnote(endnote: document_d_exports.Endnote): boolean;
-/**
- * Get footnote number for display (excluding separators)
- * @param footnote - The footnote to get the number for
- * @param footnoteMap - The footnote map
- * @param startNumber - Starting number (default 1)
- * @returns The display number, or null for separator footnotes
- */
-declare function getFootnoteDisplayNumber(footnote: document_d_exports.Footnote, footnoteMap: FootnoteMap, startNumber?: number): number | null;
-/**
- * Get endnote number for display (excluding separators)
- * @param endnote - The endnote to get the number for
- * @param endnoteMap - The endnote map
- * @param startNumber - Starting number (default 1)
- * @returns The display number, or null for separator endnotes
- */
-declare function getEndnoteDisplayNumber(endnote: document_d_exports.Endnote, endnoteMap: EndnoteMap, startNumber?: number): number | null;
 /**
  * Create an empty footnote map
  */
@@ -106,4 +90,4 @@ declare function mergeFootnoteMaps(...maps: FootnoteMap[]): FootnoteMap;
  */
 declare function mergeEndnoteMaps(...maps: EndnoteMap[]): EndnoteMap;
 //#endregion
-export { EndnoteMap, FootnoteMap, createEmptyEndnoteMap, createEmptyFootnoteMap, getEndnoteDisplayNumber, getEndnoteText, getFootnoteDisplayNumber, getFootnoteText, isSeparatorEndnote, isSeparatorFootnote, mergeEndnoteMaps, mergeFootnoteMaps, parseEndnoteProperties, parseEndnotes, parseFootnoteProperties, parseFootnotes };
+export { EndnoteMap, FootnoteMap, createEmptyEndnoteMap, createEmptyFootnoteMap, getEndnoteText, getFootnoteText, isSeparatorEndnote, isSeparatorFootnote, mergeEndnoteMaps, mergeFootnoteMaps, parseEndnoteProperties, parseEndnotes, parseFootnoteProperties, parseFootnotes };

package/dist/docx/footnoteParser.js

@@ -205,32 +205,6 @@ function isSeparatorEndnote(endnote) {
 	return endnote.noteType === "separator" || endnote.noteType === "continuationSeparator" || endnote.noteType === "continuationNotice";
 }
 /**
-* Get footnote number for display (excluding separators)
-* @param footnote - The footnote to get the number for
-* @param footnoteMap - The footnote map
-* @param startNumber - Starting number (default 1)
-* @returns The display number, or null for separator footnotes
-*/
-function getFootnoteDisplayNumber(footnote, footnoteMap, startNumber = 1) {
-	if (isSeparatorFootnote(footnote)) return null;
-	const index = footnoteMap.getNormalFootnotes().findIndex((fn) => fn.id === footnote.id);
-	if (index === -1) return null;
-	return startNumber + index;
-}
-/**
-* Get endnote number for display (excluding separators)
-* @param endnote - The endnote to get the number for
-* @param endnoteMap - The endnote map
-* @param startNumber - Starting number (default 1)
-* @returns The display number, or null for separator endnotes
-*/
-function getEndnoteDisplayNumber(endnote, endnoteMap, startNumber = 1) {
-	if (isSeparatorEndnote(endnote)) return null;
-	const index = endnoteMap.getNormalEndnotes().findIndex((en) => en.id === endnote.id);
-	if (index === -1) return null;
-	return startNumber + index;
-}
-/**
 * Create an empty footnote map
 */
 function createEmptyFootnoteMap() {
@@ -267,4 +241,4 @@ function mergeEndnoteMaps(...maps) {
 	return createEndnoteMap(byId, endnotes);
 }
 //#endregion
-export { createEmptyEndnoteMap, createEmptyFootnoteMap, getEndnoteDisplayNumber, getEndnoteText, getFootnoteDisplayNumber, getFootnoteText, isSeparatorEndnote, isSeparatorFootnote, mergeEndnoteMaps, mergeFootnoteMaps, parseEndnoteProperties, parseEndnotes, parseFootnoteProperties, parseFootnotes };
+export { createEmptyEndnoteMap, createEmptyFootnoteMap, getEndnoteText, getFootnoteText, isSeparatorEndnote, isSeparatorFootnote, mergeEndnoteMaps, mergeFootnoteMaps, parseEndnoteProperties, parseEndnotes, parseFootnoteProperties, parseFootnotes };

package/dist/docx/groupDrawingParser.d.ts

@@ -0,0 +1,8 @@
+import { document_d_exports } from "../types/document.js";
+import { XmlElement } from "./xmlParser.js";
+
+//#region src/docx/groupDrawingParser.d.ts
+/** Parse a WordprocessingGroup drawing into a safe SVG-backed image preview. */
+declare const parseGroupDrawing: (drawing: XmlElement) => document_d_exports.Image | null;
+//#endregion
+export { parseGroupDrawing };

package/dist/docx/groupDrawingParser.js

@@ -0,0 +1,131 @@
+import { findAllDeep, findChildByLocalName, findChildrenByLocalName, getAttribute, getLocalName, getTextContent, parseNumericAttribute } from "./xmlParser.js";
+import { emuToPixels } from "../utils/units.js";
+import { parseImage } from "./imageParser.js";
+//#region src/docx/groupDrawingParser.ts
+const HEX_COLOR = /^[0-9A-Fa-f]{6}$/u;
+const DEFAULT_TEXT_COLOR = "000000";
+const DEFAULT_FONT_HALF_POINTS = 22;
+const DEFAULT_LINE_WIDTH_EMU = 9525;
+const HALF_POINT_TO_EMU = 6350;
+const MAX_GROUP_SHAPES = 256;
+const MAX_PATH_COMMANDS = 1e4;
+const MAX_TEXT_CHARACTERS = 2e4;
+const MAX_SVG_CHARACTERS = 1e6;
+const escapeXml = (value) => value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll("\"", "&quot;").replaceAll("'", "&apos;");
+const numericAttr = (element, name) => {
+	const direct = parseNumericAttribute(element, null, name);
+	if (direct !== void 0) return direct;
+	const wordValue = getAttribute(element, "w", name);
+	if (!wordValue) return 0;
+	const parsed = Number.parseInt(wordValue, 10);
+	return Number.isNaN(parsed) ? 0 : parsed;
+};
+const childTransform = (wsp) => {
+	const xfrm = findChildByLocalName(findChildByLocalName(wsp, "spPr"), "xfrm");
+	const off = findChildByLocalName(xfrm, "off");
+	const ext = findChildByLocalName(xfrm, "ext");
+	return {
+		x: numericAttr(off, "x"),
+		y: numericAttr(off, "y"),
+		width: numericAttr(ext, "cx"),
+		height: numericAttr(ext, "cy")
+	};
+};
+const colorFrom = (parent, fallback) => {
+	if (parent && getLocalName(parent.name ?? "") === "color") {
+		const value = getAttribute(parent, "w", "val");
+		if (value && HEX_COLOR.test(value)) return value.toUpperCase();
+	}
+	const value = getAttribute(findChildByLocalName(findChildByLocalName(parent, "solidFill"), "srgbClr"), null, "val");
+	if (value && HEX_COLOR.test(value)) return value.toUpperCase();
+	return fallback;
+};
+const wrapLine = (line, maxCharacters) => {
+	const words = line.trim().split(/\s+/u);
+	const lines = [];
+	let current = "";
+	for (const word of words) {
+		const candidate = current ? `${current} ${word}` : word;
+		if (current && candidate.length > maxCharacters) {
+			lines.push(current);
+			current = word;
+		} else current = candidate;
+	}
+	if (current) lines.push(current);
+	return lines;
+};
+const pathData = (path) => {
+	const commands = [];
+	for (const command of path.elements ?? []) {
+		if (commands.length >= MAX_PATH_COMMANDS) break;
+		if (command.type !== "element") continue;
+		const point = findChildByLocalName(command, "pt");
+		const x = numericAttr(point, "x");
+		const y = numericAttr(point, "y");
+		const name = command.name?.split(":").at(-1);
+		if (name === "moveTo") commands.push(`M ${x} ${y}`);
+		else if (name === "lnTo") commands.push(`L ${x} ${y}`);
+		else if (name === "quadBezTo") {
+			const points = findChildrenByLocalName(command, "pt");
+			if (points.length >= 2) commands.push(`Q ${numericAttr(points[0] ?? null, "x")} ${numericAttr(points[0] ?? null, "y")} ${numericAttr(points[1] ?? null, "x")} ${numericAttr(points[1] ?? null, "y")}`);
+		} else if (name === "cubicBezTo") {
+			const points = findChildrenByLocalName(command, "pt");
+			if (points.length >= 3) commands.push(`C ${numericAttr(points[0] ?? null, "x")} ${numericAttr(points[0] ?? null, "y")} ${numericAttr(points[1] ?? null, "x")} ${numericAttr(points[1] ?? null, "y")} ${numericAttr(points[2] ?? null, "x")} ${numericAttr(points[2] ?? null, "y")}`);
+		} else if (name === "close") commands.push("Z");
+	}
+	return commands.join(" ");
+};
+const renderGeometry = (wsp) => {
+	const { x, y, width, height } = childTransform(wsp);
+	if (width <= 0 || height <= 0) return "";
+	const spPr = findChildByLocalName(wsp, "spPr");
+	const fill = colorFrom(spPr, "none");
+	const line = findChildByLocalName(spPr, "ln");
+	const stroke = colorFrom(line, "none");
+	const strokeWidth = line ? parseNumericAttribute(line, null, "w") ?? DEFAULT_LINE_WIDTH_EMU : 0;
+	const paths = findAllDeep(findChildByLocalName(spPr, "custGeom"), "a", "path");
+	if (paths.length === 0) return `<rect x="${x}" y="${y}" width="${width}" height="${height}" fill="${fill === "none" ? "none" : `#${fill}`}" stroke="${stroke === "none" ? "none" : `#${stroke}`}" stroke-width="${strokeWidth}"/>`;
+	return paths.map((path) => {
+		const viewWidth = numericAttr(path, "w") || width;
+		const viewHeight = numericAttr(path, "h") || height;
+		const d = pathData(path);
+		if (!d) return "";
+		return `<path d="${d}" transform="translate(${x} ${y}) scale(${width / viewWidth} ${height / viewHeight})" fill="${fill === "none" ? "none" : `#${fill}`}" stroke="${stroke === "none" ? "none" : `#${stroke}`}" stroke-width="${strokeWidth}"/>`;
+	}).join("");
+};
+const renderTextBox = (wsp) => {
+	const { x, y, width, height } = childTransform(wsp);
+	if (width <= 0 || height <= 0) return "";
+	const paragraphs = findAllDeep(wsp, "w", "p");
+	const firstSize = findAllDeep(wsp, "w", "sz").at(0);
+	const halfPoints = numericAttr(firstSize ?? null, "val") || DEFAULT_FONT_HALF_POINTS;
+	const color = colorFrom(findAllDeep(wsp, "w", "color").at(0) ?? null, DEFAULT_TEXT_COLOR);
+	const fontSize = halfPoints * HALF_POINT_TO_EMU;
+	const maxCharacters = Math.max(1, Math.floor(width / (fontSize * .38)));
+	const lines = paragraphs.flatMap((paragraph) => wrapLine(getTextContent(paragraph).slice(0, MAX_TEXT_CHARACTERS), maxCharacters)).map(escapeXml);
+	if (lines.length === 0) return "";
+	const lineHeight = fontSize * 1.15;
+	const svgFontSize = 1e3;
+	const scale = fontSize / svgFontSize;
+	const lineStep = lineHeight / fontSize * svgFontSize;
+	return `<text x="0" y="${svgFontSize}" transform="translate(${x} ${y}) scale(${scale})" font-family="Arial, sans-serif" font-size="${svgFontSize}" fill="#${color}">${lines.map((line, index) => `<tspan x="0" dy="${index === 0 ? 0 : lineStep}">${line}</tspan>`).join("")}</text>`;
+};
+const createSvg = (group, width, height) => {
+	const content = findChildrenByLocalName(group, "wsp").slice(0, MAX_GROUP_SHAPES).map((wsp) => findChildByLocalName(wsp, "txbx") ? renderTextBox(wsp) : renderGeometry(wsp)).join("");
+	return `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 ${width} ${height}" width="${emuToPixels(width)}" height="${emuToPixels(height)}">${content}</svg>`;
+};
+/** Parse a WordprocessingGroup drawing into a safe SVG-backed image preview. */
+const parseGroupDrawing = (drawing) => {
+	const group = findChildByLocalName(findAllDeep(drawing, "a", "graphicData").at(0) ?? null, "wgp");
+	if (!group) return null;
+	const image = parseImage(drawing, void 0, void 0);
+	if (!image || image.size.width <= 0 || image.size.height <= 0) return null;
+	const svg = createSvg(group, image.size.width, image.size.height);
+	if (svg.length > MAX_SVG_CHARACTERS) return null;
+	image.src = `data:image/svg+xml;charset=utf-8,${encodeURIComponent(svg)}`;
+	image.mimeType = "image/svg+xml";
+	image.filename = "wordprocessing-group.svg";
+	return image;
+};
+//#endregion
+export { parseGroupDrawing };

package/dist/docx/index.d.ts

@@ -1,2 +1,4 @@
 import { getCachedNumberingMap } from "./numberingParser.js";
-export { getCachedNumberingMap };
+import { DOCX_ENCRYPTION_ERROR_CODES, DocxEncryptionError, DocxEncryptionErrorCode, isDocxEncryptionError } from "./encryption/errors.js";
+import { DecryptDocxOptions, DecryptDocxResult, decryptDocxIfNeeded, openDocxBuffer } from "./encryption/openEncryptedDocx.js";
+export { DOCX_ENCRYPTION_ERROR_CODES, type DecryptDocxOptions, type DecryptDocxResult, DocxEncryptionError, type DocxEncryptionErrorCode, decryptDocxIfNeeded, getCachedNumberingMap, isDocxEncryptionError, openDocxBuffer };

package/dist/docx/index.js

@@ -1,2 +1,4 @@
 import { getCachedNumberingMap } from "./numberingParser.js";
-export { getCachedNumberingMap };
+import { DOCX_ENCRYPTION_ERROR_CODES, DocxEncryptionError, isDocxEncryptionError } from "./encryption/errors.js";
+import { decryptDocxIfNeeded, openDocxBuffer } from "./encryption/openEncryptedDocx.js";
+export { DOCX_ENCRYPTION_ERROR_CODES, DocxEncryptionError, decryptDocxIfNeeded, getCachedNumberingMap, isDocxEncryptionError, openDocxBuffer };

package/dist/docx/numberingParser.d.ts

@@ -39,7 +39,9 @@ declare function createNumberingMap(definitions: document_d_exports.NumberingDef
 declare function computeListRendering(numPr: {
   numId?: number;
   ilvl?: number;
-}, numbering: NumberingMap): document_d_exports.ListRendering | null;
+}, numbering: NumberingMap): (document_d_exports.ListRendering & {
+  levelStarts: number[];
+}) | null;
 /**
  * Format a number according to the specified format
  *

package/dist/docx/numberingParser.js

@@ -581,7 +581,12 @@ function computeListRendering(numPr, numbering) {
 	const level = numbering.getLevel(numId, ilvl);
 	if (!level) return null;
 	const levelNumFmts = [];
-	for (let i = 0; i <= ilvl; i += 1) levelNumFmts.push(level.isLgl ? "decimal" : numbering.getLevel(numId, i)?.numFmt ?? "decimal");
+	const levelStarts = [];
+	for (let i = 0; i <= ilvl; i += 1) {
+		const listLevel = numbering.getLevel(numId, i);
+		levelNumFmts.push(level.isLgl ? "decimal" : listLevel?.numFmt ?? "decimal");
+		levelStarts.push(listLevel?.start ?? 1);
+	}
 	const instance = numbering.getInstance(numId);
 	const overrideForLevel = instance?.levelOverrides?.find((override) => override.ilvl === ilvl);
 	const rendering = {
@@ -590,7 +595,8 @@ function computeListRendering(numPr, numbering) {
 		marker: level.lvlText,
 		isBullet: level.numFmt === "bullet",
 		numFmt: level.isLgl ? "decimal" : level.numFmt,
-		levelNumFmts
+		levelNumFmts,
+		levelStarts
 	};
 	if (level.isLgl) rendering.isLegal = true;
 	if (level.rPr?.hidden) rendering.markerHidden = true;

package/dist/docx/paragraphParser.js

@@ -436,7 +436,7 @@ function paragraphStartsWithRenderedPageBreak(node) {
 		return "continue";
 	};
 	const outcome = visit(node);
-	if (outcome === "forced") return true;
+	if (outcome === "forced") return sawRenderedPageBreak;
 	return outcome === "visible" && sawRenderedPageBreak;
 }
 function replaceLocalName(name, localName) {
@@ -949,13 +949,19 @@ function parseParagraph(node, styles, theme, numbering, rels = null, media = nul
 			const level = numbering.getLevel(numId, ilvl);
 			if (level) {
 				const levelNumFmts = [];
-				for (let levelIndex = 0; levelIndex <= ilvl; levelIndex += 1) levelNumFmts.push(level.isLgl ? "decimal" : numbering.getLevel(numId, levelIndex)?.numFmt ?? "decimal");
+				const levelStarts = [];
+				for (let levelIndex = 0; levelIndex <= ilvl; levelIndex += 1) {
+					const listLevel = numbering.getLevel(numId, levelIndex);
+					levelNumFmts.push(level.isLgl ? "decimal" : listLevel?.numFmt ?? "decimal");
+					levelStarts.push(listLevel?.start ?? 1);
+				}
 				const listRendering = {
 					level: ilvl,
 					numId,
 					marker: level.lvlText,
 					isBullet: level.numFmt === "bullet",
-					levelNumFmts
+					levelNumFmts,
+					levelStarts
 				};
 				const instance = numbering.getInstance(numId);
 				const overrideForLevel = instance?.levelOverrides?.find((override) => override.ilvl === ilvl);

package/dist/docx/parser.d.ts

@@ -1,5 +1,5 @@
 import { document_d_exports } from "../types/document.js";
-import { DocxUnzipLimits } from "./unzip.js";
+import { DocxUnzipOptions } from "./unzip.js";
 import { DocxInput } from "../utils/docxInput.js";
 
 //#region src/docx/parser.d.ts
@@ -24,10 +24,9 @@ type ParseOptions = {
   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>;
-  }; /** Optional async hook to override display URLs for non-browser media. */
+  detectVariables?: boolean; /** Password for Agile-encrypted .docx files (Office 2010+). */
+  password?: string | undefined; /** Security limits for DOCX ZIP extraction */
+  unzipLimits?: DocxUnzipOptions; /** Optional async hook to override display URLs for non-browser media. */
   mediaResolver?: MediaResolver;
 };
 /**

package/dist/docx/parser.js

@@ -3,6 +3,7 @@ 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 { DocxEncryptionError } from "./encryption/errors.js";
 import { getMediaMimeType, mediaToDataUrl, unzipDocx } from "./unzip.js";
 import { parseComments } from "./commentParser.js";
 import { parseFooter, parseHeader } from "./headerFooterParser.js";
@@ -48,13 +49,17 @@ 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, mediaResolver } = options;
+	const { onProgress = () => {}, preloadFonts = true, parseHeadersFooters = true, parseNotes = true, detectVariables = true, password, unzipLimits, mediaResolver } = 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));
+		const raw = await timeStageAsync("unzip", () => unzipDocx(buffer, {
+			...unzipLimits,
+			password
+		}));
+		if (raw.wasEncrypted) warnings.push("Document was opened from password-protected storage; saving writes an unencrypted .docx file.");
 		warnings.push(...raw.warnings);
 		onProgress("Extracted DOCX", 10);
 		onProgress("Parsing relationships...", 10);
@@ -186,6 +191,7 @@ async function parseDocx(input, options = {}) {
 		onProgress("Complete", 100);
 		return document;
 	} catch (error) {
+		if (error instanceof DocxEncryptionError) throw error;
 		throw new DocxParseError({
 			message: `Failed to parse DOCX: ${error instanceof Error ? error.message : String(error)}`,
 			cause: error