@docen/docx 0.3.0 → 0.3.2

package/dist/converters/docx.mjs

@@ -1,14 +1,22 @@
-import { parseDocx, renderDocx } from "../extensions/heading.mjs";
-import { parseDocx as parseDocx$1, renderDocx as renderDocx$1 } from "../extensions/image.mjs";
-import { parseDocx as parseDocx$2, renderDocx as renderDocx$2 } from "../extensions/paragraph.mjs";
-import { parseDocx as parseDocx$3, renderDocx as renderDocx$3 } from "../extensions/strike.mjs";
-import { parseDocx as parseDocx$4, renderDocx as renderDocx$4 } from "../extensions/table.mjs";
-import { parseDocx as parseDocx$5, renderDocx as renderDocx$5 } from "../extensions/table-cell.mjs";
-import { parseDocx as parseDocx$6, renderDocx as renderDocx$6 } from "../extensions/table-header.mjs";
-import { parseDocx as parseDocx$7, renderDocx as renderDocx$7 } from "../extensions/table-row.mjs";
-import { parseDocx as parseDocx$8, renderDocx as renderDocx$8 } from "../extensions/text-style.mjs";
+import { BLOCKQUOTE_BORDER, applyBlockquoteStyle } from "../extensions/blockquote.mjs";
+import { renderDocx } from "../extensions/code-block.mjs";
+import { DETAILS_SUMMARY_STYLE, DETAILS_TAG } from "../extensions/details.mjs";
+import { parseDocx, renderDocx as renderDocx$1 } from "../extensions/heading.mjs";
+import { parseDocx as parseDocx$1, renderDocx as renderDocx$2 } from "../extensions/image.mjs";
+import { createMention, isMention, readMention } from "../extensions/mention.mjs";
+import { ORDERED_REFERENCE_PREFIX, buildOrderedLevels } from "../extensions/ordered-list.mjs";
+import { parseDocx as parseDocx$2, renderDocx as renderDocx$3 } from "../extensions/paragraph.mjs";
+import { parseDocx as parseDocx$3, renderDocx as renderDocx$4 } from "../extensions/strike.mjs";
+import { parseDocx as parseDocx$4, renderDocx as renderDocx$5 } from "../extensions/table.mjs";
+import { parseDocx as parseDocx$5, renderDocx as renderDocx$6 } from "../extensions/table-cell.mjs";
+import { parseDocx as parseDocx$6, renderDocx as renderDocx$7 } from "../extensions/table-header.mjs";
+import { parseDocx as parseDocx$7, renderDocx as renderDocx$8 } from "../extensions/table-row.mjs";
+import { createTaskCheckbox, isTaskCheckbox, readCheckboxState } from "../extensions/task-item.mjs";
+import { parseDocx as parseDocx$8, renderDocx as renderDocx$9 } from "../extensions/text-style.mjs";
 import { prepareDocument } from "./prepare.mjs";
+import { emojis, shortcodeToEmoji } from "@tiptap/extension-emoji";
 import { generateDocument, generateDocumentStream, generateDocumentSync, parseDocument } from "@office-open/docx";
+import { encodeBase64 } from "@office-open/core";
 //#region src/converters/docx.ts
 /** Remove keys with null/undefined values */
 function cleanAttrs(attrs) {
@@ -16,6 +24,53 @@ function cleanAttrs(attrs) {
 	for (const [key, value] of Object.entries(attrs)) if (value !== null && value !== void 0) result[key] = value;
 	return result;
 }
+/** True when two cell-margin sets (w:tcMar / w:tblCellMar) match on every side's
+*  size — used to detect a cell that merely echoes the table's default so its
+*  redundant tcMar can be dropped for a near-identity round-trip. */
+function sameCellMargins(a, b) {
+	const sz = (m, k) => m[k]?.size ?? null;
+	return [
+		"top",
+		"right",
+		"bottom",
+		"left"
+	].every((k) => sz(a, k) === sz(b, k));
+}
+/** Keys round-tripped between DocumentOptions core properties and `doc.attrs.core`. */
+const CORE_PROPERTY_KEYS = [
+	"title",
+	"subject",
+	"creator",
+	"keywords",
+	"description",
+	"lastModifiedBy",
+	"lastPrinted",
+	"created",
+	"modified",
+	"revision"
+];
+/**
+* DocumentOptions keys that DocxManager reconstructs (sections/numbering) or
+* carries in dedicated attrs (styles/background/core). Excluded from the
+* documentExtras pass-through so they aren't duplicated.
+*/
+const COMPILE_OWNED_KEYS = new Set([
+	"sections",
+	"numbering",
+	"styles",
+	"background",
+	...CORE_PROPERTY_KEYS
+]);
+/** Collect core properties present on DocumentOptions into a plain object. */
+function extractCoreProperties(docOpts) {
+	const source = docOpts;
+	const core = {};
+	for (const key of CORE_PROPERTY_KEYS) {
+		const value = source[key];
+		if (value !== void 0 && value !== null) core[key] = value;
+	}
+	return Object.keys(core).length > 0 ? core : null;
+}
 /** Merge consecutive text nodes with same marks */
 function mergeTextNodes(nodes) {
 	const result = [];
@@ -38,74 +93,202 @@ function mergeTextNodes(nodes) {
 * DocxManager handles tree walking, child assembly, and dispatching.
 */
 var DocxManager = class {
+	numberingConfigs = [];
+	orderedInstanceCounter = 0;
+	resolveStyles;
 	compile(json) {
-		const children = [];
+		this.numberingConfigs = [];
+		this.orderedInstanceCounter = 0;
+		const sections = [];
+		let currentChildren = [];
 		if (json.content) for (const node of json.content) {
 			const child = this.compileSectionChild(node);
-			if (!child) continue;
-			if (Array.isArray(child)) children.push(...child);
-			else children.push(child);
+			if (child) if (Array.isArray(child)) currentChildren.push(...child);
+			else currentChildren.push(child);
+			if (node.type === "paragraph") {
+				const na = node.attrs ?? {};
+				if (na.sectionProperties != null) {
+					sections.push(this.buildSection(currentChildren, na.sectionProperties, this.compileHeaderFooter(na.sectionHeaders ?? null), this.compileHeaderFooter(na.sectionFooters ?? null)));
+					currentChildren = [];
+				}
+			}
+		}
+		const docAttrs = json.attrs ?? {};
+		sections.push(this.buildSection(currentChildren, docAttrs.sectionProperties ?? null, this.compileHeaderFooter(docAttrs.sectionHeaders ?? null), this.compileHeaderFooter(docAttrs.sectionFooters ?? null)));
+		const styles = docAttrs.styles ?? void 0;
+		const core = docAttrs.core ?? void 0;
+		const background = docAttrs.background ?? void 0;
+		const documentExtras = docAttrs.documentExtras ?? void 0;
+		return {
+			sections,
+			...styles ? { styles } : {},
+			...core,
+			...background ? { background } : {},
+			...documentExtras,
+			...this.numberingConfigs.length > 0 ? { numbering: { config: this.numberingConfigs } } : {}
+		};
+	}
+	/** Assemble a SectionOptions from compiled children + optional layout/headers/footers. */
+	buildSection(children, properties, headers, footers) {
+		return {
+			children,
+			...properties ? { properties } : {},
+			...headers ? { headers } : {},
+			...footers ? { footers } : {}
+		};
+	}
+	/**
+	* Compile resolved header/footer slots (JSONContent[] per slot) back into
+	* SectionChild[] per slot. Returns undefined when no slot has content.
+	*/
+	compileHeaderFooter(slots) {
+		if (!slots) return void 0;
+		const group = {};
+		for (const slot of [
+			"default",
+			"first",
+			"even"
+		]) {
+			const json = slots[slot];
+			if (!json?.length) continue;
+			const children = [];
+			for (const node of json) {
+				const child = this.compileSectionChild(node);
+				if (!child) continue;
+				if (Array.isArray(child)) children.push(...child);
+				else children.push(child);
+			}
+			if (children.length > 0) group[slot] = children;
+		}
+		return Object.keys(group).length > 0 ? group : void 0;
+	}
+	/**
+	* Resolve a section's header/footer group (SectionChild[] per slot) into
+	* Tiptap JSON slots. Returns null when no slot has content.
+	*/
+	resolveHeaderFooter(group, numberingLookup) {
+		if (!group) return null;
+		const slots = {};
+		for (const slot of [
+			"default",
+			"first",
+			"even"
+		]) {
+			const children = group[slot];
+			if (children?.length) slots[slot] = this.resolveSectionChildren(children, numberingLookup);
 		}
-		return { sections: [{ children }] };
+		return Object.keys(slots).length > 0 ? slots : null;
 	}
 	resolve(docOpts) {
+		this.resolveStyles = docOpts.styles ?? void 0;
 		const sections = docOpts.sections ?? [];
 		if (sections.length === 0) return {
 			type: "doc",
 			content: [{ type: "paragraph" }]
 		};
-		const children = sections[0].children ?? [];
+		const numberingLookup = this.buildNumberingLookup(docOpts);
 		const content = [];
-		for (const child of children) {
-			const node = this.resolveSectionChild(child);
-			if (node) content.push(node);
+		const lastIndex = sections.length - 1;
+		for (let i = 0; i < sections.length; i++) {
+			const section = sections[i];
+			const sectionContent = this.resolveSectionChildren(section.children ?? [], numberingLookup);
+			if (i < lastIndex) {
+				const sectAttrs = {
+					sectionProperties: section.properties ?? null,
+					sectionHeaders: this.resolveHeaderFooter(section.headers, numberingLookup),
+					sectionFooters: this.resolveHeaderFooter(section.footers, numberingLookup)
+				};
+				const last = sectionContent[sectionContent.length - 1];
+				if (last?.type === "paragraph") last.attrs = {
+					...last.attrs,
+					...sectAttrs
+				};
+				else sectionContent.push({
+					type: "paragraph",
+					attrs: sectAttrs
+				});
+			}
+			content.push(...sectionContent);
 		}
-		return {
+		const doc = {
 			type: "doc",
 			content: content.length > 0 ? content : [{ type: "paragraph" }]
 		};
+		const attrs = {};
+		if (docOpts.styles) attrs.styles = docOpts.styles;
+		if (docOpts.background) attrs.background = docOpts.background;
+		const core = extractCoreProperties(docOpts);
+		if (core) attrs.core = core;
+		const lastSection = sections[lastIndex];
+		if (lastSection.properties) attrs.sectionProperties = lastSection.properties;
+		const lastHeaders = this.resolveHeaderFooter(lastSection.headers, numberingLookup);
+		if (lastHeaders) attrs.sectionHeaders = lastHeaders;
+		const lastFooters = this.resolveHeaderFooter(lastSection.footers, numberingLookup);
+		if (lastFooters) attrs.sectionFooters = lastFooters;
+		const documentExtras = {};
+		for (const [k, v] of Object.entries(docOpts)) {
+			if (COMPILE_OWNED_KEYS.has(k)) continue;
+			if (v === void 0 || v === null) continue;
+			documentExtras[k] = v;
+		}
+		if (Object.keys(documentExtras).length > 0) attrs.documentExtras = documentExtras;
+		if (Object.keys(attrs).length > 0) doc.attrs = attrs;
+		return doc;
 	}
 	compileSectionChild(node) {
 		switch (node.type) {
 			case "paragraph": return { paragraph: this.compileParagraphNode(node) };
 			case "heading": return { paragraph: this.compileHeadingNode(node) };
-			case "blockquote":
-				for (const child of node.content ?? []) if (child.type === "paragraph") return { paragraph: this.compileParagraphNode(child) };
-				return null;
-			case "codeBlock": return { paragraph: this.compileCodeBlock(node) };
+			case "blockquote": {
+				const items = [];
+				for (const child of node.content ?? []) if (child.type === "paragraph" || child.type === "heading") {
+					const para = child.type === "heading" ? this.compileHeadingNode(child) : this.compileParagraphNode(child);
+					const paraObj = typeof para === "string" ? { text: para } : para;
+					applyBlockquoteStyle(paraObj);
+					items.push({ paragraph: paraObj });
+				}
+				return items.length > 0 ? items : null;
+			}
+			case "codeBlock": {
+				const opts = renderDocx(node);
+				const childList = this.compileInlineContent(node.content);
+				if (childList.length > 0) opts.children = childList;
+				return { paragraph: this.simplifyParagraph(opts) };
+			}
 			case "horizontalRule": return { paragraph: { thematicBreak: true } };
 			case "table": return { table: this.compileTableNode(node) };
 			case "image": {
-				const imageRun = renderDocx$1(node);
+				const imageRun = renderDocx$2(node);
 				if (!imageRun) return null;
 				return { paragraph: { children: [imageRun] } };
 			}
 			case "bulletList":
 			case "orderedList":
-			case "taskList": return this.compileListFromNode(node);
+			case "taskList": return this.compileListFromNode(node, 0);
+			case "details": return this.compileDetailsNode(node);
+			case "passthrough": {
+				const data = node.attrs?.data ?? "{}";
+				try {
+					return JSON.parse(data);
+				} catch {
+					return null;
+				}
+			}
 			default: return null;
 		}
 	}
 	compileParagraphNode(node) {
-		const opts = renderDocx$2(node);
+		const opts = renderDocx$3(node);
 		const childList = this.compileInlineContent(node.content);
 		if (childList.length > 0) opts.children = childList;
 		return this.simplifyParagraph(opts);
 	}
 	compileHeadingNode(node) {
-		const opts = renderDocx(node);
+		const opts = renderDocx$1(node);
 		const childList = this.compileInlineContent(node.content);
 		if (childList.length > 0) opts.children = childList;
 		return this.simplifyParagraph(opts);
 	}
-	compileCodeBlock(node) {
-		const text = (node.content ?? []).map((c) => c.text ?? "").join("");
-		return {
-			style: "Code",
-			...node.attrs?.language ? { run: { font: "Consolas" } } : {},
-			text
-		};
-	}
 	/** Simple text optimization: merge plain runs into text field */
 	simplifyParagraph(opts) {
 		const children = opts.children;
@@ -119,13 +302,14 @@ var DocxManager = class {
 		return opts;
 	}
 	compileTableNode(node) {
-		const opts = renderDocx$4(node);
+		const opts = renderDocx$5(node);
 		const colCount = this.getTableColumnCount(node);
+		const tableCellMargins = opts.cellMargin ?? opts.margins ?? null;
 		const rows = [];
 		let activeSpans = [];
 		for (const rowNode of node.content ?? []) {
 			if (rowNode.type !== "tableRow") continue;
-			const rowOpts = renderDocx$7(rowNode);
+			const rowOpts = renderDocx$8(rowNode);
 			const pmCells = (rowNode.content ?? []).filter((c) => c.type === "tableCell" || c.type === "tableHeader");
 			const currentSpans = [...activeSpans].sort((a, b) => a.colStart - b.colStart);
 			const newSpans = [];
@@ -145,7 +329,7 @@ var DocxManager = class {
 					colIdx += span.colspan;
 					spanIdx++;
 				} else {
-					const cell = this.compileTableCellNode(pmCells[cellIdx]);
+					const cell = this.compileTableCellNode(pmCells[cellIdx], tableCellMargins);
 					const cs = cell.columnSpan ?? 1;
 					const rs = cell.rowSpan ?? 1;
 					if (rs > 1) {
@@ -241,8 +425,9 @@ var DocxManager = class {
 			}
 		};
 	}
-	compileTableCellNode(cellNode) {
-		const cellOpts = cellNode.type === "tableHeader" ? renderDocx$6(cellNode) : renderDocx$5(cellNode);
+	compileTableCellNode(cellNode, tableMargins) {
+		const cellOpts = cellNode.type === "tableHeader" ? renderDocx$7(cellNode) : renderDocx$6(cellNode);
+		if (tableMargins && cellOpts.margins && sameCellMargins(cellOpts.margins, tableMargins)) delete cellOpts.margins;
 		const cellAlign = cellNode.attrs?.align ?? null;
 		const cellChildren = [];
 		for (const paraNode of cellNode.content ?? []) {
@@ -254,23 +439,95 @@ var DocxManager = class {
 		if (cellChildren.length > 0) cellOpts.children = cellChildren;
 		return cellOpts;
 	}
-	compileListFromNode(node) {
+	compileListFromNode(node, level) {
 		const items = [];
+		const isOrdered = node.type === "orderedList";
+		const isTask = node.type === "taskList";
+		let ordered;
+		if (isOrdered) ordered = this.registerOrderedNumbering(node);
 		for (const listItem of node.content ?? []) {
 			if (listItem.type !== "listItem" && listItem.type !== "taskItem") continue;
+			const checked = Boolean(listItem.attrs?.checked);
 			for (const child of listItem.content ?? []) if (child.type === "paragraph" || child.type === "heading") {
-				const para = this.compileParagraphNode(child);
+				const para = child.type === "heading" ? this.compileHeadingNode(child) : this.compileParagraphNode(child);
 				const paraObj = typeof para === "string" ? { text: para } : para;
-				if (node.type === "bulletList") paraObj.bullet = { level: 0 };
-				else if (node.type === "orderedList") paraObj.numbering = {
-					reference: "default-numbering",
-					level: 0
+				if (ordered) paraObj.numbering = {
+					reference: ordered.reference,
+					instance: ordered.instance,
+					level
 				};
+				else paraObj.bullet = { level };
+				if (isTask) this.injectTaskCheckbox(paraObj, checked);
 				items.push({ paragraph: paraObj });
+			} else if (child.type === "bulletList" || child.type === "orderedList" || child.type === "taskList") {
+				const nested = this.compileListFromNode(child, level + 1);
+				if (nested) items.push(...nested);
 			}
 		}
 		return items.length > 0 ? items : null;
 	}
+	/**
+	* Register (or reuse) an abstractNum for an ordered list's `start`, and
+	* return a fresh instance so this list counts independently of other lists
+	* that share the same definition.
+	*/
+	registerOrderedNumbering(node) {
+		const start = Number(node.attrs?.start ?? 1) || 1;
+		let entry = this.numberingConfigs.find((c) => Number(c.levels[0]?.start ?? 1) === start);
+		if (!entry) {
+			entry = {
+				reference: `${ORDERED_REFERENCE_PREFIX}-${this.numberingConfigs.length + 1}`,
+				levels: buildOrderedLevels(start)
+			};
+			this.numberingConfigs.push(entry);
+		}
+		this.orderedInstanceCounter += 1;
+		return {
+			reference: entry.reference,
+			instance: this.orderedInstanceCounter
+		};
+	}
+	/**
+	* Prepend an inline checkbox SDT to a task paragraph. The SDT is tagged
+	* "docen-task" so resolve can tell task items apart from ordinary paragraphs
+	* that happen to contain an SDT.
+	*/
+	injectTaskCheckbox(paraObj, checked) {
+		let existing = [];
+		if (Array.isArray(paraObj.children)) existing = paraObj.children;
+		else if (typeof paraObj.text === "string") {
+			if (paraObj.text) existing = [{ text: paraObj.text }];
+			delete paraObj.text;
+		}
+		paraObj.children = [createTaskCheckbox(checked), ...existing];
+	}
+	/**
+	* details → block-level group-SDT. The summary paragraph is tagged with a
+	* fixed style so resolve can split it back out; content blocks flatten in
+	* after it. (No native collapse in DOCX — structure round-trips, the view
+	* stays expanded.)
+	*/
+	compileDetailsNode(node) {
+		const sdtChildren = [];
+		for (const child of node.content ?? []) if (child.type === "detailsSummary") {
+			const inline = this.compileInlineContent(child.content);
+			const summaryPara = { style: DETAILS_SUMMARY_STYLE };
+			if (inline.length > 0) summaryPara.children = inline;
+			sdtChildren.push({ paragraph: summaryPara });
+		} else if (child.type === "detailsContent") for (const block of child.content ?? []) {
+			const compiled = this.compileSectionChild(block);
+			if (!compiled) continue;
+			if (Array.isArray(compiled)) sdtChildren.push(...compiled);
+			else sdtChildren.push(compiled);
+		}
+		return { sdt: {
+			properties: {
+				tag: DETAILS_TAG,
+				group: true
+			},
+			children: sdtChildren
+		} };
+	}
 	compileInlineContent(content) {
 		if (!content) return [];
 		const children = [];
@@ -281,20 +538,52 @@ var DocxManager = class {
 			case "hardBreak":
 				children.push({ break: 1 });
 				break;
+			case "pageBreak":
+				children.push({ pageBreak: true });
+				break;
+			case "columnBreak":
+				children.push({ columnBreak: true });
+				break;
 			case "image": {
-				const imageRun = renderDocx$1(node);
+				const imageRun = renderDocx$2(node);
 				if (imageRun) children.push(imageRun);
 				break;
 			}
+			case "wpgGroup": {
+				const wpgGroup = node.attrs?.wpgGroup;
+				if (wpgGroup) children.push({ wpgGroup });
+				break;
+			}
+			case "wpsShape": {
+				const wpsShape = node.attrs?.wpsShape;
+				if (wpsShape) children.push({ wpsShape });
+				break;
+			}
+			case "mention":
+				children.push(createMention(String(node.attrs?.id ?? ""), String(node.attrs?.label ?? "")));
+				break;
+			case "emoji": {
+				const name = String(node.attrs?.name ?? "");
+				const text = (name ? shortcodeToEmoji(name, emojis)?.emoji : void 0) ?? (name ? `:${name}:` : "");
+				if (text) children.push({ text });
+				break;
+			}
 		}
 		return children;
 	}
 	compileTextNode(node, children) {
 		const text = node.text ?? "";
 		if (!text) return;
-		const marks = node.marks ?? [];
+		const segments = text.split("\n");
+		for (let i = 0; i < segments.length; i++) {
+			if (i > 0) children.push({ break: 1 });
+			if (segments[i]) this.compileTextRun(segments[i], node.marks, children);
+		}
+	}
+	/** Emit a single run for `text` with all inline marks applied. */
+	compileTextRun(text, marks, children) {
 		const runOpts = { text };
-		for (const mark of marks) switch (mark.type) {
+		for (const mark of marks ?? []) switch (mark.type) {
 			case "bold":
 				runOpts.bold = true;
 				break;
@@ -305,7 +594,7 @@ var DocxManager = class {
 				runOpts.underline = { type: "single" };
 				break;
 			case "strike": {
-				const strikeProps = renderDocx$3(mark.attrs ?? {});
+				const strikeProps = renderDocx$4(mark.attrs ?? {});
 				Object.assign(runOpts, strikeProps);
 				break;
 			}
@@ -319,10 +608,11 @@ var DocxManager = class {
 				runOpts.highlight = mark.attrs?.color ?? "yellow";
 				break;
 			case "code":
+				runOpts.style = "CodeChar";
 				runOpts.font = "Consolas";
 				break;
 			case "textStyle": {
-				const tsProps = renderDocx$8(mark.attrs ?? {});
+				const tsProps = renderDocx$9(mark.attrs ?? {});
 				Object.assign(runOpts, tsProps);
 				break;
 			}
@@ -350,15 +640,72 @@ var DocxManager = class {
 	resolveSectionChild(child) {
 		if ("paragraph" in child) return this.resolveParagraph(child.paragraph);
 		if ("table" in child) return this.resolveTable(child.table);
-		return null;
+		if ("sdt" in child) {
+			const sdt = child.sdt;
+			if (sdt.properties?.tag === "docen-details") return this.resolveDetailsSdt(sdt);
+			return this.resolvePassthrough(child);
+		}
+		return this.resolvePassthrough(child);
+	}
+	/** Wrap an opaque SectionChild in a passthrough atom (attrs.data = JSON). */
+	resolvePassthrough(child) {
+		return {
+			type: "passthrough",
+			attrs: { data: JSON.stringify(child) }
+		};
+	}
+	/**
+	* Resolve a details group-SDT: the summary-style paragraph becomes
+	* detailsSummary, the remaining blocks fold into detailsContent.
+	*/
+	resolveDetailsSdt(sdt) {
+		const content = [];
+		let summary = null;
+		for (const child of sdt.children ?? []) {
+			if ("paragraph" in child) {
+				const para = child.paragraph;
+				if (para.style === "DocenDetailsSummary") {
+					summary = this.resolveInlineContent(para);
+					continue;
+				}
+			}
+			const node = this.resolveSectionChild(child);
+			if (!node) continue;
+			if (Array.isArray(node)) content.push(...node);
+			else content.push(node);
+		}
+		const details = {
+			type: "details",
+			content: []
+		};
+		if (summary !== null) details.content.push({
+			type: "detailsSummary",
+			content: summary
+		});
+		if (content.length > 0) details.content.push({
+			type: "detailsContent",
+			content
+		});
+		return details;
 	}
 	resolveParagraph(opts) {
 		const resolved = typeof opts === "string" ? { text: opts } : opts;
-		const headingLevel = resolved.heading ? HEADING_LEVEL_MAP[resolved.heading] : void 0;
+		if (resolved.thematicBreak) return { type: "horizontalRule" };
+		if (resolved.style === "Code") return this.resolveCodeBlock(resolved);
+		let headingLevel = resolved.heading ? HEADING_LEVEL_MAP[resolved.heading] : void 0;
+		if (!headingLevel && resolved.style) {
+			const name = this.styleNameOf(resolved.style);
+			if (name) {
+				const m = /^heading\s+(\d)$/i.exec(name);
+				if (m) {
+					const lvl = Number(m[1]);
+					if (lvl >= 1 && lvl <= 6) headingLevel = lvl;
+				} else if (/^title$/i.test(name)) headingLevel = 1;
+			}
+		}
+		if (headingLevel && !resolved.heading) resolved.heading = `Heading${headingLevel}`;
 		const nodeType = headingLevel ? "heading" : "paragraph";
 		const attrs = headingLevel ? parseDocx(resolved) : parseDocx$2(resolved);
-		if (resolved.bullet) return this.resolveListItem(resolved, "bulletList", attrs);
-		if (resolved.numbering) return this.resolveListItem(resolved, "orderedList", attrs);
 		const content = this.resolveInlineContent(resolved);
 		const cleanAttrsObj = cleanAttrs(attrs);
 		const node = { type: nodeType };
@@ -366,24 +713,262 @@ var DocxManager = class {
 		if (content.length > 0) node.content = content;
 		return node;
 	}
-	resolveListItem(opts, listType, paraAttrs) {
-		const content = this.resolveInlineContent(opts);
-		const cleanAttrsObj = cleanAttrs(paraAttrs);
-		const paragraphNode = { type: "paragraph" };
-		if (Object.keys(cleanAttrsObj).length > 0) paragraphNode.attrs = cleanAttrsObj;
-		if (content.length > 0) paragraphNode.content = content;
+	/** Look up a paragraph style's NAME from its styleId, via the styles table
+	*  carried on the current resolve(). Returns undefined outside resolve. */
+	styleNameOf(styleId) {
+		return this.resolveStyles?.paragraphStyles?.find((p) => p.id === styleId)?.name;
+	}
+	/** reference → level-0 format/start, for classifying numbering paragraphs. */
+	buildNumberingLookup(docOpts) {
+		const lookup = /* @__PURE__ */ new Map();
+		const config = docOpts.numbering?.config;
+		if (config) for (const entry of config) {
+			const lvl0 = entry.levels[0];
+			lookup.set(entry.reference, {
+				format: lvl0?.format,
+				start: lvl0?.start
+			});
+		}
+		return lookup;
+	}
+	/**
+	* Walk section children, grouping consecutive list paragraphs into nested
+	* Tiptap lists. Non-list children resolve individually. DOCX flattens lists
+	* to a paragraph sequence (depth carried by `level`); this rebuilds the tree.
+	*/
+	resolveSectionChildren(children, numberingLookup) {
+		const content = [];
+		let i = 0;
+		while (i < children.length) {
+			const child = children[i];
+			const firstPara = "paragraph" in child ? child.paragraph : null;
+			if (!(firstPara && typeof firstPara !== "string" ? this.detectList(firstPara, numberingLookup) : null)) {
+				if (firstPara && typeof firstPara !== "string" && this.detectBlockquote(firstPara)) {
+					const group = [];
+					while (i < children.length) {
+						const member = children[i];
+						if (!("paragraph" in member)) break;
+						const para = member.paragraph;
+						if (typeof para === "string" || !this.detectBlockquote(para)) break;
+						group.push(para);
+						i++;
+					}
+					content.push(this.buildBlockquote(group));
+					continue;
+				}
+				const node = this.resolveSectionChild(child);
+				if (node) content.push(node);
+				i++;
+				continue;
+			}
+			const group = [];
+			while (i < children.length) {
+				const member = children[i];
+				if (!("paragraph" in member)) break;
+				const para = member.paragraph;
+				if (typeof para === "string") break;
+				const info = this.detectList(para, numberingLookup);
+				if (!info) break;
+				group.push({
+					para,
+					info
+				});
+				i++;
+			}
+			content.push(...this.buildListTree(group));
+		}
+		return content;
+	}
+	/** Classify a paragraph as a list item, or null if it isn't one. */
+	detectList(para, lookup) {
+		const p = para;
+		const numbering = p.numbering;
+		const bullet = p.bullet;
+		let kind;
+		let level;
+		let reference;
+		let start;
+		if (numbering) {
+			reference = numbering.reference;
+			level = numbering.level ?? 0;
+			const cfg = reference ? lookup.get(reference) : void 0;
+			if (cfg && cfg.format && cfg.format !== "bullet") {
+				kind = "ordered";
+				start = cfg.start;
+			} else {
+				kind = "bullet";
+				reference = void 0;
+			}
+		} else if (bullet) {
+			kind = "bullet";
+			level = bullet.level ?? 0;
+		} else return null;
+		const first = p.children?.[0];
 		return {
-			type: listType,
-			content: [{
-				type: "listItem",
-				content: [paragraphNode]
-			}]
+			kind: isTaskCheckbox(first) ? "task" : kind,
+			level,
+			reference,
+			start,
+			checked: readCheckboxState(first)
 		};
 	}
+	/**
+	* Rebuild nested Tiptap lists from a flat run of list paragraphs. Stack-based:
+	* each frame is an active list at a given depth; the `key` (level:type:
+	* reference) decides whether a paragraph continues the top list, starts a
+	* nested list, or splits off a new sibling list.
+	*/
+	buildListTree(group) {
+		const topLevel = [];
+		const stack = [];
+		for (const { para, info } of group) {
+			const listType = info.kind === "ordered" ? "orderedList" : info.kind === "task" ? "taskList" : "bulletList";
+			const itemType = info.kind === "task" ? "taskItem" : "listItem";
+			const key = `${info.level}:${listType}:${info.reference ?? ""}`;
+			while (stack.length > 0) {
+				const top = stack[stack.length - 1];
+				if (top.level > info.level || top.level === info.level && top.key !== key) {
+					stack.pop();
+					continue;
+				}
+				break;
+			}
+			const newItem = {
+				type: itemType,
+				content: [this.resolveListItemParagraph(para, info)]
+			};
+			if (itemType === "taskItem") newItem.attrs = { checked: info.checked };
+			const top = stack[stack.length - 1];
+			if (top && top.level === info.level && top.key === key) {
+				top.listNode.content.push(newItem);
+				top.currentItem = newItem;
+			} else {
+				const newList = {
+					type: listType,
+					content: [newItem]
+				};
+				if (listType === "orderedList" && info.level === 0 && typeof info.start === "number" && info.start !== 1) newList.attrs = { start: info.start };
+				if (top) top.currentItem.content.push(newList);
+				else topLevel.push(newList);
+				stack.push({
+					level: info.level,
+					key,
+					listNode: newList,
+					currentItem: newItem
+				});
+			}
+		}
+		return topLevel;
+	}
+	/** Classify a paragraph as a blockquote member by its signature. */
+	detectBlockquote(para) {
+		const p = para;
+		const indent = p.indent;
+		const border = p.border;
+		if (!indent || indent.left !== 720) return false;
+		const bl = border?.left;
+		if (!bl) return false;
+		const sig = BLOCKQUOTE_BORDER;
+		return bl.style === sig.style && bl.size === sig.size && bl.space === sig.space && bl.color === sig.color;
+	}
+	/**
+	* Rebuild a blockquote node from a run of signature-carrying paragraphs,
+	* stripping the indent/border signature so child paragraphs render clean.
+	*/
+	buildBlockquote(group) {
+		const content = [];
+		for (const para of group) {
+			const node = this.resolveParagraph(para);
+			const attrs = node.attrs;
+			if (attrs) {
+				if (attrs.indent) {
+					const indent = { ...attrs.indent };
+					delete indent.left;
+					attrs.indent = Object.keys(indent).length > 0 ? indent : void 0;
+				}
+				if (attrs.border) {
+					const border = { ...attrs.border };
+					delete border.left;
+					attrs.border = Object.keys(border).length > 0 ? border : void 0;
+				}
+				const cleaned = cleanAttrs(attrs);
+				if (Object.keys(cleaned).length > 0) node.attrs = cleaned;
+				else delete node.attrs;
+			}
+			content.push(node);
+		}
+		return {
+			type: "blockquote",
+			content
+		};
+	}
+	/**
+	* Resolve a list-item paragraph to a Tiptap paragraph/heading node, stripping
+	* the list marker (bullet/numbering) and the leading task checkbox — those
+	* are expressed at the list/item level, not inside the paragraph.
+	*/
+	resolveListItemParagraph(para, info) {
+		const resolved = typeof para === "string" ? { text: para } : para;
+		const headingLevel = resolved.heading ? HEADING_LEVEL_MAP[resolved.heading] : void 0;
+		const nodeType = headingLevel ? "heading" : "paragraph";
+		const attrs = headingLevel ? parseDocx(resolved) : parseDocx$2(resolved);
+		const stripped = info.kind === "task" ? this.stripTaskCheckbox(resolved) : resolved;
+		const content = this.resolveInlineContent(stripped);
+		const node = { type: nodeType };
+		const cleanAttrsObj = cleanAttrs(attrs);
+		if (Object.keys(cleanAttrsObj).length > 0) node.attrs = cleanAttrsObj;
+		if (content.length > 0) node.content = content;
+		return node;
+	}
+	/** Return a copy of `para` with its leading docen-task checkbox SDT removed. */
+	stripTaskCheckbox(para) {
+		const children = para.children;
+		if (Array.isArray(children) && children.length > 0 && isTaskCheckbox(children[0])) return {
+			...para,
+			children: children.slice(1)
+		};
+		return para;
+	}
+	resolveCodeBlock(opts) {
+		const children = opts.children;
+		const content = [];
+		if (children) {
+			for (const child of children) if (typeof child === "string") {
+				if (child) content.push({
+					type: "text",
+					text: child
+				});
+			} else if (typeof child === "object" && child !== null) {
+				if ("break" in child) {
+					const prev = content[content.length - 1];
+					if (prev && prev.type === "text") prev.text = (prev.text ?? "") + "\n";
+					else content.push({
+						type: "text",
+						text: "\n"
+					});
+				} else if ("text" in child) {
+					const marks = this.resolveMarks(child);
+					const textNode = {
+						type: "text",
+						text: child.text
+					};
+					if (marks) textNode.marks = marks;
+					content.push(textNode);
+				}
+			}
+		} else if (opts.text) content.push({
+			type: "text",
+			text: opts.text
+		});
+		const node = { type: "codeBlock" };
+		if (content.length > 0) node.content = content;
+		return node;
+	}
 	resolveTable(tableOpts) {
 		const attrs = parseDocx$4(tableOpts);
 		const rows = tableOpts.rows ?? [];
 		const content = [];
+		const tableCellMargins = tableOpts.cellMargin ?? tableOpts.margins ?? null;
 		let activeSpans = /* @__PURE__ */ new Map();
 		for (const row of rows) {
 			const rowAttrs = parseDocx$7(row);
@@ -407,6 +992,7 @@ var DocxManager = class {
 				const isHeader = row.tableHeader;
 				const cellAttrs = isHeader ? parseDocx$6(cell) : parseDocx$5(cell);
 				delete cellAttrs.verticalMerge;
+				if (!cellAttrs.margins && tableCellMargins) cellAttrs.margins = tableCellMargins;
 				const cellChildren = cell.children ?? [];
 				const cellContent = [];
 				for (const cc of cellChildren) {
@@ -416,10 +1002,27 @@ var DocxManager = class {
 				const cellNode = { type: isHeader ? "tableHeader" : "tableCell" };
 				if (Object.keys(cellAttrs).length > 0) cellNode.attrs = cleanAttrs(cellAttrs);
 				if (cellContent.length > 0) cellNode.content = cellContent;
+				else cellNode.content = [{ type: "paragraph" }];
 				if (vMerge === "restart") for (let c = colIdx; c < colIdx + cellColspan; c++) nextActiveSpans.set(c, cellNode);
 				cellNodes.push(cellNode);
 				colIdx += cellColspan;
 			}
+			const gridAfter = row.gridAfter ?? 0;
+			if (gridAfter > 0) {
+				const trailingType = row.tableHeader ? "tableHeader" : "tableCell";
+				const nilBorders = {
+					top: { style: "nil" },
+					right: { style: "nil" },
+					bottom: { style: "nil" },
+					left: { style: "nil" }
+				};
+				for (let c = 0; c < gridAfter; c++) cellNodes.push({
+					type: trailingType,
+					attrs: { borders: nilBorders },
+					content: [{ type: "paragraph" }]
+				});
+				colIdx += gridAfter;
+			}
 			activeSpans = nextActiveSpans;
 			const rowNode = { type: "tableRow" };
 			if (Object.keys(rowAttrs).length > 0) rowNode.attrs = cleanAttrs(rowAttrs);
@@ -471,15 +1074,36 @@ var DocxManager = class {
 	resolveParagraphChild(child) {
 		if ("text" in child || "children" in child || "break" in child) return this.resolveRun(child);
 		if ("image" in child) return this.resolveImage(child.image);
-		if ("hyperlink" in child) return this.resolveHyperlink(child.hyperlink);
-		if ("pageBreak" in child) return {
-			type: "paragraph",
-			attrs: { pageBreak: true }
+		if ("wpgGroup" in child) return {
+			type: "wpgGroup",
+			attrs: { wpgGroup: child.wpgGroup }
 		};
-		if ("columnBreak" in child) return { type: "hardBreak" };
+		if ("wpsShape" in child) return {
+			type: "wpsShape",
+			attrs: { wpsShape: child.wpsShape }
+		};
+		if ("sdt" in child) return this.resolveInlineSdt(child);
+		if ("hyperlink" in child) return this.resolveHyperlink(child.hyperlink);
+		if ("pageBreak" in child) return { type: "pageBreak" };
+		if ("columnBreak" in child) return { type: "columnBreak" };
+		return null;
+	}
+	/** Resolve an inline SDT (mention carrier; other inline SDTs unsupported). */
+	resolveInlineSdt(child) {
+		if (isMention(child)) {
+			const { id, label } = readMention(child);
+			return {
+				type: "mention",
+				attrs: {
+					id,
+					label
+				}
+			};
+		}
 		return null;
 	}
 	resolveRun(opts) {
+		if (opts.break && opts.text === void 0 && !opts.children) return { type: "hardBreak" };
 		const text = opts.text;
 		if (text === void 0 && !opts.children) return null;
 		if (opts.children && !text) {
@@ -512,10 +1136,16 @@ var DocxManager = class {
 		}
 		if (opts.subScript) marks.push({ type: "subscript" });
 		if (opts.superScript) marks.push({ type: "superscript" });
-		if (opts.highlight) marks.push({ type: "highlight" });
-		if (opts.font === "Consolas" || opts.font === "monospace") marks.push({ type: "code" });
+		if (opts.highlight) marks.push({
+			type: "highlight",
+			attrs: { color: opts.highlight }
+		});
+		if (opts.style === "CodeChar") marks.push({ type: "code" });
 		const textStyleAttrs = parseDocx$8(opts);
-		if (opts.font === "Consolas" || opts.font === "monospace") delete textStyleAttrs.font;
+		if (opts.style === "CodeChar") {
+			delete textStyleAttrs.font;
+			delete textStyleAttrs.styleId;
+		}
 		if (Object.keys(textStyleAttrs).length > 0) marks.push({
 			type: "textStyle",
 			attrs: textStyleAttrs
@@ -526,7 +1156,7 @@ var DocxManager = class {
 		const attrs = parseDocx$1(imageOpts);
 		const data = imageOpts.data;
 		const type = imageOpts.type;
-		if (data && type) attrs.src = `data:image/${type};base64,${typeof btoa !== "undefined" ? btoa(String.fromCharCode(...data instanceof ArrayBuffer ? new Uint8Array(data) : data)) : Buffer.from(data).toString("base64")}`;
+		if (data && type) attrs.src = `data:image/${type};base64,${encodeBase64(data instanceof ArrayBuffer ? new Uint8Array(data) : data)}`;
 		return {
 			type: "image",
 			attrs
@@ -573,6 +1203,25 @@ function parseDOCX(data) {
 	return defaultManager.resolve(parseDocument(data));
 }
 /**
+* Merge {@link DocxGenerateOptions.document} into the `DocumentOptions`
+* compiled from Tiptap JSON.
+*
+* - `sections`/`numbering`: compile-owned (excluded from `document`, never
+*   overridden).
+* - `styles`/`externalStyles`: option wins over `json.attrs.styles`; the two
+*   are mutually exclusive, so `externalStyles` clears compiled `styles`.
+* - Everything else (core properties, background, features, …): injected.
+*/
+function applyDocumentOptions(base, document) {
+	if (!document) return base;
+	const merged = {
+		...base,
+		...document
+	};
+	if (document.externalStyles !== void 0) delete merged.styles;
+	return merged;
+}
+/**
 * Generate a DOCX file from Tiptap JSON (runtime model), asynchronously.
 *
 * Pipeline: `prepareDocument` (default: fetch http images, in place) →
@@ -582,19 +1231,20 @@ function parseDOCX(data) {
 * in place (http image URLs become embedded data URLs).
 */
 async function generateDOCX(json, options) {
-	const { prepare = true, packer } = options ?? {};
+	const { prepare = true, packer, document } = options ?? {};
 	if (prepare !== false) await prepareDocument(json, prepare === true ? void 0 : prepare);
-	return generateDocument(compileDocument(json), packer);
+	return generateDocument(applyDocumentOptions(compileDocument(json), document), packer);
 }
 /**
 * Generate a DOCX file synchronously — fastest throughput, blocks the event loop.
 *
 * Pipeline: `DocxManager.compile` → `generateDocumentSync`. Does **not** run
 * `prepareDocument` (it is async); call `await prepareDocument(json)` first
-* when http images need embedding.
+* when http images need embedding. `options.document` is still applied.
 */
-function generateDOCXSync(json, packerOptions) {
-	return generateDocumentSync(compileDocument(json), packerOptions);
+function generateDOCXSync(json, options) {
+	const { packer, document } = options ?? {};
+	return generateDocumentSync(applyDocumentOptions(compileDocument(json), document), packer);
 }
 /**
 * Generate a DOCX file as a `ReadableStream<Uint8Array>` — for large documents
@@ -604,9 +1254,9 @@ function generateDOCXSync(json, packerOptions) {
 * `DocxManager.compile` → `generateDocumentStream`. Async due to preparation.
 */
 async function generateDOCXStream(json, options) {
-	const { prepare = true, packer } = options ?? {};
+	const { prepare = true, packer, document } = options ?? {};
 	if (prepare !== false) await prepareDocument(json, prepare === true ? void 0 : prepare);
-	return generateDocumentStream(compileDocument(json), packer);
+	return generateDocumentStream(applyDocumentOptions(compileDocument(json), document), packer);
 }
 /**
 * Convert DocumentOptions (persistence model) to Tiptap JSON (runtime model).